settld 0.1.0

package/src/core/settlement-kernel.js

@@ -0,0 +1,405 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V1 = "SettlementDecisionRecord.v1";
+export const SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V2 = "SettlementDecisionRecord.v2";
+export const SETTLEMENT_POLICY_NORMALIZATION_VERSION_V1 = "v1";
+// Back-compat constant for callers that treat "the decision record schema version" as a single value.
+export const SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION = SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V2;
+export const SETTLEMENT_RECEIPT_SCHEMA_VERSION = "SettlementReceipt.v1";
+
+export const SETTLEMENT_FINALITY_STATE = Object.freeze({
+  PENDING: "pending",
+  FINAL: "final"
+});
+
+export const SETTLEMENT_FINALITY_PROVIDER = Object.freeze({
+  INTERNAL_LEDGER: "internal_ledger"
+});
+
+export const SETTLEMENT_KERNEL_VERIFICATION_CODE = Object.freeze({
+  SETTLEMENT_MISSING: "settlement_missing",
+  SETTLEMENT_RUN_ID_MISMATCH: "settlement_run_id_mismatch",
+
+  DECISION_RECORD_MISSING: "decision_record_missing",
+  DECISION_RECORD_HASH_INVALID: "decision_record_hash_invalid",
+  DECISION_RECORD_HASH_MISMATCH: "decision_record_hash_mismatch",
+  DECISION_RECORD_RUN_ID_MISMATCH: "decision_record_run_id_mismatch",
+  DECISION_RECORD_SETTLEMENT_ID_MISMATCH: "decision_record_settlement_id_mismatch",
+  DECISION_RECORD_DECIDED_AT_INVALID: "decision_record_decided_at_invalid",
+  DECISION_RECORD_POLICY_HASH_USED_MISSING: "decision_record_policy_hash_used_missing",
+  DECISION_RECORD_POLICY_HASH_USED_INVALID: "decision_record_policy_hash_used_invalid",
+  DECISION_RECORD_POLICY_NORMALIZATION_VERSION_INVALID: "decision_record_policy_normalization_version_invalid",
+  DECISION_RECORD_VERIFICATION_METHOD_HASH_USED_INVALID: "decision_record_verification_method_hash_used_invalid",
+
+  SETTLEMENT_RECEIPT_MISSING: "settlement_receipt_missing",
+  SETTLEMENT_RECEIPT_HASH_INVALID: "settlement_receipt_hash_invalid",
+  SETTLEMENT_RECEIPT_HASH_MISMATCH: "settlement_receipt_hash_mismatch",
+  SETTLEMENT_RECEIPT_RUN_ID_MISMATCH: "settlement_receipt_run_id_mismatch",
+  SETTLEMENT_RECEIPT_SETTLEMENT_ID_MISMATCH: "settlement_receipt_settlement_id_mismatch",
+  SETTLEMENT_RECEIPT_DECISION_REF_MISSING: "settlement_receipt_decision_ref_missing",
+  SETTLEMENT_RECEIPT_DECISION_ID_MISMATCH: "settlement_receipt_decision_id_mismatch",
+  SETTLEMENT_RECEIPT_DECISION_HASH_MISMATCH: "settlement_receipt_decision_hash_mismatch",
+  SETTLEMENT_RECEIPT_CREATED_AT_INVALID: "settlement_receipt_created_at_invalid",
+  SETTLEMENT_RECEIPT_SETTLED_AT_INVALID: "settlement_receipt_settled_at_invalid",
+  SETTLEMENT_RECEIPT_BEFORE_DECISION: "settlement_receipt_before_decision",
+  SETTLEMENT_RECEIPT_SETTLED_BEFORE_DECISION: "settlement_receipt_settled_before_decision",
+  SETTLEMENT_RECEIPT_SETTLED_BEFORE_CREATED: "settlement_receipt_settled_before_created"
+});
+
+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 (allowNull && (value === null || value === undefined)) return;
+  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 normalizeTenantId(value, name) {
+  return normalizeId(value, name, { min: 1, max: 128 });
+}
+
+function normalizeHexHash(value, name, { allowNull = false } = {}) {
+  if (allowNull && (value === null || value === undefined)) return null;
+  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 assertNonNegativeSafeInt(value, name, { min = 0 } = {}) {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < min) throw new TypeError(`${name} must be a safe integer >= ${min}`);
+  return n;
+}
+
+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 computeKernelHash({ obj, hashField } = {}) {
+  assertPlainObject(obj, "obj");
+  assertNonEmptyString(hashField, "hashField");
+  const copy = { ...obj };
+  delete copy[hashField];
+  delete copy.artifactHash; // storage-level hash must not affect kernel binding
+  const normalized = normalizeForCanonicalJson(copy, { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function buildSettlementDecisionRecord({
+  schemaVersion = SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V2,
+  decisionId,
+  tenantId,
+  runId,
+  settlementId,
+  agreementId = null,
+  decisionStatus,
+  decisionMode,
+  decisionReason = null,
+  verificationStatus = null,
+  policyNormalizationVersion = undefined,
+  policyHashUsed,
+  verificationMethodHashUsed = undefined,
+  policyRef,
+  verifierRef,
+  runStatus = null,
+  runLastEventId = null,
+  runLastChainHash = null,
+  resolutionEventId = null,
+  decidedAt
+} = {}) {
+  assertIsoDate(decidedAt, "decidedAt");
+  const resolvedSchemaVersion = String(schemaVersion ?? "").trim();
+  if (resolvedSchemaVersion !== SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V1 && resolvedSchemaVersion !== SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V2) {
+    throw new TypeError("schemaVersion must be SettlementDecisionRecord.v1 or SettlementDecisionRecord.v2");
+  }
+  const normalized = normalizeForCanonicalJson(
+    {
+      schemaVersion: resolvedSchemaVersion,
+      decisionId: normalizeId(decisionId, "decisionId", { min: 1, max: 200 }),
+      tenantId: normalizeTenantId(tenantId, "tenantId"),
+      runId: normalizeId(runId, "runId", { min: 1, max: 128 }),
+      settlementId: normalizeId(settlementId, "settlementId", { min: 1, max: 200 }),
+      agreementId: agreementId === null ? null : String(agreementId),
+      decisionStatus: String(decisionStatus ?? "").trim(),
+      decisionMode: String(decisionMode ?? "").trim(),
+      decisionReason: decisionReason === null ? null : String(decisionReason),
+      verificationStatus: verificationStatus === null ? null : String(verificationStatus),
+      ...(resolvedSchemaVersion === SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V2
+        ? {
+            policyNormalizationVersion:
+              policyNormalizationVersion === undefined
+                ? SETTLEMENT_POLICY_NORMALIZATION_VERSION_V1
+                : String(policyNormalizationVersion ?? "").trim(),
+            policyHashUsed: normalizeHexHash(policyHashUsed, "policyHashUsed", { allowNull: false }),
+            ...(verificationMethodHashUsed === null || verificationMethodHashUsed === undefined
+              ? {}
+              : {
+                  verificationMethodHashUsed: normalizeHexHash(verificationMethodHashUsed, "verificationMethodHashUsed", {
+                    allowNull: false
+                  })
+                })
+          }
+        : {}),
+      policyRef: {
+        policyHash: normalizeHexHash(policyRef?.policyHash, "policyRef.policyHash", { allowNull: true }),
+        verificationMethodHash: normalizeHexHash(policyRef?.verificationMethodHash, "policyRef.verificationMethodHash", { allowNull: true })
+      },
+      verifierRef: {
+        verifierId: verifierRef?.verifierId === null || verifierRef?.verifierId === undefined ? null : String(verifierRef.verifierId),
+        verifierVersion: verifierRef?.verifierVersion === null || verifierRef?.verifierVersion === undefined ? null : String(verifierRef.verifierVersion),
+        verifierHash: normalizeHexHash(verifierRef?.verifierHash, "verifierRef.verifierHash", { allowNull: true }),
+        modality: verifierRef?.modality === null || verifierRef?.modality === undefined ? null : String(verifierRef.modality)
+      },
+      workRef: {
+        runStatus: runStatus === null ? null : String(runStatus),
+        runLastEventId: runLastEventId === null ? null : String(runLastEventId),
+        runLastChainHash: runLastChainHash === null ? null : String(runLastChainHash),
+        resolutionEventId: resolutionEventId === null ? null : String(resolutionEventId)
+      },
+      decidedAt: String(decidedAt)
+    },
+    { path: "$" }
+  );
+
+  const decisionHash = computeKernelHash({ obj: normalized, hashField: "decisionHash" });
+  return normalizeForCanonicalJson({ ...normalized, decisionHash }, { path: "$" });
+}
+
+export function buildSettlementDecisionRecordV1(args) {
+  return buildSettlementDecisionRecord({ ...args, schemaVersion: SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V1 });
+}
+
+export function buildSettlementDecisionRecordV2(args) {
+  return buildSettlementDecisionRecord({ ...args, schemaVersion: SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V2 });
+}
+
+export function buildSettlementReceipt({
+  receiptId,
+  tenantId,
+  runId,
+  settlementId,
+  decisionRecord,
+  status,
+  amountCents,
+  releasedAmountCents,
+  refundedAmountCents,
+  releaseRatePct,
+  currency,
+  runStatus = null,
+  resolutionEventId = null,
+  finalityProvider = SETTLEMENT_FINALITY_PROVIDER.INTERNAL_LEDGER,
+  finalityState = undefined,
+  settledAt = null,
+  createdAt
+} = {}) {
+  assertPlainObject(decisionRecord, "decisionRecord");
+  assertIsoDate(createdAt, "createdAt");
+  assertIsoDate(settledAt, "settledAt", { allowNull: true });
+  const resolvedFinalityState =
+    finalityState === undefined || finalityState === null
+      ? String(status ?? "").trim().toLowerCase() === "locked"
+        ? SETTLEMENT_FINALITY_STATE.PENDING
+        : SETTLEMENT_FINALITY_STATE.FINAL
+      : String(finalityState);
+  const normalized = normalizeForCanonicalJson(
+    {
+      schemaVersion: SETTLEMENT_RECEIPT_SCHEMA_VERSION,
+      receiptId: normalizeId(receiptId, "receiptId", { min: 1, max: 200 }),
+      tenantId: normalizeTenantId(tenantId, "tenantId"),
+      runId: normalizeId(runId, "runId", { min: 1, max: 128 }),
+      settlementId: normalizeId(settlementId, "settlementId", { min: 1, max: 200 }),
+      decisionRef: {
+        decisionId: normalizeId(decisionRecord.decisionId, "decisionRecord.decisionId", { min: 1, max: 200 }),
+        decisionHash: normalizeHexHash(decisionRecord.decisionHash, "decisionRecord.decisionHash")
+      },
+      status: String(status ?? "").trim(),
+      amountCents: assertNonNegativeSafeInt(amountCents, "amountCents", { min: 1 }),
+      releasedAmountCents: assertNonNegativeSafeInt(releasedAmountCents, "releasedAmountCents", { min: 0 }),
+      refundedAmountCents: assertNonNegativeSafeInt(refundedAmountCents, "refundedAmountCents", { min: 0 }),
+      releaseRatePct: assertNonNegativeSafeInt(releaseRatePct, "releaseRatePct", { min: 0 }),
+      currency: normalizeCurrency(currency, "currency"),
+      runStatus: runStatus === null ? null : String(runStatus),
+      resolutionEventId: resolutionEventId === null ? null : String(resolutionEventId),
+      finalityProvider: String(finalityProvider ?? SETTLEMENT_FINALITY_PROVIDER.INTERNAL_LEDGER),
+      finalityState: resolvedFinalityState,
+      settledAt: settledAt === null ? null : String(settledAt),
+      createdAt: String(createdAt)
+    },
+    { path: "$" }
+  );
+
+  const receiptHash = computeKernelHash({ obj: normalized, hashField: "receiptHash" });
+  return normalizeForCanonicalJson({ ...normalized, receiptHash }, { path: "$" });
+}
+
+export function buildSettlementReceiptV1(args) {
+  return buildSettlementReceipt(args);
+}
+
+export function extractSettlementKernelArtifacts(settlement) {
+  if (!settlement || typeof settlement !== "object" || Array.isArray(settlement)) {
+    return { decisionRecord: null, settlementReceipt: null };
+  }
+  const trace = settlement.decisionTrace;
+  if (!trace || typeof trace !== "object" || Array.isArray(trace)) {
+    return { decisionRecord: null, settlementReceipt: null };
+  }
+  return {
+    decisionRecord: trace.decisionRecord ?? null,
+    settlementReceipt: trace.settlementReceipt ?? null
+  };
+}
+
+export function verifySettlementKernelArtifacts({ settlement, runId = null } = {}) {
+  const errors = [];
+  if (!settlement || typeof settlement !== "object" || Array.isArray(settlement)) {
+    return { valid: false, errors: [SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_MISSING] };
+  }
+
+  const settlementRunId = typeof settlement.runId === "string" ? settlement.runId : null;
+  if (runId !== null && runId !== undefined && String(runId) !== String(settlementRunId ?? "")) {
+    errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RUN_ID_MISMATCH);
+  }
+
+  const { decisionRecord, settlementReceipt } = extractSettlementKernelArtifacts(settlement);
+
+  let decidedAtMs = Number.NaN;
+  if (!decisionRecord || typeof decisionRecord !== "object" || Array.isArray(decisionRecord)) {
+    errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_MISSING);
+  } else {
+    const schemaVersion = typeof decisionRecord.schemaVersion === "string" ? decisionRecord.schemaVersion : "";
+    if (schemaVersion === SETTLEMENT_DECISION_RECORD_SCHEMA_VERSION_V2) {
+      const normVersionRaw = decisionRecord.policyNormalizationVersion;
+      if (normVersionRaw !== undefined) {
+        const normVersion = typeof normVersionRaw === "string" ? normVersionRaw.trim() : "";
+        if (!normVersion || normVersion.length > 64) {
+          errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_POLICY_NORMALIZATION_VERSION_INVALID);
+        }
+      }
+      const policyHashUsed = typeof decisionRecord.policyHashUsed === "string" ? decisionRecord.policyHashUsed.trim().toLowerCase() : "";
+      if (!policyHashUsed) {
+        errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_POLICY_HASH_USED_MISSING);
+      } else if (!/^[0-9a-f]{64}$/.test(policyHashUsed)) {
+        errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_POLICY_HASH_USED_INVALID);
+      }
+      const methodHashUsedRaw = decisionRecord.verificationMethodHashUsed;
+      if (methodHashUsedRaw !== undefined) {
+        const methodHashUsed = typeof methodHashUsedRaw === "string" ? methodHashUsedRaw.trim().toLowerCase() : "";
+        if (!methodHashUsed || !/^[0-9a-f]{64}$/.test(methodHashUsed)) {
+          errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_VERIFICATION_METHOD_HASH_USED_INVALID);
+        }
+      }
+    }
+
+    const decisionHashRaw = decisionRecord.decisionHash;
+    const decisionHash = typeof decisionHashRaw === "string" ? decisionHashRaw.trim().toLowerCase() : "";
+    if (!/^[0-9a-f]{64}$/.test(decisionHash)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_HASH_INVALID);
+    } else {
+      try {
+        const computed = computeKernelHash({ obj: decisionRecord, hashField: "decisionHash" });
+        if (computed !== decisionHash) errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_HASH_MISMATCH);
+      } catch {
+        errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_HASH_INVALID);
+      }
+    }
+
+    if (settlementRunId && String(decisionRecord.runId ?? "") !== String(settlementRunId)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_RUN_ID_MISMATCH);
+    }
+    if (settlement.settlementId && String(decisionRecord.settlementId ?? "") !== String(settlement.settlementId)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_SETTLEMENT_ID_MISMATCH);
+    }
+
+    const decidedAt = decisionRecord.decidedAt;
+    decidedAtMs = typeof decidedAt === "string" && Number.isFinite(Date.parse(decidedAt)) ? Date.parse(decidedAt) : Number.NaN;
+    if (!Number.isFinite(decidedAtMs)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.DECISION_RECORD_DECIDED_AT_INVALID);
+    }
+  }
+
+  if (!settlementReceipt || typeof settlementReceipt !== "object" || Array.isArray(settlementReceipt)) {
+    errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_MISSING);
+  } else {
+    const receiptHashRaw = settlementReceipt.receiptHash;
+    const receiptHash = typeof receiptHashRaw === "string" ? receiptHashRaw.trim().toLowerCase() : "";
+    if (!/^[0-9a-f]{64}$/.test(receiptHash)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_HASH_INVALID);
+    } else {
+      try {
+        const computed = computeKernelHash({ obj: settlementReceipt, hashField: "receiptHash" });
+        if (computed !== receiptHash) errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_HASH_MISMATCH);
+      } catch {
+        errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_HASH_INVALID);
+      }
+    }
+
+    if (settlementRunId && String(settlementReceipt.runId ?? "") !== String(settlementRunId)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_RUN_ID_MISMATCH);
+    }
+    if (settlement.settlementId && String(settlementReceipt.settlementId ?? "") !== String(settlement.settlementId)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_SETTLEMENT_ID_MISMATCH);
+    }
+
+    const decisionRef = settlementReceipt.decisionRef;
+    if (!decisionRef || typeof decisionRef !== "object" || Array.isArray(decisionRef)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_DECISION_REF_MISSING);
+    } else if (decisionRecord && typeof decisionRecord === "object" && !Array.isArray(decisionRecord)) {
+      if (String(decisionRef.decisionId ?? "") !== String(decisionRecord.decisionId ?? "")) {
+        errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_DECISION_ID_MISMATCH);
+      }
+      if (String(decisionRef.decisionHash ?? "") !== String(decisionRecord.decisionHash ?? "")) {
+        errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_DECISION_HASH_MISMATCH);
+      }
+    }
+
+    const createdAt = settlementReceipt.createdAt;
+    const createdAtMs = typeof createdAt === "string" && Number.isFinite(Date.parse(createdAt)) ? Date.parse(createdAt) : Number.NaN;
+    if (!Number.isFinite(createdAtMs)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_CREATED_AT_INVALID);
+    } else if (Number.isFinite(decidedAtMs) && createdAtMs < decidedAtMs) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_BEFORE_DECISION);
+    }
+
+    const settledAt = settlementReceipt.settledAt;
+    const settledAtMs =
+      settledAt === null || settledAt === undefined
+        ? Number.NaN
+        : typeof settledAt === "string" && Number.isFinite(Date.parse(settledAt))
+          ? Date.parse(settledAt)
+          : Number.NaN;
+    if (settledAt !== null && settledAt !== undefined && !Number.isFinite(settledAtMs)) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_SETTLED_AT_INVALID);
+    }
+    if (Number.isFinite(settledAtMs) && Number.isFinite(decidedAtMs) && settledAtMs < decidedAtMs) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_SETTLED_BEFORE_DECISION);
+    }
+    if (Number.isFinite(settledAtMs) && Number.isFinite(createdAtMs) && settledAtMs < createdAtMs) {
+      errors.push(SETTLEMENT_KERNEL_VERIFICATION_CODE.SETTLEMENT_RECEIPT_SETTLED_BEFORE_CREATED);
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/core/settlement-policy.js

@@ -0,0 +1,206 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+
+export const VERIFICATION_METHOD_SCHEMA_VERSION = "VerificationMethod.v1";
+export const SETTLEMENT_POLICY_SCHEMA_VERSION = "SettlementPolicy.v1";
+
+export const VERIFICATION_METHOD_MODE = Object.freeze({
+  DETERMINISTIC: "deterministic",
+  ATTESTED: "attested",
+  DISCRETIONARY: "discretionary"
+});
+
+export const SETTLEMENT_POLICY_MODE = Object.freeze({
+  AUTOMATIC: "automatic",
+  MANUAL_REVIEW: "manual-review"
+});
+
+const ALLOWED_METHOD_MODES = new Set(Object.values(VERIFICATION_METHOD_MODE));
+const ALLOWED_POLICY_MODES = new Set(Object.values(SETTLEMENT_POLICY_MODE));
+const ALLOWED_VERIFICATION_STATUSES = new Set(["green", "amber", "red"]);
+
+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 normalizeNullableString(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+function normalizeOptionalSafeInt(value, { min = 0, max = Number.MAX_SAFE_INTEGER } = {}) {
+  if (value === null || value === undefined || value === "") return null;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed)) throw new TypeError("expected a safe integer");
+  if (parsed < min || parsed > max) throw new TypeError(`expected integer in range ${min}..${max}`);
+  return parsed;
+}
+
+function normalizeReleaseRatePct(value, fallback) {
+  if (value === null || value === undefined || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0 || parsed > 100) {
+    throw new TypeError("releaseRatePct must be an integer within 0..100");
+  }
+  return parsed;
+}
+
+export function normalizeVerificationMethod(input, { defaultMode = VERIFICATION_METHOD_MODE.DETERMINISTIC } = {}) {
+  const raw = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const modeRaw = normalizeNullableString(raw.mode);
+  const mode = (modeRaw ?? String(defaultMode)).toLowerCase();
+  if (!ALLOWED_METHOD_MODES.has(mode)) {
+    throw new TypeError("verificationMethod.mode must be deterministic|attested|discretionary");
+  }
+  const method = normalizeForCanonicalJson(
+    {
+      schemaVersion: VERIFICATION_METHOD_SCHEMA_VERSION,
+      mode,
+      source: normalizeNullableString(raw.source),
+      attestor: normalizeNullableString(raw.attestor),
+      notes: normalizeNullableString(raw.notes)
+    },
+    { path: "$" }
+  );
+  return method;
+}
+
+export function normalizeSettlementPolicy(input) {
+  const raw = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const modeRaw = normalizeNullableString(raw.mode);
+  const mode = (modeRaw ?? SETTLEMENT_POLICY_MODE.AUTOMATIC).toLowerCase();
+  if (!ALLOWED_POLICY_MODES.has(mode)) {
+    throw new TypeError("policy.mode must be automatic|manual-review");
+  }
+
+  const policyVersionRaw = raw.policyVersion ?? raw.version ?? 1;
+  const policyVersion = normalizeOptionalSafeInt(policyVersionRaw, { min: 1 });
+  if (policyVersion === null) throw new TypeError("policyVersion must be a positive safe integer");
+
+  const rulesRaw = raw.rules && typeof raw.rules === "object" && !Array.isArray(raw.rules) ? raw.rules : {};
+  const policy = normalizeForCanonicalJson(
+    {
+      schemaVersion: SETTLEMENT_POLICY_SCHEMA_VERSION,
+      policyVersion,
+      mode,
+      rules: {
+        requireDeterministicVerification: rulesRaw.requireDeterministicVerification === true,
+        autoReleaseOnGreen: rulesRaw.autoReleaseOnGreen !== false,
+        autoReleaseOnAmber: rulesRaw.autoReleaseOnAmber === true,
+        autoReleaseOnRed: rulesRaw.autoReleaseOnRed === true,
+        greenReleaseRatePct: normalizeReleaseRatePct(rulesRaw.greenReleaseRatePct, 100),
+        amberReleaseRatePct: normalizeReleaseRatePct(rulesRaw.amberReleaseRatePct, 50),
+        redReleaseRatePct: normalizeReleaseRatePct(rulesRaw.redReleaseRatePct, 0),
+        maxAutoReleaseAmountCents: normalizeOptionalSafeInt(rulesRaw.maxAutoReleaseAmountCents, { min: 1 }),
+        disputeWindowHours: normalizeOptionalSafeInt(rulesRaw.disputeWindowHours, { min: 1, max: 24 * 365 }),
+        manualReason: normalizeNullableString(rulesRaw.manualReason)
+      }
+    },
+    { path: "$" }
+  );
+  return policy;
+}
+
+export function computeSettlementPolicyHash(policy) {
+  assertPlainObject(policy, "policy");
+  if (policy.schemaVersion !== SETTLEMENT_POLICY_SCHEMA_VERSION) {
+    throw new TypeError(`policy.schemaVersion must be ${SETTLEMENT_POLICY_SCHEMA_VERSION}`);
+  }
+  return sha256Hex(canonicalJsonStringify(policy));
+}
+
+export function computeVerificationMethodHash(method) {
+  assertPlainObject(method, "verificationMethod");
+  if (method.schemaVersion !== VERIFICATION_METHOD_SCHEMA_VERSION) {
+    throw new TypeError(`verificationMethod.schemaVersion must be ${VERIFICATION_METHOD_SCHEMA_VERSION}`);
+  }
+  return sha256Hex(canonicalJsonStringify(method));
+}
+
+function computeReleaseAmounts({ amountCents, releaseRatePct }) {
+  if (!Number.isSafeInteger(amountCents) || amountCents <= 0) throw new TypeError("amountCents must be a positive safe integer");
+  if (!Number.isSafeInteger(releaseRatePct) || releaseRatePct < 0 || releaseRatePct > 100) {
+    throw new TypeError("releaseRatePct must be an integer within 0..100");
+  }
+  const releaseAmountCents = releaseRatePct <= 0 ? 0 : Math.min(amountCents, Math.floor((amountCents * releaseRatePct) / 100));
+  const refundAmountCents = amountCents - releaseAmountCents;
+  return { releaseAmountCents, refundAmountCents };
+}
+
+export function evaluateSettlementPolicy({ policy, verificationMethod, verificationStatus, runStatus, amountCents }) {
+  const normalizedPolicy = normalizeSettlementPolicy(policy);
+  const normalizedMethod = normalizeVerificationMethod(verificationMethod);
+  const status = String(verificationStatus ?? "").trim().toLowerCase();
+  if (!ALLOWED_VERIFICATION_STATUSES.has(status)) {
+    throw new TypeError("verificationStatus must be green|amber|red");
+  }
+  const normalizedRunStatus = String(runStatus ?? "").trim().toLowerCase();
+  if (normalizedRunStatus !== "completed" && normalizedRunStatus !== "failed") {
+    throw new TypeError("runStatus must be completed|failed");
+  }
+  if (!Number.isSafeInteger(Number(amountCents)) || Number(amountCents) <= 0) {
+    throw new TypeError("amountCents must be a positive safe integer");
+  }
+  const settlementAmountCents = Number(amountCents);
+
+  const reasons = [];
+  if (normalizedPolicy.mode === SETTLEMENT_POLICY_MODE.MANUAL_REVIEW) {
+    reasons.push("policy_mode_manual_review");
+  }
+  if (
+    normalizedPolicy.rules.requireDeterministicVerification &&
+    normalizedMethod.mode !== VERIFICATION_METHOD_MODE.DETERMINISTIC
+  ) {
+    reasons.push("verification_method_not_deterministic");
+  }
+  if (
+    normalizedPolicy.rules.maxAutoReleaseAmountCents !== null &&
+    settlementAmountCents > normalizedPolicy.rules.maxAutoReleaseAmountCents
+  ) {
+    reasons.push("amount_exceeds_auto_release_limit");
+  }
+
+  let releaseRatePct;
+  if (status === "green") releaseRatePct = normalizedPolicy.rules.greenReleaseRatePct;
+  else if (status === "amber") releaseRatePct = normalizedPolicy.rules.amberReleaseRatePct;
+  else releaseRatePct = normalizedPolicy.rules.redReleaseRatePct;
+
+  const autoEnabled =
+    status === "green"
+      ? normalizedPolicy.rules.autoReleaseOnGreen
+      : status === "amber"
+        ? normalizedPolicy.rules.autoReleaseOnAmber
+        : normalizedPolicy.rules.autoReleaseOnRed;
+  if (!autoEnabled) {
+    reasons.push(`auto_release_disabled_for_${status}`);
+  }
+
+  if (normalizedRunStatus === "failed") {
+    releaseRatePct = 0;
+  }
+
+  const { releaseAmountCents, refundAmountCents } = computeReleaseAmounts({
+    amountCents: settlementAmountCents,
+    releaseRatePct
+  });
+
+  const shouldAutoResolve = reasons.length === 0;
+  return {
+    policy: normalizedPolicy,
+    verificationMethod: normalizedMethod,
+    decisionMode: shouldAutoResolve ? SETTLEMENT_POLICY_MODE.AUTOMATIC : SETTLEMENT_POLICY_MODE.MANUAL_REVIEW,
+    shouldAutoResolve,
+    reasonCodes: reasons,
+    releaseRatePct,
+    releaseAmountCents,
+    refundAmountCents,
+    settlementStatus: releaseAmountCents > 0 ? "released" : "refunded",
+    verificationStatus: status,
+    runStatus: normalizedRunStatus
+  };
+}

