Jose Flores | Writing

Lifecycle Boundaries in Actor and State Machine Architecture

Jose Flores — Thu, 30 Jul 2026 00:00:04 GMT

The functional core gave the router one place to decide which route the application accepts.

I still had to connect that decision to the browser.

I was using a newer Navigation API iteration of the beta router examples to test that boundary against native navigation.

My first version used an Ignite effect. When the accepted route changed, the effect called the browser’s Navigation API. That preserved an important boundary: the resolver decided the route without importing window, and the effect handled the outward update.

For a single rendered element, that approach felt natural.

The problem became clearer when I followed everything else the router had to do. It needed to read the initial path, observe browser navigation, receive requests from several surfaces, commit accepted paths, record failures, and remove the observer when it stopped.

The route element was only one projection of that behavior. It was not the lifetime owner of the router.

The effect solved direction, not ownership

The effect established the direction of the dependency. Router state changed first, then browser navigation followed.

It did not answer which running part of the system owned the browser relationship.

An earlier version started the shared router actor in one module and registered the browser observer beside it:

export const routerActor = createActor(routerMachine, {
  input: { path: currentPath() },
}).start();

onPopState((path) =>
  routerActor.send({
    type: "POPSTATE",
    path,
  }),
);

The Ignite effect handled the opposite direction by writing accepted paths back to browser history.

Each piece worked, but their lifetimes did not line up.

onPopState returned an unsubscribe function, and this call discarded it. Stopping the actor did not remove the observer. The Ignite effect belonged to a route element even though the shared actor and browser observer could outlive that element.

The nested router made this harder to ignore. Parent navigation, documentation sections, and settings panels all projected the same router source. If one of those elements connected or disconnected, it should not decide whether the application router was still observing the browser.

The question that helped me move forward was not, “Where should this code live?”

It was:

Which parts of this behavior must start and stop together?

The router state, browser observation, accepted-path commits, failure handling, and cleanup described one running lifecycle. They needed an owner whose lifetime contained all of them.

Removing `host` made the next boundary visible

The earlier API change also mattered here.

Once host was removed from igniteCore command and effect callbacks on the v3 beta line, the custom element could no longer act as an implicit path to browser capabilities. Commands received explicit application inputs. Effects had to use explicitly provided capabilities instead of discovering them through the element.

That was intentional, but it raised another design question: how should the router receive navigation without turning Ignite Element into a browser integration framework?

I considered introducing another Ignite abstraction, something like a driver or igniteEnvironment. The idea was to give effects and sources a standard place to find browser, storage, network, or other environment capabilities.

The more I worked through it, the less it fit.

Ignite Element already has a behavioral input: the source. That source may be an XState machine or actor, a Redux store, a MobX object, or another supported runtime. Adding a second behavior runtime to igniteCore would create more configuration while making Ignite Element responsible for how every state library provisions external capabilities.

XState already has its own composition tools, including machine provisioning with .provide(). Other sources have their own construction patterns. Ignite Element does not need to replace them.

The direction we landed on was simpler: provide the environment capability while constructing the source, then give the resulting source to igniteCore.

For the router, that capability became NavigationPort.

The navigation port answers three questions the source has about its environment:

What is the current path?
How can the router observe external path changes?
How can it commit a path the application accepted?

The browser implementation uses window.navigation. A memory implementation provides the same capability for headless tests. Neither implementation owns route matching, authentication redirects, or nested route policy.

Those decisions remain in the project resolver.

The source uses the port to assemble the running behavior. Its observer is expressed as XState callback actor logic:

observeNavigation: fromCallback<RouterEvent>(
  ({ sendBack }) =>
    navigation.observe((path) =>
      sendBack({
        type: "NAVIGATION_OBSERVED",
        path,
      }),
    ),
),

navigation.observe returns its cleanup function. Because the router invokes this callback actor at its root, observation begins when the router starts and cleanup runs when the router stops.

That is the lifecycle boundary I was missing in the first version.

Architecture diagram · Scroll horizontally to explore.Open full size

The Ignite effect was useful because it showed that the browser update belonged outside the deterministic resolver. Moving navigation under the source answered the next question: the router’s running owner, not the rendered element, should coordinate that update with observation and cleanup.

Ignite Element remains the projection boundary. It receives the source, derives the view, exposes commands, and renders components. The source owns behavior that must remain coherent even when a particular projection disconnects.

The environment can change without rebuilding the router

Once navigation was supplied to the source, the same router behavior could run with browser and memory implementations:

const browserSource = createRouterSource({
  navigation: createBrowserNavigation(
    resolveBrowserNavigation(),
  ),
});

const memory = createMemoryNavigation("/");

const headlessSource = createRouterSource({
  navigation: memory.port,
});

This was important for dogfooding Ignite Element. The headless runtime should be able to exercise the same router behavior without fabricating a custom element or pretending to be a browser.

The memory implementation can report an externally observed path. It can also record paths the router asks it to commit. The browser implementation translates those operations into the native Navigation API.

Changing the implementation does not move route policy. It also does not move the observer lifetime. Both remain under the same source.

This is where ports became useful in a way that felt less abstract to me. The port is not another layer added for ceremony. It is the application-facing shape of a capability the source needs in more than one environment.

The adapter answers, “How does navigation work here?” The resolver answers, “Which route does this application accept?” The actor keeps those answers coherent as events arrive over time.

