open-standards/jcp/jcp-rs/crates/jcp-action-receipt/docs/AR-1-spec.md

Action Receipt Specification (AR-1) — Draft

Status: Draft. Profile tag ar/1-draft. Field names are settled against the existing canonical projections; the tag becomes ar/1 when the vector pack has been reviewed.

Conformance pack: jcp/conformance/v1/action_receipt.json, action_receipt_meta.json — 7 positive and 3 negative vectors, signed with a published fixture key.

---

0. Why this exists

Three receipt families already ship in this tree. Each records one quarter of what an audit actually asks for, and none of them binds to the others:

Family	Records	Carries
jcp-receipt	authority	grant chain, verdict, budget drawn
sandbox-proof	environment	attestation, isolation tier, substrate
JCR-1	work	input hash, joules, and how they were obtained (energy provenance)
(nothing)	effect	what changed, and whether it can be undone

So no single artifact answers: under what authority did this agent do that, where did it run, what did it cost, and what did it change?

The receipt encoding is implemented six independent times across the tree. That is evidence the encoding is portable, and evidence the composition was never specified. AR-1 specifies it.

Two of the three families already gesture at the chain — the sandbox proof cell carries a receipt_id, the authority receipt carries a payload_hash. The intent was there. The binding was not.

1. Design invariants

1. Envelope, not replacement. Each family keeps its own canonical encoding and its own signer. AR-1 reaches into them by content-id; they never reach back. Every existing verifier continues to work unchanged.
2. No new cryptography. Canonical det-CBOR (RFC 8949 §4.2.1) and the tagged COSE_Sign1 envelope are reused verbatim from JCR-1. If AR-1 ever appears to need a novel primitive, the design has gone wrong.
3. Refusal over record-keeping. A format that merely records claims is a log. AR-1 defines three shapes that MUST be refused at verification, so a violation is detectable rather than a matter of trust.
4. Never claim beyond the evidence. Every field that asserts a property must be falsifiable from the receipt itself or from an artifact it binds.

2. The signed core

Canonical projection, det-CBOR encoded, signed as COSE_Sign1 with EdDSA (COSE alg −8). Absent optional fields are omitted, not nulled — JCR-1 §3.1 drops nulls from the signed core, so an emitted null would not round-trip.

ActionReceipt {
  ar_receipt:        "ar/1-draft"     // profile tag
  closed_at:         Timestamp        // RFC 3339

  // binding 1 — authority
  grant_id:          ContentId
  chain_ids:         [ContentId]?     // root first; omitted when empty
  authority_receipt: ContentId
  verdict:           "allow" | "deny"

  // binding 2 — environment
  attestation_id:    ContentId
  proof_cell_id:     ContentId?
  tier:              "S0".."S7"
  grounding:         "hardware" | "software"

  // binding 3 — work
  work_receipt:      ContentId
  input_hash:        Hash
  output_hash:       Hash?            // a commitment to what the work returned (§2.3)
  joules_uj:         u64              // the work's cost, graded by energy_provenance
  energy_provenance: "HwShunt" | "ModelBased" | "Estimator"

  // binding 4 — effect (new; nothing else records this)
  effect: {
    class:       "none" | "reversible" | "compensable" | "irreversible"
    target:      ContentId
    before:      Hash?
    after:       Hash?
    compensator: ContentId?
    plan_receipt: ContentId?
  }

  // binding 5 — egress (the router's per-request privacy contract)
  egress: {
    class: "none" | "attested_enclave" | "third_party"
    bytes: u64
    peer:  ContentId?
  }

  steward: String                     // REQUIRED, as in JCR-1 §2.1
}

Receipt id = BLAKE3 over the canonical signed core.

2.1 grounding is carried, never upgraded

grounding reports whether the bound attestation is rooted in silicon or in software. It is copied verbatim from that attestation. An implementation MUST NOT promote software to hardware under any circumstance — the field exists precisely so that a software-rooted claim stays legible as one.

2.2 energy_provenance never collapses

HwShunt, ModelBased and Estimator are three different claims about how a joule figure was obtained. An implementation MUST NOT sum or average across them into a single undifferentiated number. A measured figure and an estimated one are not interchangeable, and a receipt that treats them as such is lying by arithmetic.

joules_uj is the work's cost however it was obtained. It is a hardware reading only when energy_provenance is HwShunt, and a verifier or display MUST NOT present it as a measurement otherwise.

2.3 output_hash commits to what came back

Without it a receipt shows what went in (input_hash) and what changed in the world (effect), and not what the work returned. It therefore cannot show which answer it was for. Where the producer binds the output, it seals output_hash. It is omitted when absent, so a receipt sealed before the field existed keeps its bytes.