package/src/core/settlement-splits.js

@@ -0,0 +1,46 @@
+import { sumSkillLicenseFeesCents } from "./skills.js";
+
+function assertSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer`);
+}
+
+export function computeSettlementSplitsV1({ amountCents, coverageFeeCents, hadAssist, developerRoyaltiesCents }) {
+  assertSafeInteger(amountCents, "amountCents");
+  assertSafeInteger(coverageFeeCents, "coverageFeeCents");
+  if (coverageFeeCents < 0) throw new TypeError("coverageFeeCents must be >= 0");
+  if (coverageFeeCents > amountCents) throw new TypeError("coverageFeeCents exceeds amountCents");
+  assertSafeInteger(developerRoyaltiesCents, "developerRoyaltiesCents");
+
+  const serviceAmountCents = amountCents - coverageFeeCents;
+
+  const platformFeeCents = Math.floor(serviceAmountCents * 0.2);
+  const insuranceReserveCents = Math.floor(serviceAmountCents * 0.02);
+  const operatorFeeCents = hadAssist ? Math.floor(serviceAmountCents * 0.05) : 0;
+  const ownerPayoutCents = serviceAmountCents - platformFeeCents - operatorFeeCents - developerRoyaltiesCents - insuranceReserveCents;
+  if (ownerPayoutCents < 0) {
+    throw new TypeError("settlement splits invalid: owner payout would be negative");
+  }
+
+  return {
+    amountCents,
+    serviceAmountCents,
+    coverageFeeCents,
+    platformFeeCents,
+    ownerPayoutCents,
+    operatorFeeCents,
+    developerRoyaltiesCents,
+    insuranceReserveCents
+  };
+}
+
+export function computeExpectedSettlementSplitsV1({ job, eventsBefore = [] } = {}) {
+  if (!job || typeof job !== "object") throw new TypeError("job is required");
+  const amountCents = job?.quote?.amountCents ?? null;
+  if (!Number.isSafeInteger(amountCents)) return null;
+  const currency = typeof job?.quote?.currency === "string" && job.quote.currency.trim() ? job.quote.currency : "USD";
+  const coverageFeeCentsRaw = job?.quote?.breakdown?.coverageFeeCents ?? 0;
+  const coverageFeeCents = Number.isSafeInteger(coverageFeeCentsRaw) && coverageFeeCentsRaw >= 0 ? coverageFeeCentsRaw : 0;
+  const hadAssist = Array.isArray(eventsBefore) && eventsBefore.some((e) => e?.type === "ASSIST_STARTED");
+  const developerRoyaltiesCents = sumSkillLicenseFeesCents(job?.skillLicenses ?? []);
+  return { currency, ...computeSettlementSplitsV1({ amountCents, coverageFeeCents, hadAssist, developerRoyaltiesCents }) };
+}