@atcn/core 1.4.0 → 1.5.0

package/README.md

@@ -1,16 +1,26 @@
 # @atcn/core
 
-The ATCN clearing engine. It turns verifier results into a decision under the agreed policy, posts the balanced journal (payee amount and platform fee), builds service events, and exports closure packages. It also exports `verifyClosurePackage`, the offline verifier for those packages. The package includes the reference policies (`REFERENCE_POLICIES`).
+The obligation engine of [ATCN](https://github.com/fadnisnikhil/atcn). An obligation is a piece of paid work with agreed terms: for example "fix this bug for USD 100, accepted if the tests pass". This package:
+
+- turns the results of evidence checks into a decision under the agreed policy (the reference policies are in `REFERENCE_POLICIES`);
+- posts a balanced journal: the provider's amount and the platform fee;
+- exports a **closure package**, the signed record of the obligation, and verifies it offline with `verifyClosurePackage`;
+- builds and verifies **clearing verdicts**: the decision in effect, signed for a payment rail to read. The rail decides whether to pay; ATCN moves no money.
 
 ```bash
 npm install @atcn/core
 ```
 
 ```ts
-import { verifyClosurePackage } from "@atcn/core";
+import { verifyClosurePackage, verifyClearingVerdict } from "@atcn/core";
 
 const report = verifyClosurePackage(closurePackage, { trustedKeys });
 console.log(report.valid, report.checks);
+
+const verdictReport = verifyClearingVerdict(verdict, { trustedKeys, closurePackage });
+console.log(verdictReport.valid);
 ```
 
-See [`examples/local-runner/src/network.ts`](../../examples/local-runner/src/network.ts) for the full flow: evaluation, clearing and settlement. Part of [ATCN](../../README.md). Apache-2.0.
+The verifier replays the policy decision for every automated decision, so a package whose decision doesn't follow from its evidence fails. See [`examples/local-runner/src/network.ts`](https://github.com/fadnisnikhil/atcn/blob/main/examples/local-runner/src/network.ts) for the full flow: evaluation, clearing and simulated settlement.
+
+Part of [ATCN](https://github.com/fadnisnikhil/atcn). Apache-2.0.

package/dist/clearing.d.ts

@@ -1,8 +1,13 @@
-import { type DecisionBody, type EvidenceEnvelope, type ObligationTerms, type PolicyCheck, type PolicyTemplate, type VerifierResult, type ClearingOutcome, type EventType } from "@atcn/schema";
-export declare const CLEARING_ENGINE_ID = "atcn-clearing-engine@1.0.0";
+import { type AttestationConflict, type DecisionBody, type EvidenceEnvelope, type ObligationTerms, type PolicyCheck, type PolicyTemplate, type VerifierResult, type ClearingOutcome, type EventType } from "@atcn/schema";
+/**
+ * Version 1.1.0 sends a deliverable with conflicting attestations to the reviewer instead of using the newest result.
+ * Replays honour the version a decision names: decisions by 1.0.0 are replayed without attestation conflicts.
+ */
+export declare const CLEARING_ENGINE_ID = "atcn-clearing-engine@1.1.0";
+export declare const CLEARING_ENGINE_ID_V1_0 = "atcn-clearing-engine@1.0.0";
 /** The service event that records each decision outcome. */
 export declare const OUTCOME_EVENT: Record<ClearingOutcome, EventType>;
-export type ProducerRole = "issuer" | "counterparty" | "verifier" | "other";
+export type ProducerRole = "issuer" | "counterparty" | "verifier" | "witness" | "other";
 export interface EvidenceInput {
     envelope: EvidenceEnvelope;
     event_id: string;
@@ -22,10 +27,16 @@ export interface ClearingInput {
         type: "automated" | "human";
         id: string;
     };
+    /** Conflicts among the obligation's attestations at evaluation time (see obligationAttestationConflicts). */
+    attestation_conflicts?: AttestationConflict[];
 }
 export declare function isAdmissible(evidence: EvidenceInput, policy: PolicyTemplate): boolean;
 /** Latest admissible evidence of a type covering a deliverable (ordered by created_at, then evidence_id). */
 export declare function selectEvidence(evidence: EvidenceInput[], policy: PolicyTemplate, evidenceType: string, deliverableId: string): EvidenceInput | null;
+/** Every admissible agent_trace evidence item covering a deliverable, oldest first. Retries each count. */
+export declare function traceEvidenceFor(evidence: EvidenceInput[], policy: PolicyTemplate, deliverableId: string): EvidenceInput[];
+/** Every admissible witness_attestation evidence item covering a deliverable, oldest first, for witness_quorum. */
+export declare function witnessEvidenceFor(evidence: EvidenceInput[], policy: PolicyTemplate, deliverableId: string): EvidenceInput[];
 export interface CheckPlanItem {
     deliverable_id: string;
     check: PolicyCheck;

package/dist/clearing.js

@@ -1,5 +1,10 @@
-import { digestOf, } from "@atcn/schema";
-export const CLEARING_ENGINE_ID = "atcn-clearing-engine@1.0.0";
+import { AGENT_TRACE_EVIDENCE_TYPE, digestOf, WITNESS_ATTESTATION_EVIDENCE_TYPE, } from "@atcn/schema";
+/**
+ * Version 1.1.0 sends a deliverable with conflicting attestations to the reviewer instead of using the newest result.
+ * Replays honour the version a decision names: decisions by 1.0.0 are replayed without attestation conflicts.
+ */
+export const CLEARING_ENGINE_ID = "atcn-clearing-engine@1.1.0";
+export const CLEARING_ENGINE_ID_V1_0 = "atcn-clearing-engine@1.0.0";
 /** The service event that records each decision outcome. */
 export const OUTCOME_EVENT = {
     accepted: "completion.accepted",
@@ -29,6 +34,23 @@ export function selectEvidence(evidence, policy, evidenceType, deliverableId) {
     });
     return candidates[0] ?? null;
 }
+function allEvidenceFor(evidence, policy, evidenceType, deliverableId) {
+    return evidence
+        .filter((e) => isAdmissible(e, policy) && e.envelope.evidence_type === evidenceType && covers(e.envelope, deliverableId))
+        .sort((a, b) => {
+        if (a.envelope.created_at !== b.envelope.created_at)
+            return a.envelope.created_at < b.envelope.created_at ? -1 : 1;
+        return a.envelope.evidence_id < b.envelope.evidence_id ? -1 : 1;
+    });
+}
+/** Every admissible agent_trace evidence item covering a deliverable, oldest first. Retries each count. */
+export function traceEvidenceFor(evidence, policy, deliverableId) {
+    return allEvidenceFor(evidence, policy, AGENT_TRACE_EVIDENCE_TYPE, deliverableId);
+}
+/** Every admissible witness_attestation evidence item covering a deliverable, oldest first, for witness_quorum. */
+export function witnessEvidenceFor(evidence, policy, deliverableId) {
+    return allEvidenceFor(evidence, policy, WITNESS_ATTESTATION_EVIDENCE_TYPE, deliverableId);
+}
 /** Which verifier runs are needed for an evaluation: one per (deliverable, required check). */
 export function planChecks(input) {
     const plan = [];
@@ -70,6 +92,9 @@ export function producerRole(terms, producerId) {
         return "counterparty";
     if (terms.verifier_agent_ids.includes(producerId))
         return "verifier";
+    const witnesses = terms.witness_policy?.witness_agent_ids;
+    if (terms.witness_policy && (witnesses === undefined || witnesses.includes(producerId)))
+        return "witness";
     return "other";
 }
 /**
@@ -81,6 +106,7 @@ export function evaluateClearing(input) {
     const usedEvidence = new Map();
     const usedResults = new Map();
     const deliverableOutcomes = [];
+    const conflicts = input.attestation_conflicts ?? [];
     for (const deliverable of terms.deliverables) {
         const reasons = [];
         const verdicts = [];
@@ -138,6 +164,10 @@ export function evaluateClearing(input) {
                 reasons.push({ code: "probabilistic_review_required", check_id: checkId, detail: `probabilistic result: ${result.status}` });
                 verdicts.push(policy.probabilistic_routing === "human_review" ? "disputed" : "insufficient_evidence");
             }
+            else if (result.status === "fail" && check.verifier === "witness_quorum") {
+                reasons.push({ code: "witness_quorum_not_met", check_id: checkId, detail: String(result.details.refused ?? "") });
+                verdicts.push("insufficient_evidence");
+            }
             else if (result.status === "fail") {
                 reasons.push({ code: "failed_criteria", check_id: checkId });
                 verdicts.push("rejected");
@@ -146,11 +176,26 @@ export function evaluateClearing(input) {
                 reasons.push({ code: "passed", check_id: checkId });
                 verdicts.push("accepted");
             }
+            const onCheck = conflicts.filter((c) => c.subject === `${terms.obligation_id}/${deliverable.deliverable_id}/${checkId}`);
+            if (onCheck.length > 0) {
+                reasons.push({ code: "conflicting_attestations", check_id: checkId, detail: onCheck.map((c) => c.kind).join(",") });
+                verdicts.push("disputed");
+            }
+        }
+        const onRun = conflicts.filter((c) => c.subject.startsWith(`${terms.obligation_id}/execution:`));
+        if (onRun.length > 0) {
+            reasons.push({ code: "conflicting_attestations", detail: `the counterparty declared conflicting descriptors for ${onRun.map((c) => c.subject.split("/execution:")[1]).join(", ")}` });
+            verdicts.push("disputed");
+        }
+        let verdict = combineVerdicts(verdicts);
+        if (verdict === "rejected" && terms.refund_terms?.on_failure === "dispute") {
+            verdict = "disputed";
+            reasons.push({ code: "failure_terms_dispute" });
         }
         deliverableOutcomes.push({
             deliverable_id: deliverable.deliverable_id,
             amount_minor: deliverable.amount_minor,
-            outcome: combineVerdicts(verdicts),
+            outcome: verdict,
             reasons,
         });
     }

package/dist/conflicts.d.ts

@@ -0,0 +1,26 @@
+import { type AttestationConflict, type ObligationTerms, type RecordedEvent } from "@atcn/schema";
+export interface AttestationKey {
+    actor_id: string;
+    public_key: string;
+    revoked_at: string | null;
+}
+export interface ConflictInput {
+    /** The obligation's recorded events. */
+    events: RecordedEvent[];
+    /** Its accepted terms. */
+    terms: ObligationTerms;
+    /** Attestation text by content digest (the SHA-256 of the evidence bytes). Items without text are skipped. */
+    contents: Map<string, string>;
+    resolveKey: (keyId: string, keyVersion: number) => AttestationKey | null;
+    /** Reference time: the evaluation time for clearing, generated_at for a closure package. */
+    at: string;
+    /** Only events up to this sequence count (a decision's input cutoff). */
+    cutoffSequence?: number;
+}
+/**
+ * Conflicts among an obligation's attestations in effect at `at`, plus runs the counterparty declared twice with
+ * different descriptors. An attestation counts only when its signature verifies with a key of its signer, and the signer
+ * may attest: an agreed verifier for verifier attestations; for witness attestations, anyone but the parties, limited to
+ * the agreed witnesses when the terms list them. Superseded evidence does not count; who uploaded it does not matter.
+ */
+export declare function obligationAttestationConflicts(input: ConflictInput): AttestationConflict[];

package/dist/conflicts.js

@@ -0,0 +1,85 @@
+import { ATTESTATION_EVIDENCE_TYPES, digestOf, disputesInEffect, findConflicts, inEffect, resolveAttestations, SignedExternalAttestationSchema, verifyPayload, } from "@atcn/schema";
+import { buildEvidenceInputs, declaredExecutions, resolveCounterparty } from "./evidence.js";
+/**
+ * Conflicts among an obligation's attestations in effect at `at`, plus runs the counterparty declared twice with
+ * different descriptors. An attestation counts only when its signature verifies with a key of its signer, and the signer
+ * may attest: an agreed verifier for verifier attestations; for witness attestations, anyone but the parties, limited to
+ * the agreed witnesses when the terms list them. Superseded evidence does not count; who uploaded it does not matter.
+ */
+export function obligationAttestationConflicts(input) {
+    const visible = input.events.filter((e) => input.cutoffSequence === undefined || e.sequence <= input.cutoffSequence);
+    const terms = resolveCounterparty(input.terms, visible);
+    const parties = [terms.issuer_agent_id, terms.counterparty_agent_id, terms.principal_id];
+    const items = [];
+    const claims = [];
+    const seen = new Set();
+    for (const evidence of buildEvidenceInputs(visible, input.terms)) {
+        if (evidence.superseded || !ATTESTATION_EVIDENCE_TYPES.includes(evidence.envelope.evidence_type))
+            continue;
+        const content = input.contents.get(evidence.envelope.content_digest);
+        if (content === undefined)
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(content);
+        }
+        catch {
+            continue;
+        }
+        const parsed = SignedExternalAttestationSchema.safeParse(raw);
+        if (!parsed.success)
+            continue;
+        const { payload: p, signature } = parsed.data;
+        if (p.obligation_id !== terms.obligation_id)
+            continue;
+        const role = p.role ?? "verifier";
+        const allowed = role === "verifier"
+            ? terms.verifier_agent_ids.includes(p.verifier_id)
+            : !parties.includes(p.verifier_id) && (terms.witness_policy?.witness_agent_ids ?? [p.verifier_id]).includes(p.verifier_id);
+        if (!allowed)
+            continue;
+        const key = input.resolveKey(signature.key_id, signature.key_version);
+        // An attestation whose text is not canonical JSON (a fraction in an unknown member) cannot be checked or counted.
+        let verified;
+        let digest;
+        try {
+            verified = !!key && key.actor_id === p.verifier_id && verifyPayload(raw, key.public_key);
+            digest = digestOf(raw.payload);
+        }
+        catch {
+            continue;
+        }
+        if (!key || !verified)
+            continue;
+        if (key.revoked_at !== null && Date.parse(key.revoked_at) <= Date.parse(p.issued_at ?? input.at))
+            continue;
+        if (seen.has(digest))
+            continue;
+        seen.add(digest);
+        items.push({ digest, signer: p.verifier_id, issued_at: p.issued_at, expires_at: p.expires_at, refs: p.refs });
+        claims.push({
+            digest,
+            signer: p.verifier_id,
+            subject: `${terms.obligation_id}/${p.deliverable_id}/${p.check_id}`,
+            status: p.status,
+            ...(p.execution ? { execution_digest: p.execution.execution_digest } : {}),
+        });
+    }
+    const resolution = resolveAttestations(items, input.at);
+    const effective = claims.filter((c) => inEffect(resolution, c.digest));
+    return [...findConflicts(effective, disputesInEffect(items, resolution)), ...executionConflicts(visible, terms)].sort((a, b) => a.subject !== b.subject ? (a.subject < b.subject ? -1 : 1) : a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0);
+}
+/** Two obligation.started events that give one execution_id different descriptors: the counterparty equivocated about the run. */
+function executionConflicts(events, terms) {
+    const byId = new Map();
+    for (const e of declaredExecutions(events, terms.counterparty_agent_id))
+        byId.set(e.execution_id, (byId.get(e.execution_id) ?? new Set()).add(e.execution_digest));
+    return [...byId.entries()]
+        .filter(([, digests]) => digests.size > 1)
+        .map(([executionId, digests]) => ({
+        kind: "equivocation",
+        subject: `${terms.obligation_id}/execution:${executionId}`,
+        attestation_digests: [...digests].sort(),
+        signers: [terms.counterparty_agent_id],
+    }));
+}

package/dist/evidence.js

@@ -1,4 +1,4 @@
-import { digestOf, ExecutionDescriptorSchema } from "@atcn/schema";
+import { digestOf, EvidenceEnvelopeSchema, ExecutionDescriptorSchema } from "@atcn/schema";
 import { producerRole } from "./clearing.js";
 /**
  * Runs the counterparty declared in its signed obligation.started events. A descriptor naming another agent is
@@ -11,7 +11,15 @@ export function declaredExecutions(events, counterpartyAgentId) {
         const parsed = ExecutionDescriptorSchema.safeParse(e.payload.data.execution);
         if (!parsed.success || parsed.data.agent.agent_id !== e.payload.actor_id)
             return [];
-        return [{ execution_id: parsed.data.execution_id, execution_digest: digestOf(e.payload.data.execution), started_event_id: e.payload.event_id, descriptor: parsed.data }];
+        return [
+            {
+                execution_id: parsed.data.execution_id,
+                execution_digest: digestOf(e.payload.data.execution),
+                started_event_id: e.payload.event_id,
+                descriptor: parsed.data,
+                started_at: e.received_at,
+            },
+        ];
     });
 }
 /**
@@ -30,16 +38,22 @@ export function buildEvidenceInputs(events, signedTerms, cutoffSequence) {
         if (actorOf.get(target) === e.payload.actor_id)
             superseded.add(target);
     }
-    return visible
-        .filter((e) => e.payload.event_type === "evidence.submitted")
-        .map((e) => {
-        const envelope = e.payload.data.envelope;
-        return {
-            envelope,
-            event_id: e.payload.event_id,
-            producer_role: producerRole(terms, envelope.producer_id),
-            superseded: superseded.has(e.payload.event_id),
-        };
+    // An evidence.submitted event without a well-formed envelope carries no evidence.
+    return visible.flatMap((e) => {
+        if (e.payload.event_type !== "evidence.submitted")
+            return [];
+        const parsed = EvidenceEnvelopeSchema.safeParse(e.payload.data.envelope);
+        if (!parsed.success)
+            return [];
+        const envelope = parsed.data;
+        return [
+            {
+                envelope,
+                event_id: e.payload.event_id,
+                producer_role: producerRole(terms, envelope.producer_id),
+                superseded: superseded.has(e.payload.event_id),
+            },
+        ];
     });
 }
 /**

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export * from "./allocation.js";
 export * from "./clearing.js";
+export * from "./conflicts.js";
 export * from "./delegation.js";
 export * from "./evidence.js";
 export * from "./journal.js";
 export * from "./package.js";
 export * from "./service.js";
 export * from "./templates.js";
+export * from "./verdict.js";

package/dist/index.js

@@ -1,8 +1,10 @@
 export * from "./allocation.js";
 export * from "./clearing.js";
+export * from "./conflicts.js";
 export * from "./delegation.js";
 export * from "./evidence.js";
 export * from "./journal.js";
 export * from "./package.js";
 export * from "./service.js";
 export * from "./templates.js";
+export * from "./verdict.js";

package/dist/package.d.ts

@@ -1,16 +1,23 @@
-import { type PublicKeyRecord } from "@atcn/schema";
+import { type AttestationConflict, type ClosurePackage, type PublicKeyRecord } from "@atcn/schema";
+import { type AttestationKey } from "./conflicts.js";
 export interface CheckResult {
     name: string;
     ok: boolean;
     details: string[];
+    /** Set when the check had nothing it could inspect (for example, trace evidence whose files were not supplied). Not a pass. */
+    state?: "not_inspected";
 }
 export interface PackageVerificationReport {
     valid: boolean;
+    /** Set when the package declares a version this verifier does not know; upgrade the verifier. */
+    unsupported_schema_version?: string;
     checks: CheckResult[];
 }
 export interface VerifyOptions {
     /** Published public keys trusted out of band. The ATCN service key must be among them. */
     trustedKeys: PublicKeyRecord[];
+    /** Trace files (raw bytes) behind agent_trace evidence, to recheck the traces and recompute usage_cost results. */
+    traces?: Uint8Array[];
 }
 /**
  * Offline verification of a closure package (PRD scenario L): signatures, event
@@ -18,3 +25,5 @@ export interface VerifyOptions {
  * journal balance, and settlement references. Makes no network calls.
  */
 export declare function verifyClosurePackage(input: unknown, options: VerifyOptions): PackageVerificationReport;
