settld 0.1.2 → 0.1.5

package/scripts/demo/compositional-settlement-3hop.mjs

@@ -0,0 +1,237 @@
+import { canonicalJsonStringify } from "../../src/core/canonical-json.js";
+import { sha256Hex } from "../../src/core/crypto.js";
+import {
+  buildAgreementDelegationV1,
+  cascadeSettlementCheck,
+  refundUnwindCheck
+} from "../../src/core/agreement-delegation.js";
+import {
+  buildSettlementDecisionRecordV2,
+  buildSettlementReceiptV1,
+  verifySettlementKernelArtifacts
+} from "../../src/core/settlement-kernel.js";
+
+const tenantId = "tenant_demo_3hop";
+const currency = "USD";
+const createdAt = "2026-02-01T00:00:00.000Z";
+const settledAt = "2026-02-01T00:10:00.000Z";
+const refundedAt = "2026-02-01T00:20:00.000Z";
+
+const agreementA = sha256Hex("agreement:A");
+const agreementB = sha256Hex("agreement:B");
+const agreementC = sha256Hex("agreement:C");
+
+const delegationAB = buildAgreementDelegationV1({
+  delegationId: "dlg_ab_demo",
+  tenantId,
+  parentAgreementHash: agreementA,
+  childAgreementHash: agreementB,
+  delegatorAgentId: "agt_A",
+  delegateeAgentId: "agt_B",
+  budgetCapCents: 20_000,
+  currency,
+  delegationDepth: 1,
+  maxDelegationDepth: 3,
+  ancestorChain: [agreementA],
+  createdAt
+});
+
+const delegationBC = buildAgreementDelegationV1({
+  delegationId: "dlg_bc_demo",
+  tenantId,
+  parentAgreementHash: agreementB,
+  childAgreementHash: agreementC,
+  delegatorAgentId: "agt_B",
+  delegateeAgentId: "agt_C",
+  budgetCapCents: 15_000,
+  currency,
+  delegationDepth: 2,
+  maxDelegationDepth: 3,
+  ancestorChain: [agreementA, agreementB],
+  createdAt
+});
+
+const settlePlan = cascadeSettlementCheck({
+  delegations: [delegationAB, delegationBC],
+  fromChildHash: agreementC
+});
+
+const unwindPlan = refundUnwindCheck({
+  delegations: [delegationAB, delegationBC],
+  fromParentHash: agreementA
+});
+
+const grossRevenueCents = 10_000;
+const cToBCents = 3_500;
+const bToACents = 1_200;
+const unwindRefundCents = 900;
+
+const settlePayouts = {
+  agt_A: bToACents,
+  agt_B: cToBCents - bToACents,
+  agt_C: grossRevenueCents - cToBCents
+};
+
+const unwindRefunds = {
+  agt_A: unwindRefundCents,
+  agt_B: unwindRefundCents,
+  agt_C: unwindRefundCents
+};
+
+const finalPayouts = {
+  agt_A: settlePayouts.agt_A - unwindRefundCents,
+  agt_B: settlePayouts.agt_B - unwindRefundCents,
+  agt_C: settlePayouts.agt_C - unwindRefundCents
+};
+
+const settlementSettle = {
+  runId: "run_demo_3hop_settle",
+  settlementId: "setl_demo_3hop_settle",
+  status: "released",
+  decisionTrace: {}
+};
+
+const settleDecision = buildSettlementDecisionRecordV2({
+  decisionId: "dec_demo_3hop_settle",
+  tenantId,
+  runId: settlementSettle.runId,
+  settlementId: settlementSettle.settlementId,
+  agreementId: agreementC,
+  decisionStatus: "auto_resolved",
+  decisionMode: "automatic",
+  verificationStatus: "green",
+  policyHashUsed: "1".repeat(64),
+  verificationMethodHashUsed: "2".repeat(64),
+  policyRef: {
+    policyHash: "1".repeat(64),
+    verificationMethodHash: "2".repeat(64)
+  },
+  verifierRef: {
+    verifierId: "settld.demo",
+    verifierVersion: "v1",
+    verifierHash: "3".repeat(64),
+    modality: "deterministic"
+  },
+  runStatus: "completed",
+  runLastEventId: "ev_demo_3hop_settle",
+  runLastChainHash: "4".repeat(64),
+  resolutionEventId: "res_demo_3hop_settle",
+  decidedAt: settledAt
+});
+
+const settleReceipt = buildSettlementReceiptV1({
+  receiptId: "rcpt_demo_3hop_settle",
+  tenantId,
+  runId: settlementSettle.runId,
+  settlementId: settlementSettle.settlementId,
+  decisionRecord: settleDecision,
+  status: "released",
+  amountCents: grossRevenueCents,
+  releasedAmountCents: grossRevenueCents,
+  refundedAmountCents: 0,
+  releaseRatePct: 100,
+  currency,
+  runStatus: "completed",
+  resolutionEventId: "res_demo_3hop_settle",
+  settledAt,
+  createdAt: settledAt
+});
+settlementSettle.decisionTrace = { decisionRecord: settleDecision, settlementReceipt: settleReceipt };
+const settleVerification = verifySettlementKernelArtifacts({ settlement: settlementSettle, runId: settlementSettle.runId });
+
+const settlementUnwind = {
+  runId: "run_demo_3hop_unwind",
+  settlementId: "setl_demo_3hop_unwind",
+  status: "refunded",
+  decisionTrace: {}
+};
+
+const unwindDecision = buildSettlementDecisionRecordV2({
+  decisionId: "dec_demo_3hop_unwind",
+  tenantId,
+  runId: settlementUnwind.runId,
+  settlementId: settlementUnwind.settlementId,
+  agreementId: agreementA,
+  decisionStatus: "auto_resolved",
+  decisionMode: "automatic",
+  decisionReason: "refund_unwind",
+  verificationStatus: "green",
+  policyHashUsed: "5".repeat(64),
+  verificationMethodHashUsed: "6".repeat(64),
+  policyRef: {
+    policyHash: "5".repeat(64),
+    verificationMethodHash: "6".repeat(64)
+  },
+  verifierRef: {
+    verifierId: "settld.demo",
+    verifierVersion: "v1",
+    verifierHash: "7".repeat(64),
+    modality: "deterministic"
+  },
+  runStatus: "completed",
+  runLastEventId: "ev_demo_3hop_unwind",
+  runLastChainHash: "8".repeat(64),
+  resolutionEventId: "res_demo_3hop_unwind",
+  decidedAt: refundedAt
+});
+
+const unwindReceipt = buildSettlementReceiptV1({
+  receiptId: "rcpt_demo_3hop_unwind",
+  tenantId,
+  runId: settlementUnwind.runId,
+  settlementId: settlementUnwind.settlementId,
+  decisionRecord: unwindDecision,
+  status: "refunded",
+  amountCents: unwindRefundCents,
+  releasedAmountCents: 0,
+  refundedAmountCents: unwindRefundCents,
+  releaseRatePct: 0,
+  currency,
+  runStatus: "completed",
+  resolutionEventId: "res_demo_3hop_unwind",
+  settledAt: refundedAt,
+  createdAt: refundedAt
+});
+settlementUnwind.decisionTrace = { decisionRecord: unwindDecision, settlementReceipt: unwindReceipt };
+const unwindVerification = verifySettlementKernelArtifacts({ settlement: settlementUnwind, runId: settlementUnwind.runId });
+
+const lineage = {
+  rootAgreementHash: agreementA,
+  chain: [agreementA, agreementB, agreementC],
+  delegationHashes: [delegationAB.delegationHash, delegationBC.delegationHash],
+  settleParentAgreementHashes: settlePlan.parentAgreementHashes,
+  unwindChildAgreementHashes: unwindPlan.childAgreementHashes
+};
+
+const report = {
+  schemaVersion: "CompositionalSettlementDemo.v1",
+  tenantId,
+  createdAt,
+  lineage,
+  decisionHashes: {
+    settle: settleDecision.decisionHash,
+    unwind: unwindDecision.decisionHash
+  },
+  receiptHashes: {
+    settle: settleReceipt.receiptHash,
+    unwind: unwindReceipt.receiptHash
+  },
+  settlePayouts,
+  finalRefunds: unwindRefunds,
+  finalPayouts,
+  verification: {
+    settle: settleVerification.valid === true,
+    unwind: unwindVerification.valid === true
+  }
+};
+
+const reportJson = canonicalJsonStringify(report);
+const reportHash = sha256Hex(reportJson);
+
+console.log(`[demo] lineage: ${agreementA.slice(0, 10)} -> ${agreementB.slice(0, 10)} -> ${agreementC.slice(0, 10)}`);
+console.log(`[demo] settle decisionHash=${settleDecision.decisionHash}`);
+console.log(`[demo] unwind decisionHash=${unwindDecision.decisionHash}`);
+console.log(`[demo] final payouts cents=${JSON.stringify(finalPayouts)}`);
+console.log(`[demo] final refunds cents=${JSON.stringify(unwindRefunds)}`);
+console.log(`REPORT_JSON:${reportJson}`);
+console.log(`PASS demo=compositional-settlement-3hop reportHash=${reportHash}`);

