@atcn/subledger 1.4.0 → 1.5.0

package/dist/expectations.js

@@ -0,0 +1,236 @@
+import { canonicalize, signBytes, utf8Encode, verifyBytes } from "@atcn/schema";
+import { deliveryStatus } from "./projection.js";
+import { costSign } from "./rollup.js";
+/**
+ * Estimates and holds (schema 1.5): what the agent, a budget gateway or the operator expected work to cost before it
+ * ran, compared with what it actually cost. Record only: ATCN never enforces, blocks or reserves anything.
+ */
+export const EXPECTATION_STATEMENT_TYPE = "atcn.subledger.expectation";
+export function buildExpectationStatement(input) {
+    return {
+        document_type: EXPECTATION_STATEMENT_TYPE,
+        type: input.type,
+        source: input.source,
+        source_event_id: input.source_event_id,
+        provider_reference: input.provider_reference ?? null,
+        amount_minor: input.amount_minor,
+        currency: input.currency,
+        issued_at: new Date(input.issued_at).toISOString(),
+        issued_by: input.expectation.issued_by,
+        source_ref: input.expectation.source_ref,
+        basis: input.expectation.basis,
+        expires_at: input.expectation.expires_at === null ? null : new Date(input.expectation.expires_at).toISOString(),
+        supersedes: input.expectation.supersedes,
+        hold_status: input.expectation.hold_status ?? null,
+    };
+}
+/** The statement a stored estimate or hold record was signed over. */
+export function expectationStatementOf(record) {
+    return buildExpectationStatement({
+        type: record.type,
+        source: record.source,
+        source_event_id: record.source_event_id,
+        provider_reference: record.provider_reference,
+        amount_minor: record.amount_minor,
+        currency: record.currency,
+        issued_at: record.event_date,
+        expectation: record.expectation,
+    });
+}
+/** Agent- or gateway-side signing. The operator never holds the signer's private key. */
+export function signExpectation(statement, privateKey) {
+    return signBytes(utf8Encode(canonicalize(statement)), privateKey);
+}
+export function verifyExpectationSignature(statement, signature, publicKey) {
+    return verifyBytes(utf8Encode(canonicalize(statement)), signature, publicKey);
+}
+/**
+ * Why a signed estimate or hold does not verify, or null when it does (or carries no signature). The key must be bound
+ * to the named provider and not revoked when the record was issued; an agent's estimate must be signed by the
+ * provider of the delegation it is attributed to.
+ */
+export function expectationSignatureProblem(record, delegationProviderId, keyBindings) {
+    const signer = record.expectation?.signer;
+    if (!signer)
+        return null;
+    const label = `${record.type} ${record.financial_event_id}`;
+    const binding = keyBindings.find((b) => b.binding_id === signer.binding_id && b.key_id === signer.key_id);
+    if (!binding)
+        return `${label} is signed with a key binding that is not listed`;
+    if (binding.provider_id !== signer.provider_id)
+        return `${label} key binding belongs to another provider`;
+    if (binding.revoked_at !== null && binding.revoked_at <= record.event_date)
+        return `${label} was signed after its key binding was revoked`;
+    if (record.expectation.issued_by === "agent" && signer.provider_id !== delegationProviderId)
+        return `${label} is an agent estimate signed by a provider other than the delegation's`;
+    if (!signedStatementVerifies(() => verifyExpectationSignature(expectationStatementOf(record), signer.value, binding.public_key)))
+        return `${label} signature does not verify`;
+    return null;
+}
+/** Labels are never collapsed: a verified agent signature is provider_key_signed, a gateway's is gateway_signed, anything else is buyer_recorded. */
+export function expectationAssurance(record, delegationProviderId, keyBindings) {
+    const expectation = record.expectation;
+    if (!expectation.signer || expectationSignatureProblem(record, delegationProviderId, keyBindings) !== null)
+        return ["buyer_recorded"];
+    return [expectation.issued_by === "gateway" ? "gateway_signed" : "provider_key_signed"];
+}
+/** Delivery statuses after which an open hold is treated as released: the work did not go ahead. */
+const RELEASING_STATUSES = ["cancelled", "provider_failed"];
+/** Variance in basis points of `base`, rounded half away from zero, using integers only. Null when there is no base. */
+export function varianceBps(difference, base) {
+    if (base === null || base === 0)
+        return null;
+    const sign = difference < 0 ? -1 : 1;
+    return sign * Math.floor((Math.abs(difference) * 10_000 * 2 + base) / (2 * base));
+}
+/**
+ * Estimates and holds compared with actual cost, per node and for the task, in the task's currency. Null when the task
+ * has no estimates or holds. A node's actual cost is its own net cost (what was billed against it directly).
+ */
+export function buildExpectationReport(input) {
+    const currency = input.task.currency;
+    const expectations = input.events.filter((e) => e.record.expectation !== undefined);
+    if (expectations.length === 0)
+        return null;
+    const providerOf = new Map(input.delegations.map((d) => [d.delegation_id, d.provider_id]));
+    const statusOfDelegation = (nodeId) => deliveryStatus(input.claims.filter((c) => c.delegation_id === nodeId));
+    const supersededIds = new Set(expectations.filter((e) => e.record.expectation.supersedes !== null).map((e) => `${e.record.source}\u0000${e.record.type}\u0000${e.record.expectation.supersedes}`));
+    const isSuperseded = (record) => supersededIds.has(`${record.source}\u0000${record.type}\u0000${record.source_event_id}`);
+    const directNetCost = (nodeId) => input.rollup.nodes.find((n) => n.node_id === nodeId)?.direct[currency]?.net_cost ?? 0;
+    const chargesOn = (nodeId) => input.events
+        .filter((e) => e.attributed_to === nodeId && e.record.currency === currency && costSign(e.record.type) === 1 && !input.rollup.excluded_event_ids.reversed.includes(e.record.financial_event_id))
+        .map((e) => e.record);
+    const firstChargeAt = (nodeId) => chargesOn(nodeId).map((r) => r.event_date).sort()[0] ?? null;
+    const firstChargeRecordedAt = (nodeId) => chargesOn(nodeId).map((r) => r.imported_at).sort()[0] ?? null;
+    // An estimate dated before the first charge but recorded after it was back-dated, unless the import says it is retrospective.
+    const isAfterCharge = (record, nodeId) => {
+        const firstCharge = firstChargeAt(nodeId);
+        if (firstCharge === null)
+            return false;
+        return record.event_date > firstCharge || (!record.retrospective && record.imported_at > firstChargeRecordedAt(nodeId));
+    };
+    const records = expectations.map(({ record, attributed_to: nodeId }) => {
+        let status = "current";
+        if (record.currency !== currency)
+            status = "other_currency";
+        else if (isSuperseded(record))
+            status = "superseded";
+        else if (record.type === "estimate" && isAfterCharge(record, nodeId))
+            status = "after_charge";
+        let holdStatus = record.expectation.hold_status ?? null;
+        if (holdStatus === "open" && RELEASING_STATUSES.includes(statusOfDelegation(nodeId)))
+            holdStatus = "released";
+        const assurance = expectationAssurance(record, providerOf.get(nodeId) ?? null, input.key_bindings);
+        return {
+            financial_event_id: record.financial_event_id,
+            node_id: nodeId,
+            type: record.type,
+            issued_by: record.expectation.issued_by,
+            status,
+            hold_status: holdStatus,
+            assurance: status === "superseded" ? [...assurance, "superseded"] : assurance,
+        };
+    });
+    // Of several current estimates on a node, the latest issued is used; the others stay listed as not_latest.
+    const recordById = new Map(expectations.map((e) => [e.record.financial_event_id, e.record]));
+    const nodeIds = [...new Set(records.map((r) => r.node_id))];
+    const usedEstimate = new Map();
+    for (const nodeId of nodeIds) {
+        const current = records.filter((r) => r.node_id === nodeId && r.type === "estimate" && r.status === "current").map((r) => recordById.get(r.financial_event_id));
+        const latest = current.reduce((best, e) => (best === null || e.event_date >= best.event_date ? e : best), null);
+        if (latest)
+            usedEstimate.set(nodeId, latest);
+    }
+    for (const r of records) {
+        if (r.type === "estimate" && r.status === "current" && usedEstimate.get(r.node_id)?.financial_event_id !== r.financial_event_id)
+            r.status = "not_latest";
+    }
+    const nodes = nodeIds.map((nodeId) => {
+        const estimate = usedEstimate.get(nodeId) ?? null;
+        const held = records
+            .filter((r) => r.node_id === nodeId && r.type === "hold" && r.status === "current" && (r.hold_status === "open" || r.hold_status === "captured"))
+            .reduce((total, r) => total + recordById.get(r.financial_event_id).amount_minor, 0);
+        const hasHold = records.some((r) => r.node_id === nodeId && r.type === "hold" && r.status === "current");
+        return { node_id: nodeId, estimate_event_id: estimate?.financial_event_id ?? null, ...variance(estimate?.amount_minor ?? null, hasHold ? held : null, directNetCost(nodeId)) };
+    });
+    const estimated = nodes.some((n) => n.estimated_minor !== null) ? nodes.reduce((total, n) => total + (n.estimated_minor ?? 0), 0) : null;
+    const anyHold = records.some((r) => r.type === "hold" && r.status === "current");
+    const held = nodes.reduce((total, n) => total + n.held_minor, 0);
+    const actual = input.rollup.root_total[currency]?.net_cost ?? 0;
+    const estimatedNodes = new Set(nodes.filter((n) => n.estimated_minor !== null).map((n) => n.node_id));
+    const unestimated = input.rollup.nodes.filter((n) => !estimatedNodes.has(n.node_id)).reduce((total, n) => total + (n.direct[currency]?.net_cost ?? 0), 0);
+    return { currency, task: { ...variance(estimated, anyHold ? held : null, actual), unestimated_minor: unestimated }, nodes, records };
+}
+function variance(estimated, held, actual) {
+    return {
+        estimated_minor: estimated,
+        held_minor: held ?? 0,
+        actual_minor: actual,
+        variance_vs_estimate_minor: estimated === null ? null : actual - estimated,
+        variance_vs_estimate_bps: estimated === null ? null : varianceBps(actual - estimated, estimated),
+        variance_vs_hold_minor: held === null ? null : actual - held,
+        variance_vs_hold_bps: held === null ? null : varianceBps(actual - held, held),
+    };
+}
+/**
+ * Signals from the expectation report. Recorded, not prevented: none of them blocks work or changes a clearing outcome.
+ * `closing` marks the derivation done when the task is closed, where an open hold with nothing charged is flagged.
+ */
+export function expectationExceptions(report, input) {
+    const result = [];
+    const delegationOf = (nodeId) => (nodeId === input.task.task_id ? null : nodeId);
+    const tolerance = input.task.estimate_tolerance_bps ?? 0;
+    const recordById = new Map(input.events.map((e) => [e.record.financial_event_id, e.record]));
+    for (const node of report.nodes) {
+        if (node.estimated_minor !== null && node.actual_minor * 10_000 > node.estimated_minor * (10_000 + tolerance)) {
+            result.push({
+                kind: "actual_exceeds_estimate",
+                dedupe_key: `actual_exceeds_estimate:${node.node_id}`,
+                delegation_id: delegationOf(node.node_id),
+                detail: `actual ${node.actual_minor} ${report.currency} exceeds estimate ${node.estimated_minor} by ${node.variance_vs_estimate_minor} (${node.variance_vs_estimate_bps} bps, tolerance ${tolerance} bps); recorded, not prevented`,
+            });
+        }
+        if (node.variance_vs_hold_minor !== null && node.variance_vs_hold_minor > 0) {
+            result.push({
+                kind: "actual_exceeds_hold",
+                dedupe_key: `actual_exceeds_hold:${node.node_id}`,
+                delegation_id: delegationOf(node.node_id),
+                detail: `actual ${node.actual_minor} ${report.currency} exceeds held ${node.held_minor} by ${node.variance_vs_hold_minor}; recorded, not prevented`,
+            });
+        }
+    }
+    for (const r of report.records) {
+        const record = recordById.get(r.financial_event_id);
+        if (r.status === "after_charge") {
+            result.push({
+                kind: "estimate_after_charge",
+                dedupe_key: `estimate_after_charge:${r.financial_event_id}`,
+                delegation_id: delegationOf(r.node_id),
+                detail: `estimate ${r.financial_event_id} issued ${record.event_date} and recorded ${record.imported_at}, after the first charge on its node; kept, not used as the estimate`,
+            });
+        }
+        if (r.type !== "hold" || r.status !== "current" || r.hold_status !== "open")
+            continue;
+        const expiresAt = record.expectation.expires_at;
+        const expired = expiresAt !== null && expiresAt < input.now;
+        const nothingCharged = report.nodes.find((n) => n.node_id === r.node_id).actual_minor === 0;
+        if (expired || (input.closing === true && nothingCharged)) {
+            result.push({
+                kind: "hold_not_released",
+                dedupe_key: `hold_not_released:${r.financial_event_id}`,
+                delegation_id: delegationOf(r.node_id),
+                detail: expired ? `hold ${r.financial_event_id} of ${record.amount_minor} ${record.currency} is still open past its expiry ${expiresAt}` : `hold ${r.financial_event_id} of ${record.amount_minor} ${record.currency} is still open at close with nothing charged`,
+            });
+        }
+    }
+    return result;
+}
+/** A statement whose dates cannot be read cannot have been signed as given, so it does not verify. */
+function signedStatementVerifies(verify) {
+    try {
+        return verify();
+    }
+    catch {
+        return false;
+    }
+}

