settld 0.1.0

package/src/core/allocations.js

@@ -0,0 +1,160 @@
+import { normalizeTenantId, DEFAULT_TENANT_ID } from "./tenancy.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`);
+  }
+}
+
+function isHexSha256(value) {
+  return typeof value === "string" && /^[a-f0-9]{64}$/i.test(value);
+}
+
+export const PARTY_ROLE = Object.freeze({
+  PLATFORM: "platform",
+  OPERATOR: "operator",
+  CUSTOMER: "customer",
+  SUBCONTRACTOR: "subcontractor",
+  INSURER: "insurer"
+});
+
+function defaultPartyRoleForAccountId(accountId) {
+  const id = String(accountId ?? "");
+
+  if (id.startsWith("acct_customer_")) return PARTY_ROLE.CUSTOMER;
+  if (id.includes("insurer_")) return PARTY_ROLE.INSURER;
+  if (id.includes("coverage_reserve")) return PARTY_ROLE.INSURER;
+  if (id.includes("developer_")) return PARTY_ROLE.SUBCONTRACTOR;
+  if (id.includes("operator_") || id.includes("owner_payable") || id.includes("operator_payable")) return PARTY_ROLE.OPERATOR;
+  if (id.includes("owner_") || id.includes("operator_")) return PARTY_ROLE.OPERATOR;
+  return PARTY_ROLE.PLATFORM;
+}
+
+function partyIdFromContractDoc({ role, contractDoc }) {
+  if (!contractDoc || typeof contractDoc !== "object") return null;
+  const parties = contractDoc.parties ?? null;
+  if (!parties || typeof parties !== "object") return null;
+  const p = parties[role] ?? null;
+  if (!p || typeof p !== "object") return null;
+  const id = p.partyId ?? null;
+  if (typeof id !== "string" || id.trim() === "") return null;
+  return String(id);
+}
+
+function defaultPartyIdForRole({ role, job }) {
+  if (role === PARTY_ROLE.PLATFORM) return "pty_platform";
+  if (role === PARTY_ROLE.OPERATOR) {
+    const operatorId = job?.operatorCoverage?.operatorId ?? job?.assist?.operatorId ?? null;
+    if (typeof operatorId === "string" && operatorId.trim() !== "") return `pty_operator:${operatorId}`;
+    return "pty_operator";
+  }
+  if (role === PARTY_ROLE.CUSTOMER) {
+    const customerId = job?.customerId ?? job?.booking?.customerId ?? null;
+    if (typeof customerId === "string" && customerId.trim() !== "") return `pty_customer:${customerId}`;
+    return "pty_customer";
+  }
+  if (role === PARTY_ROLE.INSURER) {
+    const insurerId =
+      job?.booking?.policySnapshot?.coveragePolicy?.insurerId ??
+      job?.booking?.coveragePolicy?.insurerId ??
+      null;
+    if (typeof insurerId === "string" && insurerId.trim() !== "") return `pty_insurer:${insurerId}`;
+    return "pty_insurer";
+  }
+  if (role === PARTY_ROLE.SUBCONTRACTOR) return "pty_subcontractor";
+  return "pty_unknown";
+}
+
+function resolvePartyId({ role, job, contractDoc }) {
+  const fromDoc = partyIdFromContractDoc({ role, contractDoc });
+  if (fromDoc) return fromDoc;
+  return defaultPartyIdForRole({ role, job });
+}
+
+export function allocateEntry({ tenantId = DEFAULT_TENANT_ID, entry, job, operatorContractDoc = null, currency = "USD" } = {}) {
+  tenantId = normalizeTenantId(tenantId);
+  assertPlainObject(entry, "entry");
+  assertNonEmptyString(entry.id, "entry.id");
+  if (!Array.isArray(entry.postings) || entry.postings.length < 2) throw new TypeError("entry.postings must be an array of at least 2 items");
+  if (!job || typeof job !== "object") throw new TypeError("job is required");
+
+  const allocations = [];
+
+  for (let i = 0; i < entry.postings.length; i += 1) {
+    const posting = entry.postings[i];
+    if (!posting || typeof posting !== "object") throw new TypeError("posting must be an object");
+    assertNonEmptyString(posting.accountId, "posting.accountId");
+    if (!Number.isSafeInteger(posting.amountCents)) throw new TypeError("posting.amountCents must be a safe integer");
+    if (posting.amountCents === 0) throw new TypeError("posting.amountCents must be non-zero");
+
+    const role = defaultPartyRoleForAccountId(posting.accountId);
+
+    // Coverage reserve postings can be attributed to the insurer only when an insurer is configured.
+    let effectiveRole = role;
+    if (role === PARTY_ROLE.INSURER) {
+      const insurerId =
+        job?.booking?.policySnapshot?.coveragePolicy?.insurerId ??
+        job?.booking?.coveragePolicy?.insurerId ??
+        null;
+      if (insurerId === null || insurerId === undefined || String(insurerId).trim() === "") {
+        effectiveRole = PARTY_ROLE.PLATFORM;
+      }
+    }
+
+    const partyId = resolvePartyId({ role: effectiveRole, job, contractDoc: operatorContractDoc });
+    allocations.push({
+      tenantId,
+      entryId: entry.id,
+      postingId: `p${i}`,
+      accountId: posting.accountId,
+      partyId,
+      partyRole: effectiveRole,
+      currency,
+      amountCents: posting.amountCents
+    });
+  }
+
+  verifyAllocationInvariants({ entry, allocations });
+  return allocations;
+}
+
+export function verifyAllocationInvariants({ entry, allocations }) {
+  assertPlainObject(entry, "entry");
+  if (!Array.isArray(entry.postings)) throw new TypeError("entry.postings is required");
+  if (!Array.isArray(allocations)) throw new TypeError("allocations must be an array");
+
+  const byPostingId = new Map();
+  for (const a of allocations) {
+    if (!a || typeof a !== "object") throw new TypeError("allocation must be an object");
+    assertNonEmptyString(a.postingId, "allocation.postingId");
+    if (!Number.isSafeInteger(a.amountCents)) throw new TypeError("allocation.amountCents must be a safe integer");
+    const list = byPostingId.get(a.postingId) ?? [];
+    list.push(a);
+    byPostingId.set(a.postingId, list);
+  }
+
+  for (let i = 0; i < entry.postings.length; i += 1) {
+    const postingId = `p${i}`;
+    const posting = entry.postings[i];
+    const list = byPostingId.get(postingId) ?? [];
+    const sum = list.reduce((acc, a) => acc + a.amountCents, 0);
+    if (sum !== posting.amountCents) {
+      throw new Error(`allocation sum ${sum} !== posting amount ${posting.amountCents} for ${postingId}`);
+    }
+  }
+
+  // Overall entry invariants: if each posting's allocations sum correctly, the entry still nets to zero.
+  return true;
+}
+
+export function assertOperatorPinShape({ operatorContractHash, operatorPolicyHash, operatorCompilerId }) {
+  if (operatorContractHash === null && operatorPolicyHash === null && operatorCompilerId === null) return;
+  if (!isHexSha256(operatorContractHash)) throw new TypeError("operatorContractHash must be a 64-byte hex sha256");
+  if (!isHexSha256(operatorPolicyHash)) throw new TypeError("operatorPolicyHash must be a 64-byte hex sha256");
+  if (operatorCompilerId !== null && operatorCompilerId !== undefined) assertNonEmptyString(operatorCompilerId, "operatorCompilerId");
+}

