settld 0.1.0

package/src/core/funding-hold.js

@@ -0,0 +1,185 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const FUNDING_HOLD_SCHEMA_VERSION = "FundingHold.v1";
+
+export const FUNDING_HOLD_STATUS = Object.freeze({
+  HELD: "held",
+  RELEASED: "released",
+  REFUNDED: "refunded"
+});
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertIsoDate(value, name, { allowNull = false } = {}) {
+  if (value === null || value === undefined) {
+    if (allowNull) return;
+    throw new TypeError(`${name} must be an ISO date string`);
+  }
+  assertNonEmptyString(value, name);
+  if (!Number.isFinite(Date.parse(value))) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+function normalizeId(value, name, { min = 1, max = 200 } = {}) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim();
+  if (out.length < min || out.length > max) throw new TypeError(`${name} must be length ${min}..${max}`);
+  if (!/^[A-Za-z0-9:_-]+$/.test(out)) throw new TypeError(`${name} must match ^[A-Za-z0-9:_-]+$`);
+  return out;
+}
+
+function normalizeHexHash(value, name) {
+  assertNonEmptyString(value, name);
+  const out = String(value).trim().toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(out)) throw new TypeError(`${name} must be a 64-hex sha256`);
+  return out;
+}
+
+function normalizeCurrency(value, name) {
+  const raw = typeof value === "string" && value.trim() !== "" ? value : "USD";
+  const out = raw.trim().toUpperCase();
+  if (!/^[A-Z][A-Z0-9_]{2,11}$/.test(out)) throw new TypeError(`${name} must match ^[A-Z][A-Z0-9_]{2,11}$`);
+  return out;
+}
+
+function assertNonNegativeSafeInt(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+function assertPositiveSafeInt(value, name) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function normalizeHoldStatus(value, name) {
+  const normalized = typeof value === "string" ? value.trim().toLowerCase() : "";
+  if (!Object.values(FUNDING_HOLD_STATUS).includes(normalized)) {
+    throw new TypeError(`${name} must be one of: ${Object.values(FUNDING_HOLD_STATUS).join("|")}`);
+  }
+  return normalized;
+}
+
+export function computeFundingHoldHashV1(holdCore) {
+  assertPlainObject(holdCore, "holdCore");
+  const copy = { ...holdCore };
+  delete copy.holdHash;
+  delete copy.status;
+  delete copy.resolvedAt;
+  delete copy.updatedAt;
+  delete copy.revision;
+  delete copy.metadata;
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildFundingHoldV1({
+  tenantId,
+  agreementHash,
+  receiptHash,
+  payerAgentId,
+  payeeAgentId,
+  amountCents,
+  heldAmountCents,
+  currency,
+  holdbackBps,
+  challengeWindowMs,
+  createdAt
+} = {}) {
+  const at = createdAt ?? new Date().toISOString();
+  assertIsoDate(at, "createdAt");
+
+  const normalized = normalizeForCanonicalJson(
+    {
+      schemaVersion: FUNDING_HOLD_SCHEMA_VERSION,
+      tenantId: normalizeId(tenantId, "tenantId", { min: 1, max: 128 }),
+      agreementHash: normalizeHexHash(agreementHash, "agreementHash"),
+      receiptHash: normalizeHexHash(receiptHash, "receiptHash"),
+      payerAgentId: normalizeId(payerAgentId, "payerAgentId", { min: 3, max: 128 }),
+      payeeAgentId: normalizeId(payeeAgentId, "payeeAgentId", { min: 3, max: 128 }),
+      amountCents: assertPositiveSafeInt(amountCents, "amountCents"),
+      heldAmountCents: assertNonNegativeSafeInt(heldAmountCents, "heldAmountCents"),
+      currency: normalizeCurrency(currency, "currency"),
+      holdbackBps: assertNonNegativeSafeInt(holdbackBps, "holdbackBps"),
+      challengeWindowMs: assertNonNegativeSafeInt(challengeWindowMs, "challengeWindowMs"),
+      createdAt: at
+    },
+    { path: "$" }
+  );
+
+  if (normalized.heldAmountCents > normalized.amountCents) throw new TypeError("heldAmountCents must be <= amountCents");
+
+  const holdHash = computeFundingHoldHashV1(normalized);
+  return normalizeForCanonicalJson(
+    {
+      ...normalized,
+      holdHash,
+      status: FUNDING_HOLD_STATUS.HELD,
+      revision: 0,
+      updatedAt: at
+    },
+    { path: "$" }
+  );
+}
+
+export function validateFundingHoldV1(hold) {
+  assertPlainObject(hold, "hold");
+  if (hold.schemaVersion !== FUNDING_HOLD_SCHEMA_VERSION) {
+    throw new TypeError(`hold.schemaVersion must be ${FUNDING_HOLD_SCHEMA_VERSION}`);
+  }
+  normalizeId(hold.tenantId, "hold.tenantId", { min: 1, max: 128 });
+  normalizeHexHash(hold.agreementHash, "hold.agreementHash");
+  normalizeHexHash(hold.receiptHash, "hold.receiptHash");
+  normalizeId(hold.payerAgentId, "hold.payerAgentId", { min: 3, max: 128 });
+  normalizeId(hold.payeeAgentId, "hold.payeeAgentId", { min: 3, max: 128 });
+  assertPositiveSafeInt(hold.amountCents, "hold.amountCents");
+  assertNonNegativeSafeInt(hold.heldAmountCents, "hold.heldAmountCents");
+  if (Number(hold.heldAmountCents) > Number(hold.amountCents)) throw new TypeError("hold.heldAmountCents must be <= hold.amountCents");
+  normalizeCurrency(hold.currency, "hold.currency");
+  assertNonNegativeSafeInt(hold.holdbackBps, "hold.holdbackBps");
+  assertNonNegativeSafeInt(hold.challengeWindowMs, "hold.challengeWindowMs");
+  assertIsoDate(hold.createdAt, "hold.createdAt");
+  const holdHash = normalizeHexHash(hold.holdHash, "hold.holdHash");
+  normalizeHoldStatus(hold.status, "hold.status");
+  const revision = Number(hold.revision ?? 0);
+  if (!Number.isSafeInteger(revision) || revision < 0) throw new TypeError("hold.revision must be a non-negative safe integer");
+  assertIsoDate(hold.updatedAt, "hold.updatedAt");
+  if (Object.prototype.hasOwnProperty.call(hold, "resolvedAt")) {
+    assertIsoDate(hold.resolvedAt ?? null, "hold.resolvedAt", { allowNull: true });
+  }
+  const computed = computeFundingHoldHashV1(hold);
+  if (computed !== holdHash) throw new TypeError("holdHash mismatch");
+  return true;
+}
+
+export function resolveFundingHoldV1({ hold, status, resolvedAt = null, metadata = null } = {}) {
+  validateFundingHoldV1(hold);
+  const nextStatus = normalizeHoldStatus(status, "status");
+  const at = resolvedAt ?? new Date().toISOString();
+  assertIsoDate(at, "resolvedAt");
+  if (nextStatus === FUNDING_HOLD_STATUS.HELD) throw new TypeError("cannot resolve hold to held");
+  const currentStatus = String(hold.status ?? "").toLowerCase();
+  if (currentStatus !== FUNDING_HOLD_STATUS.HELD) return hold;
+
+  const meta = metadata && typeof metadata === "object" && !Array.isArray(metadata) ? metadata : null;
+  const next = {
+    ...hold,
+    status: nextStatus,
+    resolvedAt: at,
+    revision: Number(hold.revision ?? 0) + 1,
+    updatedAt: at
+  };
+  if (meta) next.metadata = meta;
+  return normalizeForCanonicalJson(next, { path: "$" });
+}

package/src/core/gl-batch.js

@@ -0,0 +1,107 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+import { jobIdFromLedgerMemo } from "./party-statements.js";
+
+function isPlainObject(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null));
+}
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+export const GL_BATCH_SCHEMA_VERSION_V1 = "GLBatchBody.v1";
+
+export function computeGlBatchBodyV1({ tenantId, period, basis, allocationRows, generatedAt, monthClose = null } = {}) {
+  assertNonEmptyString(tenantId, "tenantId");
+  assertNonEmptyString(period, "period");
+  assertNonEmptyString(basis, "basis");
+  assertNonEmptyString(generatedAt, "generatedAt");
+  if (!Array.isArray(allocationRows)) throw new TypeError("allocationRows must be an array");
+  if (monthClose !== null && monthClose !== undefined && !isPlainObject(monthClose)) throw new TypeError("monthClose must be an object when provided");
+
+  const lines = [];
+  const totalsByAccountId = new Map();
+  const totalsByPartyId = new Map();
+  let totalCents = 0;
+
+  for (const r of allocationRows) {
+    if (!r || typeof r !== "object") continue;
+    const entryId = r.entryId ?? r.entry_id ?? null;
+    const postingId = r.postingId ?? r.posting_id ?? null;
+    const accountId = r.accountId ?? r.account_id ?? null;
+    const partyId = r.partyId ?? r.party_id ?? null;
+    const partyRole = r.partyRole ?? r.party_role ?? null;
+    const currency = r.currency ?? "USD";
+    const amountCents = r.amountCents ?? r.amount_cents ?? null;
+    const memo = r.memo ?? null;
+    const at = r.at ?? null;
+
+    if (typeof entryId !== "string" || !entryId.trim()) continue;
+    if (typeof postingId !== "string" || !postingId.trim()) continue;
+    if (typeof accountId !== "string" || !accountId.trim()) continue;
+    if (typeof partyId !== "string" || !partyId.trim()) continue;
+    if (typeof partyRole !== "string" || !partyRole.trim()) continue;
+    if (typeof currency !== "string" || !currency.trim()) continue;
+    if (!Number.isSafeInteger(amountCents)) continue;
+
+    const lineId = `${entryId}:${postingId}:${partyId}`;
+    const jobId = typeof memo === "string" && memo.trim() ? jobIdFromLedgerMemo(memo) : null;
+
+    lines.push({
+      lineId,
+      entryId,
+      postingId,
+      at: typeof at === "string" && at.trim() ? at : null,
+      memo: typeof memo === "string" && memo.trim() ? memo : null,
+      jobId: typeof jobId === "string" && jobId.trim() ? jobId : null,
+      accountId,
+      partyId,
+      partyRole,
+      currency,
+      amountCents
+    });
+
+    totalCents += amountCents;
+    totalsByAccountId.set(accountId, (totalsByAccountId.get(accountId) ?? 0) + amountCents);
+    totalsByPartyId.set(partyId, (totalsByPartyId.get(partyId) ?? 0) + amountCents);
+  }
+
+  lines.sort((a, b) => {
+    if (a.entryId !== b.entryId) return a.entryId < b.entryId ? -1 : 1;
+    if (a.postingId !== b.postingId) return a.postingId < b.postingId ? -1 : 1;
+    if (a.partyId !== b.partyId) return a.partyId < b.partyId ? -1 : 1;
+    return 0;
+  });
+
+  const totalsByAccountIdObj = {};
+  for (const k of Array.from(totalsByAccountId.keys()).sort()) totalsByAccountIdObj[k] = totalsByAccountId.get(k);
+  const totalsByPartyIdObj = {};
+  for (const k of Array.from(totalsByPartyId.keys()).sort()) totalsByPartyIdObj[k] = totalsByPartyId.get(k);
+
+  if (totalCents !== 0) {
+    const err = new Error(`GL batch does not balance: totalCents ${totalCents} != 0`);
+    err.code = "GL_BATCH_IMBALANCED";
+    err.totalCents = totalCents;
+    throw err;
+  }
+
+  const body = {
+    type: GL_BATCH_SCHEMA_VERSION_V1,
+    tenantId,
+    period,
+    basis,
+    generatedAt,
+    monthClose: monthClose ?? null,
+    totals: {
+      totalCents,
+      totalsByAccountId: totalsByAccountIdObj,
+      totalsByPartyId: totalsByPartyIdObj
+    },
+    lines
+  };
+
+  const bodyHash = sha256Hex(canonicalJsonStringify(body));
+  return { body, bodyHash };
+}
+