package/dist/importing.d.ts

@@ -0,0 +1,53 @@
+import { type ExpectationIssuer } from "./types.js";
+/**
+ * Turns rows of an external export (a provider bill, a gateway's estimate/hold log) into financial event bodies.
+ * Rows come from CSV or JSONL; a column map names which column feeds which field. Unsigned: imported rows are
+ * buyer_recorded, whoever produced the export.
+ */
+export type ImportRow = Record<string, unknown>;
+export type ImportKind = "charge" | "invoice" | "estimate" | "hold";
+export declare const IMPORT_KINDS: readonly ImportKind[];
+/** Fields a column can feed. amount_major is a decimal amount ("1.25") converted exactly to minor units. */
+export declare const IMPORT_FIELDS: readonly ["source_event_id", "amount_minor", "amount_major", "currency", "event_date", "provider_reference", "provider_status", "provider_job_ref", "task_external_ref", "delegation_external_ref", "issued_by", "source_ref", "basis", "expires_at", "supersedes", "hold_status"];
+export type ImportField = (typeof IMPORT_FIELDS)[number];
+export interface ImportOptions {
+    kind: ImportKind;
+    /** The financial event source, for example "gamma-billing" or "cost-gateway". */
+    source: string;
+    /** Field -> column. A field without an entry reads the column of the same name. */
+    map?: Partial<Record<ImportField, string>>;
+    /** Used when no currency column is mapped or present. */
+    currency?: string;
+    /** Who issued imported estimates and holds when no issued_by column is given (default "gateway"). */
+    issuedBy?: ExpectationIssuer;
+    /**
+     * Columns that identify a row when the export has no stable event id. The key is a hash of their canonical JSON,
+     * so an exact replay deduplicates and a replay that changes any other field is refused as duplicate_event.
+     */
+    keyColumns?: string[];
+    /** Digits after the decimal point for amount_major (default 2). */
+    minorDigits?: number;
+}
+/** RFC 4180 CSV with a header row: comma separated, double-quoted fields, doubled quotes inside quotes. */
+export declare function parseCsvRows(text: string): ImportRow[];
+/** One JSON object per line; blank lines are skipped. */
+export declare function parseJsonlRows(text: string): ImportRow[];
+/** A source_event_id derived from the canonical JSON of a row's identifying columns. */
+export declare function derivedSourceEventId(identity: Record<string, unknown>): string;
+/** Converts "12.5" to 1250 with 2 minor digits, using string arithmetic so no floating point rounding occurs. */
+export declare function majorToMinor(value: string, minorDigits?: number): number;
+/** A financial event body for one row. Throws with a readable message when a required value is missing. */
+export declare function financialEventFromRow(row: ImportRow, options: ImportOptions): Record<string, unknown>;
+export interface ImportResult {
+    /** Each event with the 1-based number of the row it came from. */
+    events: {
+        row: number;
+        event: Record<string, unknown>;
+    }[];
+    errors: {
+        row: number;
+        error: string;
+    }[];
+}
+/** Converts every row; a bad row is reported by its 1-based number without stopping the others. */
+export declare function importRows(rows: ImportRow[], options: ImportOptions): ImportResult;