package/src/core/artifact-verification-status.js

@@ -0,0 +1,216 @@
+import { PROOF_STATUS } from "./proof.js";
+
+export const ARTIFACT_VERIFICATION_STATUS = Object.freeze({
+  GREEN: "green",
+  AMBER: "amber",
+  RED: "red"
+});
+
+function asPositiveIntegerOrNull(value) {
+  if (value === null || value === undefined) return null;
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) return null;
+  return parsed;
+}
+
+function normalizeReasonCodes(reasonCodes) {
+  if (!Array.isArray(reasonCodes)) return [];
+  const out = [];
+  for (const value of reasonCodes) {
+    if (typeof value !== "string") continue;
+    const code = value.trim();
+    if (!code) continue;
+    out.push(code);
+  }
+  return out;
+}
+
+function normalizeMissingEvidence(missingEvidence) {
+  if (!Array.isArray(missingEvidence)) return [];
+  const out = [];
+  for (const value of missingEvidence) {
+    if (typeof value !== "string") continue;
+    const token = value.trim();
+    if (!token) continue;
+    out.push(token);
+  }
+  return out;
+}
+
+function normalizeMetrics(metricsRaw) {
+  const metrics = metricsRaw && typeof metricsRaw === "object" && !Array.isArray(metricsRaw) ? metricsRaw : {};
+  return {
+    requiredZones: asPositiveIntegerOrNull(metrics.requiredZones),
+    reportedZones: asPositiveIntegerOrNull(metrics.reportedZones),
+    excusedZones: asPositiveIntegerOrNull(metrics.excusedZones),
+    belowThresholdZones: asPositiveIntegerOrNull(metrics.belowThresholdZones),
+    minCoveragePct: asPositiveIntegerOrNull(metrics.minCoveragePct)
+  };
+}
+
+function normalizeProofStatus(statusRaw) {
+  if (typeof statusRaw !== "string" || !statusRaw.trim()) return null;
+  const status = statusRaw.trim().toUpperCase();
+  if (status === PROOF_STATUS.PASS) return PROOF_STATUS.PASS;
+  if (status === PROOF_STATUS.FAIL) return PROOF_STATUS.FAIL;
+  if (status === PROOF_STATUS.INSUFFICIENT_EVIDENCE) return PROOF_STATUS.INSUFFICIENT_EVIDENCE;
+  return null;
+}
+
+function mapProofStatusToVerificationStatus(proofStatus) {
+  if (proofStatus === PROOF_STATUS.PASS) return ARTIFACT_VERIFICATION_STATUS.GREEN;
+  if (proofStatus === PROOF_STATUS.FAIL) return ARTIFACT_VERIFICATION_STATUS.RED;
+  return ARTIFACT_VERIFICATION_STATUS.AMBER;
+}
+
+function countMissingZoneCoverageEvidence(missingEvidence) {
+  if (!Array.isArray(missingEvidence)) return 0;
+  let count = 0;
+  for (const token of missingEvidence) {
+    const text = typeof token === "string" ? token.trim().toUpperCase() : "";
+    if (!text) continue;
+    if (text.startsWith("ZONE_COVERAGE:")) count += 1;
+  }
+  return count;
+}
+
+function extractProofSignalsFromArtifact(artifact) {
+  if (!artifact || typeof artifact !== "object") return null;
+
+  const fromProof = artifact.proof;
+  if (fromProof && typeof fromProof === "object" && !Array.isArray(fromProof)) {
+    return {
+      source: "artifact.proof",
+      status: normalizeProofStatus(fromProof.status),
+      reasonCodes: normalizeReasonCodes(fromProof.reasonCodes),
+      missingEvidence: normalizeMissingEvidence(fromProof.missingEvidence),
+      metrics: normalizeMetrics(fromProof.metrics),
+      evaluatedAt: typeof fromProof.evaluatedAt === "string" ? fromProof.evaluatedAt : null,
+      evaluatedAtChainHash: typeof fromProof.evaluatedAtChainHash === "string" ? fromProof.evaluatedAtChainHash : null
+    };
+  }
+
+  const fromProofReceipt = artifact.proofReceipt;
+  if (fromProofReceipt && typeof fromProofReceipt === "object" && !Array.isArray(fromProofReceipt)) {
+    return {
+      source: "artifact.proofReceipt",
+      status: normalizeProofStatus(fromProofReceipt.status),
+      reasonCodes: normalizeReasonCodes(fromProofReceipt.reasonCodes),
+      missingEvidence: normalizeMissingEvidence(fromProofReceipt.missingEvidence),
+      metrics: normalizeMetrics(fromProofReceipt.metrics),
+      evaluatedAt: typeof fromProofReceipt.proofEventAt === "string" ? fromProofReceipt.proofEventAt : null,
+      evaluatedAtChainHash: typeof fromProofReceipt.evaluatedAtChainHash === "string" ? fromProofReceipt.evaluatedAtChainHash : null
+    };
+  }
+
+  const settlementRef = artifact.settlement?.settlementProofRef;
+  if (settlementRef && typeof settlementRef === "object" && !Array.isArray(settlementRef)) {
+    return {
+      source: "artifact.settlement.settlementProofRef",
+      status: normalizeProofStatus(settlementRef.status),
+      reasonCodes: normalizeReasonCodes(settlementRef.reasonCodes),
+      missingEvidence: normalizeMissingEvidence(settlementRef.missingEvidence),
+      metrics: normalizeMetrics(settlementRef.metrics),
+      evaluatedAt: typeof settlementRef.proofEventAt === "string" ? settlementRef.proofEventAt : null,
+      evaluatedAtChainHash: typeof settlementRef.evaluatedAtChainHash === "string" ? settlementRef.evaluatedAtChainHash : null
+    };
+  }
+
+  return null;
+}
+
+function extractProofSignalsFromJob(job) {
+  if (!job || typeof job !== "object") return null;
+  const proof = job.proof;
+  if (!proof || typeof proof !== "object" || Array.isArray(proof)) return null;
+  return {
+    source: "job.proof",
+    status: normalizeProofStatus(proof.status),
+    reasonCodes: normalizeReasonCodes(proof.reasonCodes),
+    missingEvidence: normalizeMissingEvidence(proof.missingEvidence),
+    metrics: normalizeMetrics(proof.metrics),
+    evaluatedAt: typeof proof.evaluatedAt === "string" ? proof.evaluatedAt : null,
+    evaluatedAtChainHash: typeof proof.evaluatedAtChainHash === "string" ? proof.evaluatedAtChainHash : null
+  };
+}
+
+function computeEvidenceCounts({ artifact, job }) {
+  const artifactEvidence = Array.isArray(artifact?.evidence) ? artifact.evidence : null;
+  const jobEvidence = Array.isArray(job?.evidence) ? job.evidence : null;
+  const evidence = artifactEvidence ?? jobEvidence ?? [];
+  const totalEvidenceCount = evidence.length;
+  let activeEvidenceCount = 0;
+  for (const item of evidence) {
+    if (!item || typeof item !== "object") continue;
+    const expiredAt = item.expiredAt;
+    if (expiredAt === null || expiredAt === undefined || String(expiredAt).trim() === "") activeEvidenceCount += 1;
+  }
+  return { totalEvidenceCount, activeEvidenceCount };
+}
+
+function computeSlaCompliance({ status, metrics, missingEvidence }) {
+  const requiredZones = metrics.requiredZones;
+  const reportedZones = metrics.reportedZones;
+  const excusedZones = metrics.excusedZones ?? 0;
+  const belowThresholdZones = metrics.belowThresholdZones ?? 0;
+
+  let missingZoneCount = countMissingZoneCoverageEvidence(missingEvidence);
+  if (missingZoneCount === 0 && Number.isSafeInteger(requiredZones) && Number.isSafeInteger(reportedZones)) {
+    const inferred = requiredZones - reportedZones - excusedZones;
+    missingZoneCount = inferred > 0 ? inferred : 0;
+  }
+
+  let slaCompliancePct = null;
+  if (Number.isSafeInteger(requiredZones) && requiredZones > 0) {
+    const deficient = Math.max(0, Math.min(requiredZones, belowThresholdZones + missingZoneCount));
+    const compliantZones = requiredZones - deficient;
+    slaCompliancePct = Math.max(0, Math.min(100, Math.round((compliantZones / requiredZones) * 100)));
+  } else if (status === PROOF_STATUS.PASS) {
+    slaCompliancePct = 100;
+  } else if (status === PROOF_STATUS.FAIL) {
+    slaCompliancePct = 0;
+  }
+
+  return {
+    slaCompliancePct,
+    requiredZones,
+    reportedZones,
+    excusedZones: metrics.excusedZones,
+    belowThresholdZones: metrics.belowThresholdZones,
+    missingZoneCount
+  };
+}
+
+export function computeArtifactVerificationStatus({ artifact, job = null } = {}) {
+  if (!artifact || typeof artifact !== "object") throw new TypeError("artifact is required");
+  if (job !== null && job !== undefined && (typeof job !== "object" || Array.isArray(job))) throw new TypeError("job must be null or an object");
+
+  const proofSignals = extractProofSignalsFromArtifact(artifact) ?? extractProofSignalsFromJob(job);
+  const proofStatus = proofSignals?.status ?? null;
+  const reasonCodes = proofSignals?.reasonCodes ?? [];
+  const missingEvidence = proofSignals?.missingEvidence ?? [];
+  const metrics = proofSignals?.metrics ?? normalizeMetrics(null);
+  const verificationStatus = mapProofStatusToVerificationStatus(proofStatus);
+  const evidence = computeEvidenceCounts({ artifact, job });
+  const sla = computeSlaCompliance({ status: proofStatus, metrics, missingEvidence });
+
+  return {
+    verificationStatus,
+    proofStatus,
+    reasonCodes,
+    missingEvidence,
+    evaluatedAt: proofSignals?.evaluatedAt ?? null,
+    evaluatedAtChainHash: proofSignals?.evaluatedAtChainHash ?? null,
+    source: proofSignals?.source ?? "unknown",
+    evidenceCount: evidence.totalEvidenceCount,
+    activeEvidenceCount: evidence.activeEvidenceCount,
+    slaCompliancePct: sla.slaCompliancePct,
+    metrics: {
+      requiredZones: sla.requiredZones,
+      reportedZones: sla.reportedZones,
+      excusedZones: sla.excusedZones,
+      belowThresholdZones: sla.belowThresholdZones,
+      missingZoneCount: sla.missingZoneCount
+    }
+  };
+}