@atcn/subledger 1.4.0 → 1.5.0

package/dist/types.d.ts

@@ -1,14 +1,78 @@
+import { type SkillRef } 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 declare const Currency: z.ZodString;
 export declare const Minor: z.ZodNumber;
-export declare const FINANCIAL_EVENT_TYPES: readonly ["quote", "invoice", "charge", "payment_reported", "refund", "reversal", "fee", "credit", "adjustment", "fx_rate"];
+/** "estimate" and "hold" (schema 1.5) record what was expected before work ran; they are never costs. */
+export declare const FINANCIAL_EVENT_TYPES: readonly ["quote", "invoice", "charge", "payment_reported", "refund", "reversal", "fee", "credit", "adjustment", "fx_rate", "estimate", "hold"];
 export type FinancialEventType = (typeof FINANCIAL_EVENT_TYPES)[number];
-/** Normalized status vocabulary; the provider's original status is always kept beside it. */
-export declare const NORMALIZED_STATUSES: readonly ["quoted", "issued", "pending", "reported_paid", "failed", "refunded", "reversed", "void", "unknown"];
+/**
+ * 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 declare const NORMALIZED_STATUSES: readonly ["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 declare const SKILL_BILLED_EVENT_TYPES: readonly FinancialEventType[];
+/**
+ * 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 declare const EXPECTATION_EVENT_TYPES: readonly FinancialEventType[];
+export declare const EXPECTATION_ISSUERS: readonly ["agent", "gateway", "operator"];
+export type ExpectationIssuer = (typeof EXPECTATION_ISSUERS)[number];
+export declare const HOLD_STATUSES: readonly ["open", "captured", "released", "expired"];
+export type HoldStatus = (typeof HOLD_STATUSES)[number];
+/**
+ * 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 declare const KeySignerSchema: z.ZodObject<{
+    provider_id: z.ZodString;
+    binding_id: z.ZodString;
+    key_id: z.ZodString;
+    value: z.ZodString;
+}, z.core.$strict>;
+export type KeySigner = z.infer<typeof KeySignerSchema>;
+export declare const ExpectationSchema: z.ZodObject<{
+    issued_by: z.ZodEnum<{
+        agent: "agent";
+        gateway: "gateway";
+        operator: "operator";
+    }>;
+    source_ref: z.ZodNullable<z.ZodString>;
+    basis: z.ZodNullable<z.ZodString>;
+    expires_at: z.ZodNullable<z.ZodISODateTime>;
+    supersedes: z.ZodNullable<z.ZodString>;
+    hold_status: z.ZodOptional<z.ZodEnum<{
+        open: "open";
+        captured: "captured";
+        released: "released";
+        expired: "expired";
+    }>>;
+    signer: z.ZodOptional<z.ZodObject<{
+        provider_id: z.ZodString;
+        binding_id: z.ZodString;
+        key_id: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type Expectation = z.infer<typeof ExpectationSchema>;
+/**
+ * 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 declare const RailAttestationSchema: z.ZodObject<{
+    scheme: z.ZodString;
+    record: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export type RailAttestation = z.infer<typeof RailAttestationSchema>;
+export declare const RAIL_ATTESTED_EVENT_TYPES: readonly FinancialEventType[];
 export declare const PAYERS: readonly ["buyer", "provider", "other"];
 export declare const DELIVERY_EVENT_TYPES: readonly ["acceptance", "completion", "partial_completion", "cancellation", "provider_failure", "terms_update", "correction"];
 export type DeliveryEventType = (typeof DELIVERY_EVENT_TYPES)[number];
+/** Outcome claims the provider may sign with its bound key (schema 1.5): how its work ended. */
+export declare const SIGNED_CLAIM_TYPES: readonly ["completion", "partial_completion", "cancellation", "provider_failure"];
+export type SignedClaimType = (typeof SIGNED_CLAIM_TYPES)[number];
 /**
  * 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
@@ -17,18 +81,42 @@ export type DeliveryEventType = (typeof DELIVERY_EVENT_TYPES)[number];
  */
 export declare const CLAIM_ASSERTERS: readonly ["buyer", "provider", "clearing_policy", "dispute_reviewer", "clearing_network"];
 export type ClaimAsserter = (typeof CLAIM_ASSERTERS)[number];
