@atcn/subledger 1.4.0 → 1.5.0

package/dist/types.js

@@ -1,15 +1,64 @@
-import { ExecutionDescriptorSchema } from "@atcn/schema";
+import { ExecutionDescriptorSchema, PricingSchema, RefundTermsSchema, SkillRefSchema, UsageSummarySchema } from "@atcn/schema";
 import { z } from "zod";
 /** Agent Work Subledger record shapes (PRD v1.2 §6-§7). Amounts are integer minor units; currencies are ISO 4217. */
 export const Currency = z.string().regex(/^[A-Z]{3}$/, "ISO 4217 currency code");
 export const Minor = z.number().int().refine(Number.isSafeInteger, "amount must be a safe integer");
 const Iso = z.iso.datetime();
 const Digest = z.string().regex(/^sha256:[0-9a-f]{64}$/);
-export const FINANCIAL_EVENT_TYPES = ["quote", "invoice", "charge", "payment_reported", "refund", "reversal", "fee", "credit", "adjustment", "fx_rate"];
-/** Normalized status vocabulary; the provider's original status is always kept beside it. */
-export const NORMALIZED_STATUSES = ["quoted", "issued", "pending", "reported_paid", "failed", "refunded", "reversed", "void", "unknown"];
+/** "estimate" and "hold" (schema 1.5) record what was expected before work ran; they are never costs. */
+export const FINANCIAL_EVENT_TYPES = ["quote", "invoice", "charge", "payment_reported", "refund", "reversal", "fee", "credit", "adjustment", "fx_rate", "estimate", "hold"];
+/**
+ * Normalized status vocabulary; the provider's original status is always kept beside it. "pending_finality" (schema
+ * 1.5) is a payment the rail reports as settled that can still be reversed until the rail's finality window ends.
+ */
+export const NORMALIZED_STATUSES = ["quoted", "issued", "pending", "reported_paid", "pending_finality", "failed", "refunded", "reversed", "void", "unknown"];
+/** Financial event types that bill for work and so may name the skill billed (schema 1.5). */
+export const SKILL_BILLED_EVENT_TYPES = ["quote", "invoice", "charge"];
+/**
+ * Estimates and holds (schema 1.5): what the agent, a budget gateway or the operator expected a piece of work to cost
+ * before it ran. ATCN records them and reports the gap against actual cost; it never enforces, blocks or reserves.
+ */
+export const EXPECTATION_EVENT_TYPES = ["estimate", "hold"];
+export const EXPECTATION_ISSUERS = ["agent", "gateway", "operator"];
+export const HOLD_STATUSES = ["open", "captured", "released", "expired"];
+/**
+ * A signature by a key bound to a registered provider (an agent's provider or a gateway), over the statement of an
+ * estimate, a hold, or a terminal delivery claim (schema 1.5).
+ */
+export const KeySignerSchema = z.strictObject({
+    provider_id: z.string().min(1),
+    binding_id: z.string().min(1),
+    key_id: z.string().min(1),
+    value: z.string().min(1),
+});
+export const ExpectationSchema = z.strictObject({
+    /** Who made the estimate or hold. */
+    issued_by: z.enum(EXPECTATION_ISSUERS),
+    /** The issuer's own reference, such as a gateway request ID. */
+    source_ref: z.string().max(200).nullable(),
+    /** How the amount was worked out, for example "max tokens x rate". */
+    basis: z.string().max(500).nullable(),
+    expires_at: Iso.nullable(),
+    /** The source_event_id (same source) of the earlier estimate, or earlier record of the same hold, this one replaces. */
+    supersedes: z.string().max(200).nullable(),
+    /** Holds only: the hold's status as of this record. */
+    hold_status: z.enum(HOLD_STATUSES).optional(),
+    /** Absent when the operator recorded it; the record is then buyer_recorded. */
+    signer: KeySignerSchema.optional(),
+});
+/**
+ * A payment rail's own record of a payment or refund (schema 1.5), for example an A2A-SE escrow attestation with its
+ * Merkle inclusion proof. `scheme` names the format; `record` is the rail's record exactly as received.
+ */
+export const RailAttestationSchema = z.strictObject({
+    scheme: z.string().min(1).max(200),
+    record: z.record(z.string(), z.unknown()),
+});
+export const RAIL_ATTESTED_EVENT_TYPES = ["payment_reported", "refund"];
 export const PAYERS = ["buyer", "provider", "other"];
 export const DELIVERY_EVENT_TYPES = ["acceptance", "completion", "partial_completion", "cancellation", "provider_failure", "terms_update", "correction"];