package/scripts/demo/delivery-robot/export-ui-fixture.mjs

@@ -0,0 +1,188 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+async function exists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function copyFile(src, dst) {
+  await fs.mkdir(path.dirname(dst), { recursive: true });
+  await fs.copyFile(src, dst);
+}
+
+async function listFiles(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  return entries.filter((e) => e.isFile()).map((e) => e.name);
+}
+
+async function listDirs(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  return entries.filter((e) => e.isDirectory()).map((e) => e.name);
+}
+
+async function latestFinancePackBundleZip() {
+  const bundlesDir = path.resolve("demo/finance-pack/bundles");
+  if (!(await exists(bundlesDir))) return null;
+  const files = (await listFiles(bundlesDir)).filter((f) => f.endsWith(".zip")).sort();
+  return files.length ? path.join(bundlesDir, files[files.length - 1]) : null;
+}
+
+async function exportHistory({ srcRoot, dstRoot, requiredFiles, limit }) {
+  if (!(await exists(srcRoot))) return { copiedRuns: [], skipped: "missing_src_root" };
+
+  const runDirs = (await listDirs(srcRoot))
+    .filter((d) => d !== "latest")
+    .sort()
+    .slice(-limit);
+
+  const copiedRuns = [];
+  for (const runId of runDirs) {
+    const srcDir = path.join(srcRoot, runId);
+    const dstDir = path.join(dstRoot, runId);
+    const copied = [];
+    for (const f of requiredFiles) {
+      const src = path.join(srcDir, f);
+      if (!(await exists(src))) continue;
+      await copyFile(src, path.join(dstDir, f));
+      copied.push(f);
+    }
+    if (copied.length) copiedRuns.push({ runId, copied });
+  }
+
+  const index = { copiedRuns, latestRunId: copiedRuns.at(-1)?.runId ?? null };
+  await fs.mkdir(dstRoot, { recursive: true });
+  await fs.writeFile(path.join(dstRoot, "index.json"), JSON.stringify(index, null, 2) + "\n", "utf8");
+  return index;
+}
+
+async function main() {
+  const deliverySrcDir = path.resolve("demo/delivery-robot/output/latest");
+  const deliveryDstDirLegacy = path.resolve("dashboard/public/demo/latest");
+  const deliveryDstDir = path.resolve("dashboard/public/demo/delivery/latest");
+  const financeSrcDir = path.resolve("demo/finance-pack/output/latest");
+  const financeDstDir = path.resolve("dashboard/public/demo/finance/latest");
+
+  if (!(await exists(deliverySrcDir))) {
+    throw new Error(`missing demo output: ${deliverySrcDir}. Run \`npm run demo:delivery\` first.`);
+  }
+
+  const files = [
+    "run.json",
+    "sample_ingest_request.json",
+    "sample_ingest_response.json",
+    "timeline.json",
+    "WorkCertificate.v1.json",
+    "SettlementStatement.v1.json",
+    "CreditMemo.v1.json"
+  ];
+
+  const copiedDelivery = [];
+  for (const f of files) {
+    const src = path.join(deliverySrcDir, f);
+    if (!(await exists(src))) continue;
+    await copyFile(src, path.join(deliveryDstDirLegacy, f));
+    await copyFile(src, path.join(deliveryDstDir, f));
+    copiedDelivery.push(f);
+  }
+
+  await fs.writeFile(path.join(deliveryDstDirLegacy, "index.json"), JSON.stringify({ copied: copiedDelivery }, null, 2) + "\n", "utf8");
+  await fs.writeFile(path.join(deliveryDstDir, "index.json"), JSON.stringify({ copied: copiedDelivery }, null, 2) + "\n", "utf8");
+
+  // Delivery history (to support “fleet playback” demos).
+  const deliveryHistory = await exportHistory({
+    srcRoot: path.resolve("demo/delivery-robot/output"),
+    dstRoot: path.resolve("dashboard/public/demo/delivery/history"),
+    requiredFiles: ["run.json", "timeline.json", "WorkCertificate.v1.json", "SettlementStatement.v1.json", "CreditMemo.v1.json"],
+    limit: 6
+  });
+
+  // Finance pack fixture (optional, but enables a “finance demo” button).
+  const copiedFinance = [];
+  let financeHistory = null;
+  if (await exists(financeSrcDir)) {
+    const financeFiles = [
+      "run.json",
+      "steps.json",
+      "WorkCertificate.v1.json",
+      "SettlementStatement.v1.json",
+      "CreditMemo.v1.json",
+      "GLBatch.v1.json",
+      "GLBatch.v1.csv",
+      "JournalCsv.v1.json",
+      "JournalCsv.v1.csv",
+      "JobProofBundle.v1.zip",
+      "MonthProofBundle.v1.zip"
+    ];
+
+    for (const f of financeFiles) {
+      const src = path.join(financeSrcDir, f);
+      if (!(await exists(src))) continue;
+      await copyFile(src, path.join(financeDstDir, f));
+      copiedFinance.push(f);
+    }
+
+    const financePackZip = await latestFinancePackBundleZip();
+    if (financePackZip) {
+      await copyFile(financePackZip, path.join(financeDstDir, "FinancePackBundle.v1.zip"));
+      copiedFinance.push("FinancePackBundle.v1.zip");
+
+      // Best-effort: also copy reconcile.json from the unpacked bundle (if present).
+      const unpackedDir = financePackZip.replace(/\.zip$/i, "");
+      const reconcile = path.join(unpackedDir, "finance", "reconcile.json");
+      if (await exists(reconcile)) {
+        await copyFile(reconcile, path.join(financeDstDir, "reconcile.json"));
+        copiedFinance.push("reconcile.json");
+      }
+    }
+
+    await fs.writeFile(path.join(financeDstDir, "index.json"), JSON.stringify({ copied: copiedFinance }, null, 2) + "\n", "utf8");
+
+    financeHistory = await exportHistory({
+      srcRoot: path.resolve("demo/finance-pack/output"),
+      dstRoot: path.resolve("dashboard/public/demo/finance/history"),
+      requiredFiles: ["run.json", "steps.json", "WorkCertificate.v1.json", "SettlementStatement.v1.json", "GLBatch.v1.json", "JournalCsv.v1.csv"],
+      limit: 4
+    });
+  }
+
+  // Root index for UI scenario picker.
+  const index = {
+    generatedAt: new Date().toISOString(),
+    history: {
+      delivery: { runs: deliveryHistory?.copiedRuns?.length ?? 0, latestRunId: deliveryHistory?.latestRunId ?? null },
+      finance: { runs: financeHistory?.copiedRuns?.length ?? 0, latestRunId: financeHistory?.latestRunId ?? null }
+    },
+    scenarios: [
+      {
+        id: "delivery",
+        title: "SLA Credit (Delivery)",
+        subtitle: "Facts in → breach → CreditMemo + SettlementStatement",
+        emoji: "🚚"
+      },
+      {
+        id: "finance",
+        title: "Finance Pack (Month Close)",
+        subtitle: "Statements → GLBatch + JournalCsv + bundles",
+        emoji: "📚",
+        available: copiedFinance.length > 0
+      }
+    ]
+  };
+  const rootIndexPath = path.resolve("dashboard/public/demo/index.json");
+  await fs.mkdir(path.dirname(rootIndexPath), { recursive: true });
+  await fs.writeFile(rootIndexPath, JSON.stringify(index, null, 2) + "\n", "utf8");
+
+  process.stdout.write(`Exported delivery fixture to dashboard/public/demo/delivery/latest (and legacy demo/latest)\n`);
+  if (copiedFinance.length) process.stdout.write(`Exported finance fixture to dashboard/public/demo/finance/latest\n`);
+  process.stdout.write(`Wrote dashboard/public/demo/index.json\n`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exitCode = 1;
+});