@atcn/subledger 1.4.0 → 1.5.0

package/dist/documents.js

@@ -1,17 +1,20 @@
-import { AttestationRefSchema, ExecutionBindingSchema, ExecutionDescriptorSchema } from "@atcn/schema";
+import { AttestationRefSchema, ExecutionBindingSchema, ExecutionDescriptorSchema, PricingSchema, RefundTermsSchema, SkillRefSchema, USAGE_METERS } from "@atcn/schema";
 import { z } from "zod";
-import { ASSURANCE_LABELS, ATTESTABLE_FIELDS, CLAIM_ASSERTERS, Currency, DELIVERY_EVENT_TYPES, EvidenceRefSchema, FINANCIAL_EVENT_TYPES, FxSchema, Minor, NORMALIZED_STATUSES, PAYERS, RESPONSE_TYPES } from "./types.js";
+import { SubledgerWitnessPolicySchema, ExpectationSchema, KeySignerSchema, RailAttestationSchema, EXPECTATION_ISSUERS, HOLD_STATUSES, ASSURANCE_LABELS, ATTESTABLE_FIELDS, CLAIM_ASSERTERS, Currency, DELIVERY_EVENT_TYPES, EvidenceRefSchema, FINANCIAL_EVENT_TYPES, FxSchema, Minor, NORMALIZED_STATUSES, PAYERS, RESPONSE_TYPES, UsageRecordSchema, } from "./types.js";
 /**
  * Signed documents of the Agent Work Subledger (PRD v1.2 §6, §16).
  * Schema 1.3 adds closure `obligation_links`, the clearing-network claim asserters, and the `network_recorded` assurance label;
  * 1.2 documents must use neither. Schema 1.4 adds delegation `execution`, the response statement fields `execution`,
  * `issued_at`, `expires_at` and `refs`, and the `expired` and `revoked` labels; 1.2 and 1.3 documents must use none
- * of them (see packages/schema/COMPATIBILITY.md).
+ * of them. Schema 1.5 adds delegation `pricing`, `refund_terms` and `witness_policy`, claim `usage`, the `delivery.usage`
+ * field, closure `usage_checks`, `additional_models` in runs, financial event `skill`, the `pending_finality` status,
+ * the statement `role`, the `estimate` and `hold` event types with `expectation`, task `estimate_tolerance_bps` and
+ * closure `expectation_report`; earlier documents must use none of them (see packages/schema/COMPATIBILITY.md).
  */
-export const SUBLEDGER_SCHEMA_VERSION = "1.4";
-export const SUPPORTED_SUBLEDGER_SCHEMA_VERSIONS = ["1.2", "1.3", "1.4"];
+export const SUBLEDGER_SCHEMA_VERSION = "1.5";
+export const SUPPORTED_SUBLEDGER_SCHEMA_VERSIONS = ["1.2", "1.3", "1.4", "1.5"];
 /** Must equal this package's version in package.json (checked by a test). */
-export const SUBLEDGER_VERIFIER_VERSION = "1.4.0";
+export const SUBLEDGER_VERIFIER_VERSION = "1.5.0";
 export const RECEIPT_DOCUMENT_TYPE = "atcn.subledger.receipt";
 export const CLOSURE_DOCUMENT_TYPE = "atcn.subledger.closure";
 export const RESPONSE_STATEMENT_TYPE = "atcn.subledger.receipt_response";
