@atcn/subledger 1.4.1 → 1.5.1

package/dist/presets.js

@@ -0,0 +1,192 @@
+import { derivedSourceEventId, majorToMinor, parseCsvRows, parseJsonlRows } from "./importing.js";
+export const IMPORT_PRESETS = ["litellm", "openrouter", "stripe"];
+/** Metadata key on Stripe PaymentIntents and transfers that holds the ATCN job reference. */
+export const STRIPE_JOB_REF_KEY = "atcn_job_ref";
+/** Rows of a JSON export: an array of objects, or an object wrapping one in `data` (LiteLLM) or `data.data` (OpenRouter). */
+export function exportRowsFromJson(value) {
+    let items = value;
+    if (isObject(items) && "data" in items)
+        items = items.data;
+    if (isObject(items) && "data" in items)
+        items = items.data;
+    if (isObject(items))
+        items = [items];
+    if (!Array.isArray(items))
+        throw new Error("JSON export must be an array of rows or an object with a data array");
+    return items.map((item, index) => {
+        if (!isObject(item))
+            throw new Error(`row ${index + 1} is not a JSON object`);
+        return item;
+    });
+}
+/** Reads an export saved as JSON, JSONL or CSV. */
+export function parseExportText(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith("[") && !trimmed.startsWith("{"))
+        return parseCsvRows(text);
+    let value;
+    try {
+        value = JSON.parse(trimmed);
+    }
+    catch {
+        return parseJsonlRows(text);
+    }
+    return exportRowsFromJson(value);
+}
+/** Converts rows of a known export into financial event bodies. */
+export function importPresetRows(preset, rows, options = {}) {
+    const source = options.source ?? preset;
+    if (preset === "litellm")
+        return importDailySpend(rows, { ref: "end_user", date: "startTime", amount: "spend" }, source);
+    if (preset === "openrouter")
+        return importDailySpend(rows, { ref: "external_user", date: "date__day", amount: "total_usage" }, source);
+    return importStripeBalanceRows(rows, source);
+}
+/** Fixed-point scale for summing sub-cent USD spend: 18 decimal places. */
+const SPEND_SCALE = 18;
+function importDailySpend(rows, columns, source) {
+    const result = { events: [], errors: [], skipped: [] };
+    const groups = new Map();
+    rows.forEach((row, index) => {
+        const number = index + 1;
+        const ref = text(row[columns.ref]);
+        if (ref === null) {
+            result.skipped.push({ row: number, reason: `no ${columns.ref}: send the ATCN job reference as the request's user field` });
+            return;
+        }
+        try {
+            const day = utcIso(row[columns.date], columns.date).slice(0, 10);
+            const amount = spendToScaled(row[columns.amount], columns.amount);
+            const key = JSON.stringify([ref, day]);
+            const group = groups.get(key) ?? { row: number, ref, day, total: 0n };
+            group.total += amount;
+            groups.set(key, group);
+        }
+        catch (error) {
+            result.errors.push({ row: number, error: error.message });
+        }
+    });
+    const cent = 10n ** BigInt(SPEND_SCALE - 2);
+    for (const group of groups.values()) {
+        const amountMinor = Number((group.total + cent / 2n) / cent);
+        if (amountMinor === 0) {
+            result.skipped.push({ row: group.row, reason: `spend for ${group.ref} on ${group.day} rounds to 0 cents` });
+            continue;
+        }
+        result.events.push({
+            row: group.row,
+            event: {
+                type: "charge",
+                source,
+                source_event_id: derivedSourceEventId({ provider_job_ref: group.ref, day: group.day }),
+                provider_reference: null,
+                provider_status: null,
+                amount_minor: amountMinor,
+                currency: "USD",
+                event_date: `${group.day}T00:00:00.000Z`,
+                match: { provider_job_ref: group.ref, task_external_ref: null, delegation_external_ref: null },
+            },
+        });
+    }
+    result.events.sort((a, b) => a.row - b.row);
+    result.skipped.sort((a, b) => a.row - b.row);
+    return result;
+}
+/** A non-negative decimal (a JSON number or a string, exponent allowed) as an integer at SPEND_SCALE. */
+function spendToScaled(value, column) {
+    const decimal = typeof value === "number" ? String(value) : typeof value === "string" ? value.trim() : "";
+    const match = /^(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/.exec(decimal);
+    if (!match || (match[1] === "" && !match[2]))
+        throw new Error(`${column} ${JSON.stringify(value)} is not a non-negative decimal number`);
+    const [, whole, fraction = "", exponent = "0"] = match;
+    const digits = BigInt(whole + fraction || "0");
+    const shift = SPEND_SCALE - fraction.length + Number(exponent);
+    if (shift >= 0)
+        return digits * 10n ** BigInt(shift);
+    const divisor = 10n ** BigInt(-shift);
+    return (digits + divisor / 2n) / divisor;
+}
+/** Stripe reporting categories that are job cost, the event type each becomes, and the column holding the job reference. */
+const STRIPE_CATEGORIES = {
+    charge: { type: "charge", refColumn: `payment_metadata[${STRIPE_JOB_REF_KEY}]` },
+    refund: { type: "refund", refColumn: `payment_metadata[${STRIPE_JOB_REF_KEY}]` },
+    transfer: { type: "payment_reported", refColumn: `transfer_metadata[${STRIPE_JOB_REF_KEY}]` },
+    // A reversal event needs the ATCN id of the event it reverses, which the export cannot know: money a provider
+    // returns from a transfer is recorded as a refund.
+    transfer_reversal: { type: "refund", refColumn: `transfer_metadata[${STRIPE_JOB_REF_KEY}]` },
+};
+/** ISO 4217 currencies Stripe reports without minor units, and those with three decimal places. */
+const ZERO_DECIMAL_CURRENCIES = ["BIF", "CLP", "DJF", "GNF", "ISK", "JPY", "KMF", "KRW", "MGA", "PYG", "RWF", "UGX", "VND", "VUV", "XAF", "XOF", "XPF"];
+const THREE_DECIMAL_CURRENCIES = ["BHD", "JOD", "KWD", "OMR", "TND"];
+function importStripeBalanceRows(rows, source) {
+    const result = { events: [], errors: [], skipped: [] };
+    rows.forEach((row, index) => {
+        const number = index + 1;
+        const category = text(row.reporting_category) ?? "";
+        const mapping = STRIPE_CATEGORIES[category];
+        if (!mapping) {
+            result.skipped.push({ row: number, reason: `reporting_category ${category || "(empty)"} is not job cost` });
+            return;
+        }
+        const ref = text(row[mapping.refColumn]);
+        if (ref === null) {
+            result.skipped.push({ row: number, reason: `no ${mapping.refColumn}` });
+            return;
+        }
+        try {
+            const sourceEventId = text(row.balance_transaction_id);
+            if (sourceEventId === null)
+                throw new Error("missing balance_transaction_id");
+            const currency = (text(row.currency) ?? "").toUpperCase();
+            if (!/^[A-Z]{3}$/.test(currency))
+                throw new Error(`currency ${JSON.stringify(row.currency ?? null)} is not an ISO 4217 code`);
+            const gross = text(row.gross);
+            if (gross === null)
+                throw new Error("missing gross");
+            const created = row.created_utc ?? row.created;
+            result.events.push({
+                row: number,
+                event: {
+                    type: mapping.type,
+                    source,
+                    source_event_id: sourceEventId,
+                    provider_reference: text(row.source_id),
+                    provider_status: null,
+                    amount_minor: Math.abs(stripeMajorToMinor(gross, currency)),
+                    currency,
+                    event_date: utcIso(created, row.created_utc !== undefined ? "created_utc" : "created"),
+                    match: { provider_job_ref: ref, task_external_ref: null, delegation_external_ref: null },
+                },
+            });
+        }
+        catch (error) {
+            result.errors.push({ row: number, error: error.message });
+        }
+    });
+    return result;
+}
+/** Stripe reports amounts in major units; zeros past the currency's decimal places (JPY "500.00") are dropped. */
+function stripeMajorToMinor(value, currency) {
+    const digits = ZERO_DECIMAL_CURRENCIES.includes(currency) ? 0 : THREE_DECIMAL_CURRENCIES.includes(currency) ? 3 : 2;
+    const [whole, fraction = ""] = value.split(".");
+    const trimmedFraction = fraction.length > digits ? fraction.slice(0, digits) + fraction.slice(digits).replace(/0+$/, "") : fraction;
+    return majorToMinor(trimmedFraction ? `${whole}.${trimmedFraction}` : whole, digits);
+}
+/** An ISO timestamp; a date or date-time without a zone is read as UTC, as LiteLLM and Stripe write them. */
+function utcIso(value, column) {
+    const raw = typeof value === "string" ? value.trim() : "";
+    const zoneless = /^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?$/.test(raw);
+    const time = Date.parse(zoneless ? `${raw.replace(" ", "T")}${raw.length > 10 ? "Z" : ""}` : raw);
+    if (raw === "" || Number.isNaN(time))
+        throw new Error(`${column} ${JSON.stringify(value ?? null)} is not a date`);
+    return new Date(time).toISOString();
+}
+function text(value) {
+    if (value === undefined || value === null)
+        return null;
+    const result = String(value).trim();
+    return result === "" ? null : result;
+}
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}

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 {};