# Action contracts An **action contract** (`kind: action`) verifies, after the fact, that an action an AI agent took was valid, within its limits, and produced the intended effects in the customer's systems of record. Each recorded action receives a **PASS / FAIL / UNKNOWN** verdict under two lenses, with evidence pointers and a hash-chained verdict, using the same engine that verifies billed outcomes (see [METHODOLOGY.md](/methodology)). The engine only reads. It does not sit in the agent's write path, does not block or execute anything, and cannot change a system of record. It compares what the agent said it did with what the systems of record show happened. ## Vocabulary | Term | Meaning | Stored as | |---|---|---| | **Action** | One request by an agent to change a record: "refund order 10231 for 180 USD at 10:42". Carries `params` (the agent's own arguments), a `subject_id` (the record acted on) and `requested_at`. | a `claims` row under the action contract (`raw_ref = agent_api:action:`) | | **Fact** | One event observed in a system of record about a subject: `stripe.refund_created` at 10:42:07 with `amount = 180`. | a `facts` row | | **Effect** | A fact for the action's subject (or a linked subject) observed at or after `requested_at`, within the contract's window. | — | | **State (precondition)** | The latest fact of a given type recorded at or before `requested_at`, within a lookback. | — | | **Outcome lens** | Did every expected effect happen? | the engine's `vendor` lens | | **Policy lens** | …and were the preconditions, limits and prohibitions respected? | the engine's `strict` lens | Verdict labels are display names over the engine's fixed vocabulary: `VERIFIED → PASS`, `NOT_VERIFIED → FAIL`, `UNVERIFIABLE → UNKNOWN`. API responses carry both (`verdict` and `raw_verdict`); the public hash-verification endpoint reports the raw value. ## YAML reference An action contract is a YAML document with the usual contract envelope plus an `action:` block. `lenses:` must be absent (the two lenses are derived, see below); `exclusions:` and `billing:` are allowed as in outcome contracts. ```yaml id: refund_workflow # lowercase snake_case, 3-64 chars version: 1 # >= 1; edits are new versions kind: action # required for action contracts vendor: internal # who runs the agent (used as the claim's vendor when no agent_id is sent) vendor_display: "Refund workflow (internal agent)" action_type: refund_order # default action_type for recorded actions; also the default outcome_type outcome_type: refund_processed # optional; defaults to action_type, then "action" claim_source: agent.actions # optional; defaults to agent.actions subject_kind: order # optional; defaults to record description: > Plain-language statement of the policy (shown on the public definitions page). source_citation: # required: where the policy comes from url: "internal://policies/refunds" retrieved: "2026-09-28" title: "Internal refund policy (template)" notes: "..." unknown_fields: [] action: window: "15m" preconditions: [...] limits: [...] expected_effects: [...] forbidden_effects: [...] unverifiable_if: ... billing: unit_price: 0 currency: USD ``` ### The `action:` block | Key | Required | Meaning | |---|---|---| | `window` | no (default `1h`) | Settlement window, measured from `requested_at`. Effects are only counted inside it, and the verdict stays `pending` until it closes (unless the outcome lens already passes). Durations are `m`, `h`, `d`, `w`. | | `preconditions` | no | List of state checks that must hold at the moment of the action. Each is `state_before_action: {...}` (positive spelling, recommended) or `precondition_unmet: {...}`; both compile to the violation primitive `precondition_unmet`. Policy lens only. | | `limits` | no | List of bounds on the action's own `params`. Entries are `param_max: {...}` (alias of `param_exceeds`) or `param_in: {...}` (alias of `param_not_in`); the primitive names are accepted too. Policy lens only. | | `expected_effects` | **yes, at least one** | List of `effect_observed: {...}`. All of them must be observed for PASS. Both lenses. An effect may carry `min_trust: self_reported \| shared \| independent`: a fact from a source rated below that does not satisfy it (reported as observed but not ok, reason `effect_below_trust:.`). Trust is the connection's level or the operator's per-source override on the facts-API connection, read at verification time. Default: no gate. | | `forbidden_effects` | no | List of `effect_count_exceeds`, `effect_attr_exceeds`, `effect_attr_differs` or `effect_observed`. Any observed → FAIL. Policy lens only. | | `aggregate_limits` | no | List of `aggregate_exceeds` (alias `aggregate_max`): a total of an effect attribute, or a count of effects, across the actions in scope (this agent's, this subject's, or every action under the contract) over a lookback. Policy lens only. | | `reversed_by` | no | List of `reversal_observed` (`effect_observed` is accepted as the spelling): a later record that undoes the action, looked for within its own `within` (default `30d`). Any observed → FAIL under **both** lenses; one pushed after the verdict settled re-verifies the action. | | `unverifiable_if` | no | A condition tree (`any` / `all` / `not` over primitives, same syntax as outcome contracts). When it holds the verdict is UNKNOWN under both lenses. Typically `missing_fact_source: [stripe, shopify]`. A source counts as present when a healthy or syncing connection provides it; a connection in error does not, and a caller that knows a source could not be read for one verification (the sandbox's extractor) can name it as unavailable for that verification. | Every list entry is a single-key mapping `{primitive: argument}`. Any other primitive in these lists is rejected at validation time (`'csat_negative' is not allowed here`). ### Primitives Identifiers (`type`, `source`, `attr`, `param`, keys of `where`) must match `[a-z][a-z0-9_.:-]{0,63}` (input is lowercased). Values embedded in comparisons (`where` values, `values`) must match `[A-Za-z0-9_.:@/ -]{1,120}`; anything else is rejected at validation. String comparisons are case-insensitive; numeric comparisons read the attribute as a number. #### `effect_observed` — expected effect ```yaml - effect_observed: type: refund_created # fact_type to look for (required) source: stripe # fact source (optional but recommended; also drives coverage/UNKNOWN) within: "15m" # optional; filled from action.window when omitted where: {status: succeeded} # optional; every attribute must equal the value message: "Payment refund was not created" # optional, <= 200 chars; used as the FAIL headline ``` A bare string (`- effect_observed: refund_created`) is shorthand for `{type: refund_created}`. True when at least one fact with that `type` (and `source`, and `where` attributes) exists for the action's subject or a linked subject with `requested_at <= occurred_at <= requested_at + within`. Evidence is the earliest matching fact. Reason codes: `effect_observed:.` when seen, `expected_effect_missing:.` when not. #### `effect_count_exceeds` — forbidden: too many matching effects ```yaml - effect_count_exceeds: {source: stripe, type: refund_created, max: 1} ``` Same effect arguments as `effect_observed` plus `max` (non-negative integer, default `1`). True when **more than** `max` matching effects exist in the window. Evidence is the `(max+1)`-th matching fact (for a duplicate refund, the second refund). Reason code `duplicate_effect:.`. #### `effect_attr_exceeds` — forbidden: an effect carries a value above a ceiling ```yaml - effect_attr_exceeds: {source: stripe, type: refund_created, attr: amount, max: 250} ``` Same effect arguments plus `attr` and `max` (number, required). True when any matching effect in the window has `attributes[attr] > max`. Evidence is the earliest such fact. Reason code `forbidden_effect_observed:.`. #### `effect_observed` in `forbidden_effects` Allowed: the effect must **not** be seen. Its reason code is the positive `effect_observed:.` (there is no dedicated "forbidden" code for this spelling); the check table and headline still report it as a forbidden effect. #### `effect_attr_differs` — forbidden: an effect carries a value that differs from its reference ```yaml - effect_attr_differs: {source: payments, type: payout_created, attr: amount, equals_param: amount} - effect_attr_differs: source: ledger type: account_balance attr: balance equals_state: {source: ledger, type: account_balance, attr: balance, lookback: "30d"} minus_param: amount # or plus_param; optional tolerance: 0.005 # optional, default 0 (absolute) message: "Ledger balance after the payout is not the balance before minus the amount" ``` Same effect arguments plus `attr` and exactly one reference: `equals_param` (one of the action's own `params`) or `equals_state` (the `attr` of the **latest** state fact of that `type`/`source` at or before `requested_at`, as `state_before_action` finds it), optionally `plus_param` or `minus_param`. True when any matching effect in the window has `attributes[attr]` set and `|attributes[attr] - reference| > tolerance`. **No reference, no violation**: a missing parameter or a missing state record makes the comparison NULL, so require the state with a precondition when it must exist. Evidence is the earliest mismatching fact plus the reference value; the check's `value` is `{expected, observed}`. Reason code `effect_attr_mismatch:..`. #### `aggregate_exceeds` (alias `aggregate_max`) — a total across many actions ```yaml aggregate_limits: - aggregate_exceeds: source: payments type: payout_created attr: amount # omit to count matching effects instead of summing an attribute max: 5000 over: "24h" # lookback, required by: agent # agent (default) | subject | contract message: "This agent's payouts over 24 hours exceed the daily total" ``` Every other check judges one action; this one judges the effects of the **actions in scope**: those under the same contract whose `requested_at` lies between `over` before this action and the close of this action's window, filtered to the same `agent_id` (`by: agent`), to this action's own subject and its links (`by: subject`), or to none (`by: contract`). The matching effects on those actions' subjects (own and linked) are summed over `attr`, or counted, within `(requested_at + within - over, requested_at + within]`, so the aggregate includes this action's own effects. True when the total is above `max`. Evidence is the latest contributing fact plus the total; the check's `value` is the total. Reason code `aggregate_exceeded:.[.]`. An action is judged on its own lookback, so an earlier action that passed stays PASS when a later one pushes the total over. #### `reversal_observed` — a later record undoes the action ```yaml reversed_by: - effect_observed: {source: payments, type: payout_returned, within: "30d", message: "The payout was returned"} ``` Same arguments as `effect_observed`; `within` defaults to `30d` rather than the action window. True when a matching fact exists for the subject (or a linked subject) with `requested_at <= occurred_at <= requested_at + within`. It fails the **outcome** lens as well as the policy lens, because the intended effect did not hold. Reason code `reversed:.`. When a fact of a type named in any `reversed_by` is pushed (`POST /v1/facts`, or inline in `/v1/actions/verify`), every action it undoes is re-verified by a `verify_action` job (idempotency key `verify_action::fact:`); the new run stores new verdicts, the latest verification becomes FAIL and `action.verified` is emitted again. #### `state_before_action` / `precondition_unmet` — precondition ```yaml - state_before_action: source: shopify type: order_status where: {status: eligible} # required, non-empty lookback: "30d" # optional, default 30d message: "Order was not eligible for a refund at the time of the action" ``` Looks up the **latest** fact of that `type` (and `source`) for the subject with `requested_at - lookback <= occurred_at <= requested_at`, and requires every `where` pair to match it. The precondition is **unmet** when that fact does not match **or when no such fact exists**. Evidence is the fact that was inspected. Reason code `precondition_unmet:.`. #### `param_exceeds` (alias `param_max`) — limit on the action's own parameter ```yaml - param_max: {param: amount, max: 250} ``` True when `params[param] > max`. A missing or non-numeric parameter is treated as `0`, so it never exceeds the limit. Reason code `limit_exceeded:`; evidence is the claim record with the parameter's value. #### `param_not_in` (alias `param_in`) — allowed values for a parameter ```yaml - param_in: {param: reason, values: [customer_cancelled, damaged, not_delivered]} ``` True (violation) when `lower(params[param])` is not one of `values`. A missing parameter is not a violation (limits apply to parameters the agent actually sent, as with `param_max`). Reason code `param_not_allowed:`. ### Window and time semantics - `requested_at` is the reference point for everything. It is the `requested_at` sent when the action was recorded (default: the time of recording). - Effects: `occurred_at >= requested_at` and `occurred_at <= requested_at + within`. The window is inclusive at both ends. - Preconditions: `occurred_at <= requested_at` (a state fact stamped exactly at `requested_at` counts as "before"). - Facts are matched for the action's `subject_id` and for every subject linked to it through `subject_links`, in either direction. Links come from connectors or from the `links` list pushed with facts (`POST /v1/facts`): a support ticket and the order it is about are one case, so a notification sent on the ticket satisfies `customer_notified` for the order, and the orphan-effect report never lists a linked subject. - `within` is copied into every effect argument that does not set its own, so the window becomes part of each primitive's call key and therefore of the verdict hash (see determinism below). ## How the two lenses are derived Action contracts do not declare `lenses:`. The schema compiles the `action:` block into the engine's two lenses: | Engine lens | Displayed as | `verified_if` | `not_verified_if` | `unverifiable_if` | |---|---|---|---|---| | `vendor` | **outcome** | `all` of `expected_effects` | `any` of `reversed_by` (none when the block is empty) | `action.unverifiable_if` | | `strict` | **policy** | `all` of `expected_effects` | `any` of `preconditions + limits + aggregate_limits + forbidden_effects + reversed_by` | `action.unverifiable_if` | Contract-level `exclusions` apply to both lenses, as in outcome contracts. Overrides are always empty, so transcript-assist labels can never affect an action verdict. | Verdict | Outcome lens | Policy lens | |---|---|---| | **PASS** | every expected effect was observed in the window | …and no precondition, limit or forbidden effect fired | | **FAIL** | at least one expected effect was not observed (or the action is excluded) | a precondition was unmet, a limit exceeded, a forbidden effect observed, or an expected effect missing | | **UNKNOWN** | the subject has no record in any fact source, a required source has never reported, or nothing relevant was observed | same | Because the policy lens tests violations *before* expected effects, an action whose refund went through but exceeded the limit is **PASS on outcome and FAIL on policy**. The summary counts (`GET /v1/actions/summary`) use the policy verdict. ## Evaluation order For each lens, tests run in this fixed order; the first that applies decides. | Step | Test | Verdict | Reason codes | |---|---|---|---| | 1 | a contract `exclusion` matches | FAIL | `excluded_by_contract`, plus the primitive | | 2 | no fact exists for the subject or any linked subject | UNKNOWN | `identity_unmatched` | | 3 | `unverifiable_if` holds (e.g. a named source has never reported) | UNKNOWN | the matched primitive(s), e.g. `missing_fact_source` | | 4 | *policy lens:* any precondition / limit / aggregate / forbidden effect / reversal fires; *outcome lens:* any reversal fires | FAIL | every violation that fired, in contract order: `precondition_unmet:…`, `limit_exceeded:…`, `aggregate_exceeded:…`, `duplicate_effect:…`, `forbidden_effect_observed:…`, `effect_attr_mismatch:…`, `param_not_allowed:…`, `reversed:…` | | 5 | every expected effect was observed | PASS | `effect_observed:…` for each | | 6 | the subject has facts, but none of the expected effect types were ever observed | UNKNOWN | `no_structured_signal` | | 7 | otherwise | FAIL | `verified_condition_not_met`, then `expected_effect_missing:…` for each missing effect | Each verdict is computed in SQL and re-derived in Python from the same columns; a disagreement raises and nothing is written. ## Settlement window and `pending` `settles_at = requested_at + window`. After a verification: - `status` is **`pending`** while the verdict is provisional: the outcome lens is not PASS **and** either the window is still open (`now < settles_at`) or the window has closed but a source the contract reads has not yet reported past it (below). - Otherwise `status` is **`settled`**: all expected effects already appeared (an early PASS settles at once and schedules no re-check), or the window has closed and every source has caught up, or the bounded wait ran out. Any action can still be re-verified manually at any time (`POST /v1/actions/verify`), which stores a new run. ### Settlement waits for evidence, not for the clock A window that closes on the wall clock while a connector is still syncing turns lag into a false FAIL. So a verdict that is not yet a PASS settles only when every source named in the action block (`preconditions`, `aggregate_limits`, `expected_effects`, `forbidden_effects`, `reversed_by`) has a **watermark at or past `settles_at`**: - a synced connection's watermark is the one it reports after each sync; - a source pushed through `POST /v1/facts` has the watermark the pusher last declared for it in `watermarks` (`{"crm": "2026-10-13T10:45:00Z"}`: everything up to then has been sent), and none until it does; - a source with no watermark is taken as current. While a source is behind, the view and the list carry `settlement.waiting_on: [{ source, watermark, behind_seconds }]`, the headline reads `PENDING — of expected effects observed; window closed , waiting for crm (2h 10m behind) to catch up`, and the queued re-check carries `waiting_on` so a successful sync of that source (or a push that advances its watermark) brings the re-check forward instead of waiting for the next tick (`SETTLEMENT_RECHECK_INTERVAL`, default 15m). The wait is bounded by `SETTLEMENT_MAX_LAG` after `settles_at` (default 48h): past it the verdict settles on what is known, `settlement.stale_sources` names the sources still behind, and the FAIL headline ends with `(crm (3d behind) at settlement)`. A pending verification is persisted like any other (a `Run` with `triggered_by = action` and two chained verdicts) and marked provisional in the run stats. The engine enqueues a `verify_action` job at `settlement.next_check_at` (idempotency key `verify_action::`). That job re-runs the same evaluation, stores a new run and verdicts, and emits `action.verified` once the verdict settles. The first provisional verdict emits `action.pending` once; re-checks that stay pending are quiet. The most recently computed verdict is what `GET /v1/actions` and the summary report. Every verification also reports `sources` (trust level and watermark per source the contract read), `reversal` (the later record that undid the action, when one did), `previous` (the verdict pair this run replaced) and `changed`. While pending with the window open, the headline is `PENDING — of expected effects observed so far; window closes ` when the first failing check is an expected effect. If a precondition, limit or forbidden effect has already fired, the headline is the `FAIL — …` line for that check even though `status` is still `pending`. ### The completion gate: do not say "done" before it settled A workflow that tells the customer "your order is cancelled and refunded" is making a claim. The gate is the customer's own workflow reading the verdict before it makes that claim: the action runs through the native controls and the durable runtime as before, CommitLayer observes the systems of record, and the step that reports completion waits for the settled verdict. `GET /v1/actions/{ref}/wait?timeout=` holds the request until the verdict settles or the timeout passes (at most 60 seconds per call; the SDKs loop: `cl.wait_for_settlement(ref, timeout=300)`, `await cl.waitForSettlement(ref, {timeoutMs: 300_000})`). It returns the verification plus `timed_out` and `waited_seconds`. On every poll it evaluates the evidence that has arrived; the moment the evaluation settles (an early PASS when the last expected effect lands, or the window closed with every source caught up) it stores that verification once, like a scheduled re-check would, and returns it. It never moves a verdict: facts decide. What the workflow does with the answer is the workflow's policy, and should be written down: | Result | Meaning | Typical handling | |---|---|---| | `status: settled`, outcome `PASS` | The intended outcome landed across every system and nothing forbidden was observed | Tell the customer; close the case | | `status: settled`, outcome `FAIL` | An expected effect is missing, or a forbidden effect, limit, precondition or reversal fired | Route to recovery: a compensating action (`compensates: `), a human, an incident channel | | `timed_out: true`, `status: pending` | Still inside the window, or a source is behind its watermark | The workflow's decision: wait longer, tell the customer it is in progress, or escalate. Never report success. | The gate adds no latency to the action itself and is never a single point of failure for it: the refund is already issued when the gate is consulted, and a workflow that cannot reach CommitLayer falls back to its own policy. The Temporal and Inngest integrations ship this as a verifier activity and a step helper (`integrations/`). ### Headline rules (`summary.headline`) Checks are scanned in the order preconditions → limits → aggregate limits → forbidden effects → reversals → expected effects; the first failing check produces the line: | Situation | Headline | |---|---| | both lenses PASS | `PASS — all N expected effects observed within ; preconditions, limits and prohibitions respected` | | both lenses UNKNOWN | `UNKNOWN —