@atcn/core 0.0.0-stage → 1.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,16 @@
-# Temporary Holding Version
+# @atcn/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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`).
+
+```bash
+npm install @atcn/core
+```
+
+```ts
+import { verifyClosurePackage } from "@atcn/core";
+
+const report = verifyClosurePackage(closurePackage, { trustedKeys });
+console.log(report.valid, report.checks);
+```
+
+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.

package/dist/allocation.d.ts

@@ -0,0 +1,16 @@
+export interface Share {
+    key: string;
+    weight: number;
+}
+export interface AllocationResult {
+    amounts: Record<string, number>;
+    method: "largest_remainder";
+    /** Human-readable record of how remainders were distributed (LJ-7). */
+    detail: string;
+}
+/**
+ * Splits an integer amount by integer weights using the largest-remainder method.
+ * Ties on the remainder are broken by key in ascending order, so the result is
+ * deterministic and always sums exactly to `total`.
+ */
+export declare function allocateLargestRemainder(total: number, shares: Share[]): AllocationResult;

package/dist/allocation.js

@@ -0,0 +1,32 @@
+/**
+ * Splits an integer amount by integer weights using the largest-remainder method.
+ * Ties on the remainder are broken by key in ascending order, so the result is
+ * deterministic and always sums exactly to `total`.
+ */
+export function allocateLargestRemainder(total, shares) {
+    if (!Number.isSafeInteger(total) || total < 0)
+        throw new Error("total must be a non-negative safe integer");
+    const weightSum = shares.reduce((sum, s) => sum + s.weight, 0);
+    if (weightSum <= 0)
+        throw new Error("weights must sum to a positive number");
+    const rows = shares.map((share) => {
+        const exactNumerator = total * share.weight;
+        const floor = Math.floor(exactNumerator / weightSum);
+        const remainder = exactNumerator - floor * weightSum;
+        return { key: share.key, floor, remainder };
+    });
+    let leftover = total - rows.reduce((sum, r) => sum + r.floor, 0);
+    const order = [...rows].sort((a, b) => b.remainder - a.remainder || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+    const bonus = {};
+    for (const row of order) {
+        if (leftover === 0)
+            break;
+        bonus[row.key] = 1;
+        leftover -= 1;
+    }
+    const amounts = {};
+    for (const row of rows)
+        amounts[row.key] = row.floor + (bonus[row.key] ?? 0);
+    const remainderNotes = rows.map((r) => `${r.key}=${r.floor}+${bonus[r.key] ?? 0}(rem ${r.remainder}/${weightSum})`);
+    return { amounts, method: "largest_remainder", detail: `total=${total}; ${remainderNotes.join("; ")}` };
+}

package/dist/clearing.d.ts

@@ -0,0 +1,46 @@
+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";
+/** The service event that records each decision outcome. */
+export declare const OUTCOME_EVENT: Record<ClearingOutcome, EventType>;
+export type ProducerRole = "issuer" | "counterparty" | "verifier" | "other";
+export interface EvidenceInput {
+    envelope: EvidenceEnvelope;
+    event_id: string;
+    producer_role: ProducerRole;
+    superseded: boolean;
+}
+export interface ClearingInput {
+    terms: ObligationTerms;
+    terms_digest: string;
+    policy: PolicyTemplate;
+    policy_digest: string;
+    acceptance_event_id: string;
+    completion_event_id: string | null;
+    evidence: EvidenceInput[];
+    verifier_results: VerifierResult[];
+    decision_maker?: {
+        type: "automated" | "human";
+        id: string;
+    };
+}
+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;
+export interface CheckPlanItem {
+    deliverable_id: string;
+    check: PolicyCheck;
+    evidence: EvidenceInput | null;
+}
+/** Which verifier runs are needed for an evaluation: one per (deliverable, required check). */
+export declare function planChecks(input: Pick<ClearingInput, "terms" | "policy" | "evidence">): CheckPlanItem[];
+/** Digest of a verifier result over its immutable fields (execution time excluded). */
+export declare function verifierOutputDigest(result: VerifierResult): string;
+/** Decision digest (CL-5): covers inputs and outcome; excludes ids and timestamps. */
+export declare function decisionDigest(body: DecisionBody): string;
+/** Role of an evidence producer, derived only from the signed terms. */
+export declare function producerRole(terms: ObligationTerms, producerId: string): ProducerRole;
+/**
+ * Deterministic clearing (CL-2 .. CL-7). Pure function of the accepted terms, the
+ * policy version, admissible evidence metadata, and recorded verifier results.
+ */
+export declare function evaluateClearing(input: ClearingInput): DecisionBody;

package/dist/clearing.js

@@ -0,0 +1,221 @@
+import { digestOf, } from "@atcn/schema";
+export const CLEARING_ENGINE_ID = "atcn-clearing-engine@1.0.0";
+/** The service event that records each decision outcome. */
+export const OUTCOME_EVENT = {
+    accepted: "completion.accepted",
+    partially_accepted: "completion.partially_accepted",
+    rejected: "completion.rejected",
+    insufficient_evidence: "completion.insufficient_evidence",
+    disputed: "completion.disputed",
+    cancelled: "obligation.cancelled",
+    expired: "obligation.expired",
+};
+export function isAdmissible(evidence, policy) {
+    if (evidence.superseded)
+        return false;
+    return policy.evidence_admissibility.allowed_producers.includes(evidence.producer_role);
+}
+function covers(envelope, deliverableId) {
+    return envelope.deliverable_ids.length === 0 || envelope.deliverable_ids.includes(deliverableId);
+}
+/** Latest admissible evidence of a type covering a deliverable (ordered by created_at, then evidence_id). */
+export function selectEvidence(evidence, policy, evidenceType, deliverableId) {
+    const candidates = 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;
+    });
+    return candidates[0] ?? null;
+}
+/** Which verifier runs are needed for an evaluation: one per (deliverable, required check). */
+export function planChecks(input) {
+    const plan = [];
+    for (const deliverable of input.terms.deliverables) {
+        for (const checkId of deliverable.required_checks) {
+            const check = input.policy.checks.find((c) => c.check_id === checkId);
+            if (!check)
+                continue;
+            plan.push({
+                deliverable_id: deliverable.deliverable_id,
+                check,
+                evidence: selectEvidence(input.evidence, input.policy, check.evidence_type, deliverable.deliverable_id),
+            });
+        }
+    }
+    return plan;
+}
+/** Digest of a verifier result over its immutable fields (execution time excluded). */
+export function verifierOutputDigest(result) {
+    const { executed_at: _executedAt, result_id: _resultId, ...stable } = result;
+    return digestOf(stable);
+}
+/** Decision digest (CL-5): covers inputs and outcome; excludes ids and timestamps. */
+export function decisionDigest(body) {
+    return digestOf(body);
+}
+function sortResultsNewestFirst(results) {
+    return [...results].sort((a, b) => {
+        if (a.executed_at !== b.executed_at)
+            return a.executed_at < b.executed_at ? 1 : -1;
+        return a.result_id < b.result_id ? 1 : -1;
+    });
+}
+/** Role of an evidence producer, derived only from the signed terms. */
+export function producerRole(terms, producerId) {
+    if (producerId === terms.issuer_agent_id || producerId === terms.principal_id)
+        return "issuer";
+    if (producerId === terms.counterparty_agent_id)
+        return "counterparty";
+    if (terms.verifier_agent_ids.includes(producerId))
+        return "verifier";
+    return "other";
+}
+/**
+ * Deterministic clearing (CL-2 .. CL-7). Pure function of the accepted terms, the
+ * policy version, admissible evidence metadata, and recorded verifier results.
+ */
+export function evaluateClearing(input) {
+    const { terms, policy } = input;
+    const usedEvidence = new Map();
+    const usedResults = new Map();
+    const deliverableOutcomes = [];
+    for (const deliverable of terms.deliverables) {
+        const reasons = [];
+        const verdicts = [];
+        for (const evidenceType of policy.required_evidence) {
+            const found = selectEvidence(input.evidence, policy, evidenceType, deliverable.deliverable_id);
+            if (!found) {
+                reasons.push({ code: "missing_evidence", evidence_type: evidenceType });
+                verdicts.push("insufficient_evidence");
+            }
+            else {
+                usedEvidence.set(found.envelope.evidence_id, found);
+            }
+        }
+        for (const checkId of deliverable.required_checks) {
+            const check = policy.checks.find((c) => c.check_id === checkId);
+            if (!check) {
+                reasons.push({ code: "verifier_unavailable", check_id: checkId, detail: "check not defined by policy" });
+                verdicts.push(policy.verifier_unavailable_outcome);
+                continue;
+            }
+            const evidence = selectEvidence(input.evidence, policy, check.evidence_type, deliverable.deliverable_id);
+            if (!evidence) {
+                reasons.push({ code: "missing_evidence", check_id: checkId, evidence_type: check.evidence_type });
+                verdicts.push("insufficient_evidence");
+                continue;
+            }
+            usedEvidence.set(evidence.envelope.evidence_id, evidence);
+            const results = sortResultsNewestFirst(input.verifier_results).filter((r) => r.check_id === checkId &&
+                r.deliverable_id === deliverable.deliverable_id &&
+                r.evidence_ids.includes(evidence.envelope.evidence_id) &&
+                r.verifier_name === check.verifier &&
+                r.verifier_version === check.verifier_version);
+            const deterministic = results.find((r) => r.kind === "deterministic");
+            const probabilistic = results.find((r) => r.kind === "probabilistic");
+            const result = deterministic ?? probabilistic;
+            if (!result) {
+                reasons.push({ code: "verifier_unavailable", check_id: checkId, detail: "no verifier result recorded" });
+                verdicts.push(policy.verifier_unavailable_outcome);
+                continue;
+            }
+            usedResults.set(verifierOutputDigest(result), result);
+            if (result.status === "missing_evidence") {
+                reasons.push({ code: "missing_evidence", check_id: checkId, evidence_type: check.evidence_type });
+                verdicts.push("insufficient_evidence");
+            }
+            else if (result.status === "invalid_evidence") {
+                reasons.push({ code: "invalid_evidence", check_id: checkId, evidence_type: check.evidence_type });
+                verdicts.push("insufficient_evidence");
+            }
+            else if (result.status === "unavailable") {
+                reasons.push({ code: "verifier_unavailable", check_id: checkId });
+                verdicts.push(policy.verifier_unavailable_outcome);
+            }
+            else if (result.kind === "probabilistic") {
+                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") {
+                reasons.push({ code: "failed_criteria", check_id: checkId });
+                verdicts.push("rejected");
+            }
+            else {
+                reasons.push({ code: "passed", check_id: checkId });
+                verdicts.push("accepted");
+            }
+        }
+        deliverableOutcomes.push({
+            deliverable_id: deliverable.deliverable_id,
+            amount_minor: deliverable.amount_minor,
+            outcome: combineVerdicts(verdicts),
+            reasons,
+        });
+    }
+    const outcome = overallOutcome(deliverableOutcomes, policy);
+    applyPortionPolicy(deliverableOutcomes, outcome, policy);
+    const sumBy = (verdict) => deliverableOutcomes.filter((d) => d.outcome === verdict).reduce((sum, d) => sum + d.amount_minor, 0);
+    const inputEventIds = new Set([input.acceptance_event_id]);
+    if (input.completion_event_id)
+        inputEventIds.add(input.completion_event_id);
+    for (const e of usedEvidence.values())
+        inputEventIds.add(e.event_id);
+    return {
+        obligation_id: terms.obligation_id,
+        terms_version: terms.terms_version,
+        terms_digest: input.terms_digest,
+        policy: { policy_id: policy.policy_id, policy_version: policy.policy_version, policy_digest: input.policy_digest },
+        outcome,
+        currency: terms.currency,
+        accepted_amount_minor: outcome === "insufficient_evidence" ? 0 : sumBy("accepted"),
+        rejected_amount_minor: sumBy("rejected"),
+        disputed_amount_minor: sumBy("disputed"),
+        pending_amount_minor: sumBy("insufficient_evidence") + (outcome === "insufficient_evidence" ? sumBy("accepted") : 0),
+        deliverable_outcomes: deliverableOutcomes,
+        input_event_ids: [...inputEventIds].sort(),
+        evidence_digests: [...new Set([...usedEvidence.values()].map((e) => e.envelope.content_digest))].sort(),
+        verifier_output_digests: [...usedResults.keys()].sort(),
+        decision_maker: input.decision_maker ?? { type: "automated", id: CLEARING_ENGINE_ID },
+    };
+}
+/** Worst verdict wins: insufficient_evidence > disputed > rejected > accepted. */
+function combineVerdicts(verdicts) {
+    if (verdicts.includes("insufficient_evidence"))
+        return "insufficient_evidence";
+    if (verdicts.includes("disputed"))
+        return "disputed";
+    if (verdicts.includes("rejected"))
+        return "rejected";
+    return "accepted";
+}
+function overallOutcome(outcomes, policy) {
+    const has = (v) => outcomes.some((d) => d.outcome === v);
+    const all = (v) => outcomes.every((d) => d.outcome === v);
+    if (has("insufficient_evidence"))
+        return "insufficient_evidence";
+    if (all("accepted"))
+        return "accepted";
+    if (has("disputed") && !has("accepted"))
+        return "disputed";
+    if (!has("accepted"))
+        return "rejected";
+    if (!policy.thresholds.partial_acceptance)
+        return "rejected";
+    if (has("disputed"))
+        return "disputed";
+    return "partially_accepted";
+}
+/** Applies failed-portion handling and the all-or-nothing rule after the overall outcome is known. */
+function applyPortionPolicy(outcomes, outcome, policy) {
+    for (const d of outcomes) {
+        if (outcome === "rejected" && d.outcome === "accepted") {
+            d.outcome = "rejected";
+            d.reasons.push({ code: "partial_not_permitted" });
+        }
+        if (outcome === "partially_accepted" && d.outcome === "rejected" && policy.thresholds.failed_portion_outcome === "disputed") {
+            d.outcome = "disputed";
+        }
+    }
+}