package/src/core/governance-policy.js

@@ -0,0 +1,174 @@
+import { canonicalJsonStringify } from "./canonical-json.js";
+import { sha256Hex, signHashHexEd25519 } from "./crypto.js";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new TypeError(`${name} must be a plain object`);
+}
+
+export const SIGNATURE_ALGORITHM = Object.freeze({
+  ED25519: "ed25519"
+});
+
+export const GOVERNANCE_POLICY_SCHEMA_V1 = "GovernancePolicy.v1";
+export const GOVERNANCE_POLICY_SCHEMA_V2 = "GovernancePolicy.v2";
+
+function isHex64(value) {
+  return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+export function buildDefaultGovernancePolicyV1({ generatedAt } = {}) {
+  assertNonEmptyString(generatedAt, "generatedAt");
+  return {
+    schemaVersion: GOVERNANCE_POLICY_SCHEMA_V1,
+    policyId: "governance_policy_default_v1",
+    generatedAt,
+    algorithms: [SIGNATURE_ALGORITHM.ED25519],
+    verificationReportSigners: [
+      {
+        subjectType: "JobProofBundle.v1",
+        allowedScopes: ["global", "tenant"],
+        allowedKeyIds: null,
+        requireGoverned: true,
+        requiredPurpose: "server"
+      },
+      {
+        subjectType: "MonthProofBundle.v1",
+        allowedScopes: ["global", "tenant"],
+        allowedKeyIds: null,
+        requireGoverned: true,
+        requiredPurpose: "server"
+      },
+      {
+        subjectType: "FinancePackBundle.v1",
+        allowedScopes: ["global", "tenant"],
+        allowedKeyIds: null,
+        requireGoverned: true,
+        requiredPurpose: "server"
+      }
+    ],
+    bundleHeadAttestationSigners: [
+      {
+        subjectType: "JobProofBundle.v1",
+        allowedScopes: ["global", "tenant"],
+        allowedKeyIds: null,
+        requireGoverned: true,
+        requiredPurpose: "server"
+      },
+      {
+        subjectType: "MonthProofBundle.v1",
+        allowedScopes: ["global", "tenant"],
+        allowedKeyIds: null,
+        requireGoverned: true,
+        requiredPurpose: "server"
+      },
+      {
+        subjectType: "FinancePackBundle.v1",
+        allowedScopes: ["global", "tenant"],
+        allowedKeyIds: null,
+        requireGoverned: true,
+        requiredPurpose: "server"
+      }
+    ]
+  };
+}
+
+export function validateGovernancePolicyV1(policy) {
+  assertPlainObject(policy, "policy");
+  if (policy.schemaVersion !== GOVERNANCE_POLICY_SCHEMA_V1) throw new TypeError("policy.schemaVersion must be GovernancePolicy.v1");
+  assertNonEmptyString(policy.policyId, "policy.policyId");
+  assertNonEmptyString(policy.generatedAt, "policy.generatedAt");
+  if (!Array.isArray(policy.algorithms) || policy.algorithms.length === 0) throw new TypeError("policy.algorithms must be a non-empty array");
+  if (!policy.algorithms.includes(SIGNATURE_ALGORITHM.ED25519)) throw new TypeError("policy.algorithms must include ed25519");
+  if (!Array.isArray(policy.verificationReportSigners)) throw new TypeError("policy.verificationReportSigners must be an array");
+  if (!Array.isArray(policy.bundleHeadAttestationSigners)) throw new TypeError("policy.bundleHeadAttestationSigners must be an array");
+  return { ok: true };
+}
+
+function validateSignerRuleV2(rule, name) {
+  assertPlainObject(rule, name);
+  assertNonEmptyString(rule.subjectType, `${name}.subjectType`);
+  if (!Array.isArray(rule.allowedScopes) || rule.allowedScopes.length === 0) throw new TypeError(`${name}.allowedScopes must be a non-empty array`);
+  for (const s of rule.allowedScopes) {
+    if (s !== "global" && s !== "tenant") throw new TypeError(`${name}.allowedScopes contains invalid scope`);
+  }
+  if (!Array.isArray(rule.allowedKeyIds)) throw new TypeError(`${name}.allowedKeyIds must be an array`);
+  for (const kid of rule.allowedKeyIds) assertNonEmptyString(kid, `${name}.allowedKeyIds[]`);
+  if (typeof rule.requireGoverned !== "boolean") throw new TypeError(`${name}.requireGoverned must be a boolean`);
+  if (rule.requiredPurpose !== "server") throw new TypeError(`${name}.requiredPurpose must be 'server'`);
+}
+
+function stripPolicySig(policy) {
+  const { policyHash: _h, signature: _sig, ...rest } = policy ?? {};
+  return rest;
+}
+
+export function buildGovernancePolicyV2Unsigned({
+  policyId,
+  generatedAt,
+  verificationReportSigners = [],
+  bundleHeadAttestationSigners = [],
+  revocationList
+} = {}) {
+  assertNonEmptyString(policyId, "policyId");
+  assertNonEmptyString(generatedAt, "generatedAt");
+  if (!Array.isArray(verificationReportSigners)) throw new TypeError("verificationReportSigners must be an array");
+  if (!Array.isArray(bundleHeadAttestationSigners)) throw new TypeError("bundleHeadAttestationSigners must be an array");
+  assertPlainObject(revocationList, "revocationList");
+  assertNonEmptyString(revocationList.path, "revocationList.path");
+  if (!isHex64(revocationList.sha256)) throw new TypeError("revocationList.sha256 must be a 64-char lowercase hex sha256");
+
+  return {
+    schemaVersion: GOVERNANCE_POLICY_SCHEMA_V2,
+    policyId,
+    generatedAt,
+    algorithms: [SIGNATURE_ALGORITHM.ED25519],
+    verificationReportSigners,
+    bundleHeadAttestationSigners,
+    revocationList: { path: String(revocationList.path), sha256: String(revocationList.sha256) },
+    signerKeyId: null,
+    signedAt: null,
+    policyHash: null,
+    signature: null
+  };
+}
+
+export function signGovernancePolicyV2({ policy, signer, signedAt } = {}) {
+  assertPlainObject(policy, "policy");
+  if (policy.schemaVersion !== GOVERNANCE_POLICY_SCHEMA_V2) throw new TypeError("policy.schemaVersion must be GovernancePolicy.v2");
+  if (!signer || typeof signer !== "object") throw new TypeError("signer is required");
+  assertNonEmptyString(signer.keyId, "signer.keyId");
+  assertNonEmptyString(signer.privateKeyPem, "signer.privateKeyPem");
+  assertNonEmptyString(signedAt, "signedAt");
+
+  const withSigner = { ...policy, signerKeyId: signer.keyId, signedAt, policyHash: null, signature: null };
+  const core = stripPolicySig(withSigner);
+  const policyHash = sha256Hex(canonicalJsonStringify(core));
+  const signature = signHashHexEd25519(policyHash, signer.privateKeyPem);
+  return { ...withSigner, policyHash, signature };
+}
+
+export function validateGovernancePolicyV2(policy) {
+  assertPlainObject(policy, "policy");
+  if (policy.schemaVersion !== GOVERNANCE_POLICY_SCHEMA_V2) throw new TypeError("policy.schemaVersion must be GovernancePolicy.v2");
+  assertNonEmptyString(policy.policyId, "policy.policyId");
+  assertNonEmptyString(policy.generatedAt, "policy.generatedAt");
+  if (!Array.isArray(policy.algorithms) || policy.algorithms.length === 0) throw new TypeError("policy.algorithms must be a non-empty array");
+  if (!policy.algorithms.includes(SIGNATURE_ALGORITHM.ED25519)) throw new TypeError("policy.algorithms must include ed25519");
+  if (!Array.isArray(policy.verificationReportSigners)) throw new TypeError("policy.verificationReportSigners must be an array");
+  if (!Array.isArray(policy.bundleHeadAttestationSigners)) throw new TypeError("policy.bundleHeadAttestationSigners must be an array");
+  for (let i = 0; i < policy.verificationReportSigners.length; i += 1) validateSignerRuleV2(policy.verificationReportSigners[i], `policy.verificationReportSigners[${i}]`);
+  for (let i = 0; i < policy.bundleHeadAttestationSigners.length; i += 1) validateSignerRuleV2(policy.bundleHeadAttestationSigners[i], `policy.bundleHeadAttestationSigners[${i}]`);
+  assertPlainObject(policy.revocationList, "policy.revocationList");
+  assertNonEmptyString(policy.revocationList.path, "policy.revocationList.path");
+  if (!isHex64(policy.revocationList.sha256)) throw new TypeError("policy.revocationList.sha256 must be a 64-char lowercase hex sha256");
+  if (policy.signerKeyId !== null) assertNonEmptyString(policy.signerKeyId, "policy.signerKeyId");
+  if (policy.signedAt !== null) assertNonEmptyString(policy.signedAt, "policy.signedAt");
+  if (policy.policyHash !== null && !isHex64(policy.policyHash)) throw new TypeError("policy.policyHash must be a 64-char lowercase hex sha256 or null");
+  if (policy.signature !== null) assertNonEmptyString(policy.signature, "policy.signature");
+  return { ok: true };
+}

package/src/core/governance.js

@@ -0,0 +1,92 @@
+import { DEFAULT_TENANT_ID, normalizeTenantId } from "./tenancy.js";
+import { normalizeMonthCloseHoldPolicy } from "./month-close-hold-policy.js";
+
+export const GOVERNANCE_STREAM_ID = "governance";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function assertPlainObject(value, name) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new TypeError(`${name} must be an object`);
+  if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+    throw new TypeError(`${name} must be a plain object`);
+  }
+}
+
+function assertIsoDate(value, name) {
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+  return String(value);
+}
+
+export function validateTenantPolicyUpdatedPayload(payload) {
+  assertPlainObject(payload, "payload");
+
+  const allowed = new Set(["tenantId", "policyId", "effectiveFrom", "updatedAt", "policy", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+
+  const tenantId = normalizeTenantId(payload.tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(payload.policyId, "payload.policyId");
+  const effectiveFrom = assertIsoDate(payload.effectiveFrom, "payload.effectiveFrom");
+  const updatedAt = assertIsoDate(payload.updatedAt, "payload.updatedAt");
+  assertPlainObject(payload.policy, "payload.policy");
+
+  const finance = payload.policy?.finance ?? null;
+  if (finance !== null && finance !== undefined) {
+    assertPlainObject(finance, "payload.policy.finance");
+    if (finance.monthCloseHoldPolicy !== undefined && finance.monthCloseHoldPolicy !== null) {
+      normalizeMonthCloseHoldPolicy(finance.monthCloseHoldPolicy);
+    }
+  }
+
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+
+  return { ...payload, tenantId, effectiveFrom, updatedAt };
+}
+
+export function validateServerSignerKeyRegisteredPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["tenantId", "keyId", "publicKeyPem", "registeredAt", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  const tenantId = normalizeTenantId(payload.tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(payload.keyId, "payload.keyId");
+  assertNonEmptyString(payload.publicKeyPem, "payload.publicKeyPem");
+  const registeredAt = assertIsoDate(payload.registeredAt, "payload.registeredAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  return { ...payload, tenantId, registeredAt };
+}
+
+export function validateServerSignerKeyRotatedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["tenantId", "oldKeyId", "newKeyId", "newPublicKeyPem", "rotatedAt", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  const tenantId = normalizeTenantId(payload.tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(payload.oldKeyId, "payload.oldKeyId");
+  assertNonEmptyString(payload.newKeyId, "payload.newKeyId");
+  assertNonEmptyString(payload.newPublicKeyPem, "payload.newPublicKeyPem");
+  const rotatedAt = assertIsoDate(payload.rotatedAt, "payload.rotatedAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  return { ...payload, tenantId, rotatedAt };
+}
+
+export function validateServerSignerKeyRevokedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set(["tenantId", "keyId", "revokedAt", "reason"]);
+  for (const key of Object.keys(payload)) {
+    if (!allowed.has(key)) throw new TypeError(`payload contains unknown field: ${key}`);
+  }
+  const tenantId = normalizeTenantId(payload.tenantId ?? DEFAULT_TENANT_ID);
+  assertNonEmptyString(payload.keyId, "payload.keyId");
+  const revokedAt = assertIsoDate(payload.revokedAt, "payload.revokedAt");
+  if (payload.reason !== undefined && payload.reason !== null) assertNonEmptyString(payload.reason, "payload.reason");
+  return { ...payload, tenantId, revokedAt };
+}
+

package/src/core/hold-exposure.js

@@ -0,0 +1,74 @@
+import { computeExpectedSettlementSplitsV1 } from "./settlement-splits.js";
+
+function clampInt({ value, min, max }) {
+  if (!Number.isFinite(value)) return min;
+  const n = Math.floor(value);
+  if (!Number.isSafeInteger(n)) return min;
+  return Math.max(min, Math.min(max, n));
+}
+
+function safeString(v) {
+  return typeof v === "string" && v.trim() ? v : null;
+}
+
+export function computeHoldExposureV1({ job, eventsBefore = [] } = {}) {
+  if (!job || typeof job !== "object") throw new TypeError("job is required");
+
+  const expectedSplits = computeExpectedSettlementSplitsV1({ job, eventsBefore });
+  if (!expectedSplits) return null;
+
+  const proofPolicy = job?.booking?.policySnapshot?.proofPolicy ?? null;
+  const gateModeRaw = safeString(proofPolicy?.gateMode) ?? "warn";
+  const gateMode = gateModeRaw === "strict" || gateModeRaw === "holdback" ? gateModeRaw : "warn";
+
+  const ieb = proofPolicy?.insufficientEvidenceBehavior ?? null;
+  const insufficientEvidenceMode = safeString(ieb?.mode) ?? "ALLOW";
+  const configuredHoldPercent = clampInt({ value: Number(ieb?.holdPercent ?? 0), min: 0, max: 100 });
+
+  const holdPercent =
+    gateMode === "holdback" && insufficientEvidenceMode === "HOLD_PERCENT" ? configuredHoldPercent : gateMode === "warn" ? 0 : 100;
+
+  const heldServiceAmountCents = Math.floor((expectedSplits.serviceAmountCents * holdPercent) / 100);
+  const heldCoverageFeeCents = Math.floor((expectedSplits.coverageFeeCents * holdPercent) / 100);
+  const heldPlatformFeeCents = Math.floor((expectedSplits.platformFeeCents * holdPercent) / 100);
+  const heldOperatorFeeCents = Math.floor((expectedSplits.operatorFeeCents * holdPercent) / 100);
+  const heldDeveloperRoyaltiesCents = Math.floor((expectedSplits.developerRoyaltiesCents * holdPercent) / 100);
+  const heldInsuranceReserveCents = Math.floor((expectedSplits.insuranceReserveCents * holdPercent) / 100);
+  const heldOwnerPayoutCents =
+    heldServiceAmountCents - heldPlatformFeeCents - heldOperatorFeeCents - heldDeveloperRoyaltiesCents - heldInsuranceReserveCents;
+
+  return {
+    expected: {
+      currency: safeString(expectedSplits.currency) ?? "USD",
+      amountGrossCents: expectedSplits.amountCents,
+      amountNetCents: expectedSplits.serviceAmountCents,
+      coverageFeeCents: expectedSplits.coverageFeeCents,
+      splits: {
+        platformFeeCents: expectedSplits.platformFeeCents,
+        ownerPayoutCents: expectedSplits.ownerPayoutCents,
+        operatorFeeCents: expectedSplits.operatorFeeCents,
+        developerRoyaltiesCents: expectedSplits.developerRoyaltiesCents,
+        insuranceReserveCents: expectedSplits.insuranceReserveCents
+      }
+    },
+    holdPolicy: {
+      gateMode,
+      insufficientEvidenceMode,
+      holdPercent
+    },
+    held: {
+      currency: safeString(expectedSplits.currency) ?? "USD",
+      amountGrossCents: heldServiceAmountCents + heldCoverageFeeCents,
+      amountNetCents: heldServiceAmountCents,
+      coverageFeeCents: heldCoverageFeeCents,
+      splits: {
+        platformFeeCents: heldPlatformFeeCents,
+        ownerPayoutCents: heldOwnerPayoutCents,
+        operatorFeeCents: heldOperatorFeeCents,
+        developerRoyaltiesCents: heldDeveloperRoyaltiesCents,
+        insuranceReserveCents: heldInsuranceReserveCents
+      }
+    }
+  };
+}
+