Effect contracts

The inline decision point answers whether an agent may attempt an action. It does not answer whether the action happened, whether it happened once, or whether it stayed inside the bounds the person who approved it had in mind. Those are different questions and the gap between them is where the money is: a refund API can acknowledge a request before the ledger write is durable, a deployment can report accepted and roll back thirty seconds later, and a ticket transition can succeed against a stale cache. Treating the response as completion proves the transport worked and nothing else.

The dangerous case is not failure, it is ambiguity. A timeout hides two outcomes that need opposite responses — nothing happened, or everything happened and the acknowledgement was lost — and the agent framework’s default behaviour is to retry. Retrying a read is free. Retrying a payment is a second payment. Every gateway that offers a retry policy for tool calls is, on a consequential tool, offering to duplicate the consequence, and the agent making that decision is the component most susceptible to a paragraph of retrieved text telling it to try again.

The obvious fix is not available. A remote action system cannot join Token Observe’s database transaction; MCP tools expose no common transaction protocol and most systems of record could not enlist in one if they did. Anything that promises exactly-once across that boundary is promising something it does not control. What can be built is a durable local claim taken before egress, a second tool that reads the world afterwards and a state machine in which unknown is a state you can see rather than an error somebody swallowed.

The second temptation is to make the verification step programmable — a small expression language, a template, a hook. That is flexible and it converts your governance configuration into code execution: an unbounded runtime and a second plugin platform, sitting inside the boundary that exists to bound things. The contract language here is deliberately small enough to read in one sitting and to refuse anything it does not recognise.

A contract is one immutable, integer-versioned document. It binds two mandatory roles and an optional pair: a descriptor-pinned action, a different descriptor-pinned verifier whose observation supplies the postconditions, invariants and terminal-failure conditions, and — together or not at all — a compensation action and a distinct compensation verifier. Values move between stages only by RFC 6901 JSON Pointer copies, and conditions are expressed with exactly six operators: exists, equals, not_equals, greater_than, less_than and contains. There is no expression language, no template interpolation and no way to run code, because the alternative considered and rejected was a second sandbox platform inside the governance boundary.

Pointer resolution is deliberately unforgiving, and each refusal has a reason. Only own data properties are read, so a getter cannot execute and an inherited property cannot be selected; segments spelling __proto__, prototype or constructor are refused outright; array indexes must be canonical decimal, so 0 resolves and 00 does not; and only the two escapes the standard defines are accepted, because permitting a malformed one would let two spellings select the same value and a broken contract survive review. Predicates do not coerce types either — comparing the string "3" against the number 3 is a type mismatch and fails closed rather than matching.

The bounds are stated in the code rather than left to operational luck: at most 64 predicates in each set and 64 argument mappings in each binding, pointers at most 512 characters and 32 segments, copied values at most 32 deep and 10,000 nodes, and a verification freshness window between one second and seven days. A contract that exceeds any of them is invalid at creation, not slow at runtime.

The single most consequential rule in the language is what verification is forbidden to read. No stage may consume the action’s response. Argument bindings accept the original arguments, and the compensation action alone may additionally read the verifier’s result; on the predicate side, preconditions read the original arguments and every set evaluated after dispatch — postconditions, invariants, failure conditions, compensation postconditions — reads the verifier’s result and nothing else. The reason is the failure this whole capability exists for — the action response is exactly what a timeout loses. Anything verification or compensation needs must therefore be independently observed or bound into the action arguments Token Observe already digested, and validation refuses a verifier or compensation mapping that reads an original value the action does not carry. That is what makes a governed retry’s recovery context comparable without ever storing the raw customer payload.

Editing a contract’s semantics creates version N+1; it never rewrites version N. Revisions for the same action tool must preserve the immutable effect name and advance by exactly one, and the digest that identifies a revision hashes the whole document with mapping and predicate arrays canonically sorted, because their ordering carries no meaning. Lifecycle status is deliberately excluded from that digest, so retiring a revision blocks new dispatch without destroying the digest historical runs and approvals name.

After the action returns, Token Observe calls the pinned verifier with arguments mapped from the original request and requires its result to carry a canonical timestamp at the contract’s own observation pointer. Evidence that is not a fresh post-dispatch observation is rejected: not earlier than the moment verification began, less a fixed five-second clock-skew tolerance; not more than that tolerance into the future; and not older than the contract’s freshness bound. Cached pre-action state therefore cannot commit a new run, which is the failure a naive read-after-write check walks straight into.