package/dist/delegation.d.ts

@@ -0,0 +1,30 @@
+import type { ObligationTerms } from "@atcn/schema";
+/** The amount both parties agree to on acceptance: the sum of the deliverables' amounts. */
+export declare function agreedAmount(terms: ObligationTerms): number;
+export interface ParentContext {
+    terms: ObligationTerms;
+    state: string;
+    /** Depth of the parent in its tree; root = 0. */
+    depth: number;
+    /** Subdelegation depth still permitted below the parent's own issuer chain (null = unlimited by ancestors). */
+    inheritedMaxDepth: number | null;
+    /** Sum of max_amount_minor of the parent's existing exposure-holding children (excluding the child being checked). */
+    committedChildExposureMinor: number;
+    /** Obligation ids from the parent up to the root, parent first. */
+    ancestorIds: string[];
+}
+export interface DelegationViolation {
+    code: "subdelegation_not_allowed" | "exceeds_remaining_exposure" | "exceeds_subdelegation_total" | "depth_exceeded" | "currency_mismatch" | "deadline_exceeds_parent" | "principal_mismatch" | "issuer_must_be_parent_counterparty" | "payer_must_be_parent_counterparty" | "policy_not_permitted" | "cycle_detected" | "parent_not_active";
+    message: string;
+}
+/** Remaining authorized exposure for new children (OB-3). */
+export declare function remainingExposure(parent: ParentContext): number;
+/**
+ * Checks a proposed child obligation against its parent (OB-2, OB-3, OB-5, OB-7).
+ * Returns every violation found; an empty list means the child is within bounds.
+ */
+export declare function checkChildAgainstParent(parent: ParentContext, child: ObligationTerms): DelegationViolation[];
+/** Depth budget a child inherits from its parent chain. */
+export declare function inheritedDepthForChild(parent: ParentContext): number;
+/** Generic cycle check over parent links (OB-7). */
+export declare function hasCycle(parentOf: Map<string, string | null>): boolean;

