diff --git a/docs/verification.md b/docs/verification.md index 40d5127..70a53d1 100644 --- a/docs/verification.md +++ b/docs/verification.md @@ -107,6 +107,36 @@ agentrust-trace verify-scitt session.trace.json \ A valid SCITT receipt proves the record was included in the log and cannot be retroactively removed or modified. +## Action receipts and embodied workflows + +Some deployments attach per-action receipts below the session layer. For +example, an embodied-agent controller can sign a receipt that says a specific +call was accepted, rejected, aborted, or handed off to another authority. These +receipts extend the audit chain; they do not replace Trust Record verification. + +Keep the verification results separate: + +| Evidence layer | What to verify | What not to infer | +|---|---|---| +| Session evidence | TRACE signature, freshness, policy hash, runtime measurement, transcript hash | Complete physical-world state | +| Action issuance evidence | Canonical action digest, receipt signature, trusted issuer key, session or call binding, chain order | Successful physical completion | +| Outcome evidence | Controller or monitor decision carried by the receipt payload | Functional-safety certification unless the issuer and profile explicitly claim it | + +For action receipts, a verifier should distinguish four common outcomes: + +| Outcome | Meaning | +|---|---| +| `receipt_valid_accepted` | The receipt is well-formed, trusted, bound to the call, and reports acceptance. | +| `receipt_valid_rejected` | The receipt is well-formed, trusted, bound to the call, and reports controller or policy rejection. This is valid negative evidence. | +| `receipt_missing_required` | The profile required a receipt, but none was present for the consequential action. | +| `receipt_invalid` | The receipt is present but fails signature, digest, issuer, freshness, ordering, or call-binding checks. | + +The key boundary is that a valid rejection is not malformed evidence. It is +evidence that the downstream authority declined the action. A valid acceptance +also remains action-level evidence; it does not prove the requested physical or +business outcome completed unless a stricter profile defines and trusts that +external outcome claim. + ## What verification proves | Claim verified | What it means | @@ -124,6 +154,7 @@ Verification proves *what happened during the recorded session* under the stated - Prove the agent's internal reasoning was sound - Prove the policy was correctly authored for the intent - Prove tool call *contents* (only the hash of the transcript is in v0.1) +- Prove physical completion or functional-safety compliance for externally consequential actions - Replace ongoing monitoring See [Limitations](../LIMITATIONS.md) for the full list. diff --git a/examples/README.md b/examples/README.md index 4e99819..ee286dd 100644 --- a/examples/README.md +++ b/examples/README.md @@ -6,6 +6,9 @@ Each file is a canonical TRACE v0.1 Trust Record that validates as-is against - `intel-tdx.json`: Intel TDX example. - `amd-sev-snp.json`: AMD SEV-SNP example. - `nvidia-h100.json`: NVIDIA H100 Confidential Computing example. +- `action-receipts/`: informative fixture shapes for action-level receipt + verification. These are not TRACE Trust Records and are not validated against + `schema/trace-claim.json`. The schema sets `additionalProperties: false`, so examples must not carry non-schema keys such as `_comment`. Keep descriptive notes in this file. diff --git a/examples/action-receipts/README.md b/examples/action-receipts/README.md new file mode 100644 index 0000000..10343c5 --- /dev/null +++ b/examples/action-receipts/README.md @@ -0,0 +1,70 @@ +# Action receipt verification examples + +These examples describe the fixture shapes used by embodied-action profiles +that attach per-action receipts below a TRACE Trust Record. They are informative +only: the JSON snippets are not TRACE Trust Records and are not validated by +`schema/trace-claim.json`. + +The examples exercise the boundary from +[spec section 3.3.2](../../spec/trace-v0.1.md#332-action-receipts-for-embodied-workflows-informative): + +1. session evidence verifies the Trust Record and committed transcript; +2. action issuance evidence verifies that a consequential action request was + signed, ordered, and bound to the session or call; and +3. outcome evidence reports what an external controller or monitor decided. + +## Shared receipt shape + +An action receipt profile can represent each externally consequential action as +a transcript entry plus a detached receipt: + +```json +{ + "call_id": "call-7f31", + "session_id": "trace-session-2026-07-05T09:42:11Z", + "action_ref": "sha256:...", + "controller_target": "did:web:factory.example:cell-a:robot-arm-2", + "requested_scope": "cell-a.pick.place", + "receipt": { + "issuer": "did:web:factory.example:safety-controller", + "issuer_key_id": "did:web:factory.example:safety-controller#ed25519-2026q3", + "linked_call_id": "call-7f31", + "session_id": "trace-session-2026-07-05T09:42:11Z", + "evidence_type": "application/vnd.agentrust.action-receipt+json", + "evidence_hash": "sha256:...", + "previous_receipt_hash": "sha256:...", + "decision": "accepted", + "signature": "base64url..." + } +} +``` + +The verifier checks the receipt independently of the core Trust Record: + +- recompute `action_ref` or `evidence_hash` from the canonical action preimage; +- resolve `issuer_key_id` through a pinned, manifest-bound, or otherwise trusted + key set; +- verify the signature with `signature` removed from the canonical receipt; +- verify `linked_call_id` and `session_id` match the expected transcript entry; +- verify `previous_receipt_hash` when the profile uses hash-chain ordering; and +- report the receipt result separately from the controller decision. + +## Fixture cases + +| Case | Receipt verification result | Controller outcome | Interpretation | +|---|---|---|---| +| Valid accepted action | `receipt_valid_accepted` | `accepted` | The action request was well evidenced and accepted by the controller. | +| Missing required receipt | `receipt_missing_required` | unknown | The profile required action evidence, but the consequential action had no receipt. | +| Signature or key mismatch | `receipt_invalid` | unknown | The receipt cannot be trusted, even if its payload claims success. | +| Valid controller rejection | `receipt_valid_rejected` | `rejected` | The downstream authority rejected the action; this is valid negative evidence, not malformed evidence. | + +## Boundary + +A valid action receipt proves that a trusted issuer signed a statement about a +specific action request under a specific session or call binding. It does not, +by itself, prove that the physical action completed, that the real world changed +as intended, or that a functional-safety standard was satisfied. + +Profiles that need stronger outcome claims should define the external issuer, +certification basis, and verifier trust anchor for those claims explicitly, +without making them part of base TRACE validity. diff --git a/spec/trace-v0.1.md b/spec/trace-v0.1.md index 68faee3..b493b02 100644 --- a/spec/trace-v0.1.md +++ b/spec/trace-v0.1.md @@ -241,6 +241,44 @@ A verifier configured with the issuer key that fails any of these three checks M **Trust boundary.** External execution evidence is only as trustworthy as the issuer key and the PKI behind it. TRACE binds the receipt into the audit chain — it does not certify that a physical action occurred, that it was executed safely, or that any functional-safety standard was met. Those claims belong to the issuer and its certification body, not to TRACE. +#### 3.3.2 Action receipts for embodied workflows (informative) + +Embodied-agent profiles need to keep three evidence layers separate: + +| Layer | TRACE role | Boundary | +|---|---|---| +| Session evidence | The Trust Record, policy hash, runtime measurement, and `tool_transcript.hash` bind the governed session. | Does not expose every call unless the verifier has the transcript bytes. | +| Action issuance evidence | Per-call receipts can prove that a specific action request was issued, signed, ordered, and bound to the session or call. | Does not prove that the requested physical or business outcome completed. | +| Outcome evidence | Controller, monitor, human-review, or safety-system observations can describe acceptance, rejection, aborts, or completion. | The claim belongs to the external issuer, not to core TRACE validity. | + +This split is intentionally independent of build-provenance depth. A verifier +can have a fully verified dependency chain with no action receipts, or a +complete action-receipt chain for a workload whose builder is only surface +checked. Future profiles may express this as a separate action-receipt +requirement, such as `required`, `optional`, or `none`, without folding action +evidence into the supply-chain provenance axis. + +An action receipt profile can build on the external execution evidence rules in +section 3.3.1 by requiring the verifier to: + +1. recompute the receipt's action or evidence digest from the canonical action + preimage; +2. verify the receipt signature against a pinned, manifest-bound, or otherwise + trusted issuer key, not only against a key embedded in the receipt; +3. verify receipt ordering when receipts are hash-chained; +4. verify that the receipt binds back to the TRACE session, transcript entry, or + cMCP call identifier; and +5. report missing, stale, mismatched, or unverifiable receipts separately from a + verified controller rejection. + +A signed controller rejection is valid negative evidence: it can prove that the +controller rejected the action request under a trusted key and session binding. +It is not a TRACE verification failure unless the receipt itself is malformed, +untrusted, stale, out of order, or not bound to the expected call. Conversely, a +signed acceptance receipt is not proof of physical completion or +functional-safety certification unless the external issuer and profile +explicitly make, and the verifier is configured to trust, that stronger claim. + ### 3.4 Scope TRACE governs any confidential workload — AI agent execution, regulated data processing, sovereign compute, secure multi-party computation. AI agents are the forcing function and the first reference profile, not the limit of the standard.