The current commit protocol has a limit

The browser’s Navigation API exposes more lifecycle detail than the current router port preserves. A call to navigation.navigate() provides separate committed and finished promises. One represents the URL and history entry changing. The other represents the navigation finishing, including intercepted work.

Our current NavigationPort.commit() returns Promise<void>.

The router resolves the accepted route, updates its context, and asks the port to commit the path. If the promise rejects, the source records the failure. If it resolves, the source does not receive a separate application fact.

That means router context currently represents the route accepted by application policy. It does not prove that the environment confirmed every part of the navigation lifecycle.

I think this is an important limit to keep visible without designing a larger protocol before the example needs one.

If a future application needs to distinguish accepted, browser-committed, and fully-finished navigation, the port and actor protocol will need to preserve the milestone that matters. We would also have to decide what happens when a second request arrives before the first one finishes and whether abandoned work can be cancelled.

The current dogfooding projects do not answer those questions. They demonstrate optimistic context updates, commit rejection handling, source-owned observation, and cleanup.

That is enough evidence for the boundary we changed. It is not evidence for a pending-route or confirmed-navigation protocol we have not implemented.

Why the actor owns this behavior

The resolver can remain a function because its work ends when it returns an accepted route.

The router cannot end there. It remembers state, receives requests from multiple navigation surfaces, observes the browser while running, commits accepted paths, records failures, and releases its observer when it stops.

I use an actor because those responsibilities already form a protocol over time. The meaning of a request depends on current route and authentication state. Observation can arrive between application requests. Cleanup has to occur even if no route element remains connected.

That does not mean every router needs XState. An imperative controller with start(), navigate(), and stop() could own the same lifecycle in a smaller application.

The architectural requirement is narrower: the behavior that must remain coherent from start to stop needs one owner with the right lifetime.

For Ignite Element, this also protects the library boundary. igniteCore does not need host in commands or effects, and it does not need a new environment runtime. It receives a source whose behavior and capabilities were already composed using the tools native to that source.

That feels closer to the framework-agnostic design I want. Ignite Element projects behavior without quietly becoming its lifecycle authority.

Next in the series

The router source now depends on a navigation capability without depending on window.navigation directly. The browser and memory implementations can change while route policy and lifecycle ownership remain in the same place.

The next article examines that capability boundary more closely: what belongs in a port, what belongs in an adapter, and how external values become application meaning without moving policy into the integration.

If you want to follow this work in the project itself, the Ignite Element v3 beta documentation describes the current runtime model, and the beta branch on GitHub contains the source and dogfooding examples behind this series.

Read on 0xjcf.com

Functional Core Architecture: Where Deterministic Decisions Belong

Jose Flores — Thu, 30 Jul 2026 00:00:03 GMT

The previous article ended with a semantic navigation request:

{ type: "NAVIGATE_REQUESTED", to: "/dashboard" }

That gave the router a stable message. A link, a test, or another interface could request the same destination without sending a click event or reconstructing browser markup.

I thought the next step would be straightforward. I wanted to build the router around the browser’s Navigation API, which is now available as window.navigation. It gives applications one place to observe, intercept, and initiate navigation without rebuilding everything around popstate and the History API.

It seemed like a good project for dogfooding the Ignite Element v3 beta.

The beta already contained SPA and nested-router examples built around the History API. I used the Navigation API iteration described here to revisit the same route-policy and lifecycle questions.

What I did not know was where the browser’s responsibility should end.

The Navigation API could tell me which destination was requested. It could update browser history and report how navigation progressed. It could not decide whether /dashboard was a route this application recognized or whether a signed-out user should be redirected to /login.

I had started with one routing problem. The native API made me see at least two:

What route does the application accept?
How does the current environment observe and commit that route?

The first question is a decision. The second is a capability and a lifecycle.

The first bridge was an Ignite effect

My first instinct was to keep the browser update close to Ignite Element. A command would carry the request to the router actor, and an Ignite effect would observe the resulting snapshot and update the Navigation API.

A reduced version of that direction looked like this:

const browserNavigation = window.navigation;

const routerCore = igniteCore({
  source: routerActor,

  commands: ({ actor }) => ({
    navigate: (to: string) => {
      actor.send({
        type: "NAVIGATE_REQUESTED",
        to,
      });
    },
  }),

  effects: ({ snapshot, prevSnapshot }) => {
    const nextPath = snapshot.context.route.path;
    const previousPath = prevSnapshot.context.route.path;

    if (nextPath !== previousPath) {
      void browserNavigation.navigate(nextPath).finished;
    }
  },
});

This was a reasonable place to begin. The command expressed intent. The effect synchronized accepted router state with the browser. The machine did not import window.

It also exposed a problem in Ignite Element’s API.

At the time, command and effect callbacks received the custom element as host. That made it possible for a command to discover intent from host.dataset, which was the problem the startModule example exposed earlier in the series. It also gave effects a convenient path back into the element and its browser environment.

The router made the broader issue easier to see. A navigation effect did not need a rendered element. It needed a navigation capability. Giving it host encouraged the component to become a service locator for whichever browser details the effect wanted to reach.

That pressure led me to remove host from the igniteCore command and effect callbacks on the v3 beta line. This was not only a preference in the router example. It became part of the beta API.

The custom element still owns rendering and browser interaction at its boundary. What changed is that core callbacks no longer receive the element simply because one happens to exist. A command must receive the application value it needs:

commands: ({ actor }) => ({
  navigate: (to: string) => {
    actor.send({
      type: "NAVIGATE_REQUESTED",
      to,
    });
  },
});

The v3 beta documentation introduces the current runtime, and the beta branch on GitHub contains the implementation and dogfooding projects as they evolve.

An effect that needs an environment capability must receive or close over that capability explicitly. It should not discover the environment by reaching sideways through the rendered host.

Removing host did not solve routing by itself. It made the unanswered responsibility visible.

The effect knew which accepted path to send to the browser because router state already contained one. Something still had to decide which path belonged in that state.

The browser request was not the application decision

Consider an unauthenticated request for /dashboard.

The browser can report /dashboard as the destination. The semantic command can carry that path to the router. Neither one has enough authority to say whether the application accepts it.

That answer depends on application facts:

Which routes exist?
Which route matched the requested path?
Does it require authentication?
Is the current user authenticated?
Should the application redirect to /login?

I initially described this as “policy equals decisions.” That is close, but it helps to be more specific. Policy is the rule that chooses an answer from the current state and facts. The state transition records that answer. The running actor then carries the behavior forward over time.

For the SPA router dogfooding project, the smallest useful policy became a pure function named resolveNavigation:

const requiresAuth = (name: RouteName): boolean =>
  routes.find((route) => route.name === name)
    ?.requiresAuth ?? false;

export const resolveNavigation = (
  toPath: string,
  authed: boolean,
): Resolved => {
  const match = matchRoute(toPath);

  if (requiresAuth(match.name) && !authed) {
    const login = matchRoute(LOGIN_PATH);

    return {
      path: login.path,
      route: login.name,
      params: login.params,
      redirected: true,
    };
  }

  return {
    path: match.path,
    route: match.name,
    params: match.params,
    redirected: false,
  };
};

The route table, dynamic path matching, and authentication redirect are application policy in this project. resolveNavigation does not observe window.navigation, inspect an element, or commit browser history. It receives the requested path and authentication fact, then returns the route the application accepts.

That gives the decision a small test surface:

expect(
  resolveNavigation("/dashboard", false).route,
).toBe("login");

expect(
  resolveNavigation("/dashboard", true).route,
).toBe("dashboard");

expect(
  resolveNavigation("/missing", false).route,
).toBe("not-found");

These tests do not prove that the browser navigated. They prove that the same path and authentication state produce the same application answer.

That is what made the phrase functional core useful to me. I am not using it to mean that the whole application must adopt functional programming. I mean the deterministic part of the system that owns an application decision.

The effect can perform an outward update. The Navigation API can perform browser navigation. Neither one should quietly create route policy while doing that work.

The nested router tested the same boundary again

The SPA example gave me a clean resolver, but I wondered whether the boundary would hold once navigation was divided across parent and child surfaces.

That became the nested child-router dogfooding project.

The name can make it sound like a child router runs inside a parent router. That is not how the example works. One application-owned XState router source is shared by the parent and child outlets. Parent navigation, documentation sections, and settings panels expose commands scoped to the choices available in each surface, but all of those requests reach the same router actor.

The nested resolver owns a different route policy. Instead of applying authentication redirects, it maps a root-relative path into the parent, child, and label the outlets need.

The important result was not that both projects shared one generic resolver. They do not. Each project owns a stable, closed route policy for the behavior it is testing.

What they share is the responsibility split:

Architecture diagram · Scroll horizontally to explore.Open full size

Different surfaces may offer different commands. Different projects may apply different route rules. The route decision still has one application authority.

This answered one of the questions I had while working through ports and policies. A port does not make the decision deterministic. The resolver does that. A port gives the running behavior a provider-neutral way to reach the environment after the decision is made.

What the functional core changed

Before this project, it was easy for me to think about routing as one feature. The application receives a path and the browser moves.

Dogfooding the Navigation API forced me to slow that sentence down.

The interface captures a destination. The command carries the request. The resolver applies route policy. The actor records the accepted route. An environment capability performs the browser work.

Those steps can live close together in a small implementation. They still own different decisions.

This also explains why removing host from igniteCore mattered. The change was not only about making headless tests easier. It prevented command and effect callbacks from treating the current custom element as the source of application intent or environment capability.

The current router source still uses an optimistic commit. It updates router context with the accepted route, asks its navigation capability to commit the path, and records a failure if that promise rejects. A successful commit does not return an application fact, and the source does not keep separate pending and confirmed routes.

I do not want to describe a stronger protocol than the example implements. The resolver gives us a deterministic application decision. It does not prove that the browser and application state have been reconciled after every commit.

That limit led to the next question.

The Ignite effect could update the browser after router state changed, but the router also needed to observe browser navigation, own the subscription, handle commit failures, and clean everything up when it stopped. Those responsibilities did not belong to one route decision, and tying them to whichever element rendered the route gave them the wrong lifetime.

The next post, Lifecycle Boundaries in Actor and State Machine Architecture, follows the router from the Ignite effect into the running source that owns observation, commits, failure, and cleanup.

Read on 0xjcf.com

Semantic Commands: Translating User Intent into Application Behavior

Jose Flores — Thu, 30 Jul 2026 00:00:02 GMT

A product narrative is not yet a runtime contract.

Consider the narrative from the previous article:

A developer wants to start a selected module while exercising the application from different interfaces. They should be able to identify the module directly instead of reconstructing how one browser view stores that value.

The paragraph preserves the person, their desired progress, and the presentation detail we want to keep outside the application contract.

But an actor cannot treat that paragraph as a deterministic protocol.

At the other extreme, a browser can give us a MouseEvent. That object can cross a function boundary, but it says almost nothing about the application request. It contains coordinates, targets, and browser state while leaving the behavior to reverse-engineer what the click meant.

The narrative has meaning but no protocol. The gesture has data but no application meaning.

The translation between them is where intent either survives or begins to leak.

This is where I use a semantic command: a request named in the application’s vocabulary that carries the information its authority needs to consider it.

The interface sees a gesture

In a browser, the interaction may begin with a click. In a test, it may begin with a direct function call. Another interface might use a keyboard shortcut, an HTTP request, or an agent action.

Those are delivery mechanisms. They are not the application intent.

If the command accepts a browser event, the interface becomes part of the application contract:

startModule(event: MouseEvent);

The behavior now has to discover what the click meant. It may inspect event.currentTarget, read a data attribute, or depend on a particular markup structure. A headless test must recreate enough of that interface to make the request.

The semantic command names the operation directly:

startModule(moduleId: string);

The browser binding can obtain the selected ID from its current view and pass it in. A headless test can use the same contract without creating a MouseEvent or an element.

This is not about removing context indiscriminately. It is about separating the context behavior needs from the mechanism that happened to capture it.

The behavior needs to know which module was requested. It does not need the click coordinates, target element, or markup structure.

The delivery boundary should translate the interaction. It should not ask the application to reverse-engineer the interface.

A command is a compression boundary

I think of the semantic command as a form of deliberate compression.

The product narrative contains more context than the running behavior needs. The interface interaction contains more delivery detail than the application should know. The command preserves the smallest useful meaning between them.

Form	What it preserves
Product narrative	Person, context, desired progress, and product intent
Interface interaction	How one interface observed or captured the request
Semantic command	The application request and the values behavior needs to consider it
Fact	What the application or external work determined actually happened

Compression is useful only if we preserve the right information.

If we discard moduleId, the behavior cannot identify the requested module. If we carry the entire MouseEvent, the application inherits browser details it does not need. If we announce that the module started before authoritative behavior accepts the request, we have compressed a possibility into a false fact.

The goal is not the smallest payload. It is the smallest payload that preserves application meaning.

In a larger system, that may include an idempotency key, correlation ID, initiating actor, or provenance the application needs for consistency and audit. Those values are not automatically delivery noise. The question is whether authoritative behavior needs them to interpret the request, not whether they came from outside the current function.

Carry the request to its authority

In the Ignite Element v3 beta, the command forwards the request to the actor:

commands: ({ actor }) => ({
  startModule: (moduleId: string) => {
    actor.send({
      type: "START_MODULE",
      moduleId,
    });
  },
});

The beta API makes the same boundary explicit: command callbacks receive the actor, not the custom-element host. A browser binding may still read from its element, but that translation happens before it calls the command.

Two small translations happen:

The delivery interface turns its interaction into startModule(moduleId).
The command function turns that request into START_MODULE for the actor that owns the behavior.

The command does not decide whether the module may start. It does not update actor context directly or announce that the start succeeded. It carries the request to the part of the application allowed to interpret it.

Architecture diagram · Scroll horizontally to explore.Open full size

The narrative constrains what the command means, but it does not execute the interface. The binding translates the current interaction. The command then crosses into authoritative behavior without carrying the interface with it.

That seam looks almost boring.

That is a good sign. A command should be easy to describe: receive application intent and carry it to its owner.

A request is not a fact

The message name often reveals what we think the sender has authority to claim.

START_MODULE is a request. It says someone wants the behavior to consider starting a module.

MODULE_STARTED makes a different claim. It says the start already happened.

Message	Meaning	Appropriate sender
`START_MODULE`	Please consider starting this module	A caller allowed to request the behavior
`MODULE_STARTED`	The module has successfully started	The behavior or work that observed completion

If an interface sends MODULE_STARTED because someone clicked a button, it announces an outcome it does not own. The current state may reject the request. The work may fail. Another module may already be running.

The actor may receive START_MODULE, reject it, begin work, and later receive or produce MODULE_STARTED after completion. Those messages describe different moments and require different authority.

This is why naming every event in the past tense can be as misleading as naming every event as an imperative. The useful question is not grammatical:

What does the sender have the authority to claim?

Translation can fail in two directions

A delivery boundary can translate too little.

Passing a MouseEvent, HTTP request, SDK object, or provider payload into behavior forces the application to understand an external contract. The command exists, but the delivery mechanism crossed with it.

The boundary can also translate too much.

If the command validates application policy, chooses an adapter, performs retries, changes state, and announces completion, it becomes a second behavior engine:

startModule: async (moduleId) => {
  if (!canStart(moduleId)) return;
  await retry(() => api.start(moduleId));
  actor.send({ type: "MODULE_STARTED", moduleId });
};

Some boundary validation is normal. A route parameter may need decoding. A form value may need to become an explicit application value. Structurally invalid input may need to be rejected before it enters the application.

But deciding whether a valid request is allowed now, which work should begin, and what a failure means belongs with authoritative behavior and policy.

The narrow path is:

translate delivery details into application values
preserve the context behavior actually needs
carry the request without deciding its outcome

Too little translation leaks the interface inward. Too much translation moves behavior outward.

Navigation makes the next problem easier to see.

A browser link produces a click. The application intent is to request a destination:

commands: ({ actor }) => ({
  navigate: (to: string) => {
    actor.send({
      type: "NAVIGATE_REQUESTED",
      to,
    });
  },
});

NAVIGATE_REQUESTED does not claim that the browser moved or that the destination is allowed. It asks the router’s behavior to interpret a destination under the current policy.

The router still has to answer:

Does the path match a route?
Does the route require authentication?
Should the request redirect?

Those answers should not depend on whether the request came from a link, a test, an HTTP route, or another delivery interface.

The semantic command gives each caller the same vocabulary. It does not guarantee the same outcome, because the current state and policy still matter.

That distinction is the reason the command remains a request.

Use the smallest useful vocabulary

Semantic does not mean elaborate.

We do not need a command class, command bus, or generic envelope for every request. A typed function and a typed actor event may be enough.

I add structure when it protects a real distinction:

interface interaction versus application intent
request versus completed fact
structural validation versus application policy
caller responsibility versus behavior authority

For startModule, a string argument was enough to expose the hidden dependency. For navigation, NAVIGATE_REQUESTED gives the router one place to interpret the request.

The value is not the pattern name. It is that different callers can express the same intent without importing one interface’s vocabulary or creating another policy owner.

A semantic-command check

Before exposing a command, I ask:

Is it named after what the caller wants rather than how one interface delivers it?
Does it carry every value authoritative behavior needs to consider the request?
Can another caller use it without fabricating UI, transport, or provider objects?
Does the sender have authority to make the claim expressed by the message?
Does the boundary translate structure without deciding application policy?
Is the command still understandable without knowing the current interface?

If those answers are clear, the command forms a useful seam between delivery and behavior.

Next in the series

NAVIGATE_REQUESTED gives the application a stable request, but a request is not yet a decision.

Something still has to interpret the destination under the current routes, authentication state, and navigation policy. That interpretation should produce the same answer for the same state and facts, regardless of which interface delivered the request.

The next post, Functional Core Architecture: Where Deterministic Decisions Belong, isolates that deterministic decision before we add browser history, observers, or asynchronous commits.

Read on 0xjcf.com

Product Framing Before Software Design: Deciding What to Build

Jose Flores — Thu, 30 Jul 2026 00:00:01 GMT

A clean boundary can protect the wrong behavior just as effectively as the right one.

That is uncomfortable because architectural improvements produce satisfying evidence. The code becomes easier to test. Responsibilities become clearer. Two interfaces can use the same contract. We can point to the result and say, “This is better.”

Sometimes it is.

But better architecture only tells us that the implementation matches our decision more clearly. It does not tell us whether the decision was worth making.

I am approaching this from my role as the maintainer of Ignite Element. The developer using the library is my direct user. That developer may be building for a client, an internal product team, or the people who eventually use the application.

I ran into this after cleaning up the startModule command from the previous article:

startModule(moduleId);

The caller now supplied the module ID directly. A browser binding and a headless test could express the same intent without recreating an HTML element.

That fixed a real ownership problem.

It did not prove that starting a module was the right behavior to build.

The refactor answered one question

The headless test gave us useful evidence. It had to construct an element and attach data-module-id before it could say which module should start. The test was recreating presentation markup to communicate application intent.

Changing the command answered a narrow question:

Can more than one interface express the same request without depending on one browser view?

We could verify the answer with tests. Both callers passed a module ID, sent the same event, and reached the same behavior.

That is implementation evidence.

It does not prove that developers understand the API faster, make fewer mistakes, or prefer the new contract. It does not tell us whether starting a module solves the most important problem in their workflow. Those are different claims, and they require different evidence.

This distinction is easy to lose when implementation is inexpensive. We can move from an idea to a polished component before we have written down the problem we think the component solves.

The code begins to look settled while the product decision still rests on assumptions.

Start with progress, not a command

“The system needs a start command” sounds like a requirement, but it already assumes the solution.

Before behavior, I want to know:

Who is trying to make progress?
What are they trying to accomplish?
What makes that difficult today?
What would be different if we helped?

In this example, the frame begins at the boundary between Ignite Element and the developer using it. I am trying to understand how that developer exercises component behavior through the different environments the library supports. During normal development, they might use a rendered browser control. In a test, they might use the headless runtime. In both cases, they wanted to start a particular module and observe what the application did.

The difficulty I actually observed was narrower: the headless test had to fabricate DOM state before it could make that request.

That is enough to investigate. We do not need to inflate one awkward test into a universal claim about every developer, test, or component system. We only need to describe what we know precisely enough to decide what to try next.

I have found it useful to capture that understanding in a small product frame.

A product frame makes assumptions visible

The frame is not a requirements document. It is a compact record of the problem as we currently understand it, including the places where we may be wrong.

For startModule, I would write:

Part	Current statement
Person and context	A developer using Ignite Element to invoke module behavior from a browser binding or headless test
Desired progress	Start a chosen module and inspect the resulting behavior
Observed difficulty	The headless test had to fabricate DOM state to provide the module ID
Known constraint	Starting a module requires an explicit module ID
Hypothesis	A presentation-independent command will make the behavior easier to exercise from more than one interface
Outcome signal	Developers can express the operation without learning or recreating an unrelated presentation contract

The person, desired progress, difficulty, and constraint come from the workflow we encountered. The hypothesis describes the change we believe will help. The outcome signal tells us what improvement we expect to observe.

Those lines should not quietly trade places.

A hypothesis does not become a fact because the implementation works. An outcome signal is not “the pull request merged.” If we cannot distinguish what we observed from what we hope will improve, the frame only gives uncertainty a more official-looking format.

The point is not to sound certain. The point is to make the uncertainty inspectable.

The frame can repeat at each layer

The developer is my direct user in this example, but they are not necessarily the last person affected by the design. They may use Ignite Element to build an application for a client, a product team, or an end user with a different problem.

The same product frame can be applied again at each layer:

Frame owner	Person in focus	Progress being investigated
Ignite Element maintainer	Developer using the library	Express and test the same application behavior across supported environments
Application developer or team	Client, stakeholder, or operator	Represent the workflow and rules the application needs to support
Product team or client	End user	Complete a real task with less friction

The chain will differ by product. The important part is that evidence from one layer does not automatically validate the next. A passing headless test gives me evidence about the Ignite Element contract. It does not prove that a client’s workflow is correct or that an end user benefits from the behavior.

Each layer needs its own person, desired progress, observed difficulty, hypothesis, and outcome signal. The questions repeat. The answers do not.

Correct behavior and helpful behavior need different evidence

Architecture and product discovery validate different things.

Question	Useful evidence
Did we implement the behavior we agreed to?	Transition tests, traces, contracts, and observable state
Did the behavior help with the problem we described?	Observation, feedback, usage, and outcome signals

Passing the first test does not answer the second.

A state machine can enforce a workflow perfectly while the workflow remains confusing. A provider-neutral adapter can isolate an integration while the application still models the provider’s process instead of the user’s progress. A polished interface can make the wrong next step easier to click.

None of those are failures of architecture. They are reminders that architecture protects a decision from implementation churn. It does not transform that decision into product truth.

This is why the frame belongs before behavior. It keeps the reason for the behavior close enough that we can still question it.

Turn the frame into a narrative

The frame gives us the pieces of the problem, but it does not yet describe the interaction.

For this example, the narrative might be:

A developer wants to start a selected module while exercising the application from different interfaces. They should be able to identify the module directly instead of reconstructing how one browser view stores that value.

That sentence gives us more direction than “add a reusable command.” It identifies who initiates the interaction, which value represents their intent, and which presentation detail should remain outside the application contract.

It also leaves the implementation open.

The narrative does not require XState, Ignite Element, a DOM attribute, or a particular test helper. Those choices belong later, after we agree on the progress the behavior should support.

This is where product framing begins to constrain architecture without designing it. The narrative gives us a reason to reject a contract that forces every caller to impersonate the current UI, but it does not prescribe the final command, event, or actor.

The frame guides behavior but does not govern it

There is an important boundary here.

The product frame explains why we are considering a behavior. It is not a second runtime authority.

Once a team accepts the behavior, the application still needs one place that decides whether a request is allowed now, how state changes, which work begins, and what completion or failure means. Those decisions belong to authoritative behavior and policy.

The reverse is also true. A state machine can enforce an accepted rule, but it cannot tell us whether the original product frame was sound.

The frame may change because we learn something new. The runtime should not reinterpret policy every time a product assumption changes in a document. We use new evidence to make a deliberate product decision, then change the authoritative behavior through the same explicit process as any other rule.

Keeping these responsibilities separate prevents two mistakes:

treating implementation correctness as product validation
treating a product narrative as executable policy

The frame gives behavior a reason. The behavior gives the running system authority.

Keep it small enough to change

This should not become a ceremony before every function.

I use a product frame when a change introduces or alters visible behavior, commits the application to a policy, or creates a boundary that other parts of the system will depend on.

For many changes, six short lines are enough:

Person and context:
Desired progress:
Observed difficulty:
Known constraint:
Hypothesis:
Outcome signal:

The most valuable line is often Hypothesis. It records what we expect to improve without presenting that expectation as a settled fact.

That makes later learning less defensive. If evidence contradicts the hypothesis, we can change the product decision without pretending the implementation was defective. The code may have done exactly what we asked. We simply learned that we should ask for something different.

A useful frame should make change easier, not make the original idea harder to question.

A product-frame check

Before modeling behavior, I ask:

Which layer of the product am I framing?
Can I describe the person and their desired progress without naming the implementation?
Which evidence belongs to this layer?
Which part of the difficulty have we actually observed?
Which part are we assuming?
What outcome would support the hypothesis?
What result would make us reconsider it?
Does the proposed request express the person’s intent or a detail of the current interface?

For startModule, the improvement was not merely that we found a cleaner function signature. The signature was useful because it matched the intent described by the product frame.

That still does not give every caller permission to mutate state. “Start this module” is a request. The application needs a smaller semantic command that can cross into authoritative behavior and be accepted or rejected according to its rules.

Next in the series

The product frame gives us the context. The narrative describes the interaction. Neither one is a message the application can execute.

The next post, Semantic Commands: Translating User Intent into Application Behavior, follows that translation and asks what the application should receive when a person clicks a button, a test invokes a function, or another interface requests the same behavior.

Read on 0xjcf.com

AI-Generated Code and Software Architecture: Why Ownership Matters

Jose Flores — Thu, 30 Jul 2026 00:00:00 GMT

There was a time when writing the code was the hard part.

You had to remember the syntax, learn an unfamiliar API, and wire asynchronous logic carefully enough that it would survive timing, failure, and retries. I do not miss callback hell, but that friction did limit how quickly a vague decision could become part of a system.

Today, I can describe a feature and receive a plausible implementation in seconds. It may include loading states, error handling, retries, and tests. Sometimes it is shockingly good.

But I started noticing a different kind of failure.

The logic looked correct, yet the system still felt unstable. A small change required knowledge from several files. Tests passed, but the code felt risky to touch. Replacing an integration changed behavior that should have had nothing to do with the provider.

The problem was not syntax. It was not even the tool.

It was ownership.

The bottleneck moved

AI is very good at completing the local story.

Ask it to load some data and it must decide where loading state lives, who calls the API, how errors are translated, and whether a retry belongs in the component, machine, or request helper. If those decisions are missing from the request, the implementation still has to put them somewhere.

Usually, it chooses the nearest convenient place.

That does not make the generated code inherently bad. A human working quickly will make the same choice. The difference is that we can now repeat the choice across a codebase much faster than we can inspect its consequences.

AI did not create unclear responsibility. It made unclear responsibility cheaper to multiply.

This is why I think the bottleneck moved. Producing a possible implementation is becoming easier. Deciding which part of the system is allowed to know, choose, mutate, start, stop, retry, and clean up is still design work.

That is the architectural work I care about.

A small command with a hidden decision

I ran into this while dogfooding Ignite Element, a component runtime that projects actor state into Web Components.

As the maintainer, I often build small projects to stress-test the API against realistic behavior. These projects are not client case studies. They give me a place to see whether Ignite Element’s contracts still make sense when the same behavior is exercised through a rendered interface and a headless runtime.

One of those projects included a screen that lists several modules. Each module has a Start button, an XState actor tracks which one is running, and Ignite Element renders the resulting state.

The first version of the command discovered the module ID from the rendered element:

commands: ({ actor, host }) => ({
  startModule: () =>
    actor.send({
      type: "START_MODULE",
      moduleId: host.dataset.moduleId ?? "missing",
    }),
});

Nothing about this looked alarming. It worked in the browser because the element contained the expected data-module-id. The "missing" fallback even looked defensive.

As part of that stress test, I tried to exercise the same behavior through the headless runtime.

The test did not need a DOM element. It only needed to say which module should start. But the command contract forced the test to create an element and attach data to it before it could express that intent.

That awkward setup was useful evidence.

When a test has to impersonate an unrelated boundary, the production contract may be giving that boundary too much responsibility.

Starting a module requires a module ID whether the request comes from a button, a test, a keyboard shortcut, or another interface. Reading dataset is only one way a browser view might find that value. It is not part of the application intent.

The command became:

commands: ({ actor }) => ({
  startModule: (moduleId: string) => {
    actor.send({ type: "START_MODULE", moduleId });
  },
});

The important change is not the extra parameter. It is the decision that disappeared from the command.

The caller now supplies moduleId. A browser binding may read it from the current view. A headless test can pass it directly. The command carries the request into the actor, and the machine defines whether that request is allowed in the current state.

That callback shape also became part of the Ignite Element v3 beta. The beta removes host from command and effect callbacks, so a callback no longer receives the rendered element as an implicit dependency. Commands receive explicit application inputs, while effects receive or close over the capabilities they need.

The tool sees a missing value and fills it. The architecture decides who was allowed to provide that value in the first place.

Architecture diagram · Scroll horizontally to explore.Open full size

The logic was correct. The boundary was not

The original command worked. That is what made the problem easy to miss.

Architecture problems rarely announce themselves with a syntax error. They appear later as knowledge that spreads farther than the change should require.

In this example, the ownership problem is concrete. The command knew how one browser view stored moduleId, and the headless test exposed that dependency by forcing us to recreate the view just to express the same intent.

That gives us a more useful question to ask during review:

Does this part of the system know something because the behavior requires it, or only because one interface happens to provide it that way?

The behavior required a module ID. It did not require a dataset. That detail belonged to the browser binding.

Product policy should change when the product decision changes. An integration should change when the provider changes. Presentation should change when the experience changes. When those responsibilities are mixed, a change in one part travels through all three.

That is often the feeling behind, “The code works, so why is this so difficult to change?”

Architecture distributes authority

When I say architecture, I am not talking about folder names, diagrams, or a prescribed number of layers. Those things can record a decision, but they cannot make the decision for us.

I am talking about the distribution of authority through a system:

Who may interpret an intent?
Who may decide whether it is valid now?
Who may change state?
Who may start external work?
Who owns the result, failure, retry, and cleanup?

Responsibility and authority are related, but they are not the same.

Responsibility is what a part must do. Authority is what that part alone is allowed to decide.

In the Ignite example, the caller supplies the module it wants to start. The command translates that request into an actor event. The machine defines the legal transition. The running actor owns the state and lifecycle. The view renders the result.

The command is responsible for carrying intent, but it does not have authority to invent a transition. The view is responsible for presentation, but it does not have authority to mutate actor state. The actor owns the lifecycle, but it should not have to understand how a particular button encoded the request.

Once those rules are explicit, generated code has something concrete to follow. We can review whether a new implementation respects an existing owner instead of judging each callback in isolation.

Why state machines help, and where they stop

XState is useful here because it makes part of this authority executable.

States name the modes the system can be in. Events name the messages it can receive. Transitions say which changes are legal. When the machine runs, its actor owns the current state and processes those events over time.

That gives us concrete questions during review:

Does this event exist in the protocol?
Is it allowed in the current state?
Which transition handles it?
Which actor owns the resulting lifecycle?

There is an important caveat: making a contract executable does not make it a good contract.

A machine can faithfully accept a MouseEvent that should have remained in the UI. It can expose a provider payload that should have been translated at the boundary. It can divide one policy decision across several guards, actions, and adapters.

Invoking external work from a state is not automatically the problem either. A machine may own when and why work begins while a supplied actor or adapter owns how one attempt is performed. The boundary becomes useful when those responsibilities are explicit and the result returns as a fact the application understands.

XState helps us see the contract. It cannot choose the contract for us.

It also does not mean every function needs a machine. A pure calculation or stateless transformation may already have a clear owner. Actors become useful when behavior changes over time and the state, work, results, and cleanup need to remain coherent.

How to recognize an ownership leak

The leak usually appears as friction around a change:

A test must recreate a UI, provider, or runtime just to express application intent.
The same decision appears in a component, handler, adapter, and state machine.
Changing an API response forces unrelated behavior and presentation changes.
Timing or message order changes the meaning of a result.
The system works, but changing it safely requires someone who remembers its history.

None of these observations proves the boundary is wrong. They are signals that responsibility may be distributed more widely than the behavior requires.

That is enough reason to pause and ask who actually owns the decision.

A responsibility check before implementation

Before I ask for more code, I now try to answer a few questions in plain language:

Who is trying to make progress, and in what context?
What observable result would tell us the behavior helped?
What intent enters the system?
Which part decides whether the request is valid now?
Which part is allowed to change state?
Which details belong only to the current UI, provider, or runtime?
Could another caller express the same intent without pretending to be that interface?

Then I check whether the code tells the same story.

In the Ignite example, the answer is visible in the command signature and the event it sends. The caller provides moduleId. The actor receives START_MODULE. The machine defines the legal transition, and the running actor owns its execution over time.

This does not mean every dependency needs an adapter or every decision needs another interface. A boundary is useful when it stops one part from making a decision that belongs somewhere else. If it does not protect a meaningful decision, the extra abstraction probably makes the system harder to understand.

The first draft is cheap

Faster implementation is a real advantage. I can explore an idea, discover where it breaks, and discard it without losing a day.

But the time saved by generation should create more room for judgment, not less.

AI did not change how systems work. It changed how quickly an unnamed assumption can become a dependency.

I do not think architecture matters more because AI writes worse code. It matters more because we can multiply ownership decisions faster than we notice them.

The first draft is becoming cheap. A coherent answer to who owns what is not.

Next in the series

The project gave me a concrete behavior for stress-testing the Ignite Element API. Passing moduleId directly made startModule easier to exercise from both a browser binding and a headless test. That gives us evidence that the command no longer depends on one view’s markup.

It does not prove that starting a module is the right feature for a client’s product, and that was not the question this project could answer. The immediate question was whether Ignite Element lets a developer express the same intent across supported environments without carrying one view’s markup into the command.

Before we model a command, actor, or port, we need to understand who is trying to make progress, what is getting in their way, and what evidence would show that the behavior helped.

That is where the next post, Product Framing Before Software Design: Deciding What to Build, begins.

The examples in this series come from dogfooding Ignite Element. You can read the v3 beta documentation or follow the implementation and examples on GitHub.

Read on 0xjcf.com

Jose Flores | Writing

Lifecycle Boundaries in Actor and State Machine Architecture

The effect solved direction, not ownership

Removing host made the next boundary visible

The source owns navigation over time

The environment can change without rebuilding the router

The current commit protocol has a limit

Why the actor owns this behavior

Next in the series

Functional Core Architecture: Where Deterministic Decisions Belong

The first bridge was an Ignite effect

The browser request was not the application decision

The nested router tested the same boundary again

What the functional core changed

Semantic Commands: Translating User Intent into Application Behavior

The interface sees a gesture

A command is a compression boundary

Carry the request to its authority

A request is not a fact

Translation can fail in two directions

The same boundary appears in navigation

Use the smallest useful vocabulary

A semantic-command check

Next in the series

Product Framing Before Software Design: Deciding What to Build

The refactor answered one question

Start with progress, not a command

A product frame makes assumptions visible

The frame can repeat at each layer

Correct behavior and helpful behavior need different evidence

Turn the frame into a narrative

The frame guides behavior but does not govern it

Keep it small enough to change

A product-frame check

Next in the series

AI-Generated Code and Software Architecture: Why Ownership Matters

The bottleneck moved

A small command with a hidden decision

The logic was correct. The boundary was not

Architecture distributes authority

Why state machines help, and where they stop

How to recognize an ownership leak

A responsibility check before implementation

The first draft is cheap

Next in the series

Removing `host` made the next boundary visible