Impact Boundary Labs
GitHub
Documentation navigation

Core docs

How it works

Impact Boundary turns a direct write path into a staged one. The goal is not to hide the model or the adapter. It is to separate the parts that are too often merged: what the agent wants to do, what the system decides is admissible, what work becomes claimable, and what actually happens in the target.

This page follows that flow conceptually. It stays lighter than the repo-level protocol docs, but it matches the real structure of the v0.1.0 bundle.

The five stages

Stage 1: Intent

An agent or client submits a structured request: "this is the action I want to take against this target." Unlike free-form tool output, which mixes explanation, assumptions, target details, and instructions into one string, an intent starts the write path with named fields: which target, which scope, which actor context, which task, and which operation.

That gives the rest of the system something stable to evaluate, and it keeps intent distinct from impact. A 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 the point of the boundary, not a defect.

Stage 2: State check

Before deciding whether the write should exist, the system asks for the current target state. This is one of the most important pieces of the design, because agents reason over context that changes quickly: a branch moves, a ticket is reassigned, a room is locked, a cloud resource is no longer what the agent assumed.

If the system only trusts "the agent already looked at it," the decision rests on an unverifiable claim. In the v0.1.0 bundle the state comes from an external StateProvider connector that returns a governed state view, so state is part of the decision path, not an afterthought. That narrows the gap between reasoning time and action time, and it gives both policy and Core a bounded state input instead of only agent narrative.

Stage 3: Policy evaluation

Policy reads the request and the state context and returns a candidate decision. Candidate is the load-bearing word: policy is not the final authority, and it does not directly create claimable work or trigger materialization.

Policy can say a request is admitted, blocked, in conflict with current state, or in need of approval. But each of those is still a structured input to the decision path, subject to validation by Core. A policy system can be right in spirit and still return an output that is malformed or inconsistent with the request; treating policy as candidate data keeps the system from mistaking any policy response for external authority.

Stage 4: Core validation

Core is the gate that decides whether admitted work may exist. It validates the state view, the policy output, the decision envelope, and the consistency rules that tie them together. It checks that the decision path holds up as a contract, not just as a plausible idea.

Only an admitted Core decision can create work for an adapter. A request whose likely impact is too large is not admitted automatically; it is held as needs-approval for a human before it can proceed. Admission does not mean Core proves the request is wise or semantically correct. Core is the contract authority inside the v0.1 path, not a truth oracle about the external system. Stating it that narrowly is deliberate: it is strong where it can be, and silent where it cannot.

Stage 5: Materialization and outcome

External effect can finally happen here. An adapter worker claims admitted work before touching the target, so the write path never acts on raw intent or raw policy output. After acting, the worker posts an outcome describing what actually happened.

Outcome is deliberately separate from decision. The decision says the path may proceed; the outcome says what resulted. An admitted path can still report no impact, because the target had already changed, or an error, because the worker could not complete the change safely. Permission, execution, and result stay three different facts.

End to end: a repository write

An agent wants a pull request that updates a configuration file.

  • The agent submits intent: update repository X in scope Y with operation Z.
  • The system checks current repository state through the state boundary.
  • Policy evaluates whether that 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 adapter claims the work and creates the branch or pull request.
  • The adapter posts an outcome saying what happened.

Pull requests are not special. The same path applies to tickets, rooms, accounts, and cloud resources: the target-specific write logic stays in the adapter, while the decision path stays explicit. That is what makes the boundary reusable, and what makes the route from intent to impact deterministic enough to inspect. It does not prove the model is right. It makes control, failure, and responsibility something a team can actually reason about.

Why this is secure

Security here does not come from trusting the agent or the adapter. It comes from separation.

Three sides, kept apart

The agent submits through the ingress door. Adapter workers claim admitted work through a separate adapter door. Each door has its own local credential, and the two are never interchangeable: an ingress credential cannot claim work or post an outcome, and an adapter credential cannot submit an intent or read ingress state. The Core sits between them and is never called directly.

The agent never sees the Core; the worker never sees the agent side

The agent talks to the Host and gets a decision back. It never reaches the decision path. The adapter worker receives only an admitted work order with validated operation metadata, never the agent's raw request and never the ingress state. Neither side can reach across the boundary.

The adapter is deliberately thin

It reads governed state, materializes admitted work orders, and reports outcomes. It does not admit impact, evaluate policy, create work orders, or act on raw intent. A dumb adapter is the point: the decision authority stays in one place.

Every hop is bound by a hash

The decision, the state view it was checked against, and the work order each carry a hash. Before an outcome is accepted, those hashes must match the admitted work order and its decision, so a stale or altered handoff is rejected rather than executed. These are bindings, not signatures; work order signing is future work.

The path is recorded

The local preview keeps a step-by-step trace: intent, decision, work order, claim, outcome. It is a local record for inspection, not durable audit or persistent lineage yet.