@correntelabs/beeai-ashlar-bridge 1.0.0

package/dist/src/x402/mandate.js

@@ -0,0 +1,1234 @@
+/**
+ * x402-mandate/1 — the authority a payment carries, not just the payment.
+ *
+ * x402 today proves "money moved." It says nothing about whether the agent
+ * that moved it was ALLOWED to. A Mandate is the missing half: a compact,
+ * signed capability a principal (a human, or a parent agent) issues to an
+ * agent —
+ *
+ *     "spend up to CAP, to recipients in R, for purpose P, until T"
+ *
+ * — whose digest is bound into the x402 payment preimage, so a single receipt
+ * proves BOTH that money moved AND that the payer held authority for exactly
+ * this action, within these bounds. Verification is OFFLINE (no callback) and
+ * PORTABLE across schemes and chains, because a Mandate constrains AUTHORITY
+ * and never touches SETTLEMENT.
+ *
+ * ── THE TRUST CHAIN (who is allowed to say what) ──
+ * The issuer-signed Mandate is the single trust root. It names, IN the signed
+ * bytes, the ACCOUNTANT that commits spend heads: either one Ed25519 key
+ * (Model A — a named notary/issuer/custodian, the model regulated deployments
+ * ask for) or the literal 'payees' (Model B — no single accountant; every
+ * entry is co-signed by its payee). A head is only acceptable when its own
+ * accountant field MATCHES the mandate's and its signature verifies against
+ * that key — a presenter can never introduce "the accountant" themselves.
+ *
+ * ── WHAT EACH CHECK PROVES, STATED HONESTLY ──
+ * checkPayment — ONE payment's authority: grant signature, digest binding,
+ * payer, recipient scope, asset, per-payment bound, cap ceiling, expiry on the
+ * VERIFIER's clock. It does not touch accounting.
+ *
+ * verifySpendWithinCap — a presented history is INTERNALLY sound: mandate-
+ * bound, scope-checked, duplicate-free, append-only-chained, within cap. A
+ * truncated PREFIX still passes — this alone is tamper-evidence, not
+ * completeness.
+ *
+ * verifySpendAgainstCommitment (Model A) — the presented history reproduces an
+ * accountant-committed head (root AND total), with the accountant taken from
+ * the mandate. Completeness holds ONLY against a freshness floor: pass the
+ * highest seq you have accepted (or read the highest anchored seq from Layer
+ * 2). Passing lastSeq=null is an explicit downgrade to tamper-evidence and is
+ * warned as such — a first-contact verifier without an anchor lookup or a
+ * challenge-response gets NO completeness guarantee.
+ *
+ * verifySpendWithPayeeAttestations (Model B) — every presented entry is
+ * co-signed by its payee (recipient identity IS the payee's Ed25519 key), so
+ * FABRICATION is impossible. Entry-backing ALONE does not detect omission:
+ * dropping an entry plus its attestation passes. Omission-resistance comes
+ * from reconcilePayeeEvidence below — the verifier reconciles the presented
+ * log against payee evidence it gathered INDEPENDENTLY of the agent (from the
+ * payees, or by scanning their anchors): admitted attestations absent from
+ * the log refuse; the attested floor binding the cap refuses; payee
+ * equivocation refuses; junk/foreign attestations warn but never veto.
+ *
+ * ── COUNTERPARTY MUST-RULES (the protocol the checks assume) ──
+ * A counterparty that wants the cap to bind MUST: (1) before settling, obtain
+ * the current head and require committedTotal + amount <= cap; (2) after
+ * settling, require a NEW head with seq > previous whose log includes THIS
+ * paymentId (verifyPaymentCommitted below); (3) treat failure to produce it as
+ * default. An authorized payment that is never committed is otherwise
+ * invisible to every later verifier.
+ *
+ * LAYER 2: commitmentAnchorCalldata anchors each head on Coston2 (the evidence
+ * lane's x402note/1 grammar, now carrying `by=<accountant>`), which makes an
+ * equivocating accountant publicly detectable and gives first-contact
+ * verifiers a freshness source. Anchoring is permissionless; an anchor proves
+ * WHEN a head existed, never that its contents are honest — verification
+ * always re-runs the trust chain above.
+ *
+ * Amounts are INTEGER minor-unit decimal strings (exact BigInt arithmetic, no
+ * float in a money path). NOTE (quiet): intentionally NOT in the published SDK.
+ */
+import { createHash, createPublicKey, verify as edVerify } from 'node:crypto';
+import { jcsCanonical, assertJcsSafe } from './manifest-sig.js';
+import { transcriptRoot, inclusionProof, verifyInclusion, EMPTY_ROOT, } from './merkle-transcript.js';
+export const MANDATE_VERSION = 'x402-mandate/1';
+/** Domain-separation tag: the signed/hashed input is TAG || JCS(mandate). */
+const DS_TAG = Buffer.from(MANDATE_VERSION + '\n', 'utf8');
+/** Recipient sentinel: an EXPLICIT, signed opt-in to an unconstrained payee set. Must be the SOLE element. */
+export const ANY_RECIPIENT = '*';
+/** Accountant sentinel selecting Model B: spend entries are co-signed by their payees; no single accountant key. */
+export const PAYEES_ACCOUNTANT = 'payees';
+/** 32-byte Ed25519 public key, base64url, unpadded (43 chars). */
+const B64URL_KEY = /^[A-Za-z0-9_-]{43}$/;
+const SHA256_PREFIXED = /^sha256:[0-9a-f]{64}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+/**
+ * paymentId charset: non-empty, 1–64 chars, excludes the anchor-grammar
+ * separators (';' '@' '#' '=') and newline so it is safe both in the §7 binding
+ * preimage and embedded raw in the §10 payee-anchor calldata (…@<paymentId>;by=).
+ */
+const PAYMENT_ID = /^[A-Za-z0-9._~-]{1,64}$/;
+/** True iff a string is well-formed UTF-16 (no unpaired surrogate). Feature-detects for Node <20. */
+const isWellFormedUtf16 = (s) => typeof s.isWellFormed === 'function'
+    ? s.isWellFormed()
+    : !/[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/.test(s);
+const INT = /^(0|[1-9][0-9]*)$/;
+const isInt = (s) => typeof s === 'string' && INT.test(s);
+const assertInt = (s, field) => {
+    if (!isInt(s))
+        throw new Error(`${field} must be a non-negative integer minor-unit string, got ${JSON.stringify(s)}`);
+    return BigInt(s);
+};
+/**
+ * Strict RFC 3339 UTC ('...Z'). Shape-checked, parsed, then ROUND-TRIPPED so a
+ * shape-valid-but-overflowing date (2026-02-30, hour 24) that Date.parse would
+ * silently normalize is rejected instead. Never local-time-parses.
+ */
+const RFC3339_UTC = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+function parseUtc(s) {
+    if (typeof s !== 'string' || !RFC3339_UTC.test(s))
+        return null;
+    const t = Date.parse(s);
+    if (Number.isNaN(t))
+        return null;
+    // Round-trip: normalize both sides to millisecond precision and compare.
+    const canonical = new Date(t).toISOString(); // always .SSSZ
+    const padded = s.includes('.')
+        ? s.replace(/\.(\d{1,3})Z$/, (_, f) => '.' + f.padEnd(3, '0') + 'Z')
+        : s.replace(/Z$/, '.000Z');
+    return canonical === padded ? t : null;
+}
+/** Closed key sets — unknown members are rejected on all three signed objects (§18). */
+const MANDATE_KEYS = new Set(['v', 'issuer', 'subject', 'asset', 'cap', 'perPayment', 'recipients', 'accountant', 'purpose', 'notAfter', 'nonce', 'parent']);
+const COMMIT_KEYS = new Set(['v', 'mandateDigest', 'accountant', 'seq', 'root', 'total', 'at']);
+const ATT_KEYS = new Set(['v', 'mandateDigest', 'paymentId', 'payee', 'asset', 'amount', 'at']);
+/** First unknown key in `obj` not in `allowed`, or null. */
+const unknownKey = (obj, allowed) => {
+    for (const k of Object.keys(obj))
+        if (!allowed.has(k))
+            return k;
+    return null;
+};
+/** Structural validation. Returns an error string, or null when well-formed. */
+function mandateShapeError(m) {
+    if (!m || typeof m !== 'object')
+        return 'mandate is not an object';
+    const x = m;
+    if (x.v !== MANDATE_VERSION)
+        return `mandate.v must be ${MANDATE_VERSION}`;
+    for (const k of Object.keys(x)) {
+        if (!MANDATE_KEYS.has(k))
+            return `mandate carries an unknown member '${k}' — the object is closed (fail closed on unknown fields)`;
+    }
+    for (const f of ['issuer', 'subject', 'asset', 'cap', 'accountant', 'purpose', 'notAfter', 'nonce']) {
+        if (typeof x[f] !== 'string')
+            return `mandate.${f} must be a string`;
+        if (!isWellFormedUtf16(x[f]))
+            return `mandate.${f} is not well-formed UTF-16 (unpaired surrogate)`;
+    }
+    if (x.parent !== undefined && typeof x.parent === 'string' && !isWellFormedUtf16(x.parent))
+        return 'mandate.parent is not well-formed UTF-16';
+    if (!B64URL_KEY.test(x.issuer))
+        return 'mandate.issuer must be a base64url Ed25519 public key';
+    if (!isInt(x.cap))
+        return 'mandate.cap must be an integer minor-unit string';
+    if (x.perPayment !== undefined && !isInt(x.perPayment))
+        return 'mandate.perPayment must be an integer minor-unit string';
+    if (x.perPayment !== undefined && BigInt(x.perPayment) > BigInt(x.cap)) {
+        return 'mandate.perPayment exceeds cap — a per-payment bound above the cumulative cap is incoherent';
+    }
+    if (!Array.isArray(x.recipients) || !x.recipients.every((r) => typeof r === 'string'))
+        return 'mandate.recipients must be a string[]';
+    if (!x.recipients.every(isWellFormedUtf16))
+        return 'mandate.recipients contains a value that is not well-formed UTF-16';
+    if (x.recipients.length === 0)
+        return 'mandate.recipients is empty — use [ANY_RECIPIENT] for an explicit unconstrained opt-in';
+    if (x.recipients.includes(ANY_RECIPIENT) && x.recipients.length > 1) {
+        return `'${ANY_RECIPIENT}' must be the SOLE element to opt into an unconstrained recipient set`;
+    }
+    const acct = x.accountant;
+    if (acct !== PAYEES_ACCOUNTANT && !B64URL_KEY.test(acct)) {
+        return `mandate.accountant must be a base64url Ed25519 key (Model A) or '${PAYEES_ACCOUNTANT}' (Model B)`;
+    }
+    if (acct === PAYEES_ACCOUNTANT && !x.recipients.every((r) => r === ANY_RECIPIENT || B64URL_KEY.test(r))) {
+        return "under the 'payees' accountant every recipient must itself be a base64url Ed25519 key (the identity IS the attesting key)";
+    }
+    if (parseUtc(x.notAfter) === null)
+        return 'mandate.notAfter must be strict RFC 3339 UTC (…Z)';
+    if (x.parent !== undefined && (typeof x.parent !== 'string' || !SHA256_PREFIXED.test(x.parent))) {
+        return 'mandate.parent must be sha256:<64-hex> (the parent mandate digest)';
+    }
+    return null;
+}
+function canonicalBytes(m) {
+    assertJcsSafe(m);
+    return Buffer.concat([DS_TAG, Buffer.from(jcsCanonical(m), 'utf8')]);
+}
+/** The digest a payment binds to (domain-separated). */
+export function mandateDigest(m) {
+    return 'sha256:' + createHash('sha256').update(canonicalBytes(m)).digest('hex');
+}
+/** True iff a recipient is allowed by the mandate's scope. */
+function recipientAllowed(m, recipient) {
+    if (m.recipients.length === 1 && m.recipients[0] === ANY_RECIPIENT)
+        return true;
+    return m.recipients.includes(recipient);
+}
+function ed25519Verify(bytes, publicKeyB64url, sigB64url) {
+    try {
+        const key = createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: publicKeyB64url }, format: 'jwk' });
+        return edVerify(null, bytes, key, Buffer.from(sigB64url, 'base64url'));
+    }
+    catch {
+        return false;
+    }
+}
+/** Sign a mandate with the principal's key. Rejects malformed grants, perPayment>cap, and a signer that is not the issuer. */
+export function issueMandate(m, signer) {
+    const shape = mandateShapeError(m);
+    if (shape)
+        throw new Error(`refusing to issue a malformed mandate: ${shape}`);
+    if (signer.publicKeyB64url !== m.issuer) {
+        throw new Error('signer public key does not match mandate.issuer — refusing to issue a grant nobody can attribute');
+    }
+    const cap = assertInt(m.cap, 'cap');
+    if (m.perPayment !== undefined && assertInt(m.perPayment, 'perPayment') > cap) {
+        throw new Error('perPayment exceeds cap — a per-payment bound above the cumulative cap is incoherent');
+    }
+    return { mandate: m, alg: 'Ed25519', sig: signer.sign(canonicalBytes(m)) };
+}
+/** Verify the issuer's signature over the (domain-separated) grant, offline. False on any structural or crypto failure. */
+export function verifyMandateSignature(sm) {
+    if (!sm || sm.alg !== 'Ed25519' || typeof sm.sig !== 'string')
+        return false;
+    if (mandateShapeError(sm.mandate))
+        return false;
+    try {
+        return ed25519Verify(canonicalBytes(sm.mandate), sm.mandate.issuer, sm.sig);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * The offline authority check for ONE payment against a Mandate. Total —
+ * returns a verdict, never throws — and judges expiry on the VERIFIER's clock,
+ * not the payer's self-asserted `at`.
+ *
+ * MULTI-PAYEE (`payment.splits`): a payment may pay several recipients at once
+ * (x402 `extra.splits`). EVERY leg is scope-checked, and the per-payment bound
+ * and the cap bind the TOTAL across all legs. Without that, a mandate scoped to
+ * one merchant would authorize a payment that also pays eight strangers, and a
+ * cap would bind only the primary leg while the real outflow exceeded it — the
+ * exact failure this object exists to prevent, re-entering through a scheme
+ * feature. Absent/empty `splits` is byte-for-byte today's behaviour.
+ *
+ * HONESTY: this bounds ONE payment's total. The spend LOG still records a
+ * single (recipient, amount) per entry, so a multi-leg payment's per-leg
+ * breakdown is not represented in the Merkle log — cumulative accounting sees
+ * the primary leg only. Log the TOTAL as the entry amount until SpendEntry
+ * grows legs, and treat per-leg cumulative attribution as unsolved.
+ */
+export function checkPayment(sm, payment, opts) {
+    const reasons = [];
+    const warnings = [];
+    const shape = mandateShapeError(sm?.mandate);
+    if (shape)
+        return { ok: false, reasons: [`malformed mandate: ${shape}`], warnings };
+    if (!payment || typeof payment !== 'object')
+        return { ok: false, reasons: ['payment is not an object'], warnings };
+    const m = sm.mandate;
+    if (!verifyMandateSignature(sm))
+        reasons.push('mandate signature not authentic against issuer');
+    let digest;
+    try {
+        digest = mandateDigest(m);
+    }
+    catch (e) {
+        reasons.push(`mandate digest computation failed (unsignable string): ${e.message}`);
+        digest = 'invalid';
+    }
+    if (payment.mandateDigest !== digest)
+        reasons.push('payment is not bound to this mandate (digest mismatch)');
+    if (payment.payer !== m.subject)
+        reasons.push(`payer ${payment.payer} is not the mandate subject ${m.subject}`);
+    if (payment.asset !== m.asset)
+        reasons.push(`payment asset ${payment.asset} does not match mandate asset ${m.asset}`);
+    if (!recipientAllowed(m, payment.recipient))
+        reasons.push(`recipient ${payment.recipient} is not in the mandate's allowed set`);
+    if (m.recipients.length === 1 && m.recipients[0] === ANY_RECIPIENT)
+        warnings.push('mandate opts into an unconstrained recipient set (ANY_RECIPIENT)');
+    // Every leg is scope-checked and every leg's amount counts. `splits` is
+    // hostile input like any other: a non-array, or a leg with a bad shape,
+    // REFUSES rather than being skipped — a silently-ignored leg is money that
+    // moved outside the bounds.
+    let splitTotal = 0n;
+    let splitsUsable = true;
+    if (payment.splits !== undefined) {
+        if (!Array.isArray(payment.splits)) {
+            reasons.push('payment.splits must be an array when present');
+            splitsUsable = false;
+        }
+        else {
+            for (let i = 0; i < payment.splits.length; i++) {
+                const leg = payment.splits[i];
+                if (!leg || typeof leg !== 'object') {
+                    reasons.push(`split leg ${i} is not an object`);
+                    splitsUsable = false;
+                    continue;
+                }
+                if (typeof leg.recipient !== 'string') {
+                    reasons.push(`split leg ${i} recipient must be a string`);
+                    splitsUsable = false;
+                    continue;
+                }
+                if (!recipientAllowed(m, leg.recipient))
+                    reasons.push(`split leg ${i} recipient ${leg.recipient} is not in the mandate's allowed set`);
+                if (!isInt(leg.amount)) {
+                    reasons.push(`split leg ${i} amount must be a non-negative integer minor-unit string`);
+                    splitsUsable = false;
+                    continue;
+                }
+                splitTotal += BigInt(leg.amount);
+            }
+        }
+    }
+    if (!isInt(payment.amount)) {
+        reasons.push('payment.amount must be a non-negative integer minor-unit string');
+    }
+    else if (splitsUsable) {
+        // The bound is the TOTAL moved by this payment, not the primary leg.
+        const total = BigInt(payment.amount) + splitTotal;
+        const label = splitTotal > 0n ? `${total} across ${(payment.splits?.length ?? 0) + 1} legs` : payment.amount;
+        if (m.perPayment !== undefined && total > BigInt(m.perPayment))
+            reasons.push(`payment ${label} exceeds per-payment bound ${m.perPayment}`);
+        if (total > BigInt(m.cap))
+            reasons.push(`payment ${label} exceeds the cumulative cap ${m.cap} on its own`);
+    }
+    if (payment.at !== undefined && parseUtc(payment.at) === null)
+        reasons.push('payment.at is not strict RFC 3339 UTC');
+    const now = opts?.now ? opts.now() : Date.now();
+    if (now >= parseUtc(m.notAfter))
+        reasons.push('mandate has expired (verifier clock is at or past notAfter)');
+    return { ok: reasons.length === 0, reasons, warnings };
+}
+const spendLeaf = (e) => ({
+    drawId: `${e.mandateDigest}|${e.paymentId}`,
+    nonce: `${e.recipient}|${e.asset}`,
+    seed: `${e.amount}:${e.cumulative}:${e.priorRoot}`,
+});
+/** An append-only, mandate-bound, Merkle-committed record of spend under one mandate. */
+export class SpendLog {
+    mandateDigestHex;
+    asset;
+    entries = [];
+    ids = new Set();
+    constructor(mandateDigestHex, asset) {
+        this.mandateDigestHex = mandateDigestHex;
+        this.asset = asset;
+        if (!SHA256_PREFIXED.test(mandateDigestHex)) {
+            throw new Error('SpendLog mandateDigest must be sha256:<64-hex> (use mandateDigest())');
+        }
+    }
+    add(paymentId, recipient, amount) {
+        if (typeof paymentId !== 'string' || !PAYMENT_ID.test(paymentId))
+            throw new Error('paymentId must match ^[A-Za-z0-9._~-]{1,64}$ (non-empty, no grammar separators)');
+        const amt = assertInt(amount, 'amount');
+        if (this.ids.has(paymentId))
+            throw new Error(`duplicate paymentId ${paymentId} — a payment cannot be counted twice`);
+        const prev = this.entries.length ? assertInt(this.entries[this.entries.length - 1].cumulative, 'cumulative') : 0n;
+        this.entries.push({
+            mandateDigest: this.mandateDigestHex, asset: this.asset, paymentId, recipient,
+            amount, cumulative: (prev + amt).toString(), priorRoot: this.root(),
+        });
+        this.ids.add(paymentId);
+        return this;
+    }
+    get size() { return this.entries.length; }
+    all() { return this.entries.map((e) => ({ ...e })); }
+    total() { return this.entries.length ? this.entries[this.entries.length - 1].cumulative : '0'; }
+    root() { return transcriptRoot(this.entries.map(spendLeaf)); }
+    prove(index) {
+        const entry = this.entries[index];
+        if (!entry)
+            throw new Error(`index ${index} outside spend log of ${this.entries.length}`);
+        return { entry, index, size: this.entries.length, proof: inclusionProof(this.entries.map(spendLeaf), index) };
+    }
+    /**
+     * Produce the committed head over the current (root, total) at a monotonic
+     * seq. This is the ONLY blessed committing path: the root and total are
+     * derived from the entries the log actually holds, never handed in — an
+     * accountant signing a (root, total) it did not derive is signing blind.
+     */
+    commit(seq, accountant, at) {
+        return commitHead({
+            v: COMMIT_VERSION, mandateDigest: this.mandateDigestHex, accountant: accountant.publicKeyB64url,
+            seq, root: this.root(), total: this.total(), at,
+        }, accountant);
+    }
+}
+/** Verify one spend entry belongs to a committed spend-log root, holding nothing else. */
+export function verifySpendEntry(entry, index, size, proof, root) {
+    return verifyInclusion(spendLeaf(entry), index, size, proof, root);
+}
+/**
+ * Verify a presented spend history is INTERNALLY sound against a mandate:
+ * authenticated grant, every entry bound to THIS mandate + asset, scope and
+ * per-payment re-checked, duplicate paymentIds refused, append-only chain
+ * verified, running totals gap-free, total within cap.
+ *
+ * HONESTY: a truncated PREFIX of the true history passes all of this. This
+ * function alone is tamper-evidence, not completeness — completeness comes
+ * from a committed head (Model A) with a freshness floor.
+ */
+export function verifySpendWithinCap(sm, entries) {
+    const reasons = [];
+    const warnings = [];
+    const shape = mandateShapeError(sm?.mandate);
+    if (shape)
+        return { ok: false, reasons: [`malformed mandate: ${shape}`], warnings };
+    if (!verifyMandateSignature(sm))
+        return { ok: false, reasons: ['mandate signature not authentic against issuer'], warnings };
+    const m = sm.mandate;
+    if (m.recipients.length === 1 && m.recipients[0] === ANY_RECIPIENT)
+        warnings.push('mandate opts into an unconstrained recipient set (ANY_RECIPIENT)');
+    const digest = mandateDigest(m);
+    const cap = BigInt(m.cap);
+    const per = m.perPayment !== undefined ? BigInt(m.perPayment) : null;
+    let running = 0n;
+    const seen = new Set();
+    const priorLeaves = [];
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        if (e.mandateDigest !== digest) {
+            reasons.push(`entry ${i} is bound to a different mandate`);
+            break;
+        }
+        if (e.asset !== m.asset) {
+            reasons.push(`entry ${i} asset ${e.asset} != mandate asset ${m.asset}`);
+            break;
+        }
+        if (seen.has(e.paymentId)) {
+            reasons.push(`entry ${i} duplicates paymentId ${e.paymentId} — a payment cannot be counted twice`);
+            break;
+        }
+        seen.add(e.paymentId);
+        if (!recipientAllowed(m, e.recipient)) {
+            reasons.push(`entry ${i} recipient ${e.recipient} is outside the mandate scope`);
+            break;
+        }
+        if (!isInt(e.amount)) {
+            reasons.push(`entry ${i} amount is not an integer minor-unit string`);
+            break;
+        }
+        const amt = BigInt(e.amount);
+        if (per !== null && amt > per) {
+            reasons.push(`entry ${i} amount ${e.amount} exceeds per-payment bound ${m.perPayment}`);
+            break;
+        }
+        const expectedPrior = priorLeaves.length ? transcriptRoot(priorLeaves) : EMPTY_ROOT;
+        if (e.priorRoot !== expectedPrior) {
+            reasons.push(`entry ${i} priorRoot breaks the append-only chain (edit/reorder/insert)`);
+            break;
+        }
+        running += amt;
+        if (!isInt(e.cumulative) || BigInt(e.cumulative) !== running) {
+            reasons.push(`entry ${i} cumulative ${e.cumulative} != running total ${running} — the log is not gap-free`);
+            break;
+        }
+        priorLeaves.push(spendLeaf(e));
+    }
+    if (reasons.length === 0 && running > cap)
+        reasons.push(`total spend ${running} exceeds cap ${m.cap}`);
+    return { ok: reasons.length === 0, reasons, warnings };
+}
+// ──────────────────── Model A: the committed head ────────────────────
+export const COMMIT_VERSION = 'x402-mandate-commit/1';
+const DS_COMMIT = Buffer.from(COMMIT_VERSION + '\n', 'utf8');
+function commitBytes(c) {
+    assertJcsSafe(c);
+    return Buffer.concat([DS_COMMIT, Buffer.from(jcsCanonical(c), 'utf8')]);
+}
+/** Sign a committed head. Prefer SpendLog.commit, which derives root/total from real entries. */
+export function commitHead(c, accountant) {
+    if (c.v !== COMMIT_VERSION)
+        throw new Error(`commitment.v must be ${COMMIT_VERSION}`);
+    const uk = c && typeof c === 'object' ? unknownKey(c, COMMIT_KEYS) : null;
+    if (uk)
+        throw new Error(`commitment carries an unknown member '${uk}' — the object is closed`);
+    if (!SHA256_PREFIXED.test(c.mandateDigest))
+        throw new Error('commitment.mandateDigest must be sha256:<64-hex>');
+    if (!HEX64.test(c.root))
+        throw new Error('commitment.root must be 64-hex');
+    if (!B64URL_KEY.test(c.accountant))
+        throw new Error('commitment.accountant must be a base64url Ed25519 key');
+    if (accountant.publicKeyB64url !== c.accountant)
+        throw new Error('signer key does not match commitment.accountant');
+    if (!Number.isInteger(c.seq) || c.seq < 0 || c.seq > 1e15 - 1)
+        throw new Error('commitment.seq must be an integer in [0, 10^15-1]');
+    assertInt(c.total, 'commitment.total');
+    if (parseUtc(c.at) === null)
+        throw new Error('commitment.at must be strict RFC 3339 UTC');
+    return { commitment: c, alg: 'Ed25519', sig: accountant.sign(commitBytes(c)) };
+}
+/**
+ * Verify a head is SELF-consistent: signed by the key it names as accountant.
+ * Self-consistency is not authorization — verifySpendAgainstCommitment also
+ * requires that key to equal the MANDATE's accountant (the trust root).
+ */
+export function verifyCommitment(sc) {
+    if (!sc || sc.alg !== 'Ed25519' || typeof sc.sig !== 'string' || sc.commitment?.v !== COMMIT_VERSION)
+        return false;
+    if (unknownKey(sc.commitment, COMMIT_KEYS))
+        return false;
+    if (!B64URL_KEY.test(sc.commitment.accountant ?? ''))
+        return false;
+    try {
+        return ed25519Verify(commitBytes(sc.commitment), sc.commitment.accountant, sc.sig);
+    }
+    catch {
+        return false;
+    }
+}
+/** LAYER 2: the digest anchored on-chain / in a transparency log. */
+export function commitmentAnchorDigest(sc) {
+    return 'sha256:' + createHash('sha256')
+        .update(Buffer.concat([commitBytes(sc.commitment), Buffer.from(sc.sig, 'base64url')]))
+        .digest('hex');
+}
+/**
+ * LAYER 2 calldata (the evidence lane's x402note/1 grammar). Carries the
+ * mandate + seq so a scanner can find the highest anchored head for a mandate,
+ * and `by=<accountant>` so anchors are attributable without fetching the head.
+ * Anchoring is permissionless: an anchor proves WHEN, never honesty.
+ */
+export function commitmentAnchorCalldata(sc) {
+    if (!SHA256_PREFIXED.test(sc.commitment.mandateDigest))
+        throw new Error('commitment.mandateDigest must be sha256:<64-hex>');
+    if (!B64URL_KEY.test(sc.commitment.accountant))
+        throw new Error('commitment.accountant must be a base64url Ed25519 key');
+    return `x402note/1;${commitmentAnchorDigest(sc)};for=${sc.commitment.mandateDigest}#${sc.commitment.seq};by=${sc.commitment.accountant}`;
+}
+/** Verify an on-chain anchor's calldata commits to exactly THIS head. Pair with the tx's block timestamp for the WHEN. */
+export function verifyCommitmentAnchor(sc, calldata) {
+    try {
+        return calldata === commitmentAnchorCalldata(sc);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * MODEL A cap check against a committed head. The accountant is taken from the
+ * MANDATE (the trust root) — a presenter can never name their own. The
+ * presented entries must reproduce the committed root AND total.
+ *
+ * `lastSeq` is REQUIRED: pass the highest seq you have previously accepted for
+ * this mandate (from your own state, or the highest anchored seq you read from
+ * Layer 2). Passing `null` means you have no freshness floor — the check still
+ * runs, but the verdict carries a loud warning: without a floor you get
+ * tamper-evidence, NOT completeness, because an old validly-signed head plus
+ * its prefix log passes (first-contact truncation).
+ */
+export function verifySpendAgainstCommitment(sm, entries, sc, lastSeq) {
+    const base = verifySpendWithinCap(sm, entries);
+    if (!base.ok)
+        return base;
+    const reasons = [];
+    const warnings = [...base.warnings];
+    const m = sm.mandate;
+    if (m.accountant === PAYEES_ACCOUNTANT) {
+        return { ok: false, reasons: ["mandate uses the 'payees' accountant (Model B) — a single-key committed head is not acceptable for it"], warnings };
+    }
+    if (!sc?.commitment || typeof sc.commitment !== 'object') {
+        return { ok: false, reasons: ['committed head is missing or not an object'], warnings };
+    }
+    if (sc?.commitment?.accountant !== m.accountant) {
+        reasons.push('committed head accountant does not match the mandate accountant (the trust root)');
+    }
+    if (!verifyCommitment(sc))
+        reasons.push('committed head signature not self-consistent');
+    if (sc.commitment.mandateDigest !== mandateDigest(m))
+        reasons.push('committed head is for a different mandate');
+    const root = entries.length ? transcriptRoot(entries.map(spendLeaf)) : EMPTY_ROOT;
+    if (root !== sc.commitment.root)
+        reasons.push('presented spend log does not reproduce the committed head root — omission/truncation');
+    const total = entries.length ? entries[entries.length - 1].cumulative : '0';
+    if (total !== sc.commitment.total)
+        reasons.push(`presented total ${total} != committed total ${sc.commitment.total} — omission/truncation`);
+    if (lastSeq === null) {
+        warnings.push('no freshness floor (lastSeq=null): this verdict is tamper-evidence only — an old head passes; read the highest anchored seq or track your own');
+    }
+    else if (sc.commitment.seq <= lastSeq) {
+        reasons.push(`committed head seq ${sc.commitment.seq} is not newer than the last accepted ${lastSeq} — rollback`);
+    }
+    return { ok: reasons.length === 0, reasons, warnings };
+}
+/**
+ * The counterparty's POST-SETTLE check (MUST-rule 2): the payment it just
+ * accepted is INCLUDED under a NEW committed head strictly newer than the one
+ * it saw before settling. This is what forces the head to advance per payment
+ * — an authorized payment that is never committed is otherwise invisible.
+ */
+export function verifyPaymentCommitted(sm, paymentId, proof, newHead, prevSeq, 
+/** OPTIONAL but STRONGLY RECOMMENDED: the fields decoded from the settled
+ * artifact. When supplied, the included entry's recipient/asset/amount MUST
+ * equal them — this is what stops an agent committing a truthful-looking
+ * head over an amount smaller than what actually settled (see §7/§13). */
+settled) {
+    const reasons = [];
+    const warnings = [];
+    const m = sm?.mandate;
+    const shape = mandateShapeError(m);
+    if (shape)
+        return { ok: false, reasons: [`malformed mandate: ${shape}`], warnings };
+    if (!newHead?.commitment || typeof newHead.commitment !== 'object') {
+        return { ok: false, reasons: ['new committed head is missing or not an object'], warnings };
+    }
+    if (!proof || typeof proof !== 'object' || !proof.entry) {
+        return { ok: false, reasons: ['inclusion proof is missing or malformed'], warnings };
+    }
+    if (!verifyMandateSignature(sm))
+        reasons.push('mandate signature not authentic against issuer');
+    if (m.accountant === PAYEES_ACCOUNTANT)
+        reasons.push("mandate uses the 'payees' accountant — Model A inclusion check does not apply");
+    else if (newHead?.commitment?.accountant !== m.accountant)
+        reasons.push('new head accountant does not match the mandate accountant');
+    if (!verifyCommitment(newHead))
+        reasons.push('new head signature not self-consistent');
+    if (newHead.commitment.mandateDigest !== mandateDigest(m))
+        reasons.push('new head is for a different mandate');
+    if (!(Number.isInteger(prevSeq)) || newHead.commitment.seq <= prevSeq) {
+        reasons.push(`new head seq ${newHead.commitment.seq} is not newer than the pre-settle seq ${prevSeq}`);
+    }
+    if (proof.entry.paymentId !== paymentId)
+        reasons.push(`proof is for payment ${proof.entry.paymentId}, expected ${paymentId}`);
+    if (!verifySpendEntry(proof.entry, proof.index, proof.size, proof.proof, newHead.commitment.root)) {
+        reasons.push('payment is NOT included under the new committed head');
+    }
+    if (settled) {
+        const e = proof.entry;
+        if (e.recipient !== settled.recipient)
+            reasons.push(`committed entry recipient ${e.recipient} != settled recipient ${settled.recipient}`);
+        if (e.asset !== settled.asset)
+            reasons.push(`committed entry asset ${e.asset} != settled asset ${settled.asset}`);
+        if (e.amount !== settled.amount)
+            reasons.push(`committed entry amount ${e.amount} != settled amount ${settled.amount} — under-reported spend`);
+    }
+    else {
+        warnings.push('no settled fields supplied: entry amount/recipient/asset are agent-asserted, not verified against the rail');
+    }
+    return { ok: reasons.length === 0, reasons, warnings };
+}
+// ──────────────────── Model B: aggregated payee attestations ────────────────────
+export const PAYEE_ATT_VERSION = 'x402-mandate-payee/1';
+const DS_PAYEE = Buffer.from(PAYEE_ATT_VERSION + '\n', 'utf8');
+function payeeBytes(a) {
+    assertJcsSafe(a);
+    return Buffer.concat([DS_PAYEE, Buffer.from(jcsCanonical(a), 'utf8')]);
+}
+/** The payee signs "I received this payment under this mandate." Signer's key must BE the payee identity. */
+export function attestPayment(a, payee) {
+    if (a.v !== PAYEE_ATT_VERSION)
+        throw new Error(`attestation.v must be ${PAYEE_ATT_VERSION}`);
+    const uk = a && typeof a === 'object' ? unknownKey(a, ATT_KEYS) : null;
+    if (uk)
+        throw new Error(`attestation carries an unknown member '${uk}' — the object is closed`);
+    if (!B64URL_KEY.test(a.payee))
+        throw new Error('attestation.payee must be a base64url Ed25519 key (the recipient identity IS the key)');
+    if (payee.publicKeyB64url !== a.payee)
+        throw new Error('signer key does not match attestation.payee');
+    if (!SHA256_PREFIXED.test(a.mandateDigest))
+        throw new Error('attestation.mandateDigest must be sha256:<64-hex>');
+    assertInt(a.amount, 'attestation.amount');
+    if (parseUtc(a.at) === null)
+        throw new Error('attestation.at must be strict RFC 3339 UTC');
+    return { attestation: a, alg: 'Ed25519', sig: payee.sign(payeeBytes(a)) };
+}
+/** Verify a payee attestation's signature against the payee identity itself, offline. */
+export function verifyPayeeAttestation(spa) {
+    if (!spa || spa.alg !== 'Ed25519' || typeof spa.sig !== 'string' || spa.attestation?.v !== PAYEE_ATT_VERSION)
+        return false;
+    if (unknownKey(spa.attestation, ATT_KEYS))
+        return false;
+    if (!B64URL_KEY.test(spa.attestation.payee ?? ''))
+        return false;
+    try {
+        return ed25519Verify(payeeBytes(spa.attestation), spa.attestation.payee, spa.sig);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * MODEL B check: every presented entry must be backed by an authentic
+ * attestation signed by the RECIPIENT ITSELF (identity == key). Requires the
+ * mandate's accountant to be 'payees'.
+ *
+ * WHAT THIS PROVES: no fabricated entries — an agent cannot invent a payment a
+ * payee never acknowledged.
+ * WHAT IT DOES NOT PROVE: completeness. Dropping an entry AND its attestation
+ * passes. Do not present this check alone as omission-proof — completeness in
+ * Model B comes from reconcilePayeeEvidence below, run against payee evidence
+ * the verifier gathered independently of the agent.
+ */
+export function verifySpendWithPayeeAttestations(sm, entries, attestations) {
+    const base = verifySpendWithinCap(sm, entries);
+    if (!base.ok)
+        return base;
+    const reasons = [];
+    const warnings = [...base.warnings];
+    if (sm.mandate.accountant !== PAYEES_ACCOUNTANT) {
+        return { ok: false, reasons: ["mandate does not use the 'payees' accountant — use the committed-head path (Model A)"], warnings };
+    }
+    const digest = mandateDigest(sm.mandate);
+    // Keyed by paymentId|recipient so the RIGHT payee's attestation backs each
+    // entry even when two payees reference one paymentId.
+    const byId = new Map(attestations.map((a) => [`${a.attestation.paymentId}|${a.attestation.payee}`, a]));
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        const spa = byId.get(`${e.paymentId}|${e.recipient}`);
+        if (!spa) {
+            reasons.push(`entry ${i} (payment ${e.paymentId}) has no payee attestation from its recipient — an unbacked agent claim`);
+            break;
+        }
+        const a = spa.attestation;
+        if (a.payee !== e.recipient) {
+            reasons.push(`entry ${i} attestation payee ${a.payee} != entry recipient ${e.recipient}`);
+            break;
+        }
+        if (!verifyPayeeAttestation(spa)) {
+            reasons.push(`entry ${i} payee attestation is not authentic (must be signed by the recipient's own key)`);
+            break;
+        }
+        if (a.mandateDigest !== digest) {
+            reasons.push(`entry ${i} payee attestation is for a different mandate`);
+            break;
+        }
+        if (a.asset !== e.asset || a.amount !== e.amount) {
+            reasons.push(`entry ${i} attestation amount/asset disagrees with the entry`);
+            break;
+        }
+        if (parseUtc(a.at) === null) {
+            reasons.push(`entry ${i} attestation.at is not strict RFC 3339 UTC`);
+            break;
+        }
+    }
+    return { ok: reasons.length === 0, reasons, warnings };
+}
+/** The digest a payee attestation is anchored under. */
+export function payeeAttestationAnchorDigest(spa) {
+    return 'sha256:' + createHash('sha256')
+        .update(Buffer.concat([payeeBytes(spa.attestation), Buffer.from(spa.sig, 'base64url')]))
+        .digest('hex');
+}
+/**
+ * A payee anchors ITS OWN evidence (the x402note/1 grammar; `@<paymentId>`
+ * keeps attestation anchors distinguishable from head anchors' `#<seq>`). This
+ * is what makes an omitted payment publicly discoverable: the agent controls
+ * its log, but it does not control the payee's anchor.
+ */
+export function payeeAttestationAnchorCalldata(spa) {
+    const a = spa.attestation;
+    if (!SHA256_PREFIXED.test(a.mandateDigest))
+        throw new Error('attestation.mandateDigest must be sha256:<64-hex>');
+    if (!B64URL_KEY.test(a.payee))
+        throw new Error('attestation.payee must be a base64url Ed25519 key');
+    return `x402note/1;${payeeAttestationAnchorDigest(spa)};for=${a.mandateDigest}@${a.paymentId};by=${a.payee}`;
+}
+/**
+ * MODEL B OMISSION-RESISTANCE — the payee-evidence reconciler. `evidence` is
+ * the set of payee attestations the VERIFIER gathered INDEPENDENTLY (from the
+ * payees, or by scanning their anchors) — never from the agent. Then:
+ *
+ *   1. the presented entries must all be payee-backed (no fabrication), AND
+ *   2. every valid attestation for THIS mandate must appear in the log — an
+ *      attested payment with no entry is the OMISSION, caught by the party who
+ *      cannot un-know it was paid, AND
+ *   3. the attested floor (sum over all attested payments, whether logged or
+ *      not) must be within cap — a short log cannot hide over-spend the payees
+ *      can prove.
+ *
+ * Hostile-input hygiene: attestations that fail signature verification or
+ * belong to other mandates are IGNORED with a warning (a stranger cannot DoS a
+ * verdict with junk); two authentic attestations from one payee for one
+ * paymentId with different facts = payee equivocation, refused loudly.
+ */
+export function reconcilePayeeEvidence(sm, entries, evidence) {
+    const reasons = [];
+    const warnings = [];
+    const shape = mandateShapeError(sm?.mandate);
+    if (shape)
+        return { ok: false, reasons: [`malformed mandate: ${shape}`], warnings };
+    const digest = mandateDigest(sm.mandate);
+    // 1. ADMIT the evidence set first: only authentic, this-mandate, IN-SCOPE
+    //    attestations count; junk and out-of-scope keys are noise, not veto (a
+    //    stranger cannot force a refusal); equivocation is same-payee only.
+    //    Keyed by `${payee}|${paymentId}` so a second payee reusing a known
+    //    paymentId is not mistaken for the first payee equivocating.
+    const scoped = !(sm.mandate.recipients.length === 1 && sm.mandate.recipients[0] === ANY_RECIPIENT);
+    const admitted = new Map();
+    for (const spa of evidence) {
+        if (!verifyPayeeAttestation(spa)) {
+            warnings.push(`ignored an attestation with an invalid signature (payment ${spa?.attestation?.paymentId ?? '?'})`);
+            continue;
+        }
+        const a = spa.attestation;
+        if (a.mandateDigest !== digest) {
+            warnings.push(`ignored an attestation for a different mandate (payment ${a.paymentId})`);
+            continue;
+        }
+        if (scoped && !sm.mandate.recipients.includes(a.payee)) {
+            warnings.push(`ignored an attestation from a payee outside the mandate's recipient scope (payment ${a.paymentId})`);
+            continue;
+        }
+        const key = `${a.payee}|${a.paymentId}`;
+        const prior = admitted.get(key);
+        if (prior) {
+            const p = prior.attestation;
+            if (p.amount !== a.amount || p.asset !== a.asset) {
+                reasons.push(`payee equivocation on payment ${a.paymentId}: same payee, two authentic attestations with different facts`);
+            }
+            continue;
+        }
+        admitted.set(key, spa);
+    }
+    if (reasons.length)
+        return { ok: false, reasons, warnings };
+    // 2. The presented entries must all be backed by the ADMITTED evidence.
+    const base = verifySpendWithPayeeAttestations(sm, entries, [...admitted.values()]);
+    if (!base.ok)
+        return { ok: false, reasons: base.reasons, warnings: [...warnings, ...base.warnings] };
+    warnings.push(...base.warnings);
+    // 3. COMPLETENESS: every attested payment must be in the presented log.
+    const logged = new Set(entries.map((e) => e.paymentId));
+    let attestedFloor = 0n;
+    for (const spa of admitted.values()) {
+        const paymentId = spa.attestation.paymentId;
+        attestedFloor += BigInt(spa.attestation.amount);
+        if (!logged.has(paymentId)) {
+            reasons.push(`OMISSION: payee ${spa.attestation.payee.slice(0, 12)}… attests payment ${paymentId} (${spa.attestation.amount} ${spa.attestation.asset}) absent from the presented log`);
+        }
+    }
+    // 4. The attested floor binds the cap even when the log is short.
+    if (attestedFloor > BigInt(sm.mandate.cap)) {
+        reasons.push(`attested spend floor ${attestedFloor} exceeds cap ${sm.mandate.cap} — over-spend provable from payee evidence alone`);
+    }
+    return { ok: reasons.length === 0, reasons, warnings };
+}
+// ──────────────────── delegation chains: the human origin survives hops ────────────────────
+//
+// A parent's SUBJECT (which must itself be an Ed25519 key for the grant to be
+// delegable) can carve a CHILD grant that only NARROWS: same asset, same
+// accountant, cap and per-payment no larger, expiry no later, recipients a
+// subset (ANY only under ANY). verifyDelegationChain walks root→leaf entirely
+// offline and returns the ROOT ISSUER — the human origin that #3086-style
+// multi-hop delegation otherwise dissolves.
+//
+// HONESTY: narrowing is per-link and static. Nothing here prevents a parent
+// subject from issuing SIBLING children whose caps SUM above the parent cap —
+// aggregate delegation accounting is the accountant's job across the tree and
+// is deliberately not faked statically.
+const effPerPayment = (m) => BigInt(m.perPayment ?? m.cap);
+/** One narrowing violation, or null. Exported logic via issueDelegatedMandate/verifyDelegationChain. */
+function narrowingError(child, parent) {
+    if (child.parent !== mandateDigest(parent))
+        return 'child.parent does not reference the parent mandate digest';
+    if (!B64URL_KEY.test(parent.subject))
+        return 'parent.subject is not an Ed25519 key — this grant is not delegable';
+    if (child.issuer !== parent.subject)
+        return 'child.issuer must be the parent subject (the delegator)';
+    if (child.asset !== parent.asset)
+        return 'child asset differs from parent';
+    if (child.accountant !== parent.accountant)
+        return 'child accountant differs from parent — one accounting domain per chain';
+    if (BigInt(child.cap) > BigInt(parent.cap))
+        return `child cap ${child.cap} exceeds parent cap ${parent.cap}`;
+    if (effPerPayment(child) > effPerPayment(parent))
+        return 'child per-payment bound exceeds the parent\'s';
+    if (parseUtc(child.notAfter) > parseUtc(parent.notAfter))
+        return 'child expiry is later than the parent\'s';
+    const parentAny = parent.recipients.length === 1 && parent.recipients[0] === ANY_RECIPIENT;
+    const childAny = child.recipients.length === 1 && child.recipients[0] === ANY_RECIPIENT;
+    if (!parentAny) {
+        if (childAny)
+            return 'child cannot opt into ANY_RECIPIENT under a scoped parent';
+        for (const r of child.recipients) {
+            if (!parent.recipients.includes(r))
+                return `child recipient ${r} is outside the parent scope`;
+        }
+    }
+    return null;
+}
+/** The parent's subject carves a narrowed child grant. Refuses any widening. */
+export function issueDelegatedMandate(child, parentSm, delegator) {
+    if (!verifyMandateSignature(parentSm))
+        throw new Error('parent mandate signature not authentic — refusing to delegate from it');
+    const shape = mandateShapeError(child);
+    if (shape)
+        throw new Error(`refusing to issue a malformed child mandate: ${shape}`);
+    const narrow = narrowingError(child, parentSm.mandate);
+    if (narrow)
+        throw new Error(`refusing a widening delegation: ${narrow}`);
+    return issueMandate(child, delegator);
+}
+/**
+ * Walk a delegation chain root→leaf, entirely offline: every link signed,
+ * every hop narrowing, the leaf usable exactly like any mandate. Returns the
+ * ROOT ISSUER — the human origin, recoverable at any depth.
+ */
+export function verifyDelegationChain(chain) {
+    const reasons = [];
+    const warnings = [];
+    if (!Array.isArray(chain) || chain.length === 0) {
+        return { ok: false, reasons: ['delegation chain is empty'], warnings };
+    }
+    const root = chain[0];
+    if (root.mandate?.parent !== undefined)
+        reasons.push('chain[0] must be a ROOT grant (no parent)');
+    for (let i = 0; i < chain.length; i++) {
+        const link = chain[i];
+        const shape = mandateShapeError(link?.mandate);
+        if (shape) {
+            reasons.push(`chain[${i}] malformed: ${shape}`);
+            break;
+        }
+        if (!verifyMandateSignature(link)) {
+            reasons.push(`chain[${i}] signature not authentic`);
+            break;
+        }
+        if (i > 0) {
+            const narrow = narrowingError(link.mandate, chain[i - 1].mandate);
+            if (narrow) {
+                reasons.push(`chain[${i}] widens its parent: ${narrow}`);
+                break;
+            }
+        }
+    }
+    if (reasons.length)
+        return { ok: false, reasons, warnings };
+    return { ok: true, reasons, warnings, rootIssuer: root.mandate.issuer };
+}
+// ──────────────────── the preimage binding: enforced, not asserted ────────────────────
+//
+// A MandatePayment's mandateDigest field is only a claim until the SETTLED
+// artifact commits it. Each scheme has exactly one payer-chosen 32-byte slot
+// that its signature covers:
+//
+//   EIP-3009   nonce (bytes32)      — signed in TransferWithAuthorization;
+//                                     the token contract refuses a reused nonce.
+//   Permit2    nonce (uint256)      — signed in PermitTransferFrom; unordered
+//                                     nonces are consumed once.
+//   XRPL       InvoiceID (256-bit)  — carried in the signed Payment tx (our
+//                                     lane forbids Memos; InvoiceID is the slot).
+//
+// The binding rule: that slot MUST equal sha256(DS || mandateDigest || '\n' ||
+// paymentId). A verifier holding the settled artifact re-derives and compares —
+// no trust in any presented field. Determinism gives at-most-once ONLY on the
+// two rails that enforce slot uniqueness: EIP-3009 and Permit2 consume the nonce,
+// so the SAME (mandate, paymentId) settles at most once there. XRPL does NOT
+// enforce InvoiceID uniqueness — two Payments with the same InvoiceID can both
+// settle. Any consumer deriving cumulative-spend conclusions from XRPL evidence
+// MUST de-duplicate observed settlements by (mandateDigest, paymentId) and treat
+// two distinct validated Payments with one derived InvoiceID as spend exceeding
+// the log — the rail will not enforce it.
+//
+// The slot binds only (mandate, paymentId): it does NOT constrain the
+// transferred amount/recipient/asset. verifySettledPayment reads those OUT of
+// the artifact and runs the §6 authority check on them — call it, not
+// verifyPaymentBinding alone, whenever a cap must actually bind.
+export const BINDING_VERSION = 'x402-mandate-binding/1';
+const DS_BIND = Buffer.from(BINDING_VERSION + '\n', 'utf8');
+function bindingHash(mandateDigestStr, paymentId) {
+    if (!SHA256_PREFIXED.test(mandateDigestStr))
+        throw new Error('mandateDigest must be sha256:<64-hex>');
+    if (typeof paymentId !== 'string' || !PAYMENT_ID.test(paymentId))
+        throw new Error('paymentId must match ^[A-Za-z0-9._~-]{1,64}$ (non-empty, no grammar separators)');
+    return createHash('sha256')
+        .update(Buffer.concat([DS_BIND, Buffer.from(mandateDigestStr + '\n' + paymentId, 'utf8')]))
+        .digest();
+}
+/** The bytes32 nonce an EIP-3009 TransferWithAuthorization MUST carry for this (mandate, payment). */
+export function eip3009BindingNonce(mandateDigestStr, paymentId) {
+    return '0x' + bindingHash(mandateDigestStr, paymentId).toString('hex');
+}
+/** The uint256 nonce (decimal string) a Permit2 PermitTransferFrom MUST carry. */
+export function permit2BindingNonce(mandateDigestStr, paymentId) {
+    return BigInt('0x' + bindingHash(mandateDigestStr, paymentId).toString('hex')).toString();
+}
+/** The InvoiceID (uppercase 64-hex, XRPL convention) a Payment tx MUST carry. */
+export function xrplBindingInvoiceId(mandateDigestStr, paymentId) {
+    return bindingHash(mandateDigestStr, paymentId).toString('hex').toUpperCase();
+}
+/**
+ * Verify the binding FROM THE SETTLED ARTIFACT: pass the value read out of the
+ * settled authorization/tx (the EIP-3009 nonce, the Permit2 nonce, the XRPL
+ * InvoiceID) and the claimed (mandate, paymentId). True iff the slot commits to
+ * exactly this pair. Total — false on anything malformed.
+ */
+export function verifyPaymentBinding(scheme, settledValue, mandateDigestStr, paymentId) {
+    try {
+        const h = bindingHash(mandateDigestStr, paymentId);
+        if (typeof settledValue !== 'string')
+            return false;
+        switch (scheme) {
+            case 'eip3009': return settledValue.toLowerCase() === '0x' + h.toString('hex');
+            case 'permit2': return /^(0|[1-9][0-9]*)$/.test(settledValue) && BigInt(settledValue) === BigInt('0x' + h.toString('hex'));
+            case 'xrpl': return /^[0-9A-Fa-f]{64}$/.test(settledValue) && settledValue.toUpperCase() === h.toString('hex').toUpperCase();
+            default: return false;
+        }
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * THE ENFORCEMENT the §7 binding alone cannot give: the binding slot commits
+ * only to (mandate, paymentId), NOT to amount/recipient/asset. A cap that binds
+ * only self-asserted amounts binds nothing on a rail the agent controls. This
+ * check reads the ACTUAL transferred fields out of the settled artifact and
+ * runs the full §6 authority check on THEM — so an agent that settles 1,000,000
+ * cannot log amount='1'. A counterparty deriving cumulative-spend conclusions
+ * MUST call this, not verifyPaymentBinding alone. Total — never throws.
+ */
+export function verifySettledPayment(sm, settled, paymentId, opts) {
+    const shape = mandateShapeError(sm?.mandate);
+    if (shape)
+        return { ok: false, reasons: [`malformed mandate: ${shape}`], warnings: [] };
+    if (!settled || typeof settled !== 'object')
+        return { ok: false, reasons: ['settled transfer is missing or not an object'], warnings: [] };
+    let digest;
+    try {
+        digest = mandateDigest(sm.mandate);
+    }
+    catch (e) {
+        return { ok: false, reasons: [`mandate digest failed: ${e.message}`], warnings: [] };
+    }
+    const reasons = [];
+    if (!verifyPaymentBinding(settled.scheme, settled.slot, digest, paymentId)) {
+        reasons.push('settled slot does not bind (mandate, paymentId) — binding mismatch');
+    }
+    // Run §6 on the fields DECODED from the artifact, not any presented tuple —
+    // including EVERY leg of a multi-payee split, so the cap binds the whole
+    // outflow rather than the primary transfer.
+    const decoded = {
+        payer: settled.payer, recipient: settled.recipient, asset: settled.asset,
+        amount: settled.amount, mandateDigest: digest,
+        ...(settled.splits !== undefined ? { splits: settled.splits } : {}),
+    };
+    const v = checkPayment(sm, decoded, opts);
+    return { ok: reasons.length === 0 && v.ok, reasons: [...reasons, ...v.reasons], warnings: v.warnings };
+}
+/**
+ * Parse an on-chain head-anchor calldata. Tolerates the historic pre-`by=`
+ * grammar so scanners can read every anchor ever made. Returns null on
+ * anything that is not a head anchor (payee anchors use `@`, not `#`).
+ */
+export function parseCommitmentAnchorCalldata(calldata) {
+    if (typeof calldata !== 'string')
+        return null;
+    const m = /^x402note\/1;(sha256:[0-9a-f]{64});for=(sha256:[0-9a-f]{64})#(\d{1,15})(?:;by=([A-Za-z0-9_-]{43}))?$/.exec(calldata);
+    if (!m)
+        return null;
+    const seq = Number(m[3]);
+    if (!Number.isSafeInteger(seq))
+        return null;
+    return { anchorDigest: m[1], mandateDigest: m[2], seq, ...(m[4] ? { by: m[4] } : {}) };
+}
+/**
+ * RUNG 3, done properly: derive a freshness floor ONLY from anchors whose
+ * content has been retrieved and re-verified.
+ *
+ * WHY THIS EXISTS: anchoring is permissionless and `by=` is unauthenticated
+ * plaintext, while the accountant's key is public (it is named in the grant).
+ * So `highestAnchoredSeq` — which trusts the seq printed in calldata — is
+ * POISONABLE: a stranger anchors `…#999999999;by=<the real accountant>` and
+ * every honest head afterwards is refused as a rollback. That failure is not a
+ * missed omission, it is an honest record permanently refused.
+ *
+ * Here an anchored seq is a POINTER, never a fact. For an anchor to move the
+ * floor, all of the following must hold: the calldata parses and names THIS
+ * mandate; `by=` equals the mandate's accountant; the head was retrieved; the
+ * anchor digest recomputes over that head; the head's signature verifies; and
+ * the head itself names this mandate, this accountant, and this seq. Anything
+ * short of that is ignored with a warning — which can only LOWER the floor
+ * toward the tamper-evidence downgrade, never raise it.
+ */
+export function verifiedAnchoredSeq(sm, anchors) {
+    const warnings = [];
+    const shape = mandateShapeError(sm?.mandate);
+    if (shape)
+        return { seq: null, reasons: [`malformed mandate: ${shape}`], warnings };
+    const m = sm.mandate;
+    if (m.accountant === PAYEES_ACCOUNTANT) {
+        return { seq: null, reasons: ["mandate uses the 'payees' accountant (Model B) — no committed heads to anchor"], warnings };
+    }
+    let digest;
+    try {
+        digest = mandateDigest(m);
+    }
+    catch (e) {
+        return { seq: null, reasons: [`mandate digest failed: ${e.message}`], warnings };
+    }
+    let best = null;
+    for (const a of Array.isArray(anchors) ? anchors : []) {
+        const p = a && typeof a === 'object' ? parseCommitmentAnchorCalldata(a.calldata) : null;
+        if (!p) {
+            warnings.push('ignored an anchor whose calldata does not parse');
+            continue;
+        }
+        if (p.mandateDigest !== digest)
+            continue; // another mandate's anchor: not noise, just not ours
+        if (p.by === undefined) {
+            warnings.push(`ignored an anchor with no by= segment at seq ${p.seq} (historic grammar is not floor-eligible)`);
+            continue;
+        }
+        if (p.by !== m.accountant) {
+            warnings.push(`ignored an anchor naming a key that is not the mandate's accountant at seq ${p.seq}`);
+            continue;
+        }
+        // by= is only a routing hint — everything below is the actual check.
+        if (!a.head) {
+            warnings.push(`ignored an anchor at seq ${p.seq}: content not retrieved, so its seq is unverified`);
+            continue;
+        }
+        let recomputed;
+        try {
+            recomputed = commitmentAnchorDigest(a.head);
+        }
+        catch {
+            warnings.push(`ignored an anchor at seq ${p.seq}: head could not be digested`);
+            continue;
+        }
+        if (recomputed !== p.anchorDigest) {
+            warnings.push(`ignored an anchor at seq ${p.seq}: retrieved head does not reproduce the anchored digest`);
+            continue;
+        }
+        if (!verifyCommitment(a.head)) {
+            warnings.push(`ignored an anchor at seq ${p.seq}: head signature is not self-consistent`);
+            continue;
+        }
+        const c = a.head.commitment;
+        if (c.accountant !== m.accountant) {
+            warnings.push(`ignored an anchor at seq ${p.seq}: head accountant is not the mandate's`);
+            continue;
+        }
+        if (c.mandateDigest !== digest) {
+            warnings.push(`ignored an anchor at seq ${p.seq}: head is for a different mandate`);
+            continue;
+        }
+        if (c.seq !== p.seq) {
+            warnings.push(`ignored an anchor claiming seq ${p.seq} over a head at seq ${c.seq}`);
+            continue;
+        }
+        if (best === null || c.seq > best)
+            best = c.seq;
+    }
+    return { seq: best, reasons: [], warnings };
+}
+/**
+ * ⚠️ UNVERIFIED floor: trusts the seq printed in permissionless calldata and is
+ * therefore POISONABLE by any chain writer (see verifiedAnchoredSeq). Retained
+ * for scanning/equivocation surveys where a claimed seq is a lead to follow,
+ * NOT for deriving the floor a verifier will refuse honest heads against.
+ */
+export function highestAnchoredSeq(calldatas, mandateDigestStr, accountant) {
+    let best = null;
+    for (const cd of calldatas) {
+        const p = parseCommitmentAnchorCalldata(cd);
+        if (!p || p.mandateDigest !== mandateDigestStr)
+            continue;
+        // Only the accountant's own anchors (with matching by=) set the floor; historic no-by= and foreign by= are ignored.
+        if (accountant !== undefined && (p.by === undefined || p.by !== accountant))
+            continue;
+        if (best === null || p.seq > best)
+            best = p.seq;
+    }
+    return best;
+}
+// ──────────────────── aggregate sibling delegation budget ────────────────────
+/**
+ * The accountant-side check the delegation section's honest limit calls for:
+ * given a parent grant and the set of children issued under it, every child
+ * must be an authentic, correctly-narrowing child of THIS parent, digests
+ * distinct, and the SUM of child caps must fit within the parent cap.
+ *
+ * HONESTY: this binds over the set it is GIVEN. Only the party that registers
+ * delegations (the accountant, or the delegator's own ledger) knows the set is
+ * complete — a verifier handed a partial set gets a partial answer. That is
+ * the same completeness shape as spend, and the same parties close it.
+ */
+export function verifySiblingBudget(parentSm, children) {
+    const reasons = [];
+    const warnings = [];
+    const shape = mandateShapeError(parentSm?.mandate);
+    if (shape)
+        return { ok: false, reasons: [`malformed parent mandate: ${shape}`], warnings };
+    if (!verifyMandateSignature(parentSm))
+        return { ok: false, reasons: ['parent mandate signature not authentic'], warnings };
+    const parent = parentSm.mandate;
+    const seen = new Set();
+    let sum = 0n;
+    for (let i = 0; i < children.length; i++) {
+        const c = children[i];
+        const cShape = mandateShapeError(c?.mandate);
+        if (cShape) {
+            reasons.push(`child ${i} malformed: ${cShape}`);
+            break;
+        }
+        if (!verifyMandateSignature(c)) {
+            reasons.push(`child ${i} signature not authentic`);
+            break;
+        }
+        const narrow = narrowingError(c.mandate, parent);
+        if (narrow) {
+            reasons.push(`child ${i} is not a valid child of this parent: ${narrow}`);
+            break;
+        }
+        const d = mandateDigest(c.mandate);
+        if (seen.has(d)) {
+            reasons.push(`child ${i} duplicates another child (same digest)`);
+            break;
+        }
+        seen.add(d);
+        sum += BigInt(c.mandate.cap);
+    }
+    if (reasons.length === 0 && sum > BigInt(parent.cap)) {
+        reasons.push(`sibling caps sum to ${sum}, exceeding the parent cap ${parent.cap} — over-delegation`);
+    }
+    return { ok: reasons.length === 0, reasons, warnings };
+}
+/** Authorize one payment against the LEAF of a verified delegation chain. */
+export function checkDelegatedPayment(chain, payment, opts) {
+    const chainVerdict = verifyDelegationChain(chain);
+    if (!chainVerdict.ok)
+        return chainVerdict;
+    const leaf = chain[chain.length - 1];
+    const v = checkPayment(leaf, payment, opts);
+    return {
+        ...v,
+        warnings: [...chainVerdict.warnings, ...v.warnings],
+        ...(chainVerdict.rootIssuer !== undefined ? { rootIssuer: chainVerdict.rootIssuer } : {}),
+    };
+}