@@ -93,6 +96,12 @@ export const FinancialEventRecordSchema = z.object({
     settles_event_id: z.string().nullable(),
     fx: FxSchema.nullable(),
     reason: z.string().nullable(),
+    /** Schema 1.5, present only when stated. */
+    skill: SkillRefSchema.optional(),
+    /** Schema 1.5, estimates and holds only. */
+    expectation: ExpectationSchema.optional(),
+    /** Schema 1.5, payments and refunds only. */
+    rail_attestation: RailAttestationSchema.optional(),
 });
 export const DeliveryClaimSchema = z.object({
     event_id: z.string(),
@@ -107,9 +116,14 @@ export const DeliveryClaimSchema = z.object({
     retrospective: z.boolean(),
     occurred_at: Iso,
     recorded_at: Iso,
+    /** Schema 1.5, completion and partial_completion only, present only when recorded. */
+    usage: UsageRecordSchema.optional(),
+    /** Schema 1.5, a provider-signed outcome claim only. */
+    signer: KeySignerSchema.optional(),
 });
 export const FIELD_STATES = ["missing", "imported", "buyer_asserted", "provider_reported", "contested"];
-export const FieldStatusSchema = z.record(z.enum(ATTESTABLE_FIELDS), z.enum(FIELD_STATES));
+/** Not exhaustive, because schema 1.5 added a field; the verifier checks the field set for the document's version. */
+export const FieldStatusSchema = z.partialRecord(z.enum(ATTESTABLE_FIELDS), z.enum(FIELD_STATES));
 export const CorrectionSchema = z.object({ field: z.enum(ATTESTABLE_FIELDS), proposed_value: z.string().max(1000), reason: z.string().max(2000) });
 /** The exact statement a provider signs (or a link holder submits). Binds receipt, digest, revision, issuer tenant, type, and fields. */
 export const ResponseStatementSchema = z.object({
@@ -130,6 +144,11 @@ export const ResponseStatementSchema = z.object({
     expires_at: Iso.optional(),
     /** Schema 1.4: earlier statements this one revokes (same provider only) or disputes, by statement digest. */
     refs: z.array(AttestationRefSchema).max(20).optional(),
+    /**
+     * Schema 1.5: "witness" when an independent witness, not the provider, signs that it observed the run. A witness
+     * statement is a signed_attestation that cites the run and at least one evidence item.
+     */
+    role: z.literal("witness").optional(),
 });
 export const ResponseRecordSchema = z.object({
     response_id: z.string(),
@@ -192,6 +211,12 @@ export const ReceiptPayloadSchema = z.object({
         downstream_visibility: z.enum(["unknown", "disclosed", "none"]),
         /** Schema 1.4, present only when recorded: the run a provider statement can cite. */
         execution: ExecutionDescriptorSchema.optional(),
+        /** Schema 1.5, present only when agreed: the usage prices. */
+        pricing: PricingSchema.optional(),
+        /** Schema 1.5, present only when agreed: what happens on failure or timeout, and the refund budget. */
+        refund_terms: RefundTermsSchema.optional(),
+        /** Schema 1.5, present only when required: the independent witnesses the delegation needs. */
+        witness_policy: SubledgerWitnessPolicySchema.optional(),
     }),
     provider: z.object({
         provider_id: z.string().nullable(),
@@ -207,6 +232,8 @@ export const ReceiptPayloadSchema = z.object({
     unverified_fields: z.array(z.enum(ATTESTABLE_FIELDS)),
     corrections: z.array(z.object({ response_id: z.string(), receipt_revision: z.number().int().positive(), fields: z.array(z.enum(ATTESTABLE_FIELDS)), decision: z.enum(["accepted", "rejected", "open"]) })),
     lineage: z.object({ complete: z.boolean(), capture_gaps: z.array(CaptureGapSchema.omit({ delegation_id: true })) }),
+    /** Schema 1.5, present only when a claim or estimate on the receipt is signed: exactly the key bindings its signers name. */
+    key_bindings: z.array(KeyBindingRecordSchema).optional(),
 });
 export const SignedReceiptSchema = z.object({ payload: ReceiptPayloadSchema, signature: SignatureSchema, operator_signatures: z.array(OperatorSignatureSchema).optional() });
 // ---------- Private closure snapshot (full root task; PRD §4 step 6, §6) ----------
@@ -233,6 +260,81 @@ export const ClosureDelegationSchema = z.object({
     created_at: Iso,
     /** Schema 1.4, present only when recorded, so older closures keep their bytes. */
     execution: ExecutionDescriptorSchema.optional(),
+    /** Schema 1.5, present only when agreed. */
+    pricing: PricingSchema.optional(),
+    /** Schema 1.5, present only when agreed. */
+    refund_terms: RefundTermsSchema.optional(),
+    /** Schema 1.5, present only when required. */
+    witness_policy: SubledgerWitnessPolicySchema.optional(),
+});
+/** One delegation's usage priced at its agreed rates and compared with what was billed (schema 1.5). */
+export const UsageCheckSchema = z.object({
+    delegation_id: z.string(),
+    currency: Currency,
+    /** Null when some usage has no rate. */
+    expected_minor: Minor.nullable(),
+    lines: z.array(z.object({
+        meter: z.enum(USAGE_METERS),
+        model: z.object({ provider: z.string(), name: z.string() }).optional(),
+        tool_name: z.string().optional(),
+        units: Minor,
+        cost_minor: Minor,
+    })),
+    billed_minor: Minor,
+    /** billed − expected; positive means billed above usage cost. */
+    difference_minor: Minor.nullable(),
+    allowed_difference_minor: Minor.nullable(),
+    within_tolerance: z.boolean().nullable(),
+    unpriced: z.array(z.string()),
+    trace_digests: z.array(Digest),
+    /** Labels of the usage claims, plus provider_key_signed when the provider signed an attestation of delivery.usage. */
+    assurance: Assurance,
+});
+/** Estimate and hold against actual cost for one node (the task itself or a delegation), in the node's currency. */
+export const RailAttestationEntrySchema = z.object({
+    financial_event_id: z.string(),
+    scheme: z.string(),
+    rail: z.string(),
+    rail_ref: z.string(),
+    anchor: z.string(),
+    assurance: z.tuple([z.literal("rail_attested")]),
+});
+export const ExpectationVarianceSchema = z.object({
+    /** Latest estimate issued before the node's first charge that no later estimate replaced; null when none. */
+    estimated_minor: Minor.nullable(),
+    /** Open plus captured holds. */
+    held_minor: Minor,
+    /** Net cost (task: the whole tree's net cost). */
+    actual_minor: Minor,
+    /** actual − estimated, and the same in basis points of the estimate (null without an estimate, or when it is 0). */
+    variance_vs_estimate_minor: Minor.nullable(),
+    variance_vs_estimate_bps: z.number().int().nullable(),
+    variance_vs_hold_minor: Minor.nullable(),
+    variance_vs_hold_bps: z.number().int().nullable(),
+});
+/** Estimates and holds compared with actual cost (schema 1.5). Recorded only; nothing was enforced, blocked or reserved. */
+export const ExpectationReportSchema = z.object({
+    currency: Currency,
+    task: ExpectationVarianceSchema.extend({
+        /** Net cost on nodes that have no estimate. */
+        unestimated_minor: Minor,
+    }),
+    nodes: z.array(ExpectationVarianceSchema.extend({ node_id: z.string(), estimate_event_id: z.string().nullable() })),
+    records: z.array(z.object({
+        financial_event_id: z.string(),
+        node_id: z.string(),
+        type: z.enum(["estimate", "hold"]),
+        issued_by: z.enum(EXPECTATION_ISSUERS),
+        /**
+         * "current" counts toward the node's figures (for estimates: the one used); "not_latest" is a current estimate
+         * replaced by a later one from another issuer; "superseded" was explicitly replaced; "after_charge" estimates are
+         * kept but not used; "other_currency" is not in the task's currency.
+         */
+        status: z.enum(["current", "not_latest", "superseded", "after_charge", "other_currency"]),
+        /** Holds only: the latest status, released when the work failed or was cancelled while the hold was open. */
+        hold_status: z.enum(HOLD_STATUSES).nullable(),
+        assurance: Assurance,
+    })),
 });
 export const AllocationRecordSchema = z.object({
     allocation_id: z.string(),
@@ -258,6 +360,8 @@ export const ExceptionRecordSchema = z.object({
     detail: z.string(),
     created_at: Iso,
 });
+/** A derived exception a person resolved or dismissed while its condition still holds; schema 1.5 closures list these. */
+export const ResolvedExceptionSchema = ExceptionRecordSchema.extend({ resolved_by: z.string(), resolved_at: Iso, resolution: z.string().nullable() });
 export const NodeRollupSchema = z.object({
     node_id: z.string(),
     parent_id: z.string().nullable(),
@@ -306,6 +410,8 @@ export const ClosurePayloadSchema = z.object({
         scope_ref: z.string().nullable(),
         retrospective: z.boolean(),
         created_at: Iso,
+        /** Schema 1.5, present only when set. */
+        estimate_tolerance_bps: z.number().int().nonnegative().optional(),
     }),
     delegations: z.array(ClosureDelegationSchema),
     delivery_claims: z.array(DeliveryClaimSchema),
@@ -320,5 +426,13 @@ export const ClosurePayloadSchema = z.object({
     disclosure: DisclosureSchema,
     /** Present only when at least one delegation is backed by an obligation, so older closures keep their bytes. */
     obligation_links: z.array(ObligationLinkSchema).optional(),
+    /** Schema 1.5, present only when at least one delegation has pricing and recorded usage. */
+    usage_checks: z.array(UsageCheckSchema).optional(),
+    /** Schema 1.5, present only when the task has estimates or holds. */
+    expectation_report: ExpectationReportSchema.optional(),
+    /** Schema 1.5, present only when a payment or refund carries a rail attestation: those that verify, labelled rail_attested. */
+    rail_attestations: z.array(RailAttestationEntrySchema).optional(),
+    /** Schema 1.5, present only when a person resolved a derived exception whose condition still held at generated_at. */
+    resolved_exceptions: z.array(ResolvedExceptionSchema).optional(),
 });
 export const SignedClosureSchema = z.object({ payload: ClosurePayloadSchema, signature: SignatureSchema, operator_signatures: z.array(OperatorSignatureSchema).optional() });

package/dist/exceptions.d.ts

@@ -1,6 +1,7 @@
+import { type Pricing, type RefundTerms, type SkillRef } from "@atcn/schema";
 import type { Rollup } from "./rollup.js";
-import type { DeliveryClaim } from "./documents.js";
-import type { ExceptionKind } from "./types.js";
+import type { DeliveryClaim, KeyBindingRecord, ResponseRecord } from "./documents.js";
+import { type ExceptionKind, type FinancialEventRecord, type SubledgerWitnessPolicy } from "./types.js";
 /** Exception kinds recomputed from current state; they resolve automatically when the condition clears. */
 export declare const DERIVED_EXCEPTION_KINDS: ExceptionKind[];
 export interface DerivedException {
@@ -15,6 +16,7 @@ export interface DeriveInput {
         task_id: string;
         currency: string;
         budget_minor: number | null;
+        estimate_tolerance_bps?: number;
     };
     delegations: {
         delegation_id: string;
@@ -22,16 +24,52 @@ export interface DeriveInput {
         quoted_max_minor: number | null;
         accepted_amount_minor: number | null;
         quote_valid_until: string | null;
+        expected_delivery: string | null;
+        pricing?: Pricing | null;
+        refund_terms?: RefundTerms | null;
+        execution?: {
+            skill?: SkillRef;
+        };
+        provider_id?: string | null;
+        witness_policy?: SubledgerWitnessPolicy | null;
     }[];
     claims: DeliveryClaim[];
+    /** The task's financial events with their current attribution. */
+    events: {
+        record: FinancialEventRecord;
+        attributed_to: string;
+    }[];
     rollup: Rollup;
     now: string;
+    /** Witness statements in effect, each with the registrable domain the service verified for its signing key. */
+    witnesses?: {
+        delegation_id: string;
+        witness_id: string;
+        domain: string | null;
+    }[];
+    /** Verified registrable domains of the buyer operator and of each provider (by provider_id), for witness independence. */
+    party_domains?: {
+        operator: string | null;
+        providers: Record<string, string | null>;
+    };
+    /** Responses to the task's receipts and the delegation each receipt covers, for conflicting_statements. */
+    responses?: ResponseRecord[];
+    receipts?: {
+        receipt_id: string;
+        delegation_id: string;
+    }[];
+    /** Key bindings for signed estimates and holds (they affect labels only, not exceptions). */
+    key_bindings?: KeyBindingRecord[];
+    /** True when deriving as the task is closed: an open hold with nothing charged is then flagged. */
+    closing?: boolean;
 }
 /**
  * Condition-based exceptions recomputed from current state (PRD §6). They resolve automatically when the
  * condition clears. Flags only: the product records an overrun, it never claims to have prevented spend.
  */
 export declare function deriveTaskExceptions(input: DeriveInput): DerivedException[];
+/** Kinds the offline verifier cannot recompute: witness independence needs the domains the service verified. */
+export declare const SERVICE_ONLY_EXCEPTION_KINDS: ExceptionKind[];
 /** The latest exception recorded under a derived exception's dedupe key. */
 export interface LatestException {
     status: string;
@@ -44,3 +82,10 @@ export interface LatestException {
  * otherwise it is opened, which is a no-op when one is already open.
  */
 export declare function derivedExceptionAction(latest: LatestException | null, derived: DerivedException): "keep" | "update_detail" | "open";
+/**
+ * The latest exceptions under derived dedupe keys that a person's resolution keeps closed while the condition holds.
+ * A closure lists them so the offline verifier can tell a resolved condition from an omitted one.
+ */
+export declare function resolutionsInForce<T extends LatestException & {
+    dedupe_key: string;
+}>(derived: DerivedException[], exceptions: T[]): T[];

package/dist/exceptions.js

@@ -1,5 +1,26 @@
+import { countIndependentWitnesses } from "@atcn/schema";
+import { buildExpectationReport, expectationExceptions } from "./expectations.js";
+import { deliveryStatus, statementConflicts } from "./projection.js";
+import { SKILL_BILLED_EVENT_TYPES } from "./types.js";
+import { billedMinor, usageCheckFor } from "./usage.js";
 /** Exception kinds recomputed from current state; they resolve automatically when the condition clears. */
-export const DERIVED_EXCEPTION_KINDS = ["budget_overrun", "missing_receipt", "amount_mismatch", "stale_quote"];
+export const DERIVED_EXCEPTION_KINDS = [
+    "budget_overrun",
+    "missing_receipt",
+    "amount_mismatch",
+    "stale_quote",
+    "usage_unpriced",
+    "usage_cost_mismatch",
+    "refund_terms_breach",
+    "skill_price_mismatch",
+    "witness_quorum_not_met",
+    "conflicting_statements",
+    "actual_exceeds_estimate",
+    "actual_exceeds_hold",
+    "hold_not_released",
+    "estimate_after_charge",
+    "charge_after_cancellation",
+];
 /**
  * Condition-based exceptions recomputed from current state (PRD §6). They resolve automatically when the
  * condition clears. Flags only: the product records an overrun, it never claims to have prevented spend.
@@ -17,8 +38,7 @@ export function deriveTaskExceptions(input) {
     }
     for (const d of input.delegations) {
         const node = input.rollup.nodes.find((n) => n.node_id === d.delegation_id);
-        const own = node?.direct[d.currency];
-        const billed = own ? own.invoiced + own.charged + own.fees + own.adjustments - own.credits - own.refunded : 0;
+        const billed = billedMinor(node?.direct[d.currency]);
         const claims = input.claims.filter((c) => c.delegation_id === d.delegation_id);
         const superseded = new Set(claims.map((c) => c.supersedes_event_id).filter((id) => id !== null));
         const active = claims.filter((c) => !superseded.has(c.event_id));
@@ -26,6 +46,15 @@ export function deriveTaskExceptions(input) {
         if (billed > 0 && !hasDeliveryReceipt) {
             result.push({ kind: "missing_receipt", dedupe_key: `missing_receipt:${d.delegation_id}`, delegation_id: d.delegation_id, detail: `billed ${billed} ${d.currency} with no completion receipt recorded` });
         }
+        const status = deliveryStatus(claims);
+        if ((status === "cancelled" || status === "provider_failed") && billed > 0) {
+            result.push({
+                kind: "charge_after_cancellation",
+                dedupe_key: `charge_after_cancellation:${d.delegation_id}`,
+                delegation_id: d.delegation_id,
+                detail: `the delegation is ${status.replace("_", " ")} but ${billed} ${d.currency} is still billed; a refund, credit or reversal of it would net it to zero`,
+            });
+        }
         const agreed = d.accepted_amount_minor ?? d.quoted_max_minor;
         if (agreed !== null && billed > agreed) {
             const basis = d.accepted_amount_minor !== null ? "accepted amount" : "quoted maximum";
@@ -35,9 +64,140 @@ export function deriveTaskExceptions(input) {
         if (d.quote_valid_until !== null && d.quote_valid_until < input.now && !accepted) {
             result.push({ kind: "stale_quote", dedupe_key: `stale_quote:${d.delegation_id}`, delegation_id: d.delegation_id, detail: `quote expired at ${d.quote_valid_until} without a recorded acceptance` });
         }
+        const usage = usageCheckFor({ delegation_id: d.delegation_id, currency: d.currency, pricing: d.pricing, claims, billed_minor: billed, provider_attested: false });
+        if (usage && usage.expected_minor === null) {
+            result.push({ kind: "usage_unpriced", dedupe_key: `usage_unpriced:${d.delegation_id}`, delegation_id: d.delegation_id, detail: `usage has no agreed rate: ${usage.unpriced.join(", ")}` });
+        }
+        else if (usage && usage.within_tolerance === false) {
+            const direction = usage.difference_minor > 0 ? "above" : "below";
+            result.push({
+                kind: "usage_cost_mismatch",
+                dedupe_key: `usage_cost_mismatch:${d.delegation_id}`,
+                delegation_id: d.delegation_id,
+                detail: `billed ${billed} ${d.currency} is ${direction} usage cost ${usage.expected_minor} by ${Math.abs(usage.difference_minor)}, more than the allowed ${usage.allowed_difference_minor}; traces ${usage.trace_digests.join(", ")}`,
+            });
+        }
+        const events = activeEventsOf(input.events, d.delegation_id);
+        const refundProblems = d.refund_terms ? refundTermsProblems(d.refund_terms, d.expected_delivery, d.currency, events, claims, input.now) : [];
+        if (refundProblems.length > 0) {
+            result.push({ kind: "refund_terms_breach", dedupe_key: `refund_terms_breach:${d.delegation_id}`, delegation_id: d.delegation_id, detail: refundProblems.join("; ") });
+        }
+        const agreedSkill = d.execution?.skill;
+        const offSkill = agreedSkill ? events.filter((e) => SKILL_BILLED_EVENT_TYPES.includes(e.type) && e.skill && !sameSkill(e.skill, agreedSkill)) : [];
+        if (offSkill.length > 0) {
+            const agreedPrice = d.accepted_amount_minor ?? d.quoted_max_minor;
+            const billedLines = offSkill.map((e) => `${e.type} ${e.financial_event_id} bills ${skillName(e.skill)} for ${e.amount_minor} ${e.currency}`);
+            result.push({
+                kind: "skill_price_mismatch",
+                dedupe_key: `skill_price_mismatch:${d.delegation_id}`,
+                delegation_id: d.delegation_id,
+                detail: `${billedLines.join("; ")}; the delegation agreed ${skillName(agreedSkill)}${agreedPrice !== null ? ` at ${agreedPrice} ${d.currency}` : ""}`,
+            });
+        }
+        const witnessProblem = d.witness_policy ? witnessQuorumProblem(d.witness_policy, d.delegation_id, d.provider_id ?? null, input) : null;
+        if (witnessProblem) {
+            result.push({ kind: "witness_quorum_not_met", dedupe_key: `witness_quorum_not_met:${d.delegation_id}`, delegation_id: d.delegation_id, detail: witnessProblem });
+        }
     }
+    const conflicts = statementConflicts(input.responses ?? [], input.now);
+    for (const d of input.delegations) {
+        const receiptIds = new Set((input.receipts ?? []).filter((r) => r.delegation_id === d.delegation_id).map((r) => r.receipt_id));
+        const onDelegation = conflicts.filter((c) => receiptIds.has(c.subject.slice("receipt:".length, c.subject.indexOf("@"))));
+        if (onDelegation.length > 0) {
+            result.push({
+                kind: "conflicting_statements",
+                dedupe_key: `conflicting_statements:${d.delegation_id}`,
+                delegation_id: d.delegation_id,
+                detail: onDelegation.map((c) => `${c.kind} on ${c.subject} between ${c.signers.join(", ")}`).join("; "),
+            });
+        }
+    }
+    const report = buildExpectationReport({
+        task: input.task,
+        delegations: input.delegations.map((d) => ({ delegation_id: d.delegation_id, provider_id: d.provider_id ?? null })),
+        claims: input.claims,
+        events: input.events,
+        rollup: input.rollup,
+        key_bindings: input.key_bindings ?? [],
+    });
+    if (report)
+        result.push(...expectationExceptions(report, input));
     return result;
 }
+/** Why a delegation lacks its independent witnesses, or null when enough counted. */
+function witnessQuorumProblem(policy, delegationId, providerId, input) {
+    const operatorDomain = input.party_domains?.operator ?? null;
+    const providerDomain = providerId ? (input.party_domains?.providers[providerId] ?? null) : null;
+    const unverified = [operatorDomain === null ? "the buyer operator" : null, providerDomain === null ? "the provider" : null].filter((p) => p !== null);
+    if (unverified.length > 0)
+        return `witness independence cannot be checked: ${unverified.join(" and ")} has no verified domain`;
+    const candidates = (input.witnesses ?? [])
+        .filter((w) => w.delegation_id === delegationId && w.witness_id !== providerId && (policy.witness_provider_ids ?? [w.witness_id]).includes(w.witness_id))
+        .map((w) => ({ witness_id: w.witness_id, domain: w.domain }));
+    const count = countIndependentWitnesses(candidates, [operatorDomain, providerDomain]);
+    if (count.counted.length >= policy.min_independent_witnesses)
+        return null;
+    const refused = count.refused.map((r) => `${r.witness_id} ${r.reason}`);
+    return `${count.counted.length} of ${policy.min_independent_witnesses} required independent witnesses attested${refused.length > 0 ? `; not counted: ${refused.join("; ")}` : ""}`;
+}
+function sameSkill(a, b) {
+    return a.namespace === b.namespace && a.skill_id === b.skill_id;
+}
+function skillName(skill) {
+    return `${skill.namespace}/${skill.skill_id}`;
+}
+/** A delegation's events that count: attributed to it, not reversed, and not reversals themselves. */
+function activeEventsOf(events, delegationId) {
+    const reversed = new Set(events.map((e) => e.record.reverses_event_id).filter((id) => id !== null));
+    return events
+        .filter((e) => e.attributed_to === delegationId && e.record.type !== "reversal" && !reversed.has(e.record.financial_event_id))
+        .map((e) => e.record);
+}
+const sumOf = (events) => events.reduce((total, e) => total + e.amount_minor, 0);
+/**
+ * Where the recorded refunds break the agreed refund terms: more refunded than the post-settlement cap, a refund
+ * outside the window, or a refund the terms require on failure or timeout that was not made by the window's end.
+ */
+function refundTermsProblems(terms, expectedDelivery, currency, events, claims, now) {
+    const problems = [];
+    const windowMs = terms.after_settlement.window_seconds * 1000;
+    const cap = terms.after_settlement.cap_minor;
+    const payments = events.filter((e) => e.type === "payment_reported").sort((a, b) => Date.parse(a.event_date) - Date.parse(b.event_date));
+    const refunds = events.filter((e) => e.type === "refund");
+    const paid = sumOf(payments);
+    const refunded = sumOf(refunds);
+    if (refunded > cap)
+        problems.push(`refunded ${refunded} ${currency}, more than the agreed cap of ${cap}`);
+    const superseded = new Set(claims.map((c) => c.supersedes_event_id).filter((id) => id !== null));
+    const active = claims.filter((c) => !superseded.has(c.event_id));
+    const status = deliveryStatus(claims);
+    const delivered = active.some((c) => c.type === "completion" || c.type === "partial_completion");
+    let trigger = null;
+    if ((status === "provider_failed" || status === "cancelled") && terms.on_failure === "refund") {
+        const failure = active.filter((c) => c.type === "provider_failure" || c.type === "cancellation").at(-1);
+        trigger = { reason: "failure", at: failure.occurred_at };
+    }
+    else if (!delivered && expectedDelivery !== null && expectedDelivery < now && terms.on_timeout === "refund") {
+        trigger = { reason: "timeout", at: expectedDelivery };
+    }
+    if (payments.length > 0) {
+        const windowStart = Math.max(Date.parse(payments[0].event_date), trigger ? Date.parse(trigger.at) : 0);
+        const windowEnd = new Date(windowStart + windowMs).toISOString();
+        for (const r of refunds) {
+            if (Date.parse(r.event_date) > windowStart + windowMs)
+                problems.push(`refund ${r.financial_event_id} on ${r.event_date} is after the refund window ended at ${windowEnd}`);
+        }
+    }
+    if (trigger && paid > 0) {
+        const required = Math.min(paid, cap);
+        const deadline = new Date(Date.parse(trigger.at) + windowMs).toISOString();
+        if (now > deadline && refunded < required)
+            problems.push(`the terms require a refund on ${trigger.reason}: ${required} ${currency} was due by ${deadline}, ${refunded} was refunded`);
+    }
+    return problems;
+}
+/** Kinds the offline verifier cannot recompute: witness independence needs the domains the service verified. */
+export const SERVICE_ONLY_EXCEPTION_KINDS = ["witness_quorum_not_met"];
 /**
  * What to do with a derived exception given the latest one under its dedupe key: a person's resolution of this exact
  * condition stands ("keep"); an open exception whose condition changed shows the current detail ("update_detail");
@@ -50,3 +210,13 @@ export function derivedExceptionAction(latest, derived) {
         return "update_detail";
     return "open";
 }
+/**
+ * The latest exceptions under derived dedupe keys that a person's resolution keeps closed while the condition holds.
+ * A closure lists them so the offline verifier can tell a resolved condition from an omitted one.
+ */
+export function resolutionsInForce(derived, exceptions) {
+    return derived.flatMap((d) => {
+        const latest = exceptions.filter((x) => x.dedupe_key === d.dedupe_key).at(-1) ?? null;
+        return latest && derivedExceptionAction(latest, d) === "keep" ? [latest] : [];
+    });
+}

package/dist/expectations.d.ts

@@ -0,0 +1,96 @@
+import type { DeliveryClaim, ExpectationReport, KeyBindingRecord } from "./documents.js";
+import { type Rollup } from "./rollup.js";
+import type { AssuranceLabel, Expectation, ExpectationIssuer, FinancialEventRecord, HoldStatus } from "./types.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 declare const EXPECTATION_STATEMENT_TYPE = "atcn.subledger.expectation";
+/** What an agent or gateway signs. It covers every field of the record that carries meaning. */
+export interface ExpectationStatement {
+    document_type: typeof EXPECTATION_STATEMENT_TYPE;
+    type: "estimate" | "hold";
+    source: string;
+    source_event_id: string;
+    provider_reference: string | null;
+    amount_minor: number;
+    currency: string;
+    issued_at: string;
+    issued_by: ExpectationIssuer;
+    source_ref: string | null;
+    basis: string | null;
+    expires_at: string | null;
+    supersedes: string | null;
+    hold_status: HoldStatus | null;
+}
+export interface ExpectationStatementInput {
+    type: "estimate" | "hold";
+    source: string;
+    source_event_id: string;
+    provider_reference?: string | null;
+    amount_minor: number;
+    currency: string;
+    /** The event_date of the record. */
+    issued_at: string;
+    expectation: Omit<Expectation, "signer">;
+}
+export declare function buildExpectationStatement(input: ExpectationStatementInput): ExpectationStatement;
+/** The statement a stored estimate or hold record was signed over. */
+export declare function expectationStatementOf(record: FinancialEventRecord): ExpectationStatement;
+/** Agent- or gateway-side signing. The operator never holds the signer's private key. */
+export declare function signExpectation(statement: ExpectationStatement, privateKey: string): string;
+export declare function verifyExpectationSignature(statement: ExpectationStatement, signature: string, publicKey: string): boolean;
+/**
+ * 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 declare function expectationSignatureProblem(record: FinancialEventRecord, delegationProviderId: string | null, keyBindings: KeyBindingRecord[]): string | 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 declare function expectationAssurance(record: FinancialEventRecord, delegationProviderId: string | null, keyBindings: KeyBindingRecord[]): AssuranceLabel[];
+export interface ExpectationReportInput {
+    task: {
+        task_id: string;
+        currency: string;
+    };
+    delegations: {
+        delegation_id: string;
+        provider_id: string | null;
+    }[];
+    claims: DeliveryClaim[];
+    /** The task's financial events with their attribution (node ID: the task ID or a delegation ID). */
+    events: {
+        record: FinancialEventRecord;
+        attributed_to: string;
+    }[];
+    rollup: Rollup;
+    key_bindings: KeyBindingRecord[];
+}
+/** Variance in basis points of `base`, rounded half away from zero, using integers only. Null when there is no base. */
+export declare function varianceBps(difference: number, base: number | null): number | null;
+/**
+ * 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 declare function buildExpectationReport(input: ExpectationReportInput): ExpectationReport | null;
+export interface ExpectationException {
+    kind: "actual_exceeds_estimate" | "actual_exceeds_hold" | "hold_not_released" | "estimate_after_charge";
+    dedupe_key: string;
+    delegation_id: string | null;
+    detail: string;
+}
+/**
+ * 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 declare function expectationExceptions(report: ExpectationReport, input: {
+    task: {
+        task_id: string;
+        estimate_tolerance_bps?: number;
+    };
+    events: {
+        record: FinancialEventRecord;
+    }[];
+    now: string;
+    closing?: boolean;
+}): ExpectationException[];