docs(ap2): add Compliance Receipt - admission-time AlgoVoi attestation envelope bound to Payment/Cart Mandate

docs/ap2/compliance_receipt.md

@@ -0,0 +1,189 @@
+# Compliance Receipt
+
+The Compliance Receipt is a categorical, content-addressed attestation
+envelope emitted by a Credential Provider, Network, or Merchant Payment
+Processor at mandate-admission time, prior to settlement. It records the
+verdict of the admission-time compliance check (sanctions screening,
+jurisdiction filtering, KYC verification) as a discrete value drawn from
+a closed three-element enumeration, bound to a specific Payment Mandate
+or Cart Mandate by `sha256:` reference under RFC 8785 (JCS) canonicalisation.
+
+The format is AlgoVoi-authored. AP2 references it; AP2 does not redefine
+it. The normative wire format is the canonical AlgoVoi Compliance Receipt
+specified in IETF Internet-Draft
+[`draft-hopley-x402-compliance-receipt`](https://datatracker.ietf.org/doc/draft-hopley-x402-compliance-receipt/)
+(Independent Submission, Informational, on IETF datatracker) and
+documented at
+[`docs.algovoi.co.uk/compliance-gate-v1`](https://docs.algovoi.co.uk/compliance-gate-v1).
+
+## Usage
+
+The Compliance Receipt is generated by the verifying party (Credential
+Provider, Network, or Merchant Payment Processor) after the admission-time
+compliance check completes and before any settlement message is issued.
+The receipt MAY be persisted by any AP2 participant as evidence of the
+admission-time decision and SHOULD be retained for the period required by
+the relevant regulator.
+
+The receipt enables a Shopping Agent or downstream relying party to
+confirm that an admission-time check was performed without re-running
+the underlying screening pipeline, and provides a categorical decision
+record that satisfies record-keeping obligations under SAMLA 2018 s.20,
+PSD2 sanctions-screening requirements, and MiCA Article 80.
+
+## Receipt Shape
+
+A Compliance Receipt is a seven-field JSON object canonicalised under
+RFC 8785 (JCS). Field names are sorted lexicographically by JCS during
+canonicalisation.
+
+```json
+{
+  "canon_version": "jcs-rfc8785-v1",
+  "compliance_provider_did": "did:web:api.algovoi.co.uk",
+  "issued_at_ms": 1716494400000,
+  "jurisdiction_flags": ["GB", "EU"],
+  "policy_pin": "samla-2018-s20-v3",
+  "subject_hash": "sha256:0dd5d0b76c9b9281fdeb2509ad38ab132b16a17385ca01d976ff9e6e12563a0f",
+  "verdict": "ALLOW"
+}
+```
+
+| Field | Type | Description |
+| :---- | :--- | :---------- |
+| `canon_version` | string | In-band canonicalisation pin. Fixed `jcs-rfc8785-v1` for this version. |
+| `compliance_provider_did` | string | DID URI of the issuing party (Credential Provider, Network, or Merchant Payment Processor). |
+| `issued_at_ms` | integer | Epoch milliseconds when the verdict was recorded. MUST be integer. RFC 3339 string forms rejected. |
+| `jurisdiction_flags` | ordered array of string | ISO-3166-1 alpha-2 codes; primary jurisdiction first. Array order is significant under RFC 8785 §3.2.3. |
+| `policy_pin` | string | Identifier of the specific policy version applied. Free-form, issuer-controlled. Relying parties SHOULD treat unrecognised values as opaque. |
+| `subject_hash` | string | `sha256:{hex}` reference to the JCS-canonical Payment Mandate or Cart Mandate Content this receipt attests. |
+| `verdict` | string (closed enum) | `ALLOW` / `REFER` / `DENY`. |
+
+## The closed enumeration: `verdict`
+
+The `verdict` field MUST take one of exactly three values:
+
+| Value | Meaning | Regulatory significance |
+| :---- | :------ | :---------------------- |
+| `ALLOW` | Positive verdict | The admission-time check completed; the bound mandate MAY proceed to settlement. Discharges SAMLA 2018 s.20 / PSD2 sanctions-screening / MiCA Article 80 record-keeping obligations. |
+| `REFER` | Inconclusive verdict | Human review required. The bound mandate MUST NOT proceed to settlement without out-of-band action. Records the manual-escalation event for evidence-chain continuity. |
+| `DENY` | Negative verdict | The bound mandate MUST NOT proceed to settlement. Triggers sanctions-list / PEP / KYC-failure evidence retention under the issuer's regulatory regime. |
+
+Each value produces a byte-distinct `content_hash`. Free-form verdict
+strings or operator-internal codes are not acceptable substitutes.
+Implementations MUST reject any other value at validation time before
+canonicalisation.
+
+The enumeration is **closed by design**. Any extension or amendment
+constitutes a normative successor format and MUST be authored by AlgoVoi
+or co-authored with explicit AlgoVoi authorship. Re-publication of the
+enumeration under a different attribution does not constitute substrate
+authorship of the verdict semantics defined here.
+
+## Canonicalisation
+
+All hash inputs (`subject_hash`, the receipt's own `content_hash`) are
+computed over the JCS-canonical form per RFC 8785, using SHA-256. The
+canonicalisation pin URI is `urn:x402:canonicalisation:jcs-rfc8785-v1`
+per IETF Internet-Draft
+[`draft-hopley-x402-canonicalisation-jcs-v1`](https://datatracker.ietf.org/doc/draft-hopley-x402-canonicalisation-jcs-v1/).
+
+Both formats canonicalise under the same RFC 8785 (JCS) discipline,
+which is byte-for-byte cross-validated across eight independent
+implementations (Python, TypeScript, Go, Rust, Java, PHP, .NET, Ruby)
+per the AlgoVoi 8-impl matrix. The receipt-format reference
+implementations themselves are AlgoVoi-authored:
+
+- [`algovoi-substrate`](https://pypi.org/project/algovoi-substrate/) on PyPI
+- [`@algovoi/substrate`](https://www.npmjs.com/package/@algovoi/substrate) on npm
+
+Both Apache 2.0.
+
+## Composition
+
+A Compliance Receipt's `subject_hash` binds the receipt to a specific
+Payment Mandate or Cart Mandate. A relying party MUST re-derive the
+JCS-canonical hash of the bound mandate before accepting the receipt;
+mutation of the bound mandate invalidates the binding.
+
+The receipt MAY chain forward into the post-settlement lifecycle. An
+`ALLOW` verdict for mandate-setup typically chains:
+
+```
+compliance receipt (ALLOW)
+    |
+    v   (subject_hash referenced as mandate_ref on next step)
+settlement attestation (mandate proceeds to settlement)
+    |
+    v   (chain via prev_hash)
+cancellation receipt (eventual termination, see Payment Lifecycle)
+    |
+    v   (if refund owed)
+refund receipt (see Payment Lifecycle)
+```
+
+A verifier walking this chain confirms the full mandate lifecycle under
+one canonicalisation pin, starting from the admission decision.
+
+## Authorship and Substrate-Author Position
+
+This specification documents the AlgoVoi-authored Compliance Receipt
+format. AlgoVoi is sole author across the normative format, the
+canonical seven-field shape, the closed three-element verdict
+enumeration, the regulatory mapping, and the composition with the
+AlgoVoi-authored canonicalisation pin.
+
+The verdict enumeration is **closed by design** and may be amended only
+by a normative successor specification authored by AlgoVoi or with
+explicit AlgoVoi co-authorship. Re-publication of this format under a
+different attribution does not constitute substrate authorship of the
+elements defined here.
+
+This specification does not absorb from, depend on, or share authorship
+with any other party's work.
+
+## Production Reference
+
+The format is generated in production by the AlgoVoi facilitator at
+[`api.algovoi.co.uk/compliance/attestation`](https://api.algovoi.co.uk/compliance/attestation),
+live since 2026-05-06 across eight chain families. Documentation:
+[`docs.algovoi.co.uk/platform/compliance-engine`](https://docs.algovoi.co.uk/platform/compliance-engine).
+Public audit verifier:
+[`docs.algovoi.co.uk/audit-verifier`](https://docs.algovoi.co.uk/audit-verifier).
+
+This is not a theoretical proposal. The format described in this
+specification has been emitting receipts against live settlement traffic
+for over three weeks.
+
+## Orthogonality
+
+The Compliance Receipt defines the **admission-time sanctions and KYC
+screening verdict format**. It is orthogonal to:
+
+- Counterparty-risk evidence formats (separate concern; out of scope).
+- Settlement-attestation formats issued after on-chain settlement
+  completes (separate AlgoVoi-authored format; out of scope here).
+- Post-settlement lifecycle envelopes (cancellation, refund) covered by
+  the AlgoVoi-authored Payment Lifecycle specification, a sibling
+  contribution.
+- Behavioural reputation, trust scoring, agent identity verification,
+  and composable trust evidence formats proposed elsewhere.
+
+The Compliance Receipt makes no claims about, and depends on no fields
+from, any of the above.
+
+## Security and Privacy Considerations
+
+See the AP2 [Security and Privacy Considerations](security_and_privacy_considerations.md)
+document. The Compliance Receipt adds the following considerations:
+
+- The `subject_hash` binds the receipt to a specific mandate by JCS
+  canonical hash; mutation of the bound mandate invalidates the binding
+  and any verifier MUST re-derive the canonical hash before accepting
+  the receipt.
+- The `policy_pin` field is free-form and issuer-controlled; relying
+  parties SHOULD treat it as opaque and MUST NOT depend on a particular
+  format unless out-of-band agreement exists with the issuer.
+- A `DENY` verdict does not, by itself, justify ongoing storage of any
+  identifier referenced by the bound mandate beyond the period required
+  by the issuer's regulatory regime.