@zanii/core 0.5.1 → 0.5.3

package/src/receipt.ts

@@ -1,308 +1,340 @@
-import { ed25519 } from '@noble/curves/ed25519';
-import { sha256 } from '@noble/hashes/sha256';
-import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils';
-import { canonicalBytes, decodeSig, encodeSig, jcsHash } from './encoding.js';
-import { publicKeyFromDid } from './keys.js';
-import { scopesAllow, verifyChain, type DelegationCert } from './delegation.js';
-
-export interface Receipt {
-  v: 1;
-  agent_id: string;
-  delegation: DelegationCert[];
-  action: string;
-  target: string;
-  payload_hash: string;
-  ts: string;
-  prev: string | null;
-  /** Optional provenance (SPEC §3). Present when set; covered by the signature. */
-  runtime_hash?: string;
-  model_id?: string;
-  /** Hash of the product's tool/scope manifest that governed this action. */
-  manifest_hash?: string;
-  /** Optional pseudonymous data-subject tag (SPEC §3) — lets the end user the action was
-   * about find + audit their own slice (`@zanii/subject`). Covered by the signature. */
-  subject_tag?: string;
-  /**
-   * How `payload_hash` committed to the payload (SPEC §3). `'jcs'` means the payload was
-   * encoded with `payloadBytes` (RFC 8785) before hashing — the only value written since
-   * `@zanii/sdk` 0.5.0. ABSENT means a pre-0.5.0 receipt, whose bytes came from the SDK's
-   * own `JSON.stringify`/`json.dumps` and therefore differ between the two SDKs; those
-   * are checked with `verifyPayloadLegacy`, never with `verifyPayload`.
-   */
-  payload_encoding?: 'jcs';
-  sig: string;
-}
-
-export interface VerifyResult {
-  ok: boolean;
-  error?: string;
-}
-
-export function hashPayload(payload: Uint8Array | string): string {
-  const bytes = typeof payload === 'string' ? new TextEncoder().encode(payload) : payload;
-  return `sha256:${bytesToHex(sha256(bytes))}`;
-}
-
-/**
- * Reject anything whose canonical form the two SDKs would not agree on. Mirrors
- * `_check_jcs_safe` in `zanii.encoding`: non-integer numbers are the one place JSON
- * serialisers legitimately disagree, so they are refused rather than hashed into a
- * receipt no Python verifier can reproduce. Use integer minor units (`@zanii/payments`).
- */
-function assertPayloadCanonicalizable(v: unknown, path = 'payload'): void {
-  if (v === null || typeof v === 'string' || typeof v === 'boolean') return;
-  if (typeof v === 'number') {
-    if (!Number.isFinite(v)) throw new Error(`${path}: ${v} has no JSON representation`);
-    if (!Number.isInteger(v)) {
-      throw new Error(
-        `${path}: non-integer number ${v} cannot be committed to a payload hash — the two SDKs ` +
-          'would encode it differently. Use integer minor units (see @zanii/payments) or a string.',
-      );
-    }
-    return;
-  }
-  if (Array.isArray(v)) {
-    v.forEach((x, i) => assertPayloadCanonicalizable(x, `${path}[${i}]`));
-    return;
-  }
-  if (typeof v === 'object') {
-    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
-      // An undefined member is DROPPED, per JSON.stringify: `{a:1,b:undefined}` encodes
-      // as `{"a":1}`, which is byte-identical to what Python produces for the equivalent
-      // input (the key simply absent). A Python `None` means JSON null, a different
-      // value, and correctly hashes differently. So this needs no special case.
-      if (val === undefined) continue;
-      assertPayloadCanonicalizable(val, `${path}.${k}`);
-    }
-    return;
-  }
-  throw new Error(`${path}: ${typeof v} is not canonicalizable JSON`);
-}
-
-/**
- * The bytes a `payload_hash` commits to (SPEC §3): RFC 8785 JCS, UTF-8.
- *
- * This exists because "hash the payload" was under-specified: each SDK reached for its
- * own serialiser, so the same object hashed differently in TypeScript and Python and
- * `verifyPayload` returned false across languages for honest data. One encoder, both
- * languages, byte-identical — pinned by the cross-language vectors.
- *
- * A top-level `undefined` (or `null`) encodes as `null`, which is what both SDKs already
- * hashed, so null payloads are unaffected by the change.
- */
-export function payloadBytes(payload: unknown): Uint8Array {
-  const value = payload === undefined ? null : payload;
-  assertPayloadCanonicalizable(value);
-  return canonicalBytes(value);
-}
-
-/**
- * Privacy-preserving payload commitment: `sha256(nonce ‖ payload)`. A bare
- * `hashPayload` of a low-entropy payload ("phone X, amount 500") is dictionary-
- * attackable from the public anchored log, and a linkable hash can itself be
- * personal data (PDPL). The per-receipt `nonce` is kept operator-side (NOT in the
- * receipt), so the on-chain value reveals nothing; keep it to later prove the
- * payload with `verifyPayload`. If `nonce` is omitted a fresh 16-byte one is drawn.
- */
-export function saltedPayloadHash(
-  payload: Uint8Array | string,
-  nonce?: string,
-): { payload_hash: string; nonce: string } {
-  const nonceHex = nonce ?? bytesToHex(randomBytes(16));
-  const nonceBytes = hexToBytes(nonceHex);
-  const payloadBytes = typeof payload === 'string' ? new TextEncoder().encode(payload) : payload;
-  const combined = new Uint8Array(nonceBytes.length + payloadBytes.length);
-  combined.set(nonceBytes, 0);
-  combined.set(payloadBytes, nonceBytes.length);
-  return { payload_hash: `sha256:${bytesToHex(sha256(combined))}`, nonce: nonceHex };
-}
-
-/** Prove a payload matches a salted `payload_hash`, given the nonce kept at record time. */
-export function verifyPayload(payload: Uint8Array | string, nonce: string, payloadHash: string): boolean {
-  try {
-    return saltedPayloadHash(payload, nonce).payload_hash === payloadHash;
-  } catch {
-    return false;
-  }
-}
-
-/** Which pre-0.5.0 SDK's serialiser reproduced a legacy `payload_hash`. */
-export type PayloadDialect = 'jcs' | 'legacy-ts' | 'legacy-py';
-
-/** Old `@zanii/sdk`: `JSON.stringify`, insertion order, no spaces, raw UTF-8. */
-function legacyTsEncode(payload: unknown): string | undefined {
-  return JSON.stringify(payload) ?? 'null';
-}
-
-/** Old `zanii` (Python): `json.dumps(sort_keys=True)` — `, ` / `: ` separators, \uXXXX escapes. */
-function legacyPyEncode(value: unknown): string {
-  const esc = (str: string): string => {
-    let out = '';
-    for (const ch of str) {
-      const c = ch.codePointAt(0)!;
-      if (ch === '"') out += '\\"';
-      else if (ch === '\\') out += '\\\\';
-      else if (ch === '\n') out += '\\n';
-      else if (ch === '\r') out += '\\r';
-      else if (ch === '\t') out += '\\t';
-      else if (c < 0x20) out += `\\u${c.toString(16).padStart(4, '0')}`;
-      else if (c < 0x7f) out += ch;
-      else if (c > 0xffff) {
-        // Python escapes astral characters as a surrogate pair
-        const u = c - 0x10000;
-        out += `\\u${(0xd800 + (u >> 10)).toString(16)}\\u${(0xdc00 + (u & 0x3ff)).toString(16)}`;
-      } else out += `\\u${c.toString(16).padStart(4, '0')}`;
-    }
-    return `"${out}"`;
-  };
-  const enc = (v: unknown): string => {
-    if (v === null || v === undefined) return 'null';
-    if (typeof v === 'boolean') return v ? 'true' : 'false';
-    if (typeof v === 'number') return Number.isInteger(v) ? String(v) : String(v);
-    if (typeof v === 'string') return esc(v);
-    if (Array.isArray(v)) return `[${v.map(enc).join(', ')}]`;
-    const o = v as Record<string, unknown>;
-    const keys = Object.keys(o).sort();
-    return `{${keys.map((k) => `${esc(k)}: ${enc(o[k])}`).join(', ')}}`;
-  };
-  return enc(value);
-}
-
-/**
- * Verify a payload against a receipt recorded BEFORE the JCS rule (no `payload_encoding`
- * field). Such a receipt does not record which SDK wrote it, so this tries each old
- * dialect and reports which one matched.
- *
- * Honest limits: the `legacy-ts` dialect depends on the object's original KEY INSERTION
- * ORDER, which is not recoverable from a re-parsed payload, so it only matches when the
- * caller reconstructs the object in the order it was recorded. Float formatting is
- * likewise best-effort. A `null` result means no dialect reproduced the hash; it does not
- * prove the payload wrong.
- */
-export function verifyPayloadLegacy(
-  payload: unknown,
-  nonce: string,
-  payloadHash: string,
-): { ok: boolean; dialect: PayloadDialect | null } {
-  const attempts: Array<[PayloadDialect, () => Uint8Array | string]> = [
-    ['jcs', () => payloadBytes(payload)],
-    ['legacy-ts', () => legacyTsEncode(payload)!],
-    ['legacy-py', () => legacyPyEncode(payload)],
-  ];
-  for (const [dialect, encode] of attempts) {
-    try {
-      if (saltedPayloadHash(encode(), nonce).payload_hash === payloadHash) return { ok: true, dialect };
-    } catch {
-      /* this dialect cannot encode it — try the next */
-    }
-  }
-  return { ok: false, dialect: null };
-}
-
-export function createReceipt(
-  fields: {
-    agentId: string;
-    delegation: DelegationCert[];
-    action: string;
-    target: string;
-    payloadHash: string;
-    ts: string;
-    prev: string | null;
-    /** Optional provenance — included in the signed receipt only when provided. */
-    runtimeHash?: string;
-    modelId?: string;
-    manifestHash?: string;
-    /** Optional pseudonymous data-subject tag — per-subject auditability (`@zanii/subject`). */
-    subjectTag?: string;
-    /** How `payloadHash` committed to the payload. Set `'jcs'` when it came from `payloadBytes`. */
-    payloadEncoding?: 'jcs';
-  },
-  agentPrivateKey: Uint8Array,
-): Receipt {
-  if (Number.isNaN(Date.parse(fields.ts))) throw new Error(`invalid ts timestamp: ${fields.ts}`);
-  const unsigned = {
-    v: 1 as const,
-    agent_id: fields.agentId,
-    delegation: fields.delegation,
-    action: fields.action,
-    target: fields.target,
-    payload_hash: fields.payloadHash,
-    ts: fields.ts,
-    prev: fields.prev,
-    ...(fields.runtimeHash ? { runtime_hash: fields.runtimeHash } : {}),
-    ...(fields.modelId ? { model_id: fields.modelId } : {}),
-    ...(fields.manifestHash ? { manifest_hash: fields.manifestHash } : {}),
-    ...(fields.subjectTag ? { subject_tag: fields.subjectTag } : {}),
-    ...(fields.payloadEncoding ? { payload_encoding: fields.payloadEncoding } : {}),
-  };
-  const sig = ed25519.sign(canonicalBytes(unsigned), agentPrivateKey);
-  return { ...unsigned, sig: encodeSig(sig) };
-}
-
-/** Hash of the full receipt (incl. sig) — what the next receipt's `prev` points to. */
-export function receiptHash(receipt: Receipt): string {
-  return jcsHash(receipt);
-}
-
-export function verifyReceiptSignature(receipt: Receipt): boolean {
-  const pub = publicKeyFromDid(receipt.agent_id);
-  const sig = decodeSig(receipt.sig);
-  if (!pub || !sig) return false;
-  const { sig: _omitted, ...unsigned } = receipt;
-  try {
-    return ed25519.verify(sig, canonicalBytes(unsigned), pub);
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Full single-receipt verification per SPEC §4:
- * signature → delegation chain (at receipt time) → scope covers target → prev linkage.
- */
-export function verifyReceipt(
-  receipt: Receipt,
-  opts: { expectedOwner?: string; revoked?: Set<string>; expectedPrev?: string | null } = {},
-): VerifyResult {
-  if (receipt.v !== 1) return { ok: false, error: 'unsupported receipt version' };
-  if (!verifyReceiptSignature(receipt)) return { ok: false, error: 'bad receipt signature' };
-
-  const ts = new Date(receipt.ts);
-  if (Number.isNaN(ts.getTime())) return { ok: false, error: 'invalid ts' };
-
-  const chain = verifyChain(receipt.delegation, {
-    agentId: receipt.agent_id,
-    expectedRoot: opts.expectedOwner,
-    revoked: opts.revoked,
-    at: ts,
-  });
-  if (!chain.ok) return { ok: false, error: `delegation: ${chain.error}` };
-
-  if (!scopesAllow(chain.effectiveScopes!, receipt.target)) {
-    return { ok: false, error: `target ${receipt.target} outside effective scopes` };
-  }
-
-  if (opts.expectedPrev !== undefined && receipt.prev !== opts.expectedPrev) {
-    return { ok: false, error: 'prev hash does not match preceding receipt (chain broken)' };
-  }
-
-  return { ok: true };
-}
-
-/**
- * Verify an agent's full receipt sequence: every receipt valid and hash-linked
- * to the one before it. Returns the index of the first bad receipt on failure.
- */
-export function verifyReceiptChain(
-  receipts: Receipt[],
-  opts: { expectedOwner?: string; revoked?: Set<string> } = {},
-): VerifyResult & { failedIndex?: number } {
-  let expectedPrev: string | null = null;
-  for (let i = 0; i < receipts.length; i++) {
-    const r = receipts[i]!;
-    const result = verifyReceipt(r, { ...opts, expectedPrev });
-    if (!result.ok) return { ok: false, error: `receipt ${i}: ${result.error}`, failedIndex: i };
-    expectedPrev = receiptHash(r);
-  }
-  return { ok: true };
-}
+import { ed25519 } from '@noble/curves/ed25519';
+import { sha256 } from '@noble/hashes/sha256';
+import { bytesToHex, hexToBytes, randomBytes } from '@noble/hashes/utils';
+import { canonicalBytes, decodeSig, encodeSig, jcsHash } from './encoding.js';
+import { publicKeyFromDid } from './keys.js';
+import { scopesAllow, verifyChain, type DelegationCert } from './delegation.js';
+
+/**
+ * The target of a session-close receipt (SPEC §15). An agent records one when it ends a
+ * session deliberately, so a verifier can tell a run that finished from one that was cut
+ * off. The per-agent `prev` chain already proves nothing is missing between receipts;
+ * this marks where a session was declared over.
+ */
+export const SESSION_CLOSE_TARGET = 'zanii.session.close';
+
+/** True for a solo receipt that closes a session. */
+export function isSessionClose(receipt: unknown): boolean {
+  const r = receipt as { type?: string; target?: string; action?: string } | null;
+  return !!r && r.type === undefined && r.target === SESSION_CLOSE_TARGET && r.action === 'session.close';
+}
+
+/** What is at stake in an action (SPEC §3). A label the recorder sets, signed with the receipt: useful for policy and triage, and a control only where something independent of the agent enforces it. */
+export const RISK_LEVELS = ['low', 'medium', 'high', 'critical'] as const;
+export type RiskLevel = (typeof RISK_LEVELS)[number];
+export function isRiskLevel(v: unknown): v is RiskLevel {
+  return typeof v === 'string' && (RISK_LEVELS as readonly string[]).includes(v);
+}
+
+export interface Receipt {
+  v: 1;
+  agent_id: string;
+  delegation: DelegationCert[];
+  action: string;
+  target: string;
+  payload_hash: string;
+  ts: string;
+  prev: string | null;
+  /** Optional provenance (SPEC §3). Present when set; covered by the signature. */
+  runtime_hash?: string;
+  model_id?: string;
+  /** Hash of the product's tool/scope manifest that governed this action. */
+  manifest_hash?: string;
+  /** Optional pseudonymous data-subject tag (SPEC §3) — lets the end user the action was
+   * about find + audit their own slice (`@zanii/subject`). Covered by the signature. */
+  subject_tag?: string;
+  /**
+   * How `payload_hash` committed to the payload (SPEC §3). `'jcs'` means the payload was
+   * encoded with `payloadBytes` (RFC 8785) before hashing — the only value written since
+   * `@zanii/sdk` 0.5.0. ABSENT means a pre-0.5.0 receipt, whose bytes came from the SDK's
+   * own `JSON.stringify`/`json.dumps` and therefore differ between the two SDKs; those
+   * are checked with `verifyPayloadLegacy`, never with `verifyPayload`.
+   */
+  payload_encoding?: 'jcs';
+  /** What is at stake (SPEC §3). Signed; absent means the recorder did not say. */
+  risk?: RiskLevel;
+  sig: string;
+}
+
+export interface VerifyResult {
+  ok: boolean;
+  error?: string;
+}
+
+export function hashPayload(payload: Uint8Array | string): string {
+  const bytes = typeof payload === 'string' ? new TextEncoder().encode(payload) : payload;
+  return `sha256:${bytesToHex(sha256(bytes))}`;
+}
+
+/**
+ * Reject anything whose canonical form the two SDKs would not agree on. Mirrors
+ * `_check_jcs_safe` in `zanii.encoding`: non-integer numbers are the one place JSON
+ * serialisers legitimately disagree, so they are refused rather than hashed into a
+ * receipt no Python verifier can reproduce. Use integer minor units (`@zanii/payments`).
+ */
+function assertPayloadCanonicalizable(v: unknown, path = 'payload'): void {
+  if (v === null || typeof v === 'string' || typeof v === 'boolean') return;
+  if (typeof v === 'number') {
+    if (!Number.isFinite(v)) throw new Error(`${path}: ${v} has no JSON representation`);
+    // A non-integer encodes as RFC 8785 §3.2.2.3 (ECMAScript's own form, which Python's
+    // SDK reproduces byte for byte since protocol 1.3), so it needs no check here.
+    if (Number.isInteger(v) && !Number.isSafeInteger(v)) {
+      // JavaScript has already rounded it by now; another SDK would keep it exact.
+      throw new Error(
+        `${path}: integer ${v} is outside +/-(2^53-1): not every JSON implementation can ` +
+          'represent it exactly, so the SDKs would disagree on its bytes. Pass it as a string.',
+      );
+    }
+    return;
+  }
+  if (Array.isArray(v)) {
+    v.forEach((x, i) => assertPayloadCanonicalizable(x, `${path}[${i}]`));
+    return;
+  }
+  if (typeof v === 'object') {
+    for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+      // An undefined member is DROPPED, per JSON.stringify: `{a:1,b:undefined}` encodes
+      // as `{"a":1}`, which is byte-identical to what Python produces for the equivalent
+      // input (the key simply absent). A Python `None` means JSON null, a different
+      // value, and correctly hashes differently. So this needs no special case.
+      if (val === undefined) continue;
+      assertPayloadCanonicalizable(val, `${path}.${k}`);
+    }
+    return;
+  }
+  throw new Error(`${path}: ${typeof v} is not canonicalizable JSON`);
+}
+
+/**
+ * The bytes a `payload_hash` commits to (SPEC §3): RFC 8785 JCS, UTF-8.
+ *
+ * This exists because "hash the payload" was under-specified: each SDK reached for its
+ * own serialiser, so the same object hashed differently in TypeScript and Python and
+ * `verifyPayload` returned false across languages for honest data. One encoder, both
+ * languages, byte-identical — pinned by the cross-language vectors.
+ *
+ * A top-level `undefined` (or `null`) encodes as `null`, which is what both SDKs already
+ * hashed, so null payloads are unaffected by the change.
+ */
+export function payloadBytes(payload: unknown): Uint8Array {
+  const value = payload === undefined ? null : payload;
+  assertPayloadCanonicalizable(value);
+  return canonicalBytes(value);
+}
+
+/**
+ * Privacy-preserving payload commitment: `sha256(nonce ‖ payload)`. A bare
+ * `hashPayload` of a low-entropy payload ("phone X, amount 500") is dictionary-
+ * attackable from the public anchored log, and a linkable hash can itself be
+ * personal data (PDPL). The per-receipt `nonce` is kept operator-side (NOT in the
+ * receipt), so the on-chain value reveals nothing; keep it to later prove the
+ * payload with `verifyPayload`. If `nonce` is omitted a fresh 16-byte one is drawn.
+ */
+export function saltedPayloadHash(
+  payload: Uint8Array | string,
+  nonce?: string,
+): { payload_hash: string; nonce: string } {
+  const nonceHex = nonce ?? bytesToHex(randomBytes(16));
+  const nonceBytes = hexToBytes(nonceHex);
+  const payloadBytes = typeof payload === 'string' ? new TextEncoder().encode(payload) : payload;
+  const combined = new Uint8Array(nonceBytes.length + payloadBytes.length);
+  combined.set(nonceBytes, 0);
+  combined.set(payloadBytes, nonceBytes.length);
+  return { payload_hash: `sha256:${bytesToHex(sha256(combined))}`, nonce: nonceHex };
+}
+
+/** Prove a payload matches a salted `payload_hash`, given the nonce kept at record time. */
+export function verifyPayload(payload: Uint8Array | string, nonce: string, payloadHash: string): boolean {
+  try {
+    return saltedPayloadHash(payload, nonce).payload_hash === payloadHash;
+  } catch {
+    return false;
+  }
+}
+
+/** Which pre-0.5.0 SDK's serialiser reproduced a legacy `payload_hash`. */
+export type PayloadDialect = 'jcs' | 'legacy-ts' | 'legacy-py';
+
+/** Old `@zanii/sdk`: `JSON.stringify`, insertion order, no spaces, raw UTF-8. */
+function legacyTsEncode(payload: unknown): string | undefined {
+  return JSON.stringify(payload) ?? 'null';
+}
+
+/** Old `zanii` (Python): `json.dumps(sort_keys=True)` — `, ` / `: ` separators, \uXXXX escapes. */
+function legacyPyEncode(value: unknown): string {
+  const esc = (str: string): string => {
+    let out = '';
+    for (const ch of str) {
+      const c = ch.codePointAt(0)!;
+      if (ch === '"') out += '\\"';
+      else if (ch === '\\') out += '\\\\';
+      else if (ch === '\n') out += '\\n';
+      else if (ch === '\r') out += '\\r';
+      else if (ch === '\t') out += '\\t';
+      else if (c < 0x20) out += `\\u${c.toString(16).padStart(4, '0')}`;
+      else if (c < 0x7f) out += ch;
+      else if (c > 0xffff) {
+        // Python escapes astral characters as a surrogate pair
+        const u = c - 0x10000;
+        out += `\\u${(0xd800 + (u >> 10)).toString(16)}\\u${(0xdc00 + (u & 0x3ff)).toString(16)}`;
+      } else out += `\\u${c.toString(16).padStart(4, '0')}`;
+    }
+    return `"${out}"`;
+  };
+  const enc = (v: unknown): string => {
+    if (v === null || v === undefined) return 'null';
+    if (typeof v === 'boolean') return v ? 'true' : 'false';
+    if (typeof v === 'number') return Number.isInteger(v) ? String(v) : String(v);
+    if (typeof v === 'string') return esc(v);
+    if (Array.isArray(v)) return `[${v.map(enc).join(', ')}]`;
+    const o = v as Record<string, unknown>;
+    const keys = Object.keys(o).sort();
+    return `{${keys.map((k) => `${esc(k)}: ${enc(o[k])}`).join(', ')}}`;
+  };
+  return enc(value);
+}
+
+/**
+ * Verify a payload against a receipt recorded BEFORE the JCS rule (no `payload_encoding`
+ * field). Such a receipt does not record which SDK wrote it, so this tries each old
+ * dialect and reports which one matched.
+ *
+ * Honest limits: the `legacy-ts` dialect depends on the object's original KEY INSERTION
+ * ORDER, which is not recoverable from a re-parsed payload, so it only matches when the
+ * caller reconstructs the object in the order it was recorded. Float formatting is
+ * likewise best-effort. A `null` result means no dialect reproduced the hash; it does not
+ * prove the payload wrong.
+ */
+export function verifyPayloadLegacy(
+  payload: unknown,
+  nonce: string,
+  payloadHash: string,
+): { ok: boolean; dialect: PayloadDialect | null } {
+  const attempts: Array<[PayloadDialect, () => Uint8Array | string]> = [
+    ['jcs', () => payloadBytes(payload)],
+    ['legacy-ts', () => legacyTsEncode(payload)!],
+    ['legacy-py', () => legacyPyEncode(payload)],
+  ];
+  for (const [dialect, encode] of attempts) {
+    try {
+      if (saltedPayloadHash(encode(), nonce).payload_hash === payloadHash) return { ok: true, dialect };
+    } catch {
+      /* this dialect cannot encode it — try the next */
+    }
+  }
+  return { ok: false, dialect: null };
+}
+
+export function createReceipt(
+  fields: {
+    agentId: string;
+    delegation: DelegationCert[];
+    action: string;
+    target: string;
+    payloadHash: string;
+    ts: string;
+    prev: string | null;
+    /** Optional provenance — included in the signed receipt only when provided. */
+    runtimeHash?: string;
+    modelId?: string;
+    manifestHash?: string;
+    /** Optional pseudonymous data-subject tag — per-subject auditability (`@zanii/subject`). */
+    subjectTag?: string;
+    /** How `payloadHash` committed to the payload. Set `'jcs'` when it came from `payloadBytes`. */
+    payloadEncoding?: 'jcs';
+    /** What is at stake. Signed into the receipt when set. */
+    risk?: RiskLevel;
+  },
+  agentPrivateKey: Uint8Array,
+): Receipt {
+  if (Number.isNaN(Date.parse(fields.ts))) throw new Error(`invalid ts timestamp: ${fields.ts}`);
+  if (fields.risk !== undefined && !isRiskLevel(fields.risk)) {
+    throw new Error(`invalid risk '${String(fields.risk)}': expected one of low, medium, high, critical`);
+  }
+  const unsigned = {
+    v: 1 as const,
+    agent_id: fields.agentId,
+    delegation: fields.delegation,
+    action: fields.action,
+    target: fields.target,
+    payload_hash: fields.payloadHash,
+    ts: fields.ts,
+    prev: fields.prev,
+    ...(fields.runtimeHash ? { runtime_hash: fields.runtimeHash } : {}),
+    ...(fields.modelId ? { model_id: fields.modelId } : {}),
+    ...(fields.manifestHash ? { manifest_hash: fields.manifestHash } : {}),
+    ...(fields.subjectTag ? { subject_tag: fields.subjectTag } : {}),
+    ...(fields.payloadEncoding ? { payload_encoding: fields.payloadEncoding } : {}),
+    ...(fields.risk ? { risk: fields.risk } : {}),
+  };
+  const sig = ed25519.sign(canonicalBytes(unsigned), agentPrivateKey);
+  return { ...unsigned, sig: encodeSig(sig) };
+}
+
+/** Hash of the full receipt (incl. sig) — what the next receipt's `prev` points to. */
+export function receiptHash(receipt: Receipt): string {
+  return jcsHash(receipt);
+}
+
+export function verifyReceiptSignature(receipt: Receipt): boolean {
+  const pub = publicKeyFromDid(receipt.agent_id);
+  const sig = decodeSig(receipt.sig);
+  if (!pub || !sig) return false;
+  const { sig: _omitted, ...unsigned } = receipt;
+  try {
+    return ed25519.verify(sig, canonicalBytes(unsigned), pub);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Full single-receipt verification per SPEC §4:
+ * signature → delegation chain (at receipt time) → scope covers target → prev linkage.
+ */
+export function verifyReceipt(
+  receipt: Receipt,
+  opts: { expectedOwner?: string; revoked?: Set<string>; expectedPrev?: string | null } = {},
+): VerifyResult {
+  if (receipt.v !== 1) return { ok: false, error: 'unsupported receipt version' };
+  if (!verifyReceiptSignature(receipt)) return { ok: false, error: 'bad receipt signature' };
+
+  const ts = new Date(receipt.ts);
+  if (Number.isNaN(ts.getTime())) return { ok: false, error: 'invalid ts' };
+
+  const chain = verifyChain(receipt.delegation, {
+    agentId: receipt.agent_id,
+    expectedRoot: opts.expectedOwner,
+    revoked: opts.revoked,
+    at: ts,
+  });
+  if (!chain.ok) return { ok: false, error: `delegation: ${chain.error}` };
+
+  if (!scopesAllow(chain.effectiveScopes!, receipt.target)) {
+    return { ok: false, error: `target ${receipt.target} outside effective scopes` };
+  }
+
+  if (opts.expectedPrev !== undefined && receipt.prev !== opts.expectedPrev) {
+    return { ok: false, error: 'prev hash does not match preceding receipt (chain broken)' };
+  }
+
+  return { ok: true };
+}
+
+/**
+ * Verify an agent's full receipt sequence: every receipt valid and hash-linked
+ * to the one before it. Returns the index of the first bad receipt on failure.
+ */
+export function verifyReceiptChain(
+  receipts: Receipt[],
+  opts: { expectedOwner?: string; revoked?: Set<string> } = {},
+): VerifyResult & { failedIndex?: number } {
+  let expectedPrev: string | null = null;
+  for (let i = 0; i < receipts.length; i++) {
+    const r = receipts[i]!;
+    const result = verifyReceipt(r, { ...opts, expectedPrev });
+    if (!result.ok) return { ok: false, error: `receipt ${i}: ${result.error}`, failedIndex: i };
+    expectedPrev = receiptHash(r);
+  }
+  return { ok: true };
+}