+/** The conflicts a package must record: every unredacted obligation's attestation conflicts at generated_at. */
+export declare function packageAttestationConflicts(body: Pick<ClosurePackage["payload"], "obligations" | "events" | "generated_at">, contents: Map<string, string>, resolveKey: (keyId: string, keyVersion: number) => AttestationKey | null): AttestationConflict[];

package/dist/package.js

@@ -1,6 +1,7 @@
-import { ClosurePackageSchema, digestOf, verifyPayload, } from "@atcn/schema";
-import { decisionDigest, evaluateClearing, verifierOutputDigest } from "./clearing.js";
-import { buildEvidenceInputs } from "./evidence.js";
+import { AGENT_TRACE_EVIDENCE_TYPE, ATTESTATION_EVIDENCE_TYPES, ClosurePackageSchema, ObligationTermsSchema, checkTrace, digestOf, sha256Digest, SUPPORTED_PACKAGE_VERSIONS, traceDigest, usageCostDetails, utf8Decode, utf8Encode, verifyPayload, } from "@atcn/schema";
+import { CLEARING_ENGINE_ID_V1_0, decisionDigest, evaluateClearing, verifierOutputDigest } from "./clearing.js";
+import { obligationAttestationConflicts } from "./conflicts.js";
+import { buildEvidenceInputs, declaredExecutions, resolveCounterparty } from "./evidence.js";
 import { checkBalanced } from "./journal.js";
 const SERVICE_ACTOR = "svc_atcn";
 function keyRef(keyId, version) {
@@ -9,6 +10,12 @@ function keyRef(keyId, version) {
 function keyValidAt(key, at) {
     return key.valid_from <= at && (key.revoked_at === null || key.revoked_at > at);
 }
+function sameInstant(a, b) {
+    return a === null || b === null ? a === b : Date.parse(a) === Date.parse(b);
+}
+function sameKey(a, b) {
+    return a.actor_id === b.actor_id && a.public_key === b.public_key && sameInstant(a.valid_from, b.valid_from) && sameInstant(a.revoked_at, b.revoked_at);
+}
 /**
  * Offline verification of a closure package (PRD scenario L): signatures, event
  * references, decision inputs (re-running the deterministic clearing engine),
@@ -16,6 +23,14 @@ function keyValidAt(key, at) {
  */
 export function verifyClosurePackage(input, options) {
     const checks = [];
+    const declared = input?.payload?.package_version;
+    if (typeof declared === "string" && !SUPPORTED_PACKAGE_VERSIONS.includes(declared)) {
+        return {
+            valid: false,
+            unsupported_schema_version: declared,
+            checks: [{ name: "schema", ok: false, details: [`package_version ${declared} is not supported by this verifier (supports ${SUPPORTED_PACKAGE_VERSIONS.join(", ")})`] }],
+        };
+    }
     const parsed = ClosurePackageSchema.safeParse(input);
     if (!parsed.success) {
         return {
@@ -34,10 +49,19 @@ export function verifyClosurePackage(input, options) {
     for (const trusted of options.trustedKeys) {
         const ref = keyRef(trusted.key_id, trusted.key_version);
         const existing = keys.get(ref);
-        if (existing && existing.public_key !== trusted.public_key)
+        if (existing && !sameKey(existing, trusted))
             keyProblems.push(`package key ${ref} contradicts published key`);
         keys.set(ref, trusted);
     }
+    const usedKeys = new Set([
+        keyRef(pkg.signature.key_id, pkg.signature.key_version),
+        ...body.events.map((e) => keyRef(e.signature.key_id, e.signature.key_version)),
+        ...attestationSignatureKeys(body),
+    ]);
+    for (const k of body.public_keys) {
+        if (!usedKeys.has(keyRef(k.key_id, k.key_version)))
+            keyProblems.push(`package key ${keyRef(k.key_id, k.key_version)} signs nothing in the package`);
+    }
     checks.push({ name: "keys_consistent", ok: keyProblems.length === 0, details: keyProblems });
     // Package signature by the ATCN service.
     const serviceKey = options.trustedKeys.find((k) => k.key_id === pkg.signature.key_id && k.key_version === pkg.signature.key_version && k.actor_id === SERVICE_ACTOR);
@@ -74,21 +98,33 @@ export function verifyClosurePackage(input, options) {
     // Obligation lineage and terms digests.
     const obligationIds = new Set(body.obligations.map((o) => o.obligation_id));
     const lineageProblems = [];
+    const root = body.obligations.find((o) => o.obligation_id === body.root_obligation_id);
+    if (!root)
+        lineageProblems.push(`root obligation ${body.root_obligation_id} missing`);
+    else if (root.parent_obligation_id !== null)
+        lineageProblems.push(`root obligation ${body.root_obligation_id} has a parent`);
+    if (!obligationIds.has(body.requested_obligation_id))
+        lineageProblems.push(`requested obligation ${body.requested_obligation_id} missing`);
     const termsByDigest = new Map();
     for (const event of body.events) {
         const data = event.payload.data;
         if (data.terms && data.terms_digest) {
             if (digestOf(data.terms) !== data.terms_digest)
                 lineageProblems.push(`${event.payload.event_id}: terms_digest mismatch`);
-            termsByDigest.set(data.terms_digest, data.terms);
+            // Only valid terms can be replayed; a decision citing other terms finds none.
+            if (ObligationTermsSchema.safeParse(data.terms).success)
+                termsByDigest.set(data.terms_digest, data.terms);
         }
     }
     for (const o of body.obligations) {
         if (o.parent_obligation_id && !obligationIds.has(o.parent_obligation_id)) {
             lineageProblems.push(`${o.obligation_id}: parent ${o.parent_obligation_id} missing`);
         }
-        if (o.redacted)
+        if (o.redacted) {
+            if (o.effective_terms !== null || o.effective_terms_digest !== null)
+                lineageProblems.push(`${o.obligation_id}: redacted obligation carries terms`);
             continue;
+        }
         if (!o.effective_terms || !o.effective_terms_digest) {
             lineageProblems.push(`${o.obligation_id}: unredacted obligation without terms`);
             continue;
@@ -121,8 +157,10 @@ export function verifyClosurePackage(input, options) {
     const evidenceDigests = new Set(body.evidence.map((e) => e.content_digest));
     const resultDigests = new Set(body.verifier_results.map(verifierOutputDigest));
     const policies = new Map(body.policies.map((p) => [`${p.policy_id}@${p.policy_version}`, p]));
+    const contents = attestationContents(body);
+    const resolveKey = (keyId, keyVersion) => keys.get(keyRef(keyId, keyVersion)) ?? null;
     for (const decision of body.decisions) {
-        decisionProblems.push(...checkDecision(decision, body.events, termsByDigest, policies, body.verifier_results, eventIds, evidenceDigests, resultDigests));
+        decisionProblems.push(...checkDecision(decision, body.events, termsByDigest, policies, body.verifier_results, eventIds, evidenceDigests, resultDigests, contents, resolveKey));
     }
     checks.push({ name: "decision_inputs_and_replay", ok: decisionProblems.length === 0, details: decisionProblems });
     // Journal balance and references.
@@ -163,9 +201,254 @@ export function verifyClosurePackage(input, options) {
         }
     }
     checks.push({ name: "settlement_references", ok: settlementProblems.length === 0, details: settlementProblems });
+    checks.push(recordsMatchEventsCheck(body));
+    checks.push(traceEvidenceCheck(body, options.traces ?? []));
+    if (body.package_version !== "1.0")
+        checks.push(attestationConflictsCheck(body, contents, resolveKey));
     return { valid: checks.every((c) => c.ok), checks };
 }
-function checkDecision(decision, events, termsByDigest, policies, verifierResults, eventIds, evidenceDigests, resultDigests) {
+/** Attestation text by content digest, from a 1.1 package's attestations. */
+function attestationContents(body) {
+    return new Map((body.attestations ?? []).map((a) => [sha256Digest(utf8Encode(a.content)), a.content]));
+}
+/** Key references of the signatures on the package's attestations, so their keys count as used. */
+function attestationSignatureKeys(body) {
+    return (body.attestations ?? []).flatMap((a) => {
+        try {
+            const signature = JSON.parse(a.content).signature;
+            return typeof signature?.key_id === "string" && typeof signature.key_version === "number" ? [keyRef(signature.key_id, signature.key_version)] : [];
+        }
+        catch {
+            return [];
+        }
+    });
+}
+/** The conflicts a package must record: every unredacted obligation's attestation conflicts at generated_at. */
+export function packageAttestationConflicts(body, contents, resolveKey) {
+    return body.obligations
+        .filter((o) => !o.redacted && o.effective_terms !== null)
+        .flatMap((o) => obligationAttestationConflicts({
+        events: body.events.filter((e) => e.payload.obligation_id === o.obligation_id),
+        terms: o.effective_terms,
+        contents,
+        resolveKey,
+        at: body.generated_at,
+    }))
+        .sort((a, b) => (a.subject !== b.subject ? (a.subject < b.subject ? -1 : 1) : a.kind < b.kind ? -1 : a.kind > b.kind ? 1 : 0));
+}
+/**
+ * Package 1.1: every attestation evidence item must come with its exact text (whose SHA-256 is the envelope's
+ * content_digest), and attestation_conflicts must be exactly what those attestations produce at generated_at, so a
+ * conflict cannot be removed to make the package look clean.
+ */
+function attestationConflictsCheck(body, contents, resolveKey) {
+    const problems = [];
+    const envelopes = new Map(body.evidence.map((e) => [e.evidence_id, e]));
+    for (const a of body.attestations ?? []) {
+        const envelope = envelopes.get(a.evidence_id);
+        if (!envelope || !ATTESTATION_EVIDENCE_TYPES.includes(envelope.evidence_type))
+            problems.push(`attestation ${a.evidence_id} is not attestation evidence in the package`);
+        else if (sha256Digest(utf8Encode(a.content)) !== envelope.content_digest)
+            problems.push(`attestation ${a.evidence_id} text does not match its content digest`);
+    }
+    const supplied = new Set((body.attestations ?? []).map((a) => a.evidence_id));
+    for (const e of body.evidence) {
+        if (ATTESTATION_EVIDENCE_TYPES.includes(e.evidence_type) && !supplied.has(e.evidence_id))
+            problems.push(`attestation evidence ${e.evidence_id} has no text in the package`);
+    }
+    const expected = packageAttestationConflicts(body, contents, resolveKey);
+    if (digestOf(expected) !== digestOf(body.attestation_conflicts ?? [])) {
+        problems.push(`attestation_conflicts do not match the attestations (expected ${expected.length} conflict(s), recorded ${(body.attestation_conflicts ?? []).length})`);
+    }
+    if (problems.length > 0)
+        return { name: "attestation_conflicts", ok: false, details: problems };
+    return { name: "attestation_conflicts", ok: true, details: [expected.length === 0 ? "no conflicting attestations" : `${expected.length} conflict(s) recomputed: ${expected.map((c) => `${c.kind} on ${c.subject}`).join("; ")}`] };
+}
+/**
+ * The package's tables repeat facts the service also signed as events. Each table row must match its event:
+ * settlement events their settlement.reported event, posting batches their journal event, and decisions their outcome
+ * event. Posting lines may name only the obligation's payer, payee and the actors and platforms in its events, and
+ * settlement instructions may not exceed what the decision's clearing batch made payable to the beneficiary.
+ */
+function recordsMatchEventsCheck(body) {
+    const problems = [];
+    const eventsOfType = (types) => body.events.filter((e) => types.includes(e.payload.event_type));
+    // A value that is not canonical JSON (batch totals past the safe integer range) matches nothing.
+    const same = (a, b) => {
+        try {
+            return digestOf(a ?? null) === digestOf(b ?? null);
+        }
+        catch {
+            return false;
+        }
+    };
+    const reports = eventsOfType(["settlement.reported"]);
+    for (const s of body.settlement_events) {
+        const data = reports.find((e) => e.payload.data.settlement_event_id === s.settlement_event_id)?.payload.data;
+        if (!data) {
+            problems.push(`settlement event ${s.settlement_event_id} has no settlement.reported event`);
+            continue;
+        }
+        const fields = ["instruction_id", "provider", "provider_reference", "provider_status", "normalized_status", "amount_minor", "currency"];
+        const differing = fields.filter((f) => !same(s[f], data[f]));
+        if (differing.length > 0)
+            problems.push(`settlement event ${s.settlement_event_id} ${differing.join(", ")} differ from its settlement.reported event`);
+    }
+    const journalEvents = eventsOfType(["journal.posted", "journal.reversed"]);
+    for (const b of body.posting_batches) {
+        const event = journalEvents.find((e) => e.payload.data.batch_id === b.batch_id);
+        if (!event) {
+            problems.push(`posting batch ${b.batch_id} has no journal event`);
+            continue;
+        }
+        const data = event.payload.data;
+        const totals = Object.fromEntries(Object.entries(checkBalanced(b.lines).byCurrency).map(([currency, t]) => [currency, t.debit]));
+        if (event.payload.obligation_id !== b.obligation_id)
+            problems.push(`posting batch ${b.batch_id} belongs to ${event.payload.obligation_id} by its journal event`);
+        if (!same(data.entry_type, b.entry_type) || !same(data.reverses_batch_id, b.reverses_batch_id) || !same(data.decision_id, b.decision_id)) {
+            problems.push(`posting batch ${b.batch_id} entry type, reversal or decision differ from its journal event`);
+        }
+        if (!same(data.totals, totals))
+            problems.push(`posting batch ${b.batch_id} totals differ from its journal event`);
+        if (!same([...b.source_event_ids].sort(), [...event.payload.causation_ids].sort()))
+            problems.push(`posting batch ${b.batch_id} source events differ from its journal event's causes`);
+        const obligationEvents = body.events.filter((e) => e.payload.obligation_id === b.obligation_id);
+        const agreedPolicyVersions = obligationEvents.map((e) => e.payload.data.terms?.acceptance_policy?.policy_version);
+        if (b.policy_version !== null && !agreedPolicyVersions.includes(b.policy_version))
+            problems.push(`posting batch ${b.batch_id} policy version ${b.policy_version} is not in the obligation's terms`);
+        const obligation = body.obligations.find((o) => o.obligation_id === b.obligation_id);
+        if (obligation?.effective_terms) {
+            const terms = resolveCounterparty(obligation.effective_terms, obligationEvents);
+            const parties = new Set([terms.payer_id, ...(terms.counterparty_agent_id ? [terms.counterparty_agent_id] : [])]);
+            for (const e of obligationEvents)
+                parties.add(e.payload.actor_id).add(e.payload.actor_platform_id);
+            for (const line of b.lines)
+                if (!parties.has(line.party_id))
+                    problems.push(`posting batch ${b.batch_id} names ${line.party_id}, who is not a party to ${b.obligation_id}`);
+        }
+    }
+    const outcomeEvents = eventsOfType(["completion.accepted", "completion.partially_accepted", "completion.rejected", "completion.insufficient_evidence", "completion.disputed"]);
+    for (const d of body.decisions) {
+        const event = outcomeEvents.find((e) => e.payload.data.decision_id === d.decision_id);
+        if (!event) {
+            problems.push(`decision ${d.decision_id} has no outcome event`);
+            continue;
+        }
+        const data = event.payload.data;
+        if (!same(data.decision_digest, d.decision_digest) || !same(data.outcome, d.outcome) || !same(data.supersedes_decision_id, d.supersedes_decision_id)) {
+            problems.push(`decision ${d.decision_id} differs from its outcome event`);
+        }
+        if (Date.parse(d.decided_at) > Date.parse(event.payload.event_time))
+            problems.push(`decision ${d.decision_id} was decided after its outcome event`);
+        if (d.input_cutoff_sequence >= event.sequence)
+            problems.push(`decision ${d.decision_id} input cutoff is not before its outcome event`);
+    }
+    const instructed = new Map();
+    for (const i of body.settlement_instructions) {
+        const key = `${i.decision_id}|${i.beneficiary_party_id}|${i.currency}`;
+        instructed.set(key, (instructed.get(key) ?? 0) + i.amount_minor);
+    }
+    for (const [key, amount] of instructed) {
+        const [decisionId, beneficiary, currency] = key.split("|");
+        const payable = body.posting_batches
+            .filter((b) => b.entry_type === "clearing" && b.decision_id === decisionId)
+            .flatMap((b) => b.lines)
+            .filter((l) => l.account_type === "payable" && l.party_id === beneficiary && l.currency === currency)
+            .reduce((sum, l) => sum + l.credit_minor - l.debit_minor, 0);
+        if (amount > payable)
+            problems.push(`settlement instructions for decision ${decisionId} pay ${beneficiary} ${amount} ${currency}, more than the ${payable} its clearing made payable`);
+    }
+    return { name: "records_match_signed_events", ok: problems.length === 0, details: problems };
+}
+/**
+ * Trace evidence, when its files are supplied: each file must match an agent_trace envelope's content digest, pass
+ * every agent_trace rule against the obligation's declared runs, and each recorded usage_cost result must recompute
+ * from the terms' pricing and its traces. Evidence whose file was not supplied is reported as not inspected.
+ */
+function traceEvidenceCheck(body, files) {
+    const name = "trace_evidence";
+    const envelopes = body.evidence.filter((e) => e.evidence_type === AGENT_TRACE_EVIDENCE_TYPE);
+    const usageResults = body.verifier_results.filter((r) => r.verifier_name === "usage_cost" && typeof r.details.trace_digests === "string");
+    if (envelopes.length === 0 && usageResults.length === 0)
+        return { name, ok: true, details: ["no trace evidence"] };
+    const fileByDigest = new Map(files.map((bytes) => [sha256Digest(bytes), bytes]));
+    const obligationOfEvidence = new Map();
+    for (const e of body.events) {
+        const envelope = e.payload.data.envelope;
+        if (e.payload.event_type === "evidence.submitted" && envelope?.evidence_id)
+            obligationOfEvidence.set(envelope.evidence_id, e.payload.obligation_id);
+    }
+    const problems = [];
+    const notes = [];
+    const tracesByObligation = new Map();
+    let inspected = 0;
+    for (const envelope of envelopes) {
+        const bytes = fileByDigest.get(envelope.content_digest);
+        const obligationId = obligationOfEvidence.get(envelope.evidence_id);
+        if (!bytes) {
+            notes.push(`not inspected: trace evidence ${envelope.evidence_id} (file not supplied)`);
+            continue;
+        }
+        const obligation = body.obligations.find((o) => o.obligation_id === obligationId);
+        if (!obligationId || !obligation?.effective_terms) {
+            problems.push(`trace evidence ${envelope.evidence_id}: its obligation is not in the package`);
+            continue;
+        }
+        inspected += 1;
+        let raw;
+        try {
+            raw = JSON.parse(utf8Decode(bytes));
+        }
+        catch {
+            problems.push(`trace evidence ${envelope.evidence_id}: file is not JSON`);
+            continue;
+        }
+        const events = body.events.filter((e) => e.payload.obligation_id === obligationId);
+        const terms = resolveCounterparty(obligation.effective_terms, events);
+        const checked = checkTrace(raw, declaredExecutions(events, terms.counterparty_agent_id), null);
+        if (!checked.ok) {
+            problems.push(`trace evidence ${envelope.evidence_id}: ${checked.code}: ${checked.error}`);
+            continue;
+        }
+        const traces = tracesByObligation.get(obligationId) ?? new Map();
+        traces.set(traceDigest(checked.trace), checked.trace);
+        tracesByObligation.set(obligationId, traces);
+    }
+    for (const result of usageResults) {
+        const digests = String(result.details.trace_digests).split(",").filter((d) => d.length > 0);
+        const available = tracesByObligation.get(result.obligation_id) ?? new Map();
+        const missing = digests.filter((d) => !available.has(d));
+        const label = `usage_cost result for ${result.obligation_id}/${result.deliverable_id}`;
+        if (digests.length === 0 || missing.length > 0) {
+            notes.push(`not inspected: ${label} (${missing.length || "no"} trace file(s) not supplied)`);
+            continue;
+        }
+        const terms = body.obligations.find((o) => o.obligation_id === result.obligation_id)?.effective_terms;
+        const deliverable = terms?.deliverables.find((d) => d.deliverable_id === result.deliverable_id);
+        if (!terms?.pricing || !deliverable) {
+            problems.push(`${label}: the package's terms carry no pricing for this deliverable`);
+            continue;
+        }
+        inspected += 1;
+        let recomputed;
+        try {
+            recomputed = usageCostDetails(terms.pricing, deliverable.amount_minor, digests.map((d) => available.get(d)));
+        }
+        catch {
+            problems.push(`${label}: usage too large to price exactly`);
+            continue;
+        }
+        const fields = ["expected_minor", "amount_minor", "within_tolerance", "trace_digests", "lines_digest", "unpriced"];
+        const differing = fields.filter((f) => recomputed[f] !== result.details[f]);
+        if (differing.length > 0)
+            problems.push(`${label}: recorded ${differing.join(", ")} do not match the traces and pricing`);
+    }
+    if (problems.length > 0)
+        return { name, ok: false, details: problems };
+    const details = [...(inspected > 0 ? [`${inspected} trace item(s) and usage result(s) rechecked`] : []), ...notes];
+    return inspected === 0 ? { name, ok: true, details, state: "not_inspected" } : { name, ok: true, details };
+}
+function checkDecision(decision, events, termsByDigest, policies, verifierResults, eventIds, evidenceDigests, resultDigests, contents, resolveKey) {
     const problems = [];
     const id = decision.decision_id;
     const { decision_id: _id, decision_digest: storedDigest, decided_at: _decidedAt, supersedes_decision_id: _supersedes, input_cutoff_sequence: cutoff, ...body } = decision;
@@ -207,6 +490,9 @@ function checkDecision(decision, events, termsByDigest, policies, verifierResult
         evidence: buildEvidenceInputs(obligationEvents, terms, cutoff),
         verifier_results: verifierResults.filter((r) => r.obligation_id === decision.obligation_id && r.executed_at <= decision.decided_at),
         decision_maker: decision.decision_maker,
+        attestation_conflicts: decision.decision_maker.id === CLEARING_ENGINE_ID_V1_0
+            ? []
+            : obligationAttestationConflicts({ events: obligationEvents, terms, contents, resolveKey, at: decision.decided_at, cutoffSequence: cutoff }),
     });
     if (decisionDigest(replay) !== storedDigest)
         problems.push(`${id}: replaying the clearing policy produced a different decision`);

package/dist/templates.d.ts

@@ -5,4 +5,15 @@ export declare const CODE_CHANGE_POLICY_V1: PolicyTemplate;
 export declare const CODE_CHANGE_POLICY_V1_1: PolicyTemplate;
 /** Worker-to-subworker template without platform fee (child obligations in the reference flow). */
 export declare const CODE_CHANGE_SUBTASK_POLICY_V1: PolicyTemplate;
+/**
+ * Usage-priced agent work: the counterparty submits the run's trace, which must belong to its declared run, and the
+ * usage in it must support each deliverable's amount under the terms' pricing (terms schema 1.2).
+ */
+export declare const AGENT_USAGE_POLICY_V1: PolicyTemplate;
+/**
+ * Witnessed agent work: a deliverable requiring "witnesses" is accepted only when enough independent witnesses, as the
+ * terms' witness_policy sets, attested to the declared run. "review_bound" is the run-bound review (external_attestation@1.1.0).
+ * Witnesses may submit their attestations themselves.
+ */
+export declare const WITNESSED_AGENT_WORK_POLICY_V1: PolicyTemplate;
 export declare const REFERENCE_POLICIES: PolicyTemplate[];

package/dist/templates.js

@@ -59,4 +59,40 @@ export const CODE_CHANGE_SUBTASK_POLICY_V1 = {
     description: "Subtask of a code change; same checks, no platform fee.",
     allocation: { platform_fee_bps: 0 },
 };
-export const REFERENCE_POLICIES = [CODE_CHANGE_POLICY_V1, CODE_CHANGE_POLICY_V1_1, CODE_CHANGE_SUBTASK_POLICY_V1];
+/**
+ * Usage-priced agent work: the counterparty submits the run's trace, which must belong to its declared run, and the
+ * usage in it must support each deliverable's amount under the terms' pricing (terms schema 1.2).
+ */
+export const AGENT_USAGE_POLICY_V1 = {
+    ...CODE_CHANGE_POLICY_V1,
+    policy_id: "agent-usage-checks",
+    policy_version: "1.0.0",
+    task_type: "agent_work",
+    description: "Agent work accepted when the run's trace belongs to the declared run and its usage, priced with the agreed rates, supports the amount. Deliverables may also require the code-change checks.",
+    required_evidence: ["agent_trace"],
+    checks: [
+        ...CODE_CHANGE_POLICY_V1.checks,
+        { check_id: "trace", verifier: "agent_trace", verifier_version: "1.0.0", evidence_type: "agent_trace", config: {} },
+        { check_id: "usage_cost", verifier: "usage_cost", verifier_version: "1.0.0", evidence_type: "agent_trace", config: {} },
+    ],
+};
+/**
+ * Witnessed agent work: a deliverable requiring "witnesses" is accepted only when enough independent witnesses, as the
+ * terms' witness_policy sets, attested to the declared run. "review_bound" is the run-bound review (external_attestation@1.1.0).
+ * Witnesses may submit their attestations themselves.
+ */
+export const WITNESSED_AGENT_WORK_POLICY_V1 = {
+    ...CODE_CHANGE_POLICY_V1,
+    policy_id: "witnessed-agent-work",
+    policy_version: "1.0.0",
+    task_type: "agent_work",
+    description: "Agent work accepted when the required checks pass, including a quorum of independent witnesses to the declared run when a deliverable requires it.",
+    evidence_admissibility: { allowed_producers: ["counterparty", "verifier", "witness"], require_digest_match: true },
+    required_evidence: [],
+    checks: [
+        ...AGENT_USAGE_POLICY_V1.checks,
+        { check_id: "review_bound", verifier: "external_attestation", verifier_version: "1.1.0", evidence_type: "verifier_attestation", config: {} },
+        { check_id: "witnesses", verifier: "witness_quorum", verifier_version: "1.0.0", evidence_type: "witness_attestation", config: {} },
+    ],
+};
+export const REFERENCE_POLICIES = [CODE_CHANGE_POLICY_V1, CODE_CHANGE_POLICY_V1_1, CODE_CHANGE_SUBTASK_POLICY_V1, AGENT_USAGE_POLICY_V1, WITNESSED_AGENT_WORK_POLICY_V1];

package/dist/verdict.d.ts

@@ -0,0 +1,29 @@
+import { type ClearingDecision, type ClearingVerdictPayload, type ClosurePackage, type PublicKeyRecord } from "@atcn/schema";
+import { type CheckResult } from "./package.js";
+/** The obligation's decision in effect: the latest one that no other decision supersedes. */
+export declare function currentDecision(pkg: ClosurePackage, obligationId: string): ClearingDecision | null;
+/**
+ * The verdict payload for an obligation, read from its closure package. Sign it with the service key (signPayload).
+ * Throws when the package holds no decision for the obligation.
+ */
+export declare function buildClearingVerdict(pkg: ClosurePackage, options: {
+    obligationId?: string;
+    escrow?: {
+        rail: string;
+        escrow_ref: string;
+    } | null;
+    issuedAt: string;
+}): ClearingVerdictPayload;
+export interface VerdictVerificationReport {
+    valid: boolean;
+    checks: CheckResult[];
+}
+/**
+ * Offline verification of a clearing verdict: the service signature, and, given the closure package it names, that
+ * the package verifies and the verdict states the decision in effect in it. Without the package the decision is not
+ * compared with its evidence (reported as not inspected).
+ */
+export declare function verifyClearingVerdict(input: unknown, options: {
+    trustedKeys: PublicKeyRecord[];
+    closurePackage?: unknown;
+}): VerdictVerificationReport;

package/dist/verdict.js

@@ -0,0 +1,97 @@
+import { CLEARING_VERDICT_TYPE, ClearingVerdictSchema, digestOf, verifyPayload, } from "@atcn/schema";
+import { verifyClosurePackage } from "./package.js";
+import { SERVICE_ACTOR_ID } from "./service.js";
+/** The obligation's decision in effect: the latest one that no other decision supersedes. */
+export function currentDecision(pkg, obligationId) {
+    const decisions = pkg.payload.decisions.filter((d) => d.obligation_id === obligationId);
+    const superseded = new Set(decisions.map((d) => d.supersedes_decision_id).filter((id) => id !== null));
+    const current = decisions.filter((d) => !superseded.has(d.decision_id));
+    return current.reduce((latest, d) => (latest === null || d.decided_at > latest.decided_at ? d : latest), null);
+}
+function isFinal(decision) {
+    return decision.outcome !== "disputed" && decision.outcome !== "insufficient_evidence" && decision.disputed_amount_minor === 0 && decision.pending_amount_minor === 0;
+}
+/**
+ * The verdict payload for an obligation, read from its closure package. Sign it with the service key (signPayload).
+ * Throws when the package holds no decision for the obligation.
+ */
+export function buildClearingVerdict(pkg, options) {
+    const obligationId = options.obligationId ?? pkg.payload.requested_obligation_id;
+    const decision = currentDecision(pkg, obligationId);
+    if (!decision)
+        throw new Error(`obligation ${obligationId} has no clearing decision yet`);
+    return {
+        document_type: CLEARING_VERDICT_TYPE,
+        verdict_version: "1.0",
+        issued_at: new Date(options.issuedAt).toISOString(),
+        obligation_id: obligationId,
+        decision: {
+            decision_id: decision.decision_id,
+            decision_digest: decision.decision_digest,
+            decided_at: decision.decided_at,
+            outcome: decision.outcome,
+            currency: decision.currency,
+            accepted_amount_minor: decision.accepted_amount_minor,
+            rejected_amount_minor: decision.rejected_amount_minor,
+            disputed_amount_minor: decision.disputed_amount_minor,
+            pending_amount_minor: decision.pending_amount_minor,
+        },
+        final: isFinal(decision),
+        escrow: options.escrow ?? null,
+        package_digest: digestOf(pkg.payload),
+        stance: "record_only",
+    };
+}
+/**
+ * Offline verification of a clearing verdict: the service signature, and, given the closure package it names, that
+ * the package verifies and the verdict states the decision in effect in it. Without the package the decision is not
+ * compared with its evidence (reported as not inspected).
+ */
+export function verifyClearingVerdict(input, options) {
+    const parsed = ClearingVerdictSchema.safeParse(input);
+    if (!parsed.success) {
+        return { valid: false, checks: [{ name: "schema", ok: false, details: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`) }] };
+    }
+    const verdict = parsed.data;
+    const checks = [{ name: "schema", ok: true, details: [] }];
+    const serviceKey = options.trustedKeys.find((k) => k.key_id === verdict.signature.key_id && k.key_version === verdict.signature.key_version && k.actor_id === SERVICE_ACTOR_ID);
+    const keyValid = !!serviceKey && serviceKey.valid_from <= verdict.payload.issued_at && (serviceKey.revoked_at === null || serviceKey.revoked_at > verdict.payload.issued_at);
+    const signatureOk = keyValid && verifyPayload(verdict, serviceKey.public_key);
+    const signatureProblem = !serviceKey ? "service key not among trusted keys" : !keyValid ? "service key was not valid when the verdict was issued" : "signature does not verify";
+    checks.push({ name: "verdict_signature", ok: signatureOk, details: signatureOk ? [] : [signatureProblem] });
+    if (options.closurePackage === undefined) {
+        checks.push({ name: "decision", ok: true, state: "not_inspected", details: ["no closure package supplied; the decision was not compared with its evidence"] });
+        return { valid: checks.every((c) => c.ok), checks };
+    }
+    const packageReport = verifyClosurePackage(options.closurePackage, { trustedKeys: options.trustedKeys });
+    checks.push({ name: "closure_package", ok: packageReport.valid, details: packageReport.checks.filter((c) => !c.ok).map((c) => `${c.name}: ${c.details.join("; ")}`) });
+    if (!packageReport.valid)
+        return { valid: false, checks };
+    const pkg = options.closurePackage;
+    // Unknown members are not signed, so a valid package can still hold values canonical JSON refuses; such a package is not the one read.
+    let digestOk;
+    try {
+        digestOk = digestOf(pkg.payload) === verdict.payload.package_digest;
+    }
+    catch {
+        digestOk = false;
+    }
+    checks.push({ name: "package_digest", ok: digestOk, details: digestOk ? [] : ["the closure package is not the one the verdict was read from"] });
+    const decision = currentDecision(pkg, verdict.payload.obligation_id);
+    const decisionProblems = [];
+    if (!decision) {
+        decisionProblems.push(`the package holds no decision for ${verdict.payload.obligation_id}`);
+    }
+    else {
+        if (decision.decision_id !== verdict.payload.decision.decision_id)
+            decisionProblems.push(`the decision in effect is ${decision.decision_id}, not ${verdict.payload.decision.decision_id}`);
+        for (const field of Object.keys(verdict.payload.decision)) {
+            if (decision[field] !== verdict.payload.decision[field])
+                decisionProblems.push(`decision.${field} differs from the package`);
+        }
+        if (isFinal(decision) !== verdict.payload.final)
+            decisionProblems.push("final differs from the decision's amounts and outcome");
+    }
+    checks.push({ name: "decision", ok: decisionProblems.length === 0, details: decisionProblems });
+    return { valid: checks.every((c) => c.ok), checks };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@atcn/core",
-  "version": "1.4.0",
-  "description": "Deterministic ATCN logic: delegation bounds, clearing policy evaluation, allocation, journal balance, closure-package verification",
+  "version": "1.5.0",
+  "description": "ATCN obligations: policy decisions on submitted evidence, a balanced journal, and closure packages and clearing verdicts you can verify offline",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -32,6 +32,6 @@
     "build": "tsc -p tsconfig.build.json"
   },
   "dependencies": {
-    "@atcn/schema": "1.4.0"
+    "@atcn/schema": "1.5.0"
   }
 }