package/dist/importing.js

@@ -0,0 +1,192 @@
+import { digestOf } from "@atcn/schema";
+import { EXPECTATION_ISSUERS, HOLD_STATUSES } from "./types.js";
+export const IMPORT_KINDS = ["charge", "invoice", "estimate", "hold"];
+/** Fields a column can feed. amount_major is a decimal amount ("1.25") converted exactly to minor units. */
+export const IMPORT_FIELDS = [
+    "source_event_id",
+    "amount_minor",
+    "amount_major",
+    "currency",
+    "event_date",
+    "provider_reference",
+    "provider_status",
+    "provider_job_ref",
+    "task_external_ref",
+    "delegation_external_ref",
+    "issued_by",
+    "source_ref",
+    "basis",
+    "expires_at",
+    "supersedes",
+    "hold_status",
+];
+/** RFC 4180 CSV with a header row: comma separated, double-quoted fields, doubled quotes inside quotes. */
+export function parseCsvRows(text) {
+    const rows = [];
+    let row = [];
+    let field = "";
+    let inQuotes = false;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (inQuotes) {
+            if (ch === '"' && text[i + 1] === '"') {
+                field += '"';
+                i++;
+            }
+            else if (ch === '"')
+                inQuotes = false;
+            else
+                field += ch;
+        }
+        else if (ch === '"')
+            inQuotes = true;
+        else if (ch === ",") {
+            row.push(field);
+            field = "";
+        }
+        else if (ch === "\n" || ch === "\r") {
+            if (ch === "\r" && text[i + 1] === "\n")
+                i++;
+            row.push(field);
+            rows.push(row);
+            row = [];
+            field = "";
+        }
+        else
+            field += ch;
+    }
+    if (field !== "" || row.length > 0) {
+        row.push(field);
+        rows.push(row);
+    }
+    const [header, ...data] = rows.filter((r) => r.some((cell) => cell.trim() !== ""));
+    if (!header)
+        return [];
+    const names = header.map((h) => h.trim());
+    return data.map((cells) => Object.fromEntries(names.map((name, i) => [name, (cells[i] ?? "").trim()])));
+}
+/** One JSON object per line; blank lines are skipped. */
+export function parseJsonlRows(text) {
+    return text
+        .split(/\r?\n/)
+        .map((line, index) => ({ line: line.trim(), number: index + 1 }))
+        .filter(({ line }) => line !== "")
+        .map(({ line, number }) => {
+        let value;
+        try {
+            value = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`line ${number} is not JSON: ${error.message}`);
+        }
+        if (value === null || typeof value !== "object" || Array.isArray(value))
+            throw new Error(`line ${number} is not a JSON object`);
+        return value;
+    });
+}
+/** A source_event_id derived from the canonical JSON of a row's identifying columns. */
+export function derivedSourceEventId(identity) {
+    return `jcs-${digestOf(identity)}`;
+}
+/** Converts "12.5" to 1250 with 2 minor digits, using string arithmetic so no floating point rounding occurs. */
+export function majorToMinor(value, minorDigits = 2) {
+    const match = /^(-?)(\d+)(?:\.(\d+))?$/.exec(value.trim());
+    if (!match)
+        throw new Error(`amount ${JSON.stringify(value)} is not a decimal number`);
+    const [, sign, whole, fraction = ""] = match;
+    if (fraction.length > minorDigits)
+        throw new Error(`amount ${value} has more than ${minorDigits} decimal places`);
+    const minor = Number(whole + fraction.padEnd(minorDigits, "0"));
+    if (!Number.isSafeInteger(minor))
+        throw new Error(`amount ${value} is too large`);
+    return sign === "-" ? -minor : minor;
+}
+/** A financial event body for one row. Throws with a readable message when a required value is missing. */
+export function financialEventFromRow(row, options) {
+    const columnOf = (field) => options.map?.[field] ?? field;
+    const text = (field) => {
+        const value = row[columnOf(field)];
+        if (value === undefined || value === null || value === "")
+            return null;
+        return typeof value === "string" ? value : String(value);
+    };
+    const required = (field) => {
+        const value = text(field);
+        if (value === null)
+            throw new Error(`missing ${field} (column ${columnOf(field)})`);
+        return value;
+    };
+    let amount;
+    if (text("amount_minor") !== null) {
+        amount = Number(text("amount_minor"));
+        if (!Number.isSafeInteger(amount))
+            throw new Error(`amount_minor ${text("amount_minor")} is not a whole number`);
+    }
+    else if (text("amount_major") !== null) {
+        amount = majorToMinor(text("amount_major"), options.minorDigits ?? 2);
+    }
+    else {
+        throw new Error(`missing amount (column ${columnOf("amount_minor")} or ${columnOf("amount_major")})`);
+    }
+    let sourceEventId = text("source_event_id");
+    if (sourceEventId === null) {
+        if (!options.keyColumns || options.keyColumns.length === 0)
+            throw new Error(`missing source_event_id (column ${columnOf("source_event_id")}); name the identifying columns with keyColumns`);
+        const identity = Object.fromEntries(options.keyColumns.map((column) => [column, row[column] ?? null]));
+        if (Object.values(identity).every((value) => value === null || value === ""))
+            throw new Error(`key columns ${options.keyColumns.join(", ")} are all empty`);
+        sourceEventId = derivedSourceEventId(identity);
+    }
+    const body = {
+        type: options.kind,
+        source: options.source,
+        source_event_id: sourceEventId,
+        provider_reference: text("provider_reference"),
+        provider_status: text("provider_status"),
+        amount_minor: amount,
+        currency: text("currency") ?? options.currency ?? required("currency"),
+        event_date: isoDate(required("event_date"), "event_date"),
+        match: {
+            provider_job_ref: text("provider_job_ref"),
+            task_external_ref: text("task_external_ref"),
+            delegation_external_ref: text("delegation_external_ref"),
+        },
+    };
+    if (options.kind === "estimate" || options.kind === "hold") {
+        const issuedBy = text("issued_by") ?? options.issuedBy ?? "gateway";
+        if (!EXPECTATION_ISSUERS.includes(issuedBy))
+            throw new Error(`issued_by ${issuedBy} is not one of ${EXPECTATION_ISSUERS.join(", ")}`);
+        const holdStatus = text("hold_status") ?? "open";
+        if (options.kind === "hold" && !HOLD_STATUSES.includes(holdStatus))
+            throw new Error(`hold_status ${holdStatus} is not one of ${HOLD_STATUSES.join(", ")}`);
+        const expiresAt = text("expires_at");
+        body.expectation = {
+            issued_by: issuedBy,
+            source_ref: text("source_ref"),
+            basis: text("basis"),
+            expires_at: expiresAt === null ? null : isoDate(expiresAt, "expires_at"),
+            supersedes: text("supersedes"),
+            ...(options.kind === "hold" ? { hold_status: holdStatus } : {}),
+        };
+    }
+    return body;
+}
+function isoDate(value, field) {
+    const time = Date.parse(value);
+    if (Number.isNaN(time))
+        throw new Error(`${field} ${JSON.stringify(value)} is not a date`);
+    return new Date(time).toISOString();
+}
+/** Converts every row; a bad row is reported by its 1-based number without stopping the others. */
+export function importRows(rows, options) {
+    const result = { events: [], errors: [] };
+    rows.forEach((row, index) => {
+        try {
+            result.events.push({ row: index + 1, event: financialEventFromRow(row, options) });
+        }
+        catch (error) {
+            result.errors.push({ row: index + 1, error: error.message });
+        }
+    });
+    return result;
+}