+/** Outcome claims the provider may sign with its bound key (schema 1.5): how its work ended. */
+export const SIGNED_CLAIM_TYPES = ["completion", "partial_completion", "cancellation", "provider_failure"];
 /**
  * Who made a delivery statement. Callers record "buyer" or "provider" (relayed by the buyer). The other values are
  * recorded only from clearing-network events: "clearing_policy" for a decision computed by the agreed policy from
@@ -29,6 +78,28 @@ export const EXCEPTION_KINDS = [
     "refund_after_close",
     "allocation_changed_after_close",
     "incomplete_lineage",
+    "usage_unpriced",
+    "usage_cost_mismatch",
+    /** A refund exceeds the agreed post-settlement cap or window, or a refund the terms require was not made. */
+    "refund_terms_breach",
+    /** A quote, invoice or charge names a different skill from the one delegated. */
+    "skill_price_mismatch",
+    /** Fewer independent witnesses attested to the run than the delegation requires. */
+    "witness_quorum_not_met",
+    /** Signed provider statements bound to the same receipt contradict each other. */
+    "conflicting_statements",
+    /** An estimate or hold matched no task or delegation, or several. */
+    "unmatched_estimate",
+    /** Actual cost on a node exceeds its estimate (beyond the task's tolerance). Recorded, not prevented. */
+    "actual_exceeds_estimate",
+    /** Actual cost on a node exceeds what is held for it. Recorded, not prevented. */
+    "actual_exceeds_hold",
+    /** A hold is still open past its expiry, or at close with nothing charged. */
+    "hold_not_released",
+    /** An estimate was issued after the first charge on its node; it is kept but not used as the estimate. */
+    "estimate_after_charge",
+    /** A cancelled or failed delegation still has billed cost that no refund, credit or reversal nets to zero. */
+    "charge_after_cancellation",
 ];
 /** Trust labels kept separate on every screen and export (PRD §16 "Identity assurance"). Never collapsed into "verified". */
 export const ASSURANCE_LABELS = [
@@ -46,11 +117,28 @@ export const ASSURANCE_LABELS = [
     "expired",
     /** A response statement revoked by a later statement from the same provider (schema 1.4). */
     "revoked",
+    /** An estimate or hold signed by a budget gateway's bound key (schema 1.5). */
+    "gateway_signed",
+    /** A payment or refund backed by the rail's own attestation, verified offline (schema 1.5). Not operator-reported. */
+    "rail_attested",
 ];
 export const RESPONSE_TYPES = ["acknowledge_view", "acknowledge_delivery", "submit_evidence", "propose_correction", "signed_attestation"];
-export const SHARE_ACTIONS = ["view", "acknowledge_delivery", "submit_evidence", "propose_correction", "signed_attestation"];
+/** "witness_attestation" (schema 1.5) lets an independent witness sign a statement that it observed the run. */
+export const SHARE_ACTIONS = ["view", "acknowledge_delivery", "submit_evidence", "propose_correction", "signed_attestation", "witness_attestation"];
 /** Receipt fields a provider may attest to or contest. Attesting one never implies the others (acceptance 16). */
-export const ATTESTABLE_FIELDS = ["delivery.status", "delivery.evidence", "scope.terms_digest", "financial.amounts", "financial.status"];
+export const ATTESTABLE_FIELDS = ["delivery.status", "delivery.evidence", "scope.terms_digest", "financial.amounts", "financial.status", "delivery.usage"];
+/** Schema 1.5 added "delivery.usage". Documents of earlier versions disclose exactly these fields. */
+const ATTESTABLE_FIELDS_BEFORE_1_5 = ["delivery.status", "delivery.evidence", "scope.terms_digest", "financial.amounts", "financial.status"];
+export function attestableFieldsFor(schemaVersion) {
+    return ["1.2", "1.3", "1.4"].includes(schemaVersion) ? ATTESTABLE_FIELDS_BEFORE_1_5 : ATTESTABLE_FIELDS;
+}
+/** The usage of a run as recorded on a delivery claim: the trace's summary and the digest of the full trace, which stays with its holder. */
+export const UsageRecordSchema = z.strictObject({
+    trace_digest: Digest,
+    summary: UsageSummarySchema,
+});
+/** Delivery claims that may carry usage. */
+export const USAGE_CLAIM_TYPES = ["completion", "partial_completion"];
 /** Evidence stays in its source system; only references and digests are stored. Script-capable schemes are refused. */
 export const EvidenceRefSchema = z.object({
     uri: z
@@ -61,6 +149,13 @@ export const EvidenceRefSchema = z.object({
     digest: Digest.nullable(),
     evidence_type: z.string().min(1).max(100),
 });
+/** Why part of a delegation chain was not captured. broken_edge: a reported sub-task arrived with no outcome. */
+export const CAPTURE_GAP_KINDS = ["capture_failed", "queue_overflow", "provider_undisclosed", "manual_gap", "broken_edge"];
+export const CaptureGapInputSchema = z.object({
+    delegation_id: z.string().nullable().default(null),
+    kind: z.enum(CAPTURE_GAP_KINDS),
+    detail: z.string().min(1).max(2000),
+});
 export const TaskInputSchema = z.object({
     external_ref: z.string().min(1).max(200),
     currency: Currency,
@@ -72,12 +167,25 @@ export const TaskInputSchema = z.object({
     shared_description: z.string().max(1000).nullable().default(null),
     retrospective: z.boolean().default(false),
     occurred_at: Iso.nullable().default(null),
+    /** Schema 1.5: how far actual cost may exceed an estimate, in basis points, before actual_exceeds_estimate opens. */
+    estimate_tolerance_bps: z.number().int().min(0).max(100_000).optional(),
 });
 export const ProviderInputSchema = z.object({
     name: z.string().min(1).max(200),
     provider_own_id: z.string().max(200).nullable().default(null),
     domain: z.string().max(253).nullable().default(null),
 });
+/**
+ * Independent witnesses a delegation requires (schema 1.5). A witness is a registered provider other than the
+ * delegation's own, signing with a domain-challenged key; it counts only if that registrable domain differs from the
+ * provider's, the buyer operator's and every other counted witness's. Too few raise witness_quorum_not_met.
+ */
+export const SubledgerWitnessPolicySchema = z.strictObject({
+    min_independent_witnesses: z.number().int().min(1).max(10),
+    /** If set, only these providers may witness. */
+    witness_provider_ids: z.array(z.string().min(1)).min(1).max(20).optional(),
+    independence: z.literal("distinct_verified_domain"),
+});
 export const DelegationInputSchema = z.object({
     parent_delegation_id: z.string().nullable().default(null),
     provider_id: z.string().nullable().default(null),
@@ -100,6 +208,12 @@ export const DelegationInputSchema = z.object({
     retrospective: z.boolean().default(false),
     /** The provider's run as the buyer recorded it (for A2A, from the task and agent card). Provider statements can cite it. */
     execution: ExecutionDescriptorSchema.optional(),
+    /** Agreed usage prices (schema 1.5). Billed cost is compared with usage priced at these rates. */
+    pricing: PricingSchema.optional(),
+    /** Agreed refund and failure terms (schema 1.5). Refunds that break them raise refund_terms_breach. */
+    refund_terms: RefundTermsSchema.optional(),
+    /** Independent witnesses required (schema 1.5). */
+    witness_policy: SubledgerWitnessPolicySchema.optional(),
 });
 export const DelegationEventInputSchema = z.object({
     type: z.enum(DELIVERY_EVENT_TYPES),
@@ -117,6 +231,12 @@ export const DelegationEventInputSchema = z.object({
         terms_digest: Digest.nullable().optional(),
         expected_delivery: Iso.nullable().optional(),
         downstream_visibility: z.enum(["unknown", "disclosed", "none"]).optional(),
+        /** Schema 1.5: replaces the delegation's pricing; null removes it. */
+        pricing: PricingSchema.nullable().optional(),
+        /** Schema 1.5: replaces the delegation's refund terms; null removes them. */
+        refund_terms: RefundTermsSchema.nullable().optional(),
+        /** Schema 1.5: replaces the delegation's witness policy; null removes it. */
+        witness_policy: SubledgerWitnessPolicySchema.nullable().optional(),
     })
         .nullable()
         .default(null),
@@ -125,7 +245,29 @@ export const DelegationEventInputSchema = z.object({
     reason: z.string().max(2000).nullable().default(null),
     retrospective: z.boolean().default(false),
     occurred_at: Iso.nullable().default(null),
+    /** completion and partial_completion only (schema 1.5): the run's usage, from its trace. */
+    usage: UsageRecordSchema.optional(),
+    /**
+     * Outcome claims asserted by the provider only (schema 1.5): the provider's signature over the outcome statement,
+     * which names the delegation's provider_job_ref (for A2A, the task id) and the claim's evidence.
+     */
+    signer: KeySignerSchema.optional(),
 });
+/** Rules across fields of a delivery event that the schema cannot express. */
+export function delegationEventProblems(input) {
+    const problems = [];
+    if (input.usage !== undefined && !USAGE_CLAIM_TYPES.includes(input.type))
+        problems.push(`usage is allowed only on ${USAGE_CLAIM_TYPES.join(" and ")} events`);
+    if (input.signer !== undefined) {
+        if (!SIGNED_CLAIM_TYPES.includes(input.type))
+            problems.push(`signer is allowed only on ${SIGNED_CLAIM_TYPES.join(", ")} events`);
+        if (input.asserted_by !== "provider")
+            problems.push("a signed claim must be asserted_by provider");
+        if (input.usage !== undefined)
+            problems.push("a signed claim cannot carry usage, which the outcome statement does not cover");
+    }
+    return problems;
+}
 export const FxSchema = z.object({
     base_currency: Currency,
     quote_currency: Currency,
@@ -155,6 +297,12 @@ export const FinancialEventInputSchema = z
     settles_event_id: z.string().nullable().default(null),
     fx: FxSchema.nullable().default(null),
     reason: z.string().max(2000).nullable().default(null),
+    /** Quotes, invoices and charges only (schema 1.5): the skill billed, from the provider's billing line. */
+    skill: SkillRefSchema.optional(),
+    /** Estimates and holds only (schema 1.5): who issued it, why, and how it relates to earlier ones. */
+    expectation: ExpectationSchema.optional(),
+    /** Payments and refunds only (schema 1.5): the rail's own attestation of the payment, embedded so it verifies offline. */
+    rail_attestation: RailAttestationSchema.optional(),
     /** Stable references used for matching. Only a unique match is applied automatically. */
     match: z
         .object({
@@ -175,7 +323,32 @@ export const FinancialEventInputSchema = z
         issue.addIssue({ code: "custom", path: ["reverses_event_id"], message: "reversal needs reverses_event_id" });
     if (e.type === "reversal" && !e.reason)
         issue.addIssue({ code: "custom", path: ["reason"], message: "reversal needs a reason" });
+    if (e.skill && !SKILL_BILLED_EVENT_TYPES.includes(e.type))
+        issue.addIssue({ code: "custom", path: ["skill"], message: `skill is allowed only on ${SKILL_BILLED_EVENT_TYPES.join(", ")} events` });
+    for (const problem of expectationProblems(e))
+        issue.addIssue({ code: "custom", path: ["expectation"], message: problem });
+    if (e.rail_attestation && !RAIL_ATTESTED_EVENT_TYPES.includes(e.type)) {
+        issue.addIssue({ code: "custom", path: ["rail_attestation"], message: `rail_attestation is allowed only on ${RAIL_ATTESTED_EVENT_TYPES.join(" and ")} events` });
+    }
 });
+/** Rules for estimates and holds that the schema cannot express. */
+export function expectationProblems(e) {
+    const isExpectation = EXPECTATION_EVENT_TYPES.includes(e.type);
+    if (!isExpectation)
+        return e.expectation ? ["expectation is allowed only on estimate and hold events"] : [];
+    if (!e.expectation)
+        return [`${e.type} events need expectation`];
+    const problems = [];
+    if (e.amount_minor < 0)
+        problems.push(`${e.type} amount must not be negative`);
+    if (e.type === "hold" && !e.expectation.hold_status)
+        problems.push("hold events need expectation.hold_status");
+    if (e.type === "estimate" && e.expectation.hold_status)
+        problems.push("only hold events carry hold_status");
+    if (e.expectation.issued_by === "operator" && e.expectation.signer)
+        problems.push("operator estimates and holds are recorded by the operator, not signed by a provider key");
+    return problems;
+}
 export const AllocationTargetSchema = z.object({
     type: z.enum(["task", "delegation", "cost_center", "unallocated"]),
     id: z.string().max(200).nullable(),

package/dist/usage.d.ts

@@ -0,0 +1,41 @@
+import { type Pricing } from "@atcn/schema";
+import type { DeliveryClaim, ResponseRecord, UsageCheck } from "./documents.js";
+import type { Rollup, Totals } from "./rollup.js";
+/** What a delegation was billed: invoices, charges, fees and adjustments, less credits and refunds. */
+export declare function billedMinor(totals: Totals | undefined): number;
+/**
+ * The usage claims that count for one delegation: completion and partial_completion claims with usage that no later
+ * correction superseded. Each claim reports the usage of the work it covers, so claims are summed, but a trace
+ * recorded more than once (for example by both buyer and provider) counts once, from its latest claim.
+ */
+export declare function countedUsageClaims(claims: DeliveryClaim[]): DeliveryClaim[];
+export interface UsageCheckInput {
+    delegation_id: string;
+    currency: string;
+    pricing: Pricing | null | undefined;
+    /** This delegation's claims, in recorded order. */
+    claims: DeliveryClaim[];
+    billed_minor: number;
+    /** Whether a provider key-signed, unexpired, unrevoked statement attests delivery.usage on this delegation's receipt. */
+    provider_attested: boolean;
+}
+/**
+ * Prices a delegation's usage at its agreed rates and compares it with what was billed, in both directions:
+ * overbilling is the obvious risk, and underbilling often means a charge is missing or attributed elsewhere.
+ * Null when the delegation has no pricing or no counted usage.
+ */
+export declare function usageCheckFor(input: UsageCheckInput): UsageCheck | null;
+/** Delegations whose receipts carry an in-force provider key-signed attestation of delivery.usage. */
+export declare function usageAttestedDelegations(responses: ResponseRecord[], receipts: {
+    receipt_id: string;
+    delegation_id: string;
+}[]): Set<string>;
+/** Usage checks for every delegation of a closure with pricing and counted usage, in delegation order. */
+export declare function usageChecksFor(delegations: {
+    delegation_id: string;
+    currency: string;
+    pricing?: Pricing;
+}[], claims: DeliveryClaim[], rollup: Rollup, responses: ResponseRecord[], receipts: {
+    receipt_id: string;
+    delegation_id: string;
+}[]): UsageCheck[];

package/dist/usage.js

@@ -0,0 +1,86 @@
+import { allowedDifference, expectedCostFromUsage } from "@atcn/schema";
+import { ASSURANCE_LABELS, USAGE_CLAIM_TYPES } from "./types.js";
+/** What a delegation was billed: invoices, charges, fees and adjustments, less credits and refunds. */
+export function billedMinor(totals) {
+    return totals ? totals.invoiced + totals.charged + totals.fees + totals.adjustments - totals.credits - totals.refunded : 0;
+}
+/**
+ * The usage claims that count for one delegation: completion and partial_completion claims with usage that no later
+ * correction superseded. Each claim reports the usage of the work it covers, so claims are summed, but a trace
+ * recorded more than once (for example by both buyer and provider) counts once, from its latest claim.
+ */
+export function countedUsageClaims(claims) {
+    const superseded = new Set(claims.map((c) => c.supersedes_event_id).filter((id) => id !== null));
+    const byTrace = new Map();
+    for (const c of claims) {
+        if (!c.usage || superseded.has(c.event_id) || !USAGE_CLAIM_TYPES.includes(c.type))
+            continue;
+        byTrace.set(c.usage.trace_digest, c);
+    }
+    return [...byTrace.values()];
+}
+function sortedLabels(labels) {
+    return ASSURANCE_LABELS.filter((l) => labels.has(l));
+}
+/**
+ * Prices a delegation's usage at its agreed rates and compares it with what was billed, in both directions:
+ * overbilling is the obvious risk, and underbilling often means a charge is missing or attributed elsewhere.
+ * Null when the delegation has no pricing or no counted usage.
+ */
+export function usageCheckFor(input) {
+    if (!input.pricing)
+        return null;
+    const counted = countedUsageClaims(input.claims);
+    if (counted.length === 0)
+        return null;
+    const cost = expectedCostFromUsage(input.pricing, counted.map((c) => c.usage.summary));
+    const expected = cost.expected_minor;
+    const allowed = expected === null ? null : allowedDifference(expected, input.pricing.tolerance_bps);
+    const difference = expected === null ? null : input.billed_minor - expected;
+    const labels = new Set(counted.flatMap((c) => c.assurance).filter((l) => l !== "superseded"));
+    if (input.provider_attested)
+        labels.add("provider_key_signed");
+    return {
+        delegation_id: input.delegation_id,
+        currency: input.currency,
+        expected_minor: expected,
+        lines: cost.lines,
+        billed_minor: input.billed_minor,
+        difference_minor: difference,
+        allowed_difference_minor: allowed,
+        within_tolerance: difference === null || allowed === null ? null : Math.abs(difference) <= allowed,
+        unpriced: cost.unpriced,
+        trace_digests: counted.map((c) => c.usage.trace_digest).sort(),
+        assurance: sortedLabels(labels),
+    };
+}
+/** Delegations whose receipts carry an in-force provider key-signed attestation of delivery.usage. */
+export function usageAttestedDelegations(responses, receipts) {
+    const delegationOf = new Map(receipts.map((r) => [r.receipt_id, r.delegation_id]));
+    const attested = new Set();
+    for (const r of responses) {
+        const inForce = r.assurance.includes("provider_key_signed") && !r.assurance.includes("expired") && !r.assurance.includes("revoked");
+        if (inForce && r.statement.response_type === "signed_attestation" && r.statement.fields.includes("delivery.usage")) {
+            const delegationId = delegationOf.get(r.receipt_id);
+            if (delegationId)
+                attested.add(delegationId);
+        }
+    }
+    return attested;
+}
+/** Usage checks for every delegation of a closure with pricing and counted usage, in delegation order. */
+export function usageChecksFor(delegations, claims, rollup, responses, receipts) {
+    const attested = usageAttestedDelegations(responses, receipts);
+    return delegations.flatMap((d) => {
+        const node = rollup.nodes.find((n) => n.node_id === d.delegation_id);
+        const result = usageCheckFor({
+            delegation_id: d.delegation_id,
+            currency: d.currency,
+            pricing: d.pricing,
+            claims: claims.filter((c) => c.delegation_id === d.delegation_id),
+            billed_minor: billedMinor(node?.direct[d.currency]),
+            provider_attested: attested.has(d.delegation_id),
+        });
+        return result ? [result] : [];
+    });
+}

package/dist/verify.d.ts

@@ -1,9 +1,12 @@
 import { type PublicKeyRecord } from "@atcn/schema";
-import { type OperatorKeyRecord } from "./documents.js";
+import { type OperatorKeyRecord, type SignedClosure } from "./documents.js";
+import { type DerivedException } from "./exceptions.js";
 export interface CheckResult {
     name: string;
     ok: boolean;
     details: string[];
+    /** Set when the check had nothing it could inspect (for example, traces committed but not supplied). Not a pass. */
+    state?: "not_inspected";
 }
 export interface SubledgerVerificationReport {
     valid: boolean;
@@ -25,8 +28,12 @@ export interface SubledgerVerifyOptions {
     obligationPackages?: unknown[];
     /** Time to check a receipt's expires_at against (ISO 8601). Defaults to now. */
     at?: string;
+    /** Trace files (raw bytes) behind recorded usage, to recompute each usage summary from its trace. */
+    traces?: Uint8Array[];
 }
 /** Detects the document type and verifies it offline: no network calls, no service access (acceptance 9). */
 export declare function verifySubledgerDocument(input: unknown, options: SubledgerVerifyOptions): SubledgerVerificationReport;
 export declare function verifyReceipt(input: unknown, options: SubledgerVerifyOptions): SubledgerVerificationReport;
 export declare function verifyClosure(input: unknown, options: SubledgerVerifyOptions): SubledgerVerificationReport;
+/** The derived exceptions a closure's own records imply at close, as of generated_at; the service must list each as open or resolved. */
+export declare function closureDerivedExceptions(c: SignedClosure["payload"]): DerivedException[];