-export declare const EXCEPTION_KINDS: readonly ["budget_overrun", "unmatched_charge", "ambiguous_match", "missing_receipt", "duplicate_event", "amount_mismatch", "currency_mismatch", "stale_quote", "refund_after_close", "allocation_changed_after_close", "incomplete_lineage"];
+export declare const EXCEPTION_KINDS: readonly ["budget_overrun", "unmatched_charge", "ambiguous_match", "missing_receipt", "duplicate_event", "amount_mismatch", "currency_mismatch", "stale_quote", "refund_after_close", "allocation_changed_after_close", "incomplete_lineage", "usage_unpriced", "usage_cost_mismatch", "refund_terms_breach", "skill_price_mismatch", "witness_quorum_not_met", "conflicting_statements", "unmatched_estimate", "actual_exceeds_estimate", "actual_exceeds_hold", "hold_not_released", "estimate_after_charge", "charge_after_cancellation"];
 export type ExceptionKind = (typeof EXCEPTION_KINDS)[number];
 /** Trust labels kept separate on every screen and export (PRD §16 "Identity assurance"). Never collapsed into "verified". */
-export declare const ASSURANCE_LABELS: readonly ["issuer_signed", "buyer_recorded", "network_recorded", "recipient_viewed", "link_authenticated_response", "provider_identity_bound", "provider_key_signed", "contested", "superseded", "expired", "revoked"];
+export declare const ASSURANCE_LABELS: readonly ["issuer_signed", "buyer_recorded", "network_recorded", "recipient_viewed", "link_authenticated_response", "provider_identity_bound", "provider_key_signed", "contested", "superseded", "expired", "revoked", "gateway_signed", "rail_attested"];
 export type AssuranceLabel = (typeof ASSURANCE_LABELS)[number];
 export declare const RESPONSE_TYPES: readonly ["acknowledge_view", "acknowledge_delivery", "submit_evidence", "propose_correction", "signed_attestation"];
 export type ResponseType = (typeof RESPONSE_TYPES)[number];