A producer SHOULD seal a commitment rather than a plain hash wherever the output can be short. A plain hash of a one-token answer can be reversed by trying every answer, and a receipt is shown to parties who were not owed the output. mesh/1's output_commitment (mesh SPEC §6.4), which commits under an opening its steward discloses per receipt, is such a commitment and can be carried here as it is.

3. The three rules

These MUST be enforced at verification, re-derived from the wire projection — not from a caller-supplied struct. A receipt hand-forged to violate them signs correctly and must be rejected anyway. The negative vectors in the pack exist to prove an implementation does this.

#	Rule	Rationale
1	effect.class == "irreversible" REQUIRES effect.plan_receipt	The cascade's body-tier design already separates plan from commit for actions that touch the world. AR-1 binds that discipline into the evidence: an irreversible commit with no preceding plan is a protocol violation, not a missing nicety.
2	egress.class == "none" REQUIRES egress.bytes == 0	A claim that nothing left the machine is falsified by its own byte count.
3	egress.class == "attested_enclave" REQUIRES egress.peer	The router may never claim a stronger class than it can bind evidence for. An unattested destination is third_party even when the operator believes it trustworthy. Trust is not an egress class.

4. Effect classes

Class	Contract	Enforcement
none	Read-only. Nothing changed.	Trivially safe to replay
reversible	before recorded; prior state restorable.	Undo is a state transition
compensable	Cannot be undone, but a compensating action exists and its grant is named at the time of acting — not discovered afterwards.	compensator bound in the receipt
irreversible	Once committed, permanent.	Rule 1: plan/commit separation

AR-1 does not solve effect revocation — nothing does, in general. Revoking authority does not un-send an email or un-move funds. What AR-1 does is make the distinction explicit and machine-readable at the moment of action, which is the precondition for any system that wants to reason about it afterwards.

5. Egress classes

Class	Means	Verifiable by
none	Resolved on-device.	Rule 2, plus tier and attestation
attested_enclave	Left the device to somewhere that proved what it was running.	Rule 3 — the peer attestation id
third_party	Left the device to an unattested destination.	Named and counted, honestly marked unverifiable

6. Verification flow

1. Parse the tagged COSE_Sign1 envelope; reject any alg other than EdDSA (−8).
2. Check kid against the expected steward.
3. Verify the signature over the canonical signed core.
4. Decode the core as canonical det-CBOR. Reject trailing bytes — a signed core is exactly one item, and anything appended is corruption or an attempt to smuggle data past a verifier that stops at the first complete value.
5. Check the profile tag.
6. Apply the three rules to the decoded projection.
7. Optionally resolve each bound content-id and verify the underlying receipt in its own family's verifier. AR-1 binds; it does not re-verify on their behalf.

Steps 1–6 require only the envelope and a public key. That is what makes a standalone verifier possible, and shipping that verifier is what turns an internal convention into something a third party can adopt.

7. Conformance

An implementation conforms at AR-1/basic when, given the published pack:

• every positive vector verifies, and the re-derived receipt id and canonical core match the published id_hex and core_hex byte-for-byte;
• every negative vector is rejected, despite carrying a genuine signature.

The negatives are the substance. An implementation that checks signatures and skips the structural rules passes the positives and fails the pack — which is exactly the failure mode the pack is designed to catch.

8. What AR-1 deliberately does not do

• Key custody and recovery. Unsolved everywhere; AR-1 must not be built in a way that presumes a solution.
• Re-verifying bound receipts. Each family owns its own verification. AR-1 binds content-ids and stops there.
• Proving the energy figure is honest. It carries provenance so a reader can judge; it does not adjudicate.
• Undoing effects. See §4.

9. Security considerations

A valid signature is not a valid receipt. The three rules exist because signature verification alone accepts well-formed lies. The negative vectors demonstrate this concretely: each is signed with the real fixture key and each must be refused.

Content-id binding is only as strong as the bound artifacts. AR-1 proves which authority receipt, attestation and work receipt were referenced. It does not prove those artifacts are themselves sound — that is their own verifiers' job, and a complete audit runs all of them.

The energy cross-check is a consistency check, not a proof. An attestation asserts; joules are metered, and where energy_provenance is HwShunt they are read off an independently sampled counter. Binding both means a forged attestation must also maintain a plausible energy profile across that counter, and that the failure is visible rather than silent. An Estimator figure offers no such cross-check, which is why it is labelled. An adversary with physical access who can forge a quote can also influence measurement. Claiming more than this would be exactly the overreach the design exists to avoid.