package/dist/delegation.js

@@ -0,0 +1,87 @@
+/** The amount both parties agree to on acceptance: the sum of the deliverables' amounts. */
+export function agreedAmount(terms) {
+    return terms.deliverables.reduce((sum, d) => sum + d.amount_minor, 0);
+}
+const PARENT_STATES_ALLOWING_DELEGATION = ["accepted", "active"];
+/** Remaining authorized exposure for new children (OB-3). */
+export function remainingExposure(parent) {
+    const ceiling = Math.min(parent.terms.max_amount_minor, parent.terms.subdelegation_limits?.max_total_minor ?? parent.terms.max_amount_minor);
+    return Math.max(0, ceiling - parent.committedChildExposureMinor);
+}
+/**
+ * Checks a proposed child obligation against its parent (OB-2, OB-3, OB-5, OB-7).
+ * Returns every violation found; an empty list means the child is within bounds.
+ */
+export function checkChildAgainstParent(parent, child) {
+    const violations = [];
+    const p = parent.terms;
+    if (child.obligation_id === p.obligation_id || parent.ancestorIds.includes(child.obligation_id)) {
+        violations.push({ code: "cycle_detected", message: "child obligation id already appears in the parent chain" });
+    }
+    if (!PARENT_STATES_ALLOWING_DELEGATION.includes(parent.state)) {
+        violations.push({ code: "parent_not_active", message: `parent is ${parent.state}; delegation requires accepted or active` });
+    }
+    if (!p.allow_subdelegation || !p.subdelegation_limits) {
+        violations.push({ code: "subdelegation_not_allowed", message: "parent obligation does not permit subdelegation" });
+        return violations;
+    }
+    if (child.issuer_agent_id !== p.counterparty_agent_id) {
+        violations.push({ code: "issuer_must_be_parent_counterparty", message: "only the parent's counterparty may delegate" });
+    }
+    if (child.payer_id !== p.counterparty_agent_id) {
+        violations.push({ code: "payer_must_be_parent_counterparty", message: "the delegating agent pays for the child" });
+    }
+    if (child.principal_id !== p.principal_id) {
+        violations.push({ code: "principal_mismatch", message: "child must carry the root principal" });
+    }
+    if (child.currency !== p.currency) {
+        violations.push({ code: "currency_mismatch", message: `child currency ${child.currency} differs from parent ${p.currency}` });
+    }
+    if (Date.parse(child.deadline) > Date.parse(p.deadline)) {
+        violations.push({ code: "deadline_exceeds_parent", message: "child deadline is later than parent deadline" });
+    }
+    const remaining = remainingExposure(parent);
+    if (child.max_amount_minor > remaining) {
+        violations.push({
+            code: "exceeds_remaining_exposure",
+            message: `child max_amount_minor ${child.max_amount_minor} exceeds parent's remaining authorized exposure ${remaining}`,
+        });
+    }
+    const allowedPolicies = [p.acceptance_policy.policy_id, ...p.subdelegation_limits.allowed_policy_ids];
+    if (!allowedPolicies.includes(child.acceptance_policy.policy_id)) {
+        violations.push({ code: "policy_not_permitted", message: `policy ${child.acceptance_policy.policy_id} is not permitted by the parent` });
+    }
+    const depthBudget = Math.min(p.subdelegation_limits.max_depth, parent.inheritedMaxDepth ?? Number.MAX_SAFE_INTEGER);
+    if (depthBudget < 1) {
+        violations.push({ code: "depth_exceeded", message: "no subdelegation depth remains" });
+    }
+    else if (child.allow_subdelegation) {
+        const childDepth = child.subdelegation_limits?.max_depth ?? 0;
+        if (childDepth > depthBudget - 1) {
+            violations.push({ code: "depth_exceeded", message: `child may subdelegate at most ${depthBudget - 1} further level(s)` });
+        }
+        if ((child.subdelegation_limits?.max_total_minor ?? 0) > child.max_amount_minor) {
+            violations.push({ code: "exceeds_subdelegation_total", message: "child subdelegation total exceeds its own ceiling" });
+        }
+    }
+    return violations;
+}
+/** Depth budget a child inherits from its parent chain. */
+export function inheritedDepthForChild(parent) {
+    const own = parent.terms.subdelegation_limits?.max_depth ?? 0;
+    return Math.min(own, parent.inheritedMaxDepth ?? Number.MAX_SAFE_INTEGER) - 1;
+}
+/** Generic cycle check over parent links (OB-7). */
+export function hasCycle(parentOf) {
+    for (const start of parentOf.keys()) {
+        const seen = new Set();
+        let current = start;
+        while (current) {
+            if (seen.has(current))
+                return true;
+            seen.add(current);
+            current = parentOf.get(current) ?? null;
+        }
+    }
+    return false;
+}