-export declare const SHARE_ACTIONS: readonly ["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 declare const SHARE_ACTIONS: readonly ["view", "acknowledge_delivery", "submit_evidence", "propose_correction", "signed_attestation", "witness_attestation"];
 export type ShareAction = (typeof SHARE_ACTIONS)[number];
 /** Receipt fields a provider may attest to or contest. Attesting one never implies the others (acceptance 16). */
-export declare const ATTESTABLE_FIELDS: readonly ["delivery.status", "delivery.evidence", "scope.terms_digest", "financial.amounts", "financial.status"];
+export declare const ATTESTABLE_FIELDS: readonly ["delivery.status", "delivery.evidence", "scope.terms_digest", "financial.amounts", "financial.status", "delivery.usage"];
 export type AttestableField = (typeof ATTESTABLE_FIELDS)[number];
+export declare function attestableFieldsFor(schemaVersion: string): readonly AttestableField[];
+/** 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 declare const UsageRecordSchema: z.ZodObject<{
+    trace_digest: z.ZodString;
+    summary: z.ZodObject<{
+        models: z.ZodArray<z.ZodObject<{
+            provider: z.ZodString;
+            name: z.ZodString;
+            calls: z.ZodNumber;
+            input_tokens: z.ZodNumber;
+            output_tokens: z.ZodNumber;
+            cache_read_input_tokens: z.ZodNumber;
+        }, z.core.$strict>>;
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            calls: z.ZodNumber;
+        }, z.core.$strict>>;
+        a2a_calls: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type UsageRecord = z.infer<typeof UsageRecordSchema>;
+/** Delivery claims that may carry usage. */
+export declare const USAGE_CLAIM_TYPES: readonly string[];
 /** Evidence stays in its source system; only references and digests are stored. Script-capable schemes are refused. */
 export declare const EvidenceRefSchema: z.ZodObject<{
     uri: z.ZodString;
@@ -36,6 +124,20 @@ export declare const EvidenceRefSchema: z.ZodObject<{
     evidence_type: z.ZodString;
 }, z.core.$strip>;
 export type EvidenceRef = z.infer<typeof EvidenceRefSchema>;
+/** Why part of a delegation chain was not captured. broken_edge: a reported sub-task arrived with no outcome. */
+export declare const CAPTURE_GAP_KINDS: readonly ["capture_failed", "queue_overflow", "provider_undisclosed", "manual_gap", "broken_edge"];
+export declare const CaptureGapInputSchema: z.ZodObject<{
+    delegation_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    kind: z.ZodEnum<{
+        capture_failed: "capture_failed";
+        queue_overflow: "queue_overflow";
+        provider_undisclosed: "provider_undisclosed";
+        manual_gap: "manual_gap";
+        broken_edge: "broken_edge";
+    }>;
+    detail: z.ZodString;
+}, z.core.$strip>;
+export type CaptureGapInput = z.infer<typeof CaptureGapInputSchema>;
 export declare const TaskInputSchema: z.ZodObject<{
     external_ref: z.ZodString;
     currency: z.ZodString;
@@ -47,6 +149,7 @@ export declare const TaskInputSchema: z.ZodObject<{
     shared_description: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     retrospective: z.ZodDefault<z.ZodBoolean>;
     occurred_at: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    estimate_tolerance_bps: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export type TaskInput = z.infer<typeof TaskInputSchema>;
 export declare const ProviderInputSchema: z.ZodObject<{
@@ -54,6 +157,17 @@ export declare const ProviderInputSchema: z.ZodObject<{
     provider_own_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     domain: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>;
+/**
+ * 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 declare const SubledgerWitnessPolicySchema: z.ZodObject<{
+    min_independent_witnesses: z.ZodNumber;
+    witness_provider_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    independence: z.ZodLiteral<"distinct_verified_domain">;
+}, z.core.$strict>;
+export type SubledgerWitnessPolicy = z.infer<typeof SubledgerWitnessPolicySchema>;
 export declare const DelegationInputSchema: z.ZodObject<{
     parent_delegation_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     provider_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -92,6 +206,11 @@ export declare const DelegationInputSchema: z.ZodObject<{
                 name: z.ZodString;
                 version: z.ZodString;
             }, z.core.$strip>>;
+            additional_models: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                provider: z.ZodString;
+                name: z.ZodString;
+                version: z.ZodString;
+            }, z.core.$strip>>>;
             config_digest: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>;
         skill: z.ZodOptional<z.ZodObject<{
@@ -100,6 +219,46 @@ export declare const DelegationInputSchema: z.ZodObject<{
             agent_card_url: z.ZodOptional<z.ZodURL>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
+    pricing: z.ZodOptional<z.ZodObject<{
+        rates: z.ZodArray<z.ZodObject<{
+            meter: z.ZodEnum<{
+                input_tokens: "input_tokens";
+                output_tokens: "output_tokens";
+                cache_read_input_tokens: "cache_read_input_tokens";
+                model_call: "model_call";
+                tool_call: "tool_call";
+                a2a_call: "a2a_call";
+            }>;
+            model: z.ZodOptional<z.ZodObject<{
+                provider: z.ZodString;
+                name: z.ZodString;
+            }, z.core.$strict>>;
+            tool_name: z.ZodOptional<z.ZodString>;
+            price_numerator: z.ZodNumber;
+            price_denominator: z.ZodNumber;
+        }, z.core.$strict>>;
+        fixed_minor: z.ZodOptional<z.ZodNumber>;
+        tolerance_bps: z.ZodNumber;
+    }, z.core.$strict>>;
+    refund_terms: z.ZodOptional<z.ZodObject<{
+        on_failure: z.ZodEnum<{
+            dispute: "dispute";
+            refund: "refund";
+        }>;
+        on_timeout: z.ZodEnum<{
+            dispute: "dispute";
+            refund: "refund";
+        }>;
+        after_settlement: z.ZodObject<{
+            cap_minor: z.ZodNumber;
+            window_seconds: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    witness_policy: z.ZodOptional<z.ZodObject<{
+        min_independent_witnesses: z.ZodNumber;
+        witness_provider_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        independence: z.ZodLiteral<"distinct_verified_domain">;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export type DelegationInput = z.infer<typeof DelegationInputSchema>;
 export declare const DelegationEventInputSchema: z.ZodObject<{
@@ -134,13 +293,79 @@ export declare const DelegationEventInputSchema: z.ZodObject<{
             disclosed: "disclosed";
             none: "none";
         }>>;
+        pricing: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            rates: z.ZodArray<z.ZodObject<{
+                meter: z.ZodEnum<{
+                    input_tokens: "input_tokens";
+                    output_tokens: "output_tokens";
+                    cache_read_input_tokens: "cache_read_input_tokens";
+                    model_call: "model_call";
+                    tool_call: "tool_call";
+                    a2a_call: "a2a_call";
+                }>;
+                model: z.ZodOptional<z.ZodObject<{
+                    provider: z.ZodString;
+                    name: z.ZodString;
+                }, z.core.$strict>>;
+                tool_name: z.ZodOptional<z.ZodString>;
+                price_numerator: z.ZodNumber;
+                price_denominator: z.ZodNumber;
+            }, z.core.$strict>>;
+            fixed_minor: z.ZodOptional<z.ZodNumber>;
+            tolerance_bps: z.ZodNumber;
+        }, z.core.$strict>>>;
+        refund_terms: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            on_failure: z.ZodEnum<{
+                dispute: "dispute";
+                refund: "refund";
+            }>;
+            on_timeout: z.ZodEnum<{
+                dispute: "dispute";
+                refund: "refund";
+            }>;
+            after_settlement: z.ZodObject<{
+                cap_minor: z.ZodNumber;
+                window_seconds: z.ZodNumber;
+            }, z.core.$strict>;
+        }, z.core.$strict>>>;
+        witness_policy: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            min_independent_witnesses: z.ZodNumber;
+            witness_provider_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            independence: z.ZodLiteral<"distinct_verified_domain">;
+        }, z.core.$strict>>>;
     }, z.core.$strip>>>;
     supersedes_event_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     retrospective: z.ZodDefault<z.ZodBoolean>;
     occurred_at: z.ZodDefault<z.ZodNullable<z.ZodISODateTime>>;
+    usage: z.ZodOptional<z.ZodObject<{
+        trace_digest: z.ZodString;
+        summary: z.ZodObject<{
+            models: z.ZodArray<z.ZodObject<{
+                provider: z.ZodString;
+                name: z.ZodString;
+                calls: z.ZodNumber;
+                input_tokens: z.ZodNumber;
+                output_tokens: z.ZodNumber;
+                cache_read_input_tokens: z.ZodNumber;
+            }, z.core.$strict>>;
+            tools: z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                calls: z.ZodNumber;
+            }, z.core.$strict>>;
+            a2a_calls: z.ZodNumber;
+        }, z.core.$strict>;
+    }, z.core.$strict>>;
+    signer: z.ZodOptional<z.ZodObject<{
+        provider_id: z.ZodString;
+        binding_id: z.ZodString;
+        key_id: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strict>>;
 }, z.core.$strip>;
 export type DelegationEventInput = z.infer<typeof DelegationEventInputSchema>;
+/** Rules across fields of a delivery event that the schema cannot express. */
+export declare function delegationEventProblems(input: Pick<DelegationEventInput, "type" | "usage"> & Partial<Pick<DelegationEventInput, "asserted_by" | "signer">>): string[];
 export declare const FxSchema: z.ZodObject<{
     base_currency: z.ZodString;
     quote_currency: z.ZodString;
@@ -160,6 +385,8 @@ export declare const FinancialEventInputSchema: z.ZodObject<{
         credit: "credit";
         adjustment: "adjustment";
         fx_rate: "fx_rate";
+        estimate: "estimate";
+        hold: "hold";
     }>;
     source: z.ZodString;
     source_event_id: z.ZodString;
@@ -174,6 +401,7 @@ export declare const FinancialEventInputSchema: z.ZodObject<{
         issued: "issued";
         pending: "pending";
         reported_paid: "reported_paid";
+        pending_finality: "pending_finality";
         failed: "failed";
         refunded: "refunded";
         reversed: "reversed";
@@ -203,6 +431,38 @@ export declare const FinancialEventInputSchema: z.ZodObject<{
         rate_denominator: z.ZodNumber;
     }, z.core.$strip>>>;
     reason: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    skill: z.ZodOptional<z.ZodObject<{
+        namespace: z.ZodString;
+        skill_id: z.ZodString;
+        agent_card_url: z.ZodOptional<z.ZodURL>;
+    }, z.core.$strip>>;
+    expectation: z.ZodOptional<z.ZodObject<{
+        issued_by: z.ZodEnum<{
+            agent: "agent";
+            gateway: "gateway";
+            operator: "operator";
+        }>;
+        source_ref: z.ZodNullable<z.ZodString>;
+        basis: z.ZodNullable<z.ZodString>;
+        expires_at: z.ZodNullable<z.ZodISODateTime>;
+        supersedes: z.ZodNullable<z.ZodString>;
+        hold_status: z.ZodOptional<z.ZodEnum<{
+            open: "open";
+            captured: "captured";
+            released: "released";
+            expired: "expired";
+        }>>;
+        signer: z.ZodOptional<z.ZodObject<{
+            provider_id: z.ZodString;
+            binding_id: z.ZodString;
+            key_id: z.ZodString;
+            value: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    rail_attestation: z.ZodOptional<z.ZodObject<{
+        scheme: z.ZodString;
+        record: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strict>>;
     match: z.ZodDefault<z.ZodObject<{
         task_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
         delegation_id: z.ZodDefault<z.ZodNullable<z.ZodString>>;
@@ -211,6 +471,12 @@ export declare const FinancialEventInputSchema: z.ZodObject<{
         provider_job_ref: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** Rules for estimates and holds that the schema cannot express. */
+export declare function expectationProblems(e: {
+    type: FinancialEventType;
+    amount_minor: number;
+    expectation?: Expectation;
+}): string[];
 export type FinancialEventInput = z.input<typeof FinancialEventInputSchema>;
 /** A stored financial event exactly as hashed into exports. */
 export interface FinancialEventRecord {
@@ -236,6 +502,12 @@ export interface FinancialEventRecord {
     settles_event_id: string | null;
     fx: Fx | null;
     reason: string | null;
+    /** Schema 1.5, present only when stated: the skill billed. */
+    skill?: SkillRef;
+    /** Schema 1.5, estimates and holds only. */
+    expectation?: Expectation;
+    /** Schema 1.5, payments and refunds only. */
+    rail_attestation?: RailAttestation;
 }
 export declare const AllocationTargetSchema: z.ZodObject<{
     type: z.ZodEnum<{