--- title: "Capability: Effect contracts" canonical_url: "https://tokenobserve.com/platform/effect-contracts" published: 2026-09-02 last_updated: 2026-10-21 --- # Capability: Effect contracts The action leaves once, and success is what a second pinned tool observed. ## What it is Effect contracts govern the actions that change something outside the gateway: a payment, a ticket transition, a deployment, a database write. A contract pins one action tool and a different verifier tool to their exact descriptor digests, and a successful action response never completes the run on its own: the verifier is called afterwards, its observation must be fresh and post-dispatch, and every postcondition must match before the effect is recorded as committed. A durable claim on the business idempotency value is taken before a byte leaves, so a lost response is reconciled by a read rather than a replay. ## Facts - Contract: Pinned action, pinned verifier, optional compensation pair - Language: JSON Pointers and six operators; no code, no templates - Claim: One durable row per effect name and idempotency digest - Receipt: Ed25519, verified from its bytes and a key you supply ## The limit Not exactly-once: The downstream must enforce the idempotency key you send ## Why it exists: A tool that returned 200 has not proved that anything happened. 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. 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 needing opposite responses — nothing happened, or everything happened and the acknowledgement was lost — and an agent framework’s default is to retry. Retrying a read is free. Retrying a payment is a second payment. ## How it works - A contract is drafted against exact descriptor digests: The draft names an action tool and a different verifier tool by server, tool name and the exact SHA-256 of the approved descriptor, plus, where compensation exists, a distinct compensation verifier. Activation refuses unless every binding is present, pinned and matching. - Preconditions run, the claim is taken, the action leaves once: Policy, data controls and the payload-bound approval inspect the exact payload the contract will send. The claim on the business key is taken last, after redaction and before the first byte leaves, in the transaction that writes the run and outbox rows. A second delivery of the same key is refused as a non-retryable conflict, and a transport timeout moves the run to verifying and never back to dispatch. - The verifier is called, and the predicates decide: The verifier is invoked with arguments mapped from the original request, and its result must carry an observation timestamp that is post-dispatch and no older than the freshness bound. Every postcondition and invariant must match. A pending answer is polled again inside a bounded cap; exhaustion parks the run for manual review rather than replaying a mutating stage. ## Where it runs in the request path Step 9 of the request path, and the durable recovery after it ## What it does not do - No distributed exactly-once. Token Observe claims at most one dispatch from its own side; whether the action happened exactly once also depends on the downstream honouring the key it is sent, and that half is outside the boundary. - A different pinned verifier is not an independent authority; it is separation of contract role. Nothing proves a different organisation or an attested system controlled the observation, and putting verifier evidence behind separately controlled infrastructure remains follow-on work. - Nothing is reversible unless you built the reverse. An external effect is reversible only where its contract carries a tested compensation and compensation verifier; without that pair a failed effect is a manual review and a forward fix. - Receipt-key custody is unproved, and with no signing key configured there is no receipt at all; the run API reports that absence rather than promoting an HMAC to a trust root. Verification accepts a public key the caller already trusts; provisioning, rotation, retention and independent custody of that key are deployment duties this product does not evidence. The anchor block inside a receipt is a signed reference, not an offline inclusion proof. - Multi-replica concurrency is not qualified. Locked migrations, fenced stage leases and a leader-elected recovery worker exist and carry test coverage, but the known-issues register is explicit that this is not retained evidence of real replicas racing, losing leadership and recovering against a live downstream system. That evidence remains a release gate. ## Read next - https://tokenobserve.com/platform/mcp-gateway - https://tokenobserve.com/platform/human-approvals - https://tokenobserve.com/platform/audit-chain ## Questions and answers Q: How is this different from retrying with an idempotency key? A: An idempotency key asks the downstream system to deduplicate. An effect contract deduplicates before the request is sent, then checks what happened: a unique durable claim on the business key is taken before the first byte leaves, and a different pinned tool then observes the result. The key still has to be honoured downstream; the difference is that a lost response leads to a read rather than a retry. Q: What happens when the action times out? A: The run moves from executing to verifying and the verifier is called. Nothing is re-dispatched, because a timeout hides two opposite outcomes and both blind retry and assumed failure are unsafe, so the state graph offers neither move. If the verifier proves the effect, the run commits and the caller is told the response was lost but the effect stands. Otherwise it enters manual review with the ambiguity visible. Q: What stops someone writing a verifier that always says yes? A: Nothing in the product. A verifier is a contract-bound read-after-write check by a different pinned tool: separation of role, not an independent trust authority. What is enforced is narrower and still useful: a distinct tool pinned to an exact descriptor digest, unable to read the action’s response, and required to observe freshly and post-dispatch. The long-form detail on this capability (the anchored sections, the worked policies and the error envelopes) is on the page itself at https://tokenobserve.com/platform/effect-contracts.