package/dist/index.d.ts

@@ -8,3 +8,8 @@ export * from "./response.js";
 export * from "./verify.js";
 export * from "./bridge.js";
 export * from "./matching.js";
+export * from "./usage.js";
+export * from "./expectations.js";
+export * from "./importing.js";
+export * from "./outcome.js";
+export * from "./rails.js";

package/dist/index.js

@@ -8,3 +8,8 @@ export * from "./response.js";
 export * from "./verify.js";
 export * from "./bridge.js";
 export * from "./matching.js";
+export * from "./usage.js";
+export * from "./expectations.js";
+export * from "./importing.js";
+export * from "./outcome.js";
+export * from "./rails.js";

package/dist/outcome.d.ts

@@ -0,0 +1,36 @@
+import type { DeliveryClaim, KeyBindingRecord } from "./documents.js";
+import { type EvidenceRef, type SignedClaimType } from "./types.js";
+/**
+ * Signed outcome claims (schema 1.5): the provider signs how its work ended (completed, partly completed, cancelled or
+ * failed), naming its own job reference (for A2A, the task id) and pointing at its evidence. The buyer records the
+ * claim; a matching key binding makes it provider_key_signed. A downstream agent the buyer never dealt with can sign
+ * one too, so a delegation chain with a broken edge still carries a verifiable outcome for that edge.
+ */
+export declare const OUTCOME_STATEMENT_TYPE = "atcn.subledger.outcome";
+/** What the provider signs. */
+export interface OutcomeStatement {
+    document_type: typeof OUTCOME_STATEMENT_TYPE;
+    type: SignedClaimType;
+    provider_job_ref: string;
+    occurred_at: string;
+    note: string | null;
+    evidence: EvidenceRef[];
+}
+export declare function buildOutcomeStatement(input: {
+    type: SignedClaimType;
+    provider_job_ref: string;
+    occurred_at: string;
+    note?: string | null;
+    evidence?: EvidenceRef[];
+}): OutcomeStatement;
+/** Provider-side signing. The operator never holds the provider's private key. */
+export declare function signOutcomeStatement(statement: OutcomeStatement, privateKey: string): string;
+export declare function verifyOutcomeSignature(statement: OutcomeStatement, signature: string, publicKey: string): boolean;
+/**
+ * Why a signed outcome claim does not verify, or null when it does (or carries no signature). The key must be bound to
+ * the delegation's provider and not revoked when the claim occurred, and the delegation must have a provider_job_ref.
+ */
+export declare function outcomeSignatureProblem(claim: DeliveryClaim, delegation: {
+    provider_id: string | null;
+    provider_job_ref: string | null;
+}, keyBindings: KeyBindingRecord[]): string | null;