Success requires every postcondition and every invariant to match. A mismatching or pending observation is explicitly not terminal failure — an eventually-consistent system that has not caught up yet is a normal condition, not a rollback trigger — so the verifier is polled again inside a cap of eight bounded attempts, with exponential backoff from one second capped at thirty, and exhaustion parks the run for manual review rather than replaying a mutating stage. Only verifiers are ever polled. The action is never re-dispatched by recovery, and neither is a compensation.

The agent does not receive the action’s response until the effect is proved. If verification does not pass, the tool result is withheld and the caller is refused with an instruction not to retry; if the result came back uninspectable and verification nonetheless proved the effect, the caller is told the run committed and that its output remains withheld. This is the part most integrations get wrong in the other direction: a model handed a success body has already concluded the work is done and moved on, and no amount of downstream reconciliation retrieves that decision.

Ambiguity has exactly one answer, and it is to look. A transport timeout leaves the remote outcome unknown, so the run goes from executing straight to verifying — re-dispatching blindly and assuming failure are both unsafe, and the state graph does not offer either. A retry may legitimately finish the last hop from verified to committed after a lost local acknowledgement, because the expensive, irreversible part already happened and was already proved. Terminal duplicates never re-dispatch the action.

The honest reading of the word verifier is narrower than the marketing version. It means a contract-bound read-after-write check performed by a different pinned tool. A separate tool name is separation of contract role; it does not by itself establish an independent trust authority, and nothing here proves that a different organisation or an attested system controlled the observation. A deployment that needs that claim has to put the verifier behind a separately controlled or attested evidence source, and doing that properly is named as follow-on work rather than quietly implied.

Every terminal run appends a hash-chained audit entry before its final transition, carrying the contract id and digest, the trace id, the tool, the run state and version, the approval payload hash and the digests of the action arguments, action result, verifier result and both compensation results. Digests, not payloads. Where an anchor signing key is configured, Token Observe then issues at most one canonical, Ed25519-signed receipt per run, and only for a committed or compensated outcome.

The receipt binds the installation and receipt identifiers, the run id, the authority that acted — subject, team, trace and the payload hash of the approval, with its id where there was one — the contract id, digest, effect name and tool, the payload digests, the outcome state with its run version and predicate-evidence digests, and the audit entry’s sequence number and hash. Verifying it needs nothing from Token Observe: a caller supplies the bundle and a public key they already trust, and verification recomputes the statement digest, checks the signature, requires the statement to be exactly the canonical JSON that was signed, and then checks internal coherence — a committed receipt carrying compensation digests, or a compensated one missing its compensation predicate evidence, is rejected as inconsistent. There is no database read, no configuration and no network call, and a receipt is never permitted to nominate its own trust root.

With no signing key there is no receipt, and the run API reports that absence rather than promoting an HMAC or an ephemeral key to a trust root. The limit inside the receipt is equally explicit. Its anchor block is a signed reference, not an offline inclusion proof: it names the anchor sequence, the chain head sequence, the head hash and the key id, and the version-one bundle deliberately does not carry the separate signed anchor bytes or the intervening chain entries. An auditor who needs to prove coverage must obtain and verify that anchor and chain evidence independently. Provisioning, rotation, historical-key retention and independent custody of the receipt key are deployment duties, and they remain unproved.

An activated contract is also a piece of configuration, and it travels as one. Effect contracts are exported as their own resource kind in the per-resource SHA-256-locked configuration bundle, alongside agents, seats, roles, policies, providers, routes, servers, tool pins and webhooks. Importing a bundle means planning, never applying by surprise: the plan compares the declared bundle against deployed state and, where a CycloneDX 1.6 observed inventory is supplied, deployed state against what was observed, classifying each resource as in sync, missing, modified, unmanaged or unverified. A matching identity with no configuration digest is reported as unverified rather than as equality, on purpose.

Promotion between environments is a digest-locked copy that emits a new artifact and an audit record, and refuses outright if the source bundle changed after the review it was based on. What this proves is stored effective-configuration equality — that the contract revision named in one environment is byte-identical to the one named in another. It does not prove that a workload binary or a cloud runtime loaded it, and observation stays bounded by the inventories and governed paths you actually supply.