settld 0.1.2 → 0.2.0

package/scripts/examples/sdk-first-verified-run.py

@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import random
+import sys
+import time
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "packages" / "api-sdk-python"))
+
+from settld_api_sdk import SettldClient  # noqa: E402
+
+
+def _unique_suffix() -> str:
+    return f"{int(time.time() * 1000):x}_{random.randint(0, 0xFFFFFF):06x}"
+
+
+def _fixture_keys() -> tuple[str, str]:
+    fixture_path = REPO_ROOT / "test" / "fixtures" / "keys" / "fixture_keypairs.json"
+    with fixture_path.open("r", encoding="utf-8") as fp:
+        raw = json.load(fp)
+    payee = str(raw["serverA"]["publicKeyPem"])
+    payer = str(raw["serverB"]["publicKeyPem"])
+    return payee, payer
+
+
+def main() -> int:
+    base_url = os.environ.get("SETTLD_BASE_URL", "http://127.0.0.1:3000")
+    tenant_id = os.environ.get("SETTLD_TENANT_ID", "tenant_default")
+    api_key = os.environ.get("SETTLD_API_KEY")
+
+    if not api_key:
+        print("SETTLD_API_KEY is not set; calls will fail unless API auth is disabled.", file=sys.stderr)
+
+    payee_public_key_pem, payer_public_key_pem = _fixture_keys()
+    suffix = _unique_suffix()
+    run_id = f"run_sdk_py_{suffix}"
+
+    client = SettldClient(
+        base_url=base_url,
+        tenant_id=tenant_id,
+        api_key=api_key,
+    )
+
+    result = client.first_verified_run(
+        {
+            "payee_agent": {
+                "agentId": f"agt_py_payee_{suffix}",
+                "displayName": "Python SDK Demo Payee",
+                "owner": {"ownerType": "service", "ownerId": "svc_sdk_py_demo"},
+                "capabilities": ["translate", "summarize"],
+                "publicKeyPem": payee_public_key_pem,
+            },
+            "payer_agent": {
+                "agentId": f"agt_py_payer_{suffix}",
+                "displayName": "Python SDK Demo Payer",
+                "owner": {"ownerType": "service", "ownerId": "svc_sdk_py_demo"},
+                "capabilities": ["dispatch"],
+                "publicKeyPem": payer_public_key_pem,
+            },
+            "payer_credit": {"amountCents": 5000, "currency": "USD"},
+            "settlement": {"amountCents": 1250, "currency": "USD"},
+            "run": {
+                "runId": run_id,
+                "taskType": "translation",
+                "inputRef": f"urn:sdk:python:first-run:{suffix}",
+            },
+            "completed_metrics": {"latencyMs": 420},
+        }
+    )
+
+    verification_body = result.get("verification", {}).get("body", {})
+    verification_status = None
+    if isinstance(verification_body, dict):
+        verification = verification_body.get("verification", {})
+        if isinstance(verification, dict):
+            verification_status = verification.get("verificationStatus")
+        if verification_status is None:
+            verification_status = verification_body.get("verificationStatus")
+
+    summary = {
+        "runId": result.get("ids", {}).get("run_id"),
+        "payeeAgentId": result.get("ids", {}).get("payee_agent_id"),
+        "payerAgentId": result.get("ids", {}).get("payer_agent_id"),
+        "runStatus": result.get("run_completed", {}).get("body", {}).get("run", {}).get("status"),
+        "verificationStatus": verification_status,
+        "settlementStatus": result.get("settlement", {}).get("body", {}).get("settlement", {}).get("status")
+        if result.get("settlement")
+        else None,
+    }
+    print(json.dumps(summary, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/examples/sdk-tenant-analytics.mjs

@@ -0,0 +1,103 @@
+import { SettldClient } from "../../packages/api-sdk/src/index.js";
+
+function monthKeyUtcNow() {
+  const d = new Date();
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, "0");
+  return `${year}-${month}`;
+}
+
+function previousMonthKey(monthKey) {
+  const m = /^([0-9]{4})-([0-9]{2})$/.exec(String(monthKey ?? "").trim());
+  if (!m) return monthKeyUtcNow();
+  const year = Number.parseInt(m[1], 10);
+  const month = Number.parseInt(m[2], 10);
+  const d = new Date(Date.UTC(year, month - 1, 1));
+  d.setUTCMonth(d.getUTCMonth() - 1);
+  const y = d.getUTCFullYear();
+  const mm = String(d.getUTCMonth() + 1).padStart(2, "0");
+  return `${y}-${mm}`;
+}
+
+async function main() {
+  const baseUrl = process.env.SETTLD_BASE_URL ?? "http://127.0.0.1:8787";
+  const tenantId = process.env.SETTLD_TENANT_ID ?? "tenant_default";
+  const apiKey = process.env.SETTLD_API_KEY ?? "";
+  const xApiKey = process.env.SETTLD_X_API_KEY ?? "";
+  const month = process.env.SETTLD_MONTH ?? monthKeyUtcNow();
+  const baseMonth = process.env.SETTLD_BASE_MONTH ?? previousMonthKey(month);
+
+  if (!xApiKey) {
+    // eslint-disable-next-line no-console
+    console.error("SETTLD_X_API_KEY is not set; calls will fail unless Magic Link auth is disabled.");
+  }
+
+  const client = new SettldClient({
+    baseUrl,
+    tenantId,
+    apiKey: apiKey || undefined,
+    xApiKey: xApiKey || undefined
+  });
+
+  const analyticsRes = await client.getTenantAnalytics(tenantId, {
+    month,
+    bucket: "day",
+    limit: 20
+  });
+  const graphRes = await client.getTenantTrustGraph(tenantId, {
+    month,
+    minRuns: 1,
+    maxEdges: 200
+  });
+  const snapshotsRes = await client.listTenantTrustGraphSnapshots(tenantId, { limit: 10 });
+  const snapshotCreateRes = await client.createTenantTrustGraphSnapshot(tenantId, {
+    month,
+    minRuns: 1,
+    maxEdges: 200
+  });
+  const diffRes = await client.diffTenantTrustGraph(tenantId, {
+    baseMonth,
+    compareMonth: month,
+    limit: 20,
+    minRuns: 1,
+    maxEdges: 200
+  });
+
+  const report = analyticsRes?.body?.report ?? null;
+  const graph = graphRes?.body?.graph ?? null;
+  const snapshot = snapshotCreateRes?.body?.snapshot ?? null;
+  const diff = diffRes?.body?.diff ?? null;
+  const totals = report?.totals ?? null;
+  const summary = {
+    tenantId,
+    month,
+    baseMonth,
+    analytics: {
+      runs: totals?.runs ?? null,
+      greenRatePct: totals?.greenRatePct ?? null,
+      approvalRatePct: totals?.approvalRatePct ?? null,
+      holdRatePct: totals?.holdRatePct ?? null
+    },
+    trustGraph: {
+      nodes: Array.isArray(graph?.nodes) ? graph.nodes.length : null,
+      edges: Array.isArray(graph?.edges) ? graph.edges.length : null,
+      runs: Number.isFinite(Number(graph?.summary?.runs)) ? Number(graph.summary.runs) : null
+    },
+    snapshots: {
+      listed: Number.isFinite(Number(snapshotsRes?.body?.count)) ? Number(snapshotsRes.body.count) : null,
+      createdMonth: typeof snapshot?.month === "string" ? snapshot.month : null,
+      createdAt: typeof snapshot?.generatedAt === "string" ? snapshot.generatedAt : null
+    },
+    diff: {
+      nodeChanges: Number.isFinite(Number(diff?.summary?.nodeChanges)) ? Number(diff.summary.nodeChanges) : null,
+      edgeChanges: Number.isFinite(Number(diff?.summary?.edgeChanges)) ? Number(diff.summary.edgeChanges) : null,
+      added: Number.isFinite(Number(diff?.summary?.added)) ? Number(diff.summary.added) : null,
+      removed: Number.isFinite(Number(diff?.summary?.removed)) ? Number(diff.summary.removed) : null,
+      changed: Number.isFinite(Number(diff?.summary?.changed)) ? Number(diff.summary.changed) : null
+    }
+  };
+
+  process.stdout.write(`${JSON.stringify(summary, null, 2)}\n`);
+}
+
+await main();

package/scripts/examples/sdk-tenant-analytics.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import sys
+from datetime import datetime, timezone
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parents[2]
+sys.path.insert(0, str(REPO_ROOT / "packages" / "api-sdk-python"))
+
+from settld_api_sdk import SettldClient  # noqa: E402
+
+
+def month_key_utc_now() -> str:
+    now = datetime.now(timezone.utc)
+    return f"{now.year:04d}-{now.month:02d}"
+
+
+def previous_month_key(month_key: str) -> str:
+    raw = str(month_key or "").strip()
+    try:
+        year = int(raw[0:4])
+        month = int(raw[5:7])
+        if raw[4] != "-" or month < 1 or month > 12:
+            raise ValueError("invalid month")
+    except Exception:
+        return month_key_utc_now()
+    month -= 1
+    if month < 1:
+        month = 12
+        year -= 1
+    return f"{year:04d}-{month:02d}"
+
+
+def main() -> int:
+    base_url = os.environ.get("SETTLD_BASE_URL", "http://127.0.0.1:8787")
+    tenant_id = os.environ.get("SETTLD_TENANT_ID", "tenant_default")
+    api_key = os.environ.get("SETTLD_API_KEY")
+    x_api_key = os.environ.get("SETTLD_X_API_KEY")
+    month = os.environ.get("SETTLD_MONTH", month_key_utc_now())
+    base_month = os.environ.get("SETTLD_BASE_MONTH", previous_month_key(month))
+
+    if not x_api_key:
+        print("SETTLD_X_API_KEY is not set; calls will fail unless Magic Link auth is disabled.", file=sys.stderr)
+
+    client = SettldClient(
+        base_url=base_url,
+        tenant_id=tenant_id,
+        api_key=api_key,
+        x_api_key=x_api_key,
+    )
+
+    analytics_res = client.get_tenant_analytics(
+        tenant_id,
+        {"month": month, "bucket": "day", "limit": 20},
+    )
+    graph_res = client.get_tenant_trust_graph(
+        tenant_id,
+        {"month": month, "minRuns": 1, "maxEdges": 200},
+    )
+    snapshots_res = client.list_tenant_trust_graph_snapshots(tenant_id, {"limit": 10})
+    snapshot_create_res = client.create_tenant_trust_graph_snapshot(
+        tenant_id,
+        {"month": month, "minRuns": 1, "maxEdges": 200},
+    )
+    diff_res = client.diff_tenant_trust_graph(
+        tenant_id,
+        {
+            "baseMonth": base_month,
+            "compareMonth": month,
+            "limit": 20,
+            "minRuns": 1,
+            "maxEdges": 200,
+        },
+    )
+
+    report = analytics_res.get("body", {}).get("report", {})
+    graph = graph_res.get("body", {}).get("graph", {})
+    snapshot = snapshot_create_res.get("body", {}).get("snapshot", {})
+    diff = diff_res.get("body", {}).get("diff", {})
+    totals = report.get("totals", {}) if isinstance(report, dict) else {}
+    summary = {
+        "tenantId": tenant_id,
+        "month": month,
+        "baseMonth": base_month,
+        "analytics": {
+            "runs": totals.get("runs"),
+            "greenRatePct": totals.get("greenRatePct"),
+            "approvalRatePct": totals.get("approvalRatePct"),
+            "holdRatePct": totals.get("holdRatePct"),
+        },
+        "trustGraph": {
+            "nodes": len(graph.get("nodes", [])) if isinstance(graph.get("nodes"), list) else None,
+            "edges": len(graph.get("edges", [])) if isinstance(graph.get("edges"), list) else None,
+            "runs": graph.get("summary", {}).get("runs") if isinstance(graph.get("summary"), dict) else None,
+        },
+        "snapshots": {
+            "listed": snapshots_res.get("body", {}).get("count"),
+            "createdMonth": snapshot.get("month"),
+            "createdAt": snapshot.get("generatedAt"),
+        },
+        "diff": {
+            "nodeChanges": diff.get("summary", {}).get("nodeChanges") if isinstance(diff.get("summary"), dict) else None,
+            "edgeChanges": diff.get("summary", {}).get("edgeChanges") if isinstance(diff.get("summary"), dict) else None,
+            "added": diff.get("summary", {}).get("added") if isinstance(diff.get("summary"), dict) else None,
+            "removed": diff.get("summary", {}).get("removed") if isinstance(diff.get("summary"), dict) else None,
+            "changed": diff.get("summary", {}).get("changed") if isinstance(diff.get("summary"), dict) else None,
+        },
+    }
+
+    print(json.dumps(summary, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/finance-pack/bundle.mjs

@@ -0,0 +1,284 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { createPgStore } from "../../src/db/store-pg.js";
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "../../src/core/tenancy.js";
+import { MONTH_CLOSE_BASIS, makeMonthCloseStreamId, reduceMonthClose } from "../../src/core/month-close.js";
+import { GOVERNANCE_STREAM_ID } from "../../src/core/governance.js";
+import { buildMonthProofBundleV1 } from "../../src/core/proof-bundle.js";
+import { buildFinancePackBundleV1 } from "../../src/core/finance-pack-bundle.js";
+import { canonicalJsonStringify } from "../../src/core/canonical-json.js";
+import { reconcileGlBatchAgainstPartyStatements } from "../../packages/artifact-verify/src/index.js";
+
+import { ensureDir, writeFilesToDir, writeZipFromDir } from "../proof-bundle/lib.mjs";
+
+function readArg(name) {
+  const idx = process.argv.indexOf(name);
+  if (idx === -1) return null;
+  return process.argv[idx + 1] ?? null;
+}
+
+function usageAndExit() {
+  // eslint-disable-next-line no-console
+  console.error(
+    [
+      "usage:",
+      "  PG mode:",
+      "    DATABASE_URL=... node scripts/finance-pack/bundle.mjs --period YYYY-MM [--tenant <tenantId>] [--basis settledAt] [--out <dir>] [--zip]",
+      "  From-dir mode (no DB):",
+      "    node scripts/finance-pack/bundle.mjs --from <pilot_output_dir> [--out <dir>] [--zip]"
+    ].join("\n")
+  );
+  process.exit(2);
+}
+
+function pickLatestArtifact(list) {
+  const sorted = [...list].sort((a, b) => String(a?.artifactId ?? "").localeCompare(String(b?.artifactId ?? "")));
+  return sorted.length ? sorted[sorted.length - 1] : null;
+}
+
+function readJsonFile(filepath) {
+  const raw = fs.readFileSync(filepath, "utf8");
+  return JSON.parse(raw);
+}
+
+function readTextFileUtf8(filepath) {
+  return fs.readFileSync(filepath, "utf8");
+}
+
+function readFilesRecursive({ dir }) {
+  const files = new Map();
+  const stack = [dir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const e of entries) {
+      const full = path.join(current, e.name);
+      if (e.isDirectory()) {
+        stack.push(full);
+        continue;
+      }
+      if (!e.isFile()) continue;
+      const rel = path.relative(dir, full).split(path.sep).join("/");
+      files.set(rel, new Uint8Array(fs.readFileSync(full)));
+    }
+  }
+  return files;
+}
+
+function loadArtifactsFromDir(dirpath) {
+  if (!fs.existsSync(dirpath)) return [];
+  const entries = fs.readdirSync(dirpath, { withFileTypes: true }).filter((e) => e.isFile() && e.name.endsWith(".json"));
+  const out = [];
+  for (const e of entries) {
+    const a = readJsonFile(path.join(dirpath, e.name));
+    if (a && typeof a === "object") out.push(a);
+  }
+  return out;
+}
+
+const fromDir = readArg("--from");
+const outBase = readArg("--out") ?? path.join("demo", "finance-pack", "bundles");
+const zipFlag = process.argv.includes("--zip");
+
+if (fromDir) {
+  const root = path.resolve(fromDir);
+  const monthDir = path.join(root, "proof", "month");
+  if (!fs.existsSync(monthDir) || !fs.statSync(monthDir).isDirectory()) {
+    throw new Error(`--from must point at a pilot output dir containing proof/month (missing: ${monthDir})`);
+  }
+
+  const monthEventsPath = path.join(monthDir, "events", "events.jsonl");
+  const rawEvents = readTextFileUtf8(monthEventsPath)
+    .split("\n")
+    .filter((l) => l.trim())
+    .map((l) => JSON.parse(l));
+  const req = rawEvents.find((e) => e?.type === "MONTH_CLOSE_REQUESTED") ?? null;
+  if (!req) throw new Error("MONTH_CLOSE_REQUESTED not found in proof/month/events/events.jsonl");
+
+  const tenantId = normalizeTenantId(readArg("--tenant") ?? String(req.payload?.tenantId ?? DEFAULT_TENANT_ID));
+  const period = String(readArg("--period") ?? readArg("--month") ?? req.payload?.month ?? "");
+  const basis = String(req.payload?.basis ?? MONTH_CLOSE_BASIS.SETTLED_AT);
+  if (!period) throw new Error("period missing (use --period or ensure MONTH_CLOSE_REQUESTED has payload.month)");
+  const createdAt = String(req.payload?.requestedAt ?? req.at ?? new Date().toISOString());
+
+  const monthManifest = readJsonFile(path.join(monthDir, "manifest.json"));
+  const monthProofBundle = { manifestHash: String(monthManifest?.manifestHash ?? "") };
+  if (!monthProofBundle.manifestHash) throw new Error("proof/month/manifest.json missing manifestHash");
+
+  const monthProofFiles = readFilesRecursive({ dir: monthDir });
+
+  const glBatchPath = path.join(root, "GLBatch.v1.json");
+  const glBatch = fs.existsSync(glBatchPath)
+    ? readJsonFile(glBatchPath)
+    : pickLatestArtifact(loadArtifactsFromDir(path.join(monthDir, "artifacts", "GLBatch.v1")));
+  if (!glBatch) throw new Error("missing GLBatch.v1.json (expected at root or proof/month/artifacts/GLBatch.v1)");
+
+  const journalCsvPath = path.join(root, "JournalCsv.v1.json");
+  const journalCsv = fs.existsSync(journalCsvPath)
+    ? readJsonFile(journalCsvPath)
+    : pickLatestArtifact(loadArtifactsFromDir(path.join(monthDir, "artifacts", "JournalCsv.v1")));
+  if (!journalCsv) throw new Error("missing JournalCsv.v1.json (expected at root or proof/month/artifacts/JournalCsv.v1)");
+
+  const partyStatements = loadArtifactsFromDir(path.join(monthDir, "artifacts", "PartyStatement.v1"));
+  if (!partyStatements.length) throw new Error("missing PartyStatement.v1 artifacts under proof/month/artifacts/PartyStatement.v1");
+
+  const reconcile = reconcileGlBatchAgainstPartyStatements({ glBatch, partyStatements });
+  if (!reconcile.ok) {
+    const err = new Error(`reconcile failed: ${reconcile.error}`);
+    err.detail = reconcile;
+    throw err;
+  }
+
+  const protocol = String(readArg("--protocol") ?? "1.0");
+  const reconcileBytes = new TextEncoder().encode(`${canonicalJsonStringify(reconcile)}\n`);
+  const { files, bundle } = buildFinancePackBundleV1({
+    tenantId,
+    period,
+    protocol,
+    createdAt,
+    monthProofBundle,
+    monthProofFiles,
+    glBatchArtifact: glBatch,
+    journalCsvArtifact: journalCsv,
+    reconcileReport: reconcile,
+    reconcileReportBytes: reconcileBytes
+  });
+
+  const outDir = path.join(outBase, `finance_pack_${tenantId}_${String(period)}_${bundle.manifestHash.slice(0, 12)}`);
+  ensureDir(outDir);
+  writeFilesToDir({ files, outDir });
+
+  if (zipFlag) {
+    const zipPath = `${outDir}.zip`;
+    await writeZipFromDir({ dir: outDir, outPath: zipPath, mtime: new Date(createdAt), compression: "stored" });
+    process.stdout.write(`${zipPath}\n`);
+  } else {
+    process.stdout.write(`${outDir}\n`);
+  }
+  process.exit(0);
+}
+
+const DATABASE_URL = process.env.DATABASE_URL ?? null;
+if (!DATABASE_URL) throw new Error("DATABASE_URL is required (or use --from)");
+
+const tenantId = normalizeTenantId(process.env.TENANT_ID ?? readArg("--tenant") ?? DEFAULT_TENANT_ID);
+const period = readArg("--period") ?? readArg("--month") ?? null;
+if (!period) usageAndExit();
+
+const basis = String(readArg("--basis") ?? MONTH_CLOSE_BASIS.SETTLED_AT);
+
+const store = await createPgStore({ databaseUrl: DATABASE_URL, schema: process.env.PROXY_PG_SCHEMA ?? "public", migrateOnStartup: true });
+try {
+  const monthId = makeMonthCloseStreamId({ month: String(period), basis });
+  const monthEvents = await store.listAggregateEvents({ tenantId, aggregateType: "month", aggregateId: monthId });
+  if (!monthEvents.length) throw new Error("month close stream not found");
+  const monthState = reduceMonthClose(monthEvents);
+  const createdAt =
+    (typeof monthState?.requestedAt === "string" && monthState.requestedAt.trim() ? monthState.requestedAt : null) ??
+    (typeof monthEvents[0]?.at === "string" ? monthEvents[0].at : null) ??
+    new Date().toISOString();
+
+  const artifacts = await store.listArtifacts({ tenantId });
+  const monthArtifacts = artifacts.filter((a) => {
+    if (!a || typeof a !== "object") return false;
+    if (a.period && String(a.period) === String(period)) return true;
+    if (a.month && String(a.month) === String(period)) return true;
+    return false;
+  });
+
+  const glBatch = pickLatestArtifact(monthArtifacts.filter((a) => a?.artifactType === "GLBatch.v1"));
+  if (!glBatch) throw new Error("missing GLBatch.v1 for period");
+
+  const journalCsv = pickLatestArtifact(monthArtifacts.filter((a) => a?.artifactType === "JournalCsv.v1"));
+  if (!journalCsv) throw new Error("missing JournalCsv.v1 for period");
+
+  const partyStatements = monthArtifacts.filter((a) => a?.artifactType === "PartyStatement.v1");
+  if (!partyStatements.length) throw new Error("missing PartyStatement.v1 artifacts for period");
+
+  const reconcile = reconcileGlBatchAgainstPartyStatements({ glBatch, partyStatements });
+  if (!reconcile.ok) {
+    const err = new Error(`reconcile failed: ${reconcile.error}`);
+    err.detail = reconcile;
+    throw err;
+  }
+
+  const publicKeyByKeyId = store.publicKeyByKeyId instanceof Map ? store.publicKeyByKeyId : new Map();
+  const manifestSigner = store?.serverSigner ? { keyId: store.serverSigner.keyId, privateKeyPem: store.serverSigner.privateKeyPem } : null;
+  let signerKeys = [];
+  if (typeof store.listSignerKeys === "function") {
+    const tenantKeys = await store.listSignerKeys({ tenantId });
+    const defaultKeys = await store.listSignerKeys({ tenantId: DEFAULT_TENANT_ID });
+    const all = [...(tenantKeys ?? []), ...(defaultKeys ?? [])];
+    const byKeyId = new Map();
+    for (const r of all) {
+      const keyId = r?.keyId ? String(r.keyId) : null;
+      if (!keyId) continue;
+      byKeyId.set(keyId, r);
+    }
+    signerKeys = Array.from(byKeyId.values());
+  }
+  const tenantGovernanceEvents = await store.listAggregateEvents({ tenantId, aggregateType: "month", aggregateId: GOVERNANCE_STREAM_ID });
+  const tenantGovernanceSnapshot = {
+    streamId: GOVERNANCE_STREAM_ID,
+    lastChainHash: tenantGovernanceEvents.length ? tenantGovernanceEvents[tenantGovernanceEvents.length - 1]?.chainHash ?? null : null,
+    lastEventId: tenantGovernanceEvents.length ? tenantGovernanceEvents[tenantGovernanceEvents.length - 1]?.id ?? null : null
+  };
+  const governanceEvents = await store.listAggregateEvents({ tenantId: DEFAULT_TENANT_ID, aggregateType: "month", aggregateId: GOVERNANCE_STREAM_ID });
+  const governanceSnapshot = {
+    streamId: GOVERNANCE_STREAM_ID,
+    lastChainHash: governanceEvents.length ? governanceEvents[governanceEvents.length - 1]?.chainHash ?? null : null,
+    lastEventId: governanceEvents.length ? governanceEvents[governanceEvents.length - 1]?.id ?? null : null
+  };
+  const generatedAt = createdAt;
+  const { files: monthFiles, bundle: monthBundle } = buildMonthProofBundleV1({
+    tenantId,
+    period: String(period),
+    basis,
+    monthEvents,
+    governanceEvents,
+    governanceSnapshot,
+    tenantGovernanceEvents,
+    tenantGovernanceSnapshot,
+    artifacts: monthArtifacts,
+    contractDocsByHash: new Map(),
+    publicKeyByKeyId,
+    signerKeys,
+    manifestSigner,
+    requireHeadAttestation: true,
+    generatedAt
+  });
+
+  const protocol = "1.0";
+  const reconcileBytes = new TextEncoder().encode(`${canonicalJsonStringify(reconcile)}\n`);
+  const { files, bundle } = buildFinancePackBundleV1({
+    tenantId,
+    period: String(period),
+    protocol,
+    createdAt,
+    monthProofBundle: monthBundle,
+    monthProofFiles: monthFiles,
+    requireMonthProofAttestation: true,
+    requireHeadAttestation: true,
+    manifestSigner,
+    verificationReportSigner: manifestSigner,
+    glBatchArtifact: glBatch,
+    journalCsvArtifact: journalCsv,
+    reconcileReport: reconcile,
+    reconcileReportBytes: reconcileBytes
+  });
+
+  const outDir = path.join(outBase, `finance_pack_${tenantId}_${String(period)}_${bundle.manifestHash.slice(0, 12)}`);
+  ensureDir(outDir);
+  writeFilesToDir({ files, outDir });
+
+  if (zipFlag) {
+    const zipPath = `${outDir}.zip`;
+    await writeZipFromDir({ dir: outDir, outPath: zipPath, mtime: new Date(createdAt), compression: "stored" });
+    process.stdout.write(`${zipPath}\n`);
+  } else {
+    process.stdout.write(`${outDir}\n`);
+  }
+} finally {
+  await store.close?.();
+}