package/dist/outcome.js

@@ -0,0 +1,64 @@
+import { canonicalize, signBytes, utf8Encode, verifyBytes } from "@atcn/schema";
+import { SIGNED_CLAIM_TYPES } from "./types.js";
+/**
+ * Signed outcome claims (schema 1.5): the provider signs how its work ended (completed, partly completed, cancelled or
+ * failed), naming its own job reference (for A2A, the task id) and pointing at its evidence. The buyer records the
+ * claim; a matching key binding makes it provider_key_signed. A downstream agent the buyer never dealt with can sign
+ * one too, so a delegation chain with a broken edge still carries a verifiable outcome for that edge.
+ */
+export const OUTCOME_STATEMENT_TYPE = "atcn.subledger.outcome";
+export function buildOutcomeStatement(input) {
+    return {
+        document_type: OUTCOME_STATEMENT_TYPE,
+        type: input.type,
+        provider_job_ref: input.provider_job_ref,
+        occurred_at: new Date(input.occurred_at).toISOString(),
+        note: input.note ?? null,
+        evidence: input.evidence ?? [],
+    };
+}
+/** Provider-side signing. The operator never holds the provider's private key. */
+export function signOutcomeStatement(statement, privateKey) {
+    return signBytes(utf8Encode(canonicalize(statement)), privateKey);
+}
+export function verifyOutcomeSignature(statement, signature, publicKey) {
+    return verifyBytes(utf8Encode(canonicalize(statement)), signature, publicKey);
+}
+/**
+ * Why a signed outcome claim does not verify, or null when it does (or carries no signature). The key must be bound to
+ * the delegation's provider and not revoked when the claim occurred, and the delegation must have a provider_job_ref.
+ */
+export function outcomeSignatureProblem(claim, delegation, keyBindings) {
+    const signer = claim.signer;
+    if (!signer)
+        return null;
+    const label = `${claim.type} claim ${claim.event_id}`;
+    const type = SIGNED_CLAIM_TYPES.find((t) => t === claim.type);
+    if (!type)
+        return `${label} is signed, but only ${SIGNED_CLAIM_TYPES.join(", ")} claims may be`;
+    if (delegation.provider_job_ref === null)
+        return `${label} is signed, but its delegation has no provider_job_ref to sign over`;
+    if (signer.provider_id !== delegation.provider_id)
+        return `${label} is signed by a provider other than the delegation's`;
+    const binding = keyBindings.find((b) => b.binding_id === signer.binding_id && b.key_id === signer.key_id);
+    if (!binding)
+        return `${label} is signed with a key binding that is not listed`;
+    if (binding.provider_id !== signer.provider_id)
+        return `${label} key binding belongs to another provider`;
+    if (binding.revoked_at !== null && binding.revoked_at <= claim.occurred_at)
+        return `${label} was signed after its key binding was revoked`;
+    const jobRef = delegation.provider_job_ref;
+    const verifies = signedStatementVerifies(() => verifyOutcomeSignature(buildOutcomeStatement({ type, provider_job_ref: jobRef, occurred_at: claim.occurred_at, note: claim.note, evidence: claim.evidence }), signer.value, binding.public_key));
+    if (!verifies)
+        return `${label} signature does not verify`;
+    return null;
+}
+/** A statement whose dates cannot be read cannot have been signed as given, so it does not verify. */
+function signedStatementVerifies(verify) {
+    try {
+        return verify();
+    }
+    catch {
+        return false;
+    }
+}