@atcn/subledger 1.4.0 → 1.5.0

package/dist/projection.d.ts

@@ -1,6 +1,6 @@
-import { type AttestationItem } from "@atcn/schema";
+import { type AttestationConflict, type AttestationItem } from "@atcn/schema";
 import { type Rollup } from "./rollup.js";
-import { type AllocationRecord, type CaptureGap, type ClosureDelegation, type ClosurePayload, type DeliveryClaim, type Disclosure, type ExceptionRecord, type FieldState, type Issuer, type KeyBindingRecord, type ObligationLink, type ReceiptPayload, type ReceiptTotals, type ResponseRecord } from "./documents.js";
+import { type AllocationRecord, type CaptureGap, type ClosureDelegation, type ClosurePayload, type DeliveryClaim, type Disclosure, type ExceptionRecord, type FieldState, type Issuer, type KeyBindingRecord, type ObligationLink, type ReceiptPayload, type ReceiptTotals, type ResolvedException, type ResponseRecord } from "./documents.js";
 import { type AttestableField, type FinancialEventRecord } from "./types.js";
 /**
  * Pure builders for the two projections of one root task (PRD §16): the private closure snapshot
@@ -17,6 +17,8 @@ export interface TaskRecord {
     scope_ref: string | null;
     retrospective: boolean;
     created_at: string;
+    /** Schema 1.5, present only when set. */
+    estimate_tolerance_bps?: number;
 }
 export type DelegationRecord = ClosureDelegation & {
     root_task_id: string;
@@ -26,6 +28,12 @@ export type DelegationRecord = ClosureDelegation & {
 export declare function labelClaims(claims: DeliveryClaim[]): DeliveryClaim[];
 /** A response as an attestation. Only a key-signed statement has a signer, so only it can revoke or be revoked. */
 export declare function responseAttestation(response: ResponseRecord): AttestationItem;
+/**
+ * Conflicts among key-signed statements (provider or witness) in effect at `at`. A signed_attestation confirms its
+ * fields and a propose_correction contests the corrected ones, per receipt revision: one key doing both is
+ * equivocation, two keys doing different things is disagreement, and a `disputes` ref is a dispute.
+ */
+export declare function statementConflicts(responses: ResponseRecord[], at: string): AttestationConflict[];
 /** Recomputes the "expired" and "revoked" labels as of `at`. Revoked and expired responses stay visible. */
 export declare function labelResponses(responses: ResponseRecord[], at: string): ResponseRecord[];
 /** Delivery status is the latest non-superseded status claim. It is a recorded claim, not an adjudicated truth. */
@@ -58,7 +66,16 @@ export interface ReceiptInput {
     /** Responses to earlier revisions of this receipt chain. */
     prior_responses: ResponseRecord[];
     capture_gaps: CaptureGap[];
+    /** Every key binding known to the issuer; the receipt lists only those its signed claims and estimates name. */
+    key_bindings: KeyBindingRecord[];
 }
+/** The key bindings named by the signers of these claims and events, each once, in binding_id order. */
+export declare function signerKeyBindings(claims: {
+    signer?: {
+        binding_id: string;
+        key_id: string;
+    };
+}[], events: Pick<FinancialEventRecord, "expectation">[], keyBindings: KeyBindingRecord[]): KeyBindingRecord[];
 /**
  * Provider receipt: one delegation only. Omits sibling delegations, root customer/project/cost-center data,
  * allocation lines, liability and economic-event IDs, and private event hashes (acceptance 8, 19).
@@ -98,7 +115,15 @@ export interface ClosureInput {
     key_bindings: KeyBindingRecord[];
     capture_gaps: CaptureGap[];
     obligation_links?: ObligationLink[];
+    /** Derived exceptions a person resolved while their condition still holds (resolutionsInForce). */
+    resolved_exceptions?: ResolvedException[];
 }
-export declare function closureDisclosure(input: Pick<ClosureInput, "task" | "delegations" | "claims" | "events" | "responses" | "receipts">): Disclosure;
+/**
+ * What the closure discloses as missing, unverified, contested, provider-reported and retrospective. With
+ * `generated_at` (schema 1.5), fields with conflicting signed statements at that time are contested too.
+ */
+export declare function closureDisclosure(input: Pick<ClosureInput, "task" | "delegations" | "claims" | "events" | "responses" | "receipts"> & {
+    generated_at?: string;
+}): Disclosure;
 /** Private closure snapshot of the full root task: lineage, event digests, all allocation versions, roll-up, and open exceptions. */
 export declare function buildClosurePayload(input: ClosureInput): ClosurePayload;

package/dist/projection.js

@@ -1,7 +1,10 @@
-import { digestOf, resolveAttestations } from "@atcn/schema";
+import { digestOf, disputesInEffect, findConflicts, inEffect, resolveAttestations, } from "@atcn/schema";
 import { computeRollup, costSign } from "./rollup.js";
 import { CLOSURE_DOCUMENT_TYPE, RECEIPT_DOCUMENT_TYPE, SUBLEDGER_SCHEMA_VERSION, } from "./documents.js";
+import { buildExpectationReport } from "./expectations.js";
+import { buildRailAttestationReport } from "./rails.js";
 import { ATTESTABLE_FIELDS } from "./types.js";
+import { usageChecksFor } from "./usage.js";
 /** Claims superseded by a later correction stay visible and gain the "superseded" label. */
 export function labelClaims(claims) {
     const superseded = new Set(claims.map((c) => c.supersedes_event_id).filter((id) => id !== null));
@@ -18,6 +21,34 @@ export function responseAttestation(response) {
         refs: s.refs,
     };
 }
+/**
+ * Conflicts among key-signed statements (provider or witness) in effect at `at`. A signed_attestation confirms its
+ * fields and a propose_correction contests the corrected ones, per receipt revision: one key doing both is
+ * equivocation, two keys doing different things is disagreement, and a `disputes` ref is a dispute.
+ */
+export function statementConflicts(responses, at) {
+    const signed = responses.filter((r) => r.assurance.includes("provider_key_signed"));
+    const items = signed.map(responseAttestation);
+    const resolution = resolveAttestations(items, at);
+    const claims = signed
+        .filter((r) => inEffect(resolution, r.statement_digest))
+        .flatMap((r) => {
+        const s = r.statement;
+        const claim = (field, status) => ({
+            digest: r.statement_digest,
+            signer: r.provider_id,
+            subject: `receipt:${r.receipt_id}@${r.receipt_revision}.${field}`,
+            status,
+            ...(s.execution ? { execution_digest: s.execution.execution_digest } : {}),
+        });
+        if (s.response_type === "signed_attestation")
+            return s.fields.map((f) => claim(f, "confirmed"));
+        if (s.response_type === "propose_correction")
+            return s.corrections.map((c) => claim(c.field, "corrected"));
+        return [];
+    });
+    return findConflicts(claims, disputesInEffect(items, resolution));
+}
 const TIME_LABELS = ["expired", "revoked"];
 /** Recomputes the "expired" and "revoked" labels as of `at`. Revoked and expired responses stay visible. */
 export function labelResponses(responses, at) {
@@ -92,11 +123,19 @@ export function receiptFieldStatus(delegation, claims, events, priorResponses) {
         "scope.terms_digest": delegation.terms_digest ? "buyer_asserted" : "missing",
         "financial.amounts": events.some((e) => costSign(e.type) !== 0 || e.type === "quote") ? "imported" : "missing",
         "financial.status": events.some((e) => e.normalized_status !== "unknown") ? "imported" : "missing",
+        "delivery.usage": stateOf(active.filter((c) => c.usage !== undefined).at(-1)),
     };
     for (const field of openCorrectionFields(priorResponses))
         status[field] = "contested";
     return status;
 }
+/** The key bindings named by the signers of these claims and events, each once, in binding_id order. */
+export function signerKeyBindings(claims, events, keyBindings) {
+    const signers = [...claims.map((c) => c.signer), ...events.map((e) => e.expectation?.signer)].filter((s) => s !== undefined);
+    return keyBindings
+        .filter((b) => signers.some((s) => s.binding_id === b.binding_id && s.key_id === b.key_id))
+        .sort((a, b) => (a.binding_id < b.binding_id ? -1 : a.binding_id > b.binding_id ? 1 : 0));
+}
 /**
  * Provider receipt: one delegation only. Omits sibling delegations, root customer/project/cost-center data,
  * allocation lines, liability and economic-event IDs, and private event hashes (acceptance 8, 19).
@@ -105,6 +144,7 @@ export function buildReceiptPayload(input) {
     const d = input.delegation;
     const claims = labelClaims(input.claims);
     const fieldStatus = receiptFieldStatus(d, claims, input.events, input.prior_responses);
+    const keyBindings = signerKeyBindings(input.claims, input.events, input.key_bindings);
     return {
         document_type: RECEIPT_DOCUMENT_TYPE,
         schema_version: SUBLEDGER_SCHEMA_VERSION,
@@ -130,6 +170,9 @@ export function buildReceiptPayload(input) {
             retrospective: d.retrospective,
             downstream_visibility: d.downstream_visibility,
             ...(d.execution ? { execution: d.execution } : {}),
+            ...(d.pricing ? { pricing: d.pricing } : {}),
+            ...(d.refund_terms ? { refund_terms: d.refund_terms } : {}),
+            ...(d.witness_policy ? { witness_policy: d.witness_policy } : {}),
         },
         provider: {
             provider_id: input.provider?.provider_id ?? null,
@@ -149,6 +192,7 @@ export function buildReceiptPayload(input) {
             .filter((r) => r.statement.response_type === "propose_correction")
             .map((r) => ({ response_id: r.response_id, receipt_revision: r.receipt_revision, fields: r.statement.fields, decision: r.decision?.status ?? "open" })),
         lineage: { complete: input.capture_gaps.length === 0, capture_gaps: input.capture_gaps.map(({ delegation_id: _delegationId, ...gap }) => gap) },
+        ...(keyBindings.length > 0 ? { key_bindings: keyBindings } : {}),
     };
 }
 /** Latest allocation lines per financial event, the input the roll-up uses. */
@@ -169,6 +213,10 @@ export function rollupFor(task, delegations, events, allocations) {
         allocations: Object.fromEntries(Object.entries(latest).map(([id, a]) => [id, a.lines])),
     });
 }
+/**
+ * What the closure discloses as missing, unverified, contested, provider-reported and retrospective. With
+ * `generated_at` (schema 1.5), fields with conflicting signed statements at that time are contested too.
+ */
 export function closureDisclosure(input) {
     const missing = [];
     const unverified = [];
@@ -211,10 +259,23 @@ export function closureDisclosure(input) {
                 contested.push(`receipt:${r.receipt_id}.${c.field}`);
         }
     }
+    if (input.generated_at !== undefined) {
+        for (const conflict of statementConflicts(input.responses, input.generated_at)) {
+            const field = conflict.subject.replace(/@\d+\./, ".");
+            if (!contested.includes(field))
+                contested.push(field);
+        }
+    }
     return { missing, unverified, contested, provider_reported: providerReported, retrospective };
 }
 /** Private closure snapshot of the full root task: lineage, event digests, all allocation versions, roll-up, and open exceptions. */
 export function buildClosurePayload(input) {
+    const claims = labelClaims(input.claims);
+    const rollup = rollupFor(input.task, input.delegations, input.events, input.allocations);
+    const responses = labelResponses(input.responses, input.generated_at);
+    const usageChecks = usageChecksFor(input.delegations, claims, rollup, responses, input.receipts);
+    const expectationReport = buildExpectationReport({ task: input.task, delegations: input.delegations, claims, events: input.events, rollup, key_bindings: input.key_bindings });
+    const railAttestations = buildRailAttestationReport(input.events);
     return {
         document_type: CLOSURE_DOCUMENT_TYPE,
         schema_version: SUBLEDGER_SCHEMA_VERSION,
@@ -226,13 +287,13 @@ export function buildClosurePayload(input) {
         issuer: input.issuer,
         task: input.task,
         delegations: input.delegations,
-        delivery_claims: labelClaims(input.claims),
+        delivery_claims: claims,
         financial_events: input.events.map((e) => ({ record: e.record, event_digest: digestOf(e.record), attributed_to: e.attributed_to })),
         allocations: input.allocations,
-        rollup: rollupFor(input.task, input.delegations, input.events, input.allocations),
+        rollup,
         open_exceptions: input.open_exceptions,
         receipts: input.receipts,
-        responses: labelResponses(input.responses, input.generated_at),
+        responses,
         key_bindings: input.key_bindings,
         lineage: {
             complete: input.capture_gaps.length === 0,
@@ -241,5 +302,9 @@ export function buildClosurePayload(input) {
         },
         disclosure: closureDisclosure(input),
         ...(input.obligation_links && input.obligation_links.length > 0 ? { obligation_links: input.obligation_links } : {}),
+        ...(usageChecks.length > 0 ? { usage_checks: usageChecks } : {}),
+        ...(expectationReport ? { expectation_report: expectationReport } : {}),
+        ...(railAttestations ? { rail_attestations: railAttestations } : {}),
+        ...(input.resolved_exceptions && input.resolved_exceptions.length > 0 ? { resolved_exceptions: input.resolved_exceptions } : {}),
     };
 }

package/dist/rails.d.ts

@@ -0,0 +1,108 @@
+import type { FinancialEventRecord, RailAttestation } from "./types.js";
+/**
+ * Rail attestations (schema 1.5): a payment rail's own record that a payment or refund happened, embedded in the
+ * financial event so the closure re-verifies it offline, without contacting the rail. ATCN never moves money; it checks
+ * what the rail recorded and labels the event rail_attested, separately from operator-reported payment status.
+ */
+/** What a verified rail record proves. */
+export interface RailFacts {
+    type: "payment_reported" | "refund";
+    amount_minor: number;
+    currency: string;
+    /** The rail's reference for the payment: an escrow id or a transaction hash. Recorded as the event's provider_reference. */
+    rail_ref: string;
+    /** The buyer's job reference the rail recorded (an A2A task id, an authorization nonce), when it records one. */
+    job_ref: string | null;
+    occurred_at: string | null;
+}
+export type RailVerification = {
+    ok: true;
+    rail: string;
+    facts: RailFacts;
+    anchor: string;
+} | {
+    ok: false;
+    code: RailRefusalCode;
+    detail: string;
+};
+export type RailRefusalCode = "unsupported_scheme" | "malformed" | "data_hash_mismatch" | "merkle_proof_invalid" | "signature_invalid" | "settlement_not_successful" | "unsupported_asset";
+/** Verifies one rail's records offline. Add a rail by implementing this and listing it in RAIL_IMPORTERS. */
+export interface RailAttestationImporter {
+    rail: string;
+    schemes: readonly string[];
+    verify(attestation: RailAttestation): RailVerification;
+}
+export declare const A2A_SE_RELEASE_SCHEME = "urn:a2a-se:escrow-release-attestation:v1";
+export declare const A2A_SE_REFUND_SCHEME = "urn:a2a-se:escrow-refund-attestation:v1";
+/** Python's json.dumps(value, sort_keys=True, separators=(",", ":")), which A2A-SE hashes: keys by code point, non-ASCII escaped. */
+export declare function pythonCanonicalJson(value: unknown): string;
+/**
+ * A record from GET /v1/exchange/escrow/{escrow_id}/attestations: { leaf_index, data_hash, merkle_root, proof, schema_id,
+ * payload }. The payload's leaf hash must be data_hash, and folding the proof must give merkle_root. A2A-SE attestations
+ * are not signed; the anchor is the Merkle root of the exchange's append-only log, which the reader should compare with
+ * the root the exchange publishes.
+ */
+export declare const a2aSeImporter: RailAttestationImporter;
+export declare const X402_EXACT_EVM_SCHEME = "x402:exact-evm:v2";
+/** USD stablecoins, by CAIP-2 network and token address (lowercase). ATCN records them as USD cents at 1:1. */
+export declare const X402_USD_ASSETS: Record<string, {
+    name: string;
+    decimals: number;
+}>;
+interface X402Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/** The EIP-712 digest a payer signs for an EIP-3009 transferWithAuthorization (the x402 "exact" EVM scheme). */
+export declare function eip3009Digest(authorization: X402Authorization, domain: {
+    name: string;
+    version: string;
+    chainId: bigint;
+    verifyingContract: string;
+}): Uint8Array;
+/** The address that made a 65-byte (r, s, v) secp256k1 signature over a digest. */
+export declare function recoverAddress(digest: Uint8Array, signature: string): string;
+/**
+ * A settled x402 payment: { requirements, payload, settlement } as the client and facilitator exchanged them. The payer's
+ * EIP-3009 authorization signature must recover its `from` address and authorize exactly the required amount to payTo.
+ * The facilitator's settlement response supplies success and the transaction hash; on-chain inclusion is not checked
+ * offline.
+ */
+export declare const x402Importer: RailAttestationImporter;
+export declare const RAIL_IMPORTERS: readonly RailAttestationImporter[];
+export declare function verifyRailAttestation(attestation: RailAttestation, importers?: readonly RailAttestationImporter[]): RailVerification;
+/** Why a financial event's rail attestation does not support it, or null when it verifies and agrees with the event. */
+export declare function railAttestationProblem(event: Pick<FinancialEventRecord, "type" | "amount_minor" | "currency" | "provider_reference" | "rail_attestation">): {
+    code: string;
+    detail: string;
+} | null;
+export interface RailAttestationEntry {
+    financial_event_id: string;
+    scheme: string;
+    rail: string;
+    rail_ref: string;
+    anchor: string;
+    assurance: ["rail_attested"];
+}
+/** The closure's rail_attestations: one entry per event whose embedded attestation verifies and agrees with it; null when none carry one. */
+export declare function buildRailAttestationReport(events: {
+    record: FinancialEventRecord;
+}[]): RailAttestationEntry[] | null;
+/**
+ * Buyer side: the financial event body for a rail record, after verifying it. Throws RailAttestationError with the
+ * refusal code when it does not verify. Matching uses the job reference the rail recorded unless `match` is given.
+ */
+export declare function financialEventFromRailAttestation(attestation: RailAttestation, options: {
+    source: string;
+    match?: Record<string, string>;
+    eventDate?: string;
+}): Record<string, unknown>;
+export declare class RailAttestationError extends Error {
+    readonly code: string;
+    constructor(code: string, detail: string);
+}
+export {};

package/dist/rails.js

@@ -0,0 +1,242 @@
+import { secp256k1 } from "@noble/curves/secp256k1";
+import { sha256 } from "@noble/hashes/sha2";
+import { keccak_256 } from "@noble/hashes/sha3";
+import { bytesToHex, concatBytes, hexToBytes, utf8ToBytes } from "@noble/hashes/utils";
+const refuse = (code, detail) => ({ ok: false, code, detail });
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isHex64 = (value) => typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+const isCurrency = (value) => typeof value === "string" && /^[A-Z]{3}$/.test(value);
+const isAmount = (value) => Number.isSafeInteger(value) && value >= 0;
+// ---------- A2A-SE escrow attestations ----------
+export const A2A_SE_RELEASE_SCHEME = "urn:a2a-se:escrow-release-attestation:v1";
+export const A2A_SE_REFUND_SCHEME = "urn:a2a-se:escrow-refund-attestation:v1";
+/** Python's json.dumps(value, sort_keys=True, separators=(",", ":")), which A2A-SE hashes: keys by code point, non-ASCII escaped. */
+export function pythonCanonicalJson(value) {
+    if (value === null || typeof value === "boolean")
+        return String(value);
+    if (typeof value === "number") {
+        if (!Number.isSafeInteger(value))
+            throw new Error(`number ${value} is not an integer; A2A-SE records carry integers only`);
+        return String(value);
+    }
+    if (typeof value === "string")
+        return asciiJsonString(value);
+    if (Array.isArray(value))
+        return `[${value.map(pythonCanonicalJson).join(",")}]`;
+    if (isObject(value)) {
+        const keys = Object.keys(value).sort(byCodePoint);
+        return `{${keys.map((key) => `${asciiJsonString(key)}:${pythonCanonicalJson(value[key])}`).join(",")}}`;
+    }
+    throw new Error(`${typeof value} cannot be serialized`);
+}
+function asciiJsonString(value) {
+    return JSON.stringify(value).replace(/[\u007f-\uffff]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function byCodePoint(a, b) {
+    const left = Array.from(a, (c) => c.codePointAt(0));
+    const right = Array.from(b, (c) => c.codePointAt(0));
+    for (let i = 0; i < Math.min(left.length, right.length); i++)
+        if (left[i] !== right[i])
+            return left[i] - right[i];
+    return left.length - right.length;
+}
+const leafHash = (canonical) => bytesToHex(sha256(concatBytes(new Uint8Array([0]), utf8ToBytes(canonical))));
+const nodeHash = (left, right) => bytesToHex(sha256(concatBytes(new Uint8Array([1]), hexToBytes(left), hexToBytes(right))));
+/**
+ * A record from GET /v1/exchange/escrow/{escrow_id}/attestations: { leaf_index, data_hash, merkle_root, proof, schema_id,
+ * payload }. The payload's leaf hash must be data_hash, and folding the proof must give merkle_root. A2A-SE attestations
+ * are not signed; the anchor is the Merkle root of the exchange's append-only log, which the reader should compare with
+ * the root the exchange publishes.
+ */
+export const a2aSeImporter = {
+    rail: "a2a-se",
+    schemes: [A2A_SE_RELEASE_SCHEME, A2A_SE_REFUND_SCHEME],
+    verify({ scheme, record }) {
+        const { payload, data_hash, merkle_root, proof, schema_id } = record;
+        if (schema_id !== scheme)
+            return refuse("malformed", `schema_id ${String(schema_id)} is not the declared scheme ${scheme}`);
+        if (!isObject(payload) || !isObject(payload.header) || payload.header.schema_id !== scheme)
+            return refuse("malformed", "payload.header.schema_id must be the declared scheme");
+        if (!isHex64(data_hash) || !isHex64(merkle_root) || !Array.isArray(proof))
+            return refuse("malformed", "data_hash, merkle_root and proof are required");
+        let canonical;
+        try {
+            canonical = pythonCanonicalJson(payload);
+        }
+        catch (error) {
+            return refuse("malformed", error.message);
+        }
+        if (leafHash(canonical) !== data_hash)
+            return refuse("data_hash_mismatch", "the payload does not hash to data_hash");
+        let computed = data_hash;
+        for (const step of proof) {
+            if (!isObject(step) || !isHex64(step.sibling_hash) || (step.side !== "left" && step.side !== "right"))
+                return refuse("malformed", "each proof step needs sibling_hash and side");
+            computed = step.side === "left" ? nodeHash(step.sibling_hash, computed) : nodeHash(computed, step.sibling_hash);
+        }
+        if (computed !== merkle_root)
+            return refuse("merkle_proof_invalid", "the proof does not lead from data_hash to merkle_root");
+        const settlement = payload.settlement;
+        const amount = scheme === A2A_SE_RELEASE_SCHEME ? payload.amount_paid : payload.amount_returned;
+        if (!isObject(settlement) || typeof settlement.escrow_id !== "string" || !isCurrency(settlement.currency) || !isAmount(amount)) {
+            return refuse("malformed", "settlement.escrow_id, settlement.currency and the amount are required");
+        }
+        return {
+            ok: true,
+            rail: "a2a-se",
+            anchor: `A2A-SE log leaf ${String(record.leaf_index)} under Merkle root ${merkle_root} (unsigned; compare the root with the one the exchange publishes)`,
+            facts: {
+                type: scheme === A2A_SE_RELEASE_SCHEME ? "payment_reported" : "refund",
+                amount_minor: amount,
+                currency: settlement.currency,
+                rail_ref: settlement.escrow_id,
+                job_ref: typeof settlement.task_id === "string" ? settlement.task_id : null,
+                occurred_at: typeof settlement.occurred_at === "string" ? settlement.occurred_at : null,
+            },
+        };
+    },
+};
+// ---------- x402 exact (EVM) payments ----------
+export const X402_EXACT_EVM_SCHEME = "x402:exact-evm:v2";
+/** USD stablecoins, by CAIP-2 network and token address (lowercase). ATCN records them as USD cents at 1:1. */
+export const X402_USD_ASSETS = {
+    "eip155:84532:0x036cbd53842c5426634e7929541ec2318f3dcf7e": { name: "USDC", decimals: 6 },
+    "eip155:8453:0x833589fcd6edb6e08f4c7c32d4f71b54bda02913": { name: "USDC", decimals: 6 },
+};
+const keccakText = (text) => keccak_256(utf8ToBytes(text));
+const word = (value) => hexToBytes(value.toString(16).padStart(64, "0"));
+const addressWord = (address) => word(BigInt(address));
+const TRANSFER_TYPEHASH = keccakText("TransferWithAuthorization(address from,address to,uint256 value,uint256 validAfter,uint256 validBefore,bytes32 nonce)");
+const DOMAIN_TYPEHASH = keccakText("EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)");
+/** The EIP-712 digest a payer signs for an EIP-3009 transferWithAuthorization (the x402 "exact" EVM scheme). */
+export function eip3009Digest(authorization, domain) {
+    const domainSeparator = keccak_256(concatBytes(DOMAIN_TYPEHASH, keccakText(domain.name), keccakText(domain.version), word(domain.chainId), addressWord(domain.verifyingContract)));
+    const structHash = keccak_256(concatBytes(TRANSFER_TYPEHASH, addressWord(authorization.from), addressWord(authorization.to), word(BigInt(authorization.value)), word(BigInt(authorization.validAfter)), word(BigInt(authorization.validBefore)), hexToBytes(authorization.nonce.slice(2))));
+    return keccak_256(concatBytes(new Uint8Array([0x19, 0x01]), domainSeparator, structHash));
+}
+/** The address that made a 65-byte (r, s, v) secp256k1 signature over a digest. */
+export function recoverAddress(digest, signature) {
+    const bytes = hexToBytes(signature.slice(2));
+    const v = bytes[64];
+    const point = secp256k1.Signature.fromCompact(bytes.slice(0, 64))
+        .addRecoveryBit(v >= 27 ? v - 27 : v)
+        .recoverPublicKey(digest);
+    return `0x${bytesToHex(keccak_256(point.toRawBytes(false).slice(1)).slice(-20))}`;
+}
+/**
+ * A settled x402 payment: { requirements, payload, settlement } as the client and facilitator exchanged them. The payer's
+ * EIP-3009 authorization signature must recover its `from` address and authorize exactly the required amount to payTo.
+ * The facilitator's settlement response supplies success and the transaction hash; on-chain inclusion is not checked
+ * offline.
+ */
+export const x402Importer = {
+    rail: "x402",
+    schemes: [X402_EXACT_EVM_SCHEME],
+    verify({ record }) {
+        const { requirements, payload, settlement } = record;
+        if (!isObject(requirements) || !isObject(payload) || !isObject(settlement) || !isObject(payload.authorization) || typeof payload.signature !== "string") {
+            return refuse("malformed", "requirements, payload.authorization, payload.signature and settlement are required");
+        }
+        const authorization = payload.authorization;
+        const extra = isObject(requirements.extra) ? requirements.extra : {};
+        const network = String(requirements.network);
+        const chain = /^eip155:(\d+)$/.exec(network);
+        const hexFields = [authorization.from, authorization.to, String(requirements.asset), String(requirements.payTo)];
+        if (requirements.scheme !== "exact" || !chain || typeof extra.name !== "string" || typeof extra.version !== "string" || !hexFields.every((f) => /^0x[0-9a-fA-F]{40}$/.test(f))) {
+            return refuse("malformed", "requirements must be the exact scheme on an eip155 network, with extra.name, extra.version and EVM addresses");
+        }
+        if (!/^0x[0-9a-fA-F]{64}$/.test(authorization.nonce) || !/^0x[0-9a-fA-F]{130}$/.test(payload.signature))
+            return refuse("malformed", "nonce must be 32 bytes and signature 65 bytes, hex");
+        if (authorization.to.toLowerCase() !== String(requirements.payTo).toLowerCase() || authorization.value !== String(requirements.amount)) {
+            return refuse("malformed", "the authorization must pay exactly the required amount to payTo");
+        }
+        let signer;
+        try {
+            signer = recoverAddress(eip3009Digest(authorization, { name: extra.name, version: extra.version, chainId: BigInt(chain[1]), verifyingContract: String(requirements.asset) }), payload.signature);
+        }
+        catch {
+            return refuse("signature_invalid", "the authorization signature cannot be recovered");
+        }
+        if (signer !== authorization.from.toLowerCase())
+            return refuse("signature_invalid", `the authorization was signed by ${signer}, not the payer ${authorization.from}`);
+        if (settlement.success !== true || typeof settlement.transaction !== "string" || settlement.transaction === "" || settlement.network !== network) {
+            return refuse("settlement_not_successful", "the facilitator did not report a successful settlement on the required network");
+        }
+        const asset = X402_USD_ASSETS[`${network}:${String(requirements.asset)}`.toLowerCase()];
+        const perCent = asset ? 10n ** BigInt(asset.decimals - 2) : 0n;
+        if (!asset || BigInt(authorization.value) % perCent !== 0n)
+            return refuse("unsupported_asset", `no whole-cent USD conversion for ${String(requirements.asset)} on ${network}`);
+        return {
+            ok: true,
+            rail: "x402",
+            anchor: `payer ${authorization.from} signed the EIP-3009 authorization; transaction ${settlement.transaction} as reported by the facilitator (on-chain inclusion not checked offline)`,
+            facts: { type: "payment_reported", amount_minor: Number(BigInt(authorization.value) / perCent), currency: "USD", rail_ref: settlement.transaction, job_ref: authorization.nonce, occurred_at: null },
+        };
+    },
+};
+// ---------- Registry, consistency and the closure report ----------
+export const RAIL_IMPORTERS = [a2aSeImporter, x402Importer];
+export function verifyRailAttestation(attestation, importers = RAIL_IMPORTERS) {
+    const importer = importers.find((i) => i.schemes.includes(attestation.scheme));
+    return importer ? importer.verify(attestation) : refuse("unsupported_scheme", `no importer for scheme ${attestation.scheme}`);
+}
+/** Why a financial event's rail attestation does not support it, or null when it verifies and agrees with the event. */
+export function railAttestationProblem(event) {
+    if (!event.rail_attestation)
+        return null;
+    const result = verifyRailAttestation(event.rail_attestation);
+    if (!result.ok)
+        return { code: result.code, detail: result.detail };
+    const { facts } = result;
+    const mismatches = [
+        facts.type !== event.type ? `type ${event.type} (the rail recorded ${facts.type})` : null,
+        facts.amount_minor !== event.amount_minor ? `amount ${event.amount_minor} (the rail recorded ${facts.amount_minor})` : null,
+        facts.currency !== event.currency ? `currency ${event.currency} (the rail recorded ${facts.currency})` : null,
+        facts.rail_ref !== event.provider_reference ? `provider_reference ${String(event.provider_reference)} (the rail recorded ${facts.rail_ref})` : null,
+    ].filter((m) => m !== null);
+    return mismatches.length > 0 ? { code: "attestation_mismatch", detail: `the event does not match its rail attestation: ${mismatches.join("; ")}` } : null;
+}
+/** The closure's rail_attestations: one entry per event whose embedded attestation verifies and agrees with it; null when none carry one. */
+export function buildRailAttestationReport(events) {
+    const attested = events.filter((e) => e.record.rail_attestation);
+    if (attested.length === 0)
+        return null;
+    return attested.flatMap(({ record }) => {
+        const result = verifyRailAttestation(record.rail_attestation);
+        if (!result.ok || railAttestationProblem(record) !== null)
+            return [];
+        return [{ financial_event_id: record.financial_event_id, scheme: record.rail_attestation.scheme, rail: result.rail, rail_ref: result.facts.rail_ref, anchor: result.anchor, assurance: ["rail_attested"] }];
+    });
+}
+/**
+ * Buyer side: the financial event body for a rail record, after verifying it. Throws RailAttestationError with the
+ * refusal code when it does not verify. Matching uses the job reference the rail recorded unless `match` is given.
+ */
+export function financialEventFromRailAttestation(attestation, options) {
+    const result = verifyRailAttestation(attestation);
+    if (!result.ok)
+        throw new RailAttestationError(result.code, result.detail);
+    const { facts } = result;
+    const eventDate = facts.occurred_at ?? options.eventDate;
+    if (!eventDate)
+        throw new RailAttestationError("malformed", "the rail recorded no time; pass eventDate");
+    return {
+        type: facts.type,
+        source: options.source,
+        source_event_id: `${attestation.scheme}:${facts.rail_ref}`,
+        provider_reference: facts.rail_ref,
+        amount_minor: facts.amount_minor,
+        currency: facts.currency,
+        event_date: eventDate,
+        normalized_status: facts.type === "refund" ? "refunded" : "reported_paid",
+        match: options.match ?? (facts.job_ref ? { provider_job_ref: facts.job_ref } : {}),
+        rail_attestation: attestation,
+    };
+}
+export class RailAttestationError extends Error {
+    code;
+    constructor(code, detail) {
+        super(`${code}: ${detail}`);
+        this.code = code;
+    }
+}

package/dist/response.d.ts

@@ -18,6 +18,8 @@ export interface StatementInput {
     issued_at?: string;
     expires_at?: string;
     refs?: AttestationRef[];
+    /** Schema 1.5: "witness" when an independent witness signs that it observed the run. */
+    role?: "witness";
 }
 /** Builds the statement a provider responds with. Field order is irrelevant: the signature covers canonical JSON. */
 export declare function buildResponseStatement(input: StatementInput): ResponseStatement;

package/dist/response.js

@@ -17,6 +17,7 @@ export function buildResponseStatement(input) {
         ...(input.issued_at !== undefined ? { issued_at: input.issued_at } : {}),
         ...(input.expires_at !== undefined ? { expires_at: input.expires_at } : {}),
         ...(input.refs !== undefined ? { refs: input.refs } : {}),
+        ...(input.role !== undefined ? { role: input.role } : {}),
     };
 }
 export function statementDigest(statement) {

package/dist/rollup.d.ts

@@ -47,7 +47,7 @@ export interface Rollup {
         fx_rates: string[];
     };
 }
-/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, payment reports, reversals, rates). */
+/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, estimates, holds, payment reports, reversals, rates). */
 export declare function costSign(type: FinancialEventType): 1 | -1 | 0;
 export declare function emptyTotals(): Totals;
 /** True when an event counts as the buyer's own expense rather than reported downstream cost (acceptance 25). */

package/dist/rollup.js

@@ -1,4 +1,4 @@
-/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, payment reports, reversals, rates). */
+/** +1 adds to buyer cost, -1 reduces it, 0 carries no cost (quotes, estimates, holds, payment reports, reversals, rates). */
 export function costSign(type) {
     if (type === "invoice" || type === "charge" || type === "fee" || type === "adjustment")
         return 1;
@@ -71,6 +71,8 @@ export function computeRollup(input) {
             }
             continue;
         }
+        if (event.type === "estimate" || event.type === "hold")
+            continue;
         if (event.type === "payment_reported") {
             t.reported_paid += event.amount_minor;
             continue;
@@ -117,11 +119,14 @@ export function computeRollup(input) {
         }
     }
     // Children before parents: deepest first, so each subtree total is final when added to its parent.
+    // A parent outside the task or a parent cycle ends the walk; the verifier's lineage check reports both.
     const depth = (id) => {
         let d = 0;
         let current = nodes.get(id);
-        while (current.parent_id) {
+        const seen = new Set([id]);
+        while (current.parent_id && nodes.has(current.parent_id) && !seen.has(current.parent_id)) {
             d += 1;
+            seen.add(current.parent_id);
             current = nodes.get(current.parent_id);
         }
         return d;
@@ -131,8 +136,9 @@ export function computeRollup(input) {
         const node = nodes.get(id);
         addInto(node.total, node.direct);
         addInto(node.total, node.descendant);
-        if (node.parent_id)
-            addInto(nodes.get(node.parent_id).descendant, node.total);
+        const parent = node.parent_id ? nodes.get(node.parent_id) : undefined;
+        if (parent)
+            addInto(parent.descendant, node.total);
     }
     return {
         root_task_id: input.root.task_id,