The five main stages
Stage 1: Intent
The first stage is intent. An agent or client submits a structured request that says, in effect, "this is the action I want to take against this target."
That sounds simple, but it is an important improvement over free-form tool output. Free-form tool output often mixes explanation, assumptions, target details, and action instructions in one place. A structured intent forces the write path to start with named fields: which target, which scope, which actor context, which task, and what type of operation is being requested.
That matters for two reasons.
First, it gives the rest of the system something stable to evaluate. Policy and Core can work against a structured request more reliably than against a raw generated string.
Second, it keeps intent distinct from impact. The submitted request is not yet permission to write. It is a request to enter the decision path.
An intent can be well-formed and still not be admitted. That is a feature, not a bug. The whole point of the boundary is that the initial request is not already the external effect.
Stage 2: State check
The second stage is a system-side state check. Before the system decides whether the requested write should exist, it asks for the current target state.
This is one of the most important pieces of the design. Agents often reason over context that can change quickly. A repository branch may move. A ticket may be reassigned. A room may be locked. A cloud resource may no longer be in the state the agent assumed. If the system only relies on "the agent already looked at it," then the decision path depends on a claim that is hard to verify operationally.
The state check makes the system ask again at the moment that matters. In the v0.1.0 bundle, that state comes from an external StateProvider connector that returns a governed state view. The homepage version of that idea is simpler: before deciding whether a write should exist, the system checks what the target looks like now.
Why does that matter?
- It reduces the gap between reasoning time and action time.
- It gives policy a bounded state input instead of only agent narrative.
- It lets Core validate a decision path that is tied to actual state context.
This is not a claim that state checks solve every problem. The system still depends on the quality of the target-side integration. But state is part of the path, not an afterthought.
Stage 3: Policy evaluation
The third stage is policy evaluation. Policy looks at the request and the state context and returns a candidate decision.
Candidate is the key word here. Policy is not the final authority by itself. It does not directly create claimable work. It does not directly trigger materialization.
That separation is intentional. A policy system may be correct in spirit but still return an output that is malformed, incomplete, or inconsistent with the rest of the request. The runtime therefore treats policy as a structured input to the decision path, not as an immediate write authorization.
In practical terms, policy can say things like:
- this request is admitted;
- this request is blocked;
- this request conflicts with the current state and needs a re-check;
- this request needs approval before it can proceed.
But those meanings are still subject to validation by Core. This prevents the system from treating any policy response as if it were already external authority.
Stage 4: Core validation
The fourth stage is Core validation. This is the point where the system decides whether the decision path is structurally valid and whether admitted work may exist.
Core validates the state view, the policy output, the decision envelope, and the consistency rules that tie them together. It checks that the decision path makes sense as a contract, not just as a vague idea.
This is the gate that matters most in the architecture. Only an admitted Core decision can create work for an adapter.
That sentence is worth reading carefully. It does not mean that Core proves the request is wise, semantically correct, or morally safe. It means that Core is the contract authority inside the v0.1 path. It validates whether the request, state, policy candidate, and routing fields are consistent enough to become admitted work.
That distinction avoids overclaiming. Core is strong as a decision-path validator. It is not a truth oracle about the external system.
Stage 5: Adapter materialization and outcome
The fifth stage is where external effect can finally happen. An adapter worker claims admitted work before touching the external system. After it acts, it posts an outcome describing what actually happened.
Two parts matter here.
First, the adapter must claim work before materialization. That prevents the write path from acting on raw intent or raw policy output. The worker is only supposed to act on admitted, claimable work.
Second, outcome is distinct from the earlier decision. The decision says whether the path may proceed. The outcome says what happened after the worker tried to materialize the effect. Those are different pieces of information.
For example, an admitted path might still produce an outcome of no impact if the target had already changed in a way that made the action unnecessary. Or an admitted path might produce an error-bearing outcome if the worker failed to complete the target-side change safely.
That is why the architecture keeps outcome separate from decision and separate from intent.
A simple end-to-end example
Take a repository automation example. An agent wants to create a pull request that updates a configuration file.
- The agent submits intent: update repository X in scope Y with operation Z.
- The system checks the current repository state through the state boundary.
- Policy evaluates whether that kind of repository change is allowed in that context.
- Core validates the policy candidate and the surrounding decision path.
- If admitted, work becomes claimable for the repository adapter.
- The repository adapter claims the work.
- The adapter creates the branch or pull request in the target system.
- The adapter posts an outcome saying what happened.
The important part is not that pull requests are special. The same logic applies to ticketing systems, rooms, accounts, and cloud resources. The boundary pattern is reusable because the target-specific write logic stays with the adapter, while the decision path stays explicit.
What is intentionally separated
The design is easier to remember if you focus on the separations it enforces.
Intent is not decision
An intent is a request to enter the boundary. A decision is the result of evaluation and validation. If those become interchangeable, the system loses its main control point.
Policy candidate is not final admission
Policy can recommend a route, but the route only becomes meaningful once Core validates it. That keeps policy from silently becoming direct impact authority.
Admitted work is not materialized effect
Work becomes claimable after admission. The effect happens later, when an adapter claims and performs it. This protects the system from treating a positive decision as if the external write had already happened.
Outcome is not promise
Outcome reports what actually happened after materialization. It is not a promise made at the start of the flow. That separation helps the system distinguish between permission, execution, and result.
Why structured intent is better than free-form tool output
This is worth calling out directly because it often sounds like a small implementation detail. It is not.
Free-form tool output is hard to validate consistently. It tends to mix target details, justification, partial assumptions, and proposed actions. Structured intent narrows that into a request shape the system can evaluate. That makes downstream checks more reliable and makes the boundary easier to inspect.
The result is a flow where the system has concrete objects to reason over.
Why this matters
The value of the boundary is that it makes the path to impact deterministic enough to inspect. It does not pretend the model is perfect. It does not pretend the adapter is automatically safe. It does not pretend that every admitted action is semantically right.
What it does do is separate request, state, policy, admission, materialization, and outcome. That separation gives technical teams a clearer place to reason about control, failure, and responsibility.
Summary
Impact Boundary works by turning a direct write path into a staged flow. Intent enters first. State is checked before decision. Policy returns a candidate. Core validates the decision path. Only admitted work becomes claimable. The adapter materializes the effect and reports an outcome afterward. That sequence does not prove correctness, but it does create a clearer and more inspectable path from intent to external impact.