settld 0.1.0

package/src/core/config.js

@@ -0,0 +1,272 @@
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+function parseNonNegativeIntEnv(name, fallback) {
+  const raw = typeof process !== "undefined" ? process.env[name] : null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n < 0) throw new TypeError(`${name} must be a non-negative safe integer`);
+  return n;
+}
+
+function parsePositiveIntEnv(name, fallback) {
+  const raw = typeof process !== "undefined" ? process.env[name] : null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || !Number.isSafeInteger(n) || n <= 0) throw new TypeError(`${name} must be a positive safe integer`);
+  return n;
+}
+
+function parseFlagEnv(name, fallback) {
+  const raw = typeof process !== "undefined" ? process.env[name] : null;
+  if (raw === null || raw === undefined || String(raw).trim() === "") return fallback;
+  const v = String(raw).trim();
+  if (v === "1") return true;
+  if (v === "0") return false;
+  throw new TypeError(`${name} must be 0 or 1`);
+}
+
+function safeSchemaName(name) {
+  assertNonEmptyString(name, "PROXY_PG_SCHEMA");
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    throw new TypeError("PROXY_PG_SCHEMA must match /^[a-zA-Z_][a-zA-Z0-9_]*$/");
+  }
+  return name;
+}
+
+function redactDatabaseUrl(databaseUrl) {
+  if (!databaseUrl) return null;
+  try {
+    const u = new URL(databaseUrl);
+    if (u.password) u.password = "[REDACTED]";
+    return u.toString();
+  } catch {
+    // Some PG URLs are non-standard; just redact anything after the first ':' in userinfo.
+    const text = String(databaseUrl);
+    const at = text.indexOf("@");
+    const schemeSep = text.indexOf("://");
+    if (schemeSep !== -1 && at !== -1) {
+      const userInfo = text.slice(schemeSep + 3, at);
+      const colon = userInfo.indexOf(":");
+      if (colon !== -1) {
+        const redactedUserInfo = `${userInfo.slice(0, colon)}:[REDACTED]`;
+        return `${text.slice(0, schemeSep + 3)}${redactedUserInfo}${text.slice(at)}`;
+      }
+    }
+    return "[REDACTED]";
+  }
+}
+
+function countDestinationsByTenant(rawJson) {
+  if (!rawJson || String(rawJson).trim() === "") return { tenants: 0, destinations: 0 };
+  let parsed;
+  try {
+    parsed = JSON.parse(String(rawJson));
+  } catch (err) {
+    throw new TypeError(`invalid PROXY_EXPORT_DESTINATIONS JSON: ${err?.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError("PROXY_EXPORT_DESTINATIONS must be a JSON object");
+  let tenants = 0;
+  let destinations = 0;
+  for (const [tenantId, list] of Object.entries(parsed)) {
+    if (!tenantId) continue;
+    tenants += 1;
+    if (Array.isArray(list)) destinations += list.length;
+  }
+  return { tenants, destinations };
+}
+
+function containsInlineSecrets(rawJson) {
+  if (!rawJson || String(rawJson).trim() === "") return false;
+  let parsed;
+  try {
+    parsed = JSON.parse(String(rawJson));
+  } catch {
+    return false;
+  }
+
+  const stack = [parsed];
+  while (stack.length) {
+    const v = stack.pop();
+    if (!v) continue;
+    if (Array.isArray(v)) {
+      for (const item of v) stack.push(item);
+      continue;
+    }
+    if (typeof v === "object") {
+      for (const [k, value] of Object.entries(v)) {
+        const key = String(k).toLowerCase();
+        if (key === "secret" || key === "accesskeyid" || key === "secretaccesskey") {
+          if (typeof value === "string" && value.trim() !== "") return true;
+        }
+        stack.push(value);
+      }
+    }
+  }
+  return false;
+}
+
+export function loadConfig({ mode = "api" } = {}) {
+  const resolvedMode = String(mode);
+  if (resolvedMode !== "api" && resolvedMode !== "maintenance") throw new TypeError("mode must be api or maintenance");
+
+  const nodeEnv = typeof process !== "undefined" ? (process.env.NODE_ENV ?? "development") : "development";
+
+  const storeModeRaw = typeof process !== "undefined" ? (process.env.STORE ?? "memory") : "memory";
+  const storeMode = resolvedMode === "maintenance" ? "pg" : String(storeModeRaw);
+  if (storeMode !== "memory" && storeMode !== "pg") throw new TypeError("STORE must be memory or pg");
+
+  const pgSchema = safeSchemaName(typeof process !== "undefined" ? (process.env.PROXY_PG_SCHEMA ?? "public") : "public");
+  const persistenceDir = typeof process !== "undefined" ? (process.env.PROXY_DATA_DIR ?? null) : null;
+  const databaseUrl = typeof process !== "undefined" ? (process.env.DATABASE_URL ?? null) : null;
+
+  const migrateOnStartup = parseFlagEnv("PROXY_MIGRATE_ON_STARTUP", true);
+  const pgLogSlowMs = parseNonNegativeIntEnv("PROXY_PG_LOG_SLOW_MS", 0);
+  const pgWorkerStatementTimeoutMs = Math.min(60_000, parseNonNegativeIntEnv("PROXY_PG_WORKER_STATEMENT_TIMEOUT_MS", 0));
+
+  if (storeMode === "pg") {
+    if (!databaseUrl) throw new Error("STORE=pg requires DATABASE_URL");
+  }
+  if (resolvedMode === "maintenance") {
+    if (!databaseUrl) throw new Error("maintenance mode requires DATABASE_URL");
+  }
+
+  const port = parsePositiveIntEnv("PORT", 3000);
+
+  const maintenanceIntervalSeconds = parsePositiveIntEnv("PROXY_MAINTENANCE_INTERVAL_SECONDS", 300);
+  const retentionCleanupBatchSize = parsePositiveIntEnv("PROXY_RETENTION_CLEANUP_BATCH_SIZE", 500);
+  const retentionCleanupMaxMillis = parsePositiveIntEnv("PROXY_RETENTION_CLEANUP_MAX_MILLIS", 1500);
+  const retentionCleanupDryRun = parseFlagEnv("PROXY_RETENTION_CLEANUP_DRY_RUN", false);
+
+  // Quick validation pass for key hardening toggles.
+  const allowInlineSecrets = parseFlagEnv("PROXY_ALLOW_INLINE_SECRETS", false);
+  const exportDestinations = typeof process !== "undefined" ? (process.env.PROXY_EXPORT_DESTINATIONS ?? null) : null;
+  if (nodeEnv === "production" && !allowInlineSecrets && containsInlineSecrets(exportDestinations)) {
+    throw new Error("inline secrets in PROXY_EXPORT_DESTINATIONS are not allowed in production (use *Ref fields or set PROXY_ALLOW_INLINE_SECRETS=1)");
+  }
+
+  const maxBodyBytes = parsePositiveIntEnv("PROXY_MAX_BODY_BYTES", 1_000_000);
+  const ingestMaxEvents = parsePositiveIntEnv("PROXY_INGEST_MAX_EVENTS", 200);
+
+  const rateLimitRpm = parseNonNegativeIntEnv("PROXY_RATE_LIMIT_RPM", 0);
+  const rateLimitBurst = parseNonNegativeIntEnv("PROXY_RATE_LIMIT_BURST", rateLimitRpm);
+
+  const reclaimAfterSeconds = parsePositiveIntEnv("PROXY_RECLAIM_AFTER_SECONDS", 60);
+  const outboxMaxAttempts = parsePositiveIntEnv("PROXY_OUTBOX_MAX_ATTEMPTS", 25);
+
+  const workerConcurrencyArtifacts = Math.min(50, parsePositiveIntEnv("PROXY_WORKER_CONCURRENCY_ARTIFACTS", 1));
+  const workerConcurrencyDeliveries = Math.min(50, parsePositiveIntEnv("PROXY_WORKER_CONCURRENCY_DELIVERIES", 1));
+  const deliveryHttpTimeoutMs = parseNonNegativeIntEnv("PROXY_DELIVERY_HTTP_TIMEOUT_MS", 0);
+
+  const secretsCacheTtlSeconds = parsePositiveIntEnv("PROXY_SECRETS_CACHE_TTL_SECONDS", 30);
+
+  const evidencePresignMaxSeconds = parsePositiveIntEnv("PROXY_EVIDENCE_PRESIGN_MAX_SECONDS", 300);
+  if (evidencePresignMaxSeconds > 3600) throw new TypeError("PROXY_EVIDENCE_PRESIGN_MAX_SECONDS must be <= 3600");
+
+  const autotickEnabled = typeof process !== "undefined" && process.env.PROXY_AUTOTICK === "1";
+  const autotickIntervalMs = (() => {
+    const raw = typeof process !== "undefined" ? (process.env.PROXY_AUTOTICK_INTERVAL_MS ?? null) : null;
+    if (raw !== null && raw !== undefined && String(raw).trim() !== "") {
+      const n = Number(raw);
+      if (!Number.isFinite(n) || n <= 0) throw new TypeError("PROXY_AUTOTICK_INTERVAL_MS must be a positive number");
+      return Math.floor(n);
+    }
+    if (autotickEnabled) return 250;
+    return 0;
+  })();
+
+  const autotickMaxMessages = (() => {
+    const raw = typeof process !== "undefined" ? (process.env.PROXY_AUTOTICK_MAX_MESSAGES ?? null) : null;
+    if (raw === null || raw === undefined || String(raw).trim() === "") return 100;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) throw new TypeError("PROXY_AUTOTICK_MAX_MESSAGES must be a positive number");
+    return Math.floor(n);
+  })();
+
+  return {
+    mode: resolvedMode,
+    nodeEnv,
+    store: {
+      mode: storeMode,
+      databaseUrl,
+      pgSchema,
+      pgLogSlowMs,
+      pgWorkerStatementTimeoutMs,
+      persistenceDir,
+      migrateOnStartup
+    },
+    api: {
+      port,
+      autotick: {
+        enabled: autotickEnabled,
+        intervalMs: autotickIntervalMs,
+        maxMessages: autotickMaxMessages
+      }
+    },
+    maintenance: {
+      intervalSeconds: maintenanceIntervalSeconds,
+      retentionCleanup: {
+        batchSize: retentionCleanupBatchSize,
+        maxMillis: retentionCleanupMaxMillis,
+        dryRun: retentionCleanupDryRun
+      }
+    },
+    http: {
+      maxBodyBytes,
+      ingestMaxEvents
+    },
+    rateLimit: {
+      rpm: rateLimitRpm,
+      burst: rateLimitBurst
+    },
+    outbox: {
+      reclaimAfterSeconds,
+      maxAttempts: outboxMaxAttempts
+    },
+    workers: {
+      concurrency: {
+        artifacts: workerConcurrencyArtifacts,
+        deliveries: workerConcurrencyDeliveries
+      },
+      deliveryHttpTimeoutMs
+    },
+    secrets: {
+      cacheTtlSeconds: secretsCacheTtlSeconds
+    },
+    evidence: {
+      presignMaxSeconds: evidencePresignMaxSeconds
+    },
+    exports: {
+      allowInlineSecrets,
+      destinationsConfigured: countDestinationsByTenant(exportDestinations)
+    }
+  };
+}
+
+export function configForLog(config) {
+  if (!config || typeof config !== "object") throw new TypeError("config is required");
+  const store = config.store ?? {};
+  return {
+    mode: config.mode ?? null,
+    nodeEnv: config.nodeEnv ?? null,
+    store: {
+      mode: store.mode ?? null,
+      pgSchema: store.pgSchema ?? null,
+      migrateOnStartup: store.migrateOnStartup ?? null,
+      pgLogSlowMs: store.pgLogSlowMs ?? null,
+      pgWorkerStatementTimeoutMs: store.pgWorkerStatementTimeoutMs ?? null,
+      persistenceDir: store.persistenceDir ?? null,
+      databaseUrl: redactDatabaseUrl(store.databaseUrl ?? null)
+    },
+    api: config.api ?? null,
+    maintenance: config.maintenance ?? null,
+    http: config.http ?? null,
+    rateLimit: config.rateLimit ?? null,
+    outbox: config.outbox ?? null,
+    workers: config.workers ?? null,
+    secrets: config.secrets ?? null,
+    evidence: config.evidence ?? null,
+    exports: config.exports ?? null
+  };
+}

package/src/core/contract-compiler.js

@@ -0,0 +1,68 @@
+import { buildPolicySnapshot, computePolicyHash } from "./policy.js";
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+import { hashSplitPlanV1 } from "./contract-document.js";
+
+export const CONTRACT_COMPILER_ID = "contract_compiler.v1";
+export const CONTRACT_POLICY_TEMPLATE_VERSION = "ContractPolicyTemplate.v1";
+
+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 function compileBookingPolicySnapshot({
+  contractDoc,
+  environmentTier,
+  requiresOperatorCoverage,
+  sla,
+  proofPolicy,
+  creditPolicy,
+  evidencePolicy,
+  claimPolicy,
+  coveragePolicy
+} = {}) {
+  assertPlainObject(contractDoc, "contractDoc");
+
+  const policySnapshot = buildPolicySnapshot({
+    contractId: contractDoc.contractId ?? null,
+    contractVersion: contractDoc.contractVersion ?? null,
+    environmentTier,
+    requiresOperatorCoverage,
+    sla,
+    proofPolicy: proofPolicy ?? contractDoc?.policies?.proofPolicy ?? null,
+    creditPolicy,
+    evidencePolicy,
+    claimPolicy: claimPolicy ?? null,
+    coveragePolicy: coveragePolicy ?? null
+  });
+
+  const policyHash = computePolicyHash(policySnapshot);
+  return { policySnapshot, policyHash, compilerId: CONTRACT_COMPILER_ID, diagnostics: [] };
+}
+
+export function compileContractPolicyTemplate({ contractDoc } = {}) {
+  assertPlainObject(contractDoc, "contractDoc");
+  const connectEnabled = contractDoc?.connect?.enabled === true;
+  const splitPlanHash =
+    connectEnabled && contractDoc?.connect?.splitPlan
+      ? hashSplitPlanV1(contractDoc.connect.splitPlan)
+      : null;
+  const template = normalizeForCanonicalJson(
+    {
+      schemaVersion: CONTRACT_POLICY_TEMPLATE_VERSION,
+      contractId: contractDoc.contractId ?? null,
+      contractVersion: contractDoc.contractVersion ?? null,
+      policies: contractDoc.policies ?? null,
+      connect: {
+        enabled: connectEnabled,
+        splitPlanHash
+      }
+    },
+    { path: "$" }
+  );
+  const policyHash = sha256Hex(canonicalJsonStringify(template));
+  return { policyTemplate: template, policyHash, compilerId: CONTRACT_COMPILER_ID, diagnostics: [] };
+}

package/src/core/contract-document.js

@@ -0,0 +1,226 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+import { validateContract } from "./contracts.js";
+
+export const CONTRACT_DOCUMENT_TYPE_V1 = "ContractDocument.v1";
+export const SPLIT_PLAN_TYPE_V1 = "SplitPlan.v1";
+
+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 assertNullableNonEmptyString(value, name) {
+  if (value === null || value === undefined) return;
+  assertNonEmptyString(value, name);
+}
+
+function assertOptionalIsoDate(value, name) {
+  if (value === null || value === undefined) return;
+  assertNonEmptyString(value, name);
+  const t = Date.parse(value);
+  if (!Number.isFinite(t)) throw new TypeError(`${name} must be an ISO date string`);
+}
+
+export function validateContractDocumentV1(doc) {
+  assertPlainObject(doc, "contractDoc");
+  const allowed = new Set([
+    "type",
+    "v",
+    "contractId",
+    "contractVersion",
+    "name",
+    "parties",
+    "scope",
+    "policies",
+    "effective",
+    "connect"
+  ]);
+  for (const k of Object.keys(doc)) {
+    if (!allowed.has(k)) throw new TypeError(`contractDoc contains unknown field: ${k}`);
+  }
+
+  if (doc.type !== CONTRACT_DOCUMENT_TYPE_V1) throw new TypeError("contractDoc.type is not supported");
+  if (doc.v !== 1) throw new TypeError("contractDoc.v is not supported");
+
+  assertNonEmptyString(doc.contractId, "contractDoc.contractId");
+  if (!Number.isSafeInteger(doc.contractVersion) || doc.contractVersion <= 0) throw new TypeError("contractDoc.contractVersion must be > 0");
+  assertNonEmptyString(doc.name, "contractDoc.name");
+
+  if (doc.parties !== undefined) {
+    assertPlainObject(doc.parties, "contractDoc.parties");
+    const allowedRoles = new Set(["platform", "operator", "customer"]);
+    for (const [role, party] of Object.entries(doc.parties)) {
+      if (!allowedRoles.has(role)) throw new TypeError(`contractDoc.parties contains unknown role: ${role}`);
+      assertPlainObject(party, `contractDoc.parties.${role}`);
+      const allowedParty = new Set(["partyId", "requiresSignature"]);
+      for (const k of Object.keys(party)) {
+        if (!allowedParty.has(k)) throw new TypeError(`contractDoc.parties.${role} contains unknown field: ${k}`);
+      }
+      assertNonEmptyString(party.partyId, `contractDoc.parties.${role}.partyId`);
+      if (typeof party.requiresSignature !== "boolean") throw new TypeError(`contractDoc.parties.${role}.requiresSignature must be boolean`);
+    }
+  }
+
+  if (doc.effective !== undefined) {
+    assertPlainObject(doc.effective, "contractDoc.effective");
+    const allowedEff = new Set(["from", "to"]);
+    for (const k of Object.keys(doc.effective)) {
+      if (!allowedEff.has(k)) throw new TypeError(`contractDoc.effective contains unknown field: ${k}`);
+    }
+    assertOptionalIsoDate(doc.effective.from, "contractDoc.effective.from");
+    assertOptionalIsoDate(doc.effective.to, "contractDoc.effective.to");
+  }
+
+  if (doc.scope !== undefined) {
+    assertPlainObject(doc.scope, "contractDoc.scope");
+    const allowedScope = new Set(["customerId", "siteId", "templateId", "zoneId", "skillId", "isDefault"]);
+    for (const k of Object.keys(doc.scope)) {
+      if (!allowedScope.has(k)) throw new TypeError(`contractDoc.scope contains unknown field: ${k}`);
+    }
+    assertNullableNonEmptyString(doc.scope.customerId, "contractDoc.scope.customerId");
+    assertNullableNonEmptyString(doc.scope.siteId, "contractDoc.scope.siteId");
+    assertNullableNonEmptyString(doc.scope.templateId, "contractDoc.scope.templateId");
+    assertNullableNonEmptyString(doc.scope.zoneId, "contractDoc.scope.zoneId");
+    assertNullableNonEmptyString(doc.scope.skillId, "contractDoc.scope.skillId");
+    if (doc.scope.isDefault !== undefined && typeof doc.scope.isDefault !== "boolean") throw new TypeError("contractDoc.scope.isDefault must be boolean");
+  }
+
+  assertPlainObject(doc.policies, "contractDoc.policies");
+
+  if (doc.connect !== undefined) {
+    assertPlainObject(doc.connect, "contractDoc.connect");
+    const allowedConnect = new Set(["enabled", "splitPlan"]);
+    for (const k of Object.keys(doc.connect)) {
+      if (!allowedConnect.has(k)) throw new TypeError(`contractDoc.connect contains unknown field: ${k}`);
+    }
+    if (typeof doc.connect.enabled !== "boolean") throw new TypeError("contractDoc.connect.enabled must be boolean");
+    if (doc.connect.splitPlan !== undefined && doc.connect.splitPlan !== null) {
+      validateSplitPlanV1(doc.connect.splitPlan);
+    }
+  }
+
+  // Reuse the legacy contract validator to ensure policies are structurally sane.
+  // (We intentionally exclude timestamps from the hashed document.)
+  validateContract({
+    tenantId: "tenant_default",
+    contractId: doc.contractId,
+    contractVersion: doc.contractVersion,
+    name: doc.name,
+    customerId: doc.scope?.customerId ?? null,
+    siteId: doc.scope?.siteId ?? null,
+    templateId: doc.scope?.templateId ?? null,
+    isDefault: doc.scope?.isDefault === true,
+    policies: doc.policies,
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString()
+  });
+
+  return doc;
+}
+
+export function validateSplitPlanV1(splitPlan) {
+  assertPlainObject(splitPlan, "splitPlan");
+  const allowed = new Set(["type", "v", "currency", "rules"]);
+  for (const k of Object.keys(splitPlan)) {
+    if (!allowed.has(k)) throw new TypeError(`splitPlan contains unknown field: ${k}`);
+  }
+  if (splitPlan.type !== SPLIT_PLAN_TYPE_V1) throw new TypeError("splitPlan.type is not supported");
+  if (splitPlan.v !== 1) throw new TypeError("splitPlan.v is not supported");
+  assertNonEmptyString(splitPlan.currency, "splitPlan.currency");
+  if (splitPlan.currency !== "USD") throw new TypeError("splitPlan.currency is not supported");
+  if (!Array.isArray(splitPlan.rules)) throw new TypeError("splitPlan.rules must be an array");
+
+  const allowedRoles = new Set(["platform", "operator", "customer", "subcontractor", "insurer"]);
+  const allowedShareTypes = new Set(["percentage", "fixed", "remainder"]);
+  const allowedAppliesTo = new Set(["gross", "net_after_credits", "credits"]);
+
+  for (let i = 0; i < splitPlan.rules.length; i += 1) {
+    const rule = splitPlan.rules[i];
+    assertPlainObject(rule, `splitPlan.rules[${i}]`);
+    const allowedRule = new Set(["partyRole", "partyId", "share", "appliesTo"]);
+    for (const k of Object.keys(rule)) {
+      if (!allowedRule.has(k)) throw new TypeError(`splitPlan.rules[${i}] contains unknown field: ${k}`);
+    }
+    assertNonEmptyString(rule.partyRole, `splitPlan.rules[${i}].partyRole`);
+    if (!allowedRoles.has(rule.partyRole)) throw new TypeError(`splitPlan.rules[${i}].partyRole is not supported`);
+    if (rule.partyId !== undefined && rule.partyId !== null) assertNonEmptyString(rule.partyId, `splitPlan.rules[${i}].partyId`);
+    assertPlainObject(rule.share, `splitPlan.rules[${i}].share`);
+    const allowedShare = new Set(["type", "valueBasisPoints", "valueCents"]);
+    for (const k of Object.keys(rule.share)) {
+      if (!allowedShare.has(k)) throw new TypeError(`splitPlan.rules[${i}].share contains unknown field: ${k}`);
+    }
+    assertNonEmptyString(rule.share.type, `splitPlan.rules[${i}].share.type`);
+    if (!allowedShareTypes.has(rule.share.type)) throw new TypeError(`splitPlan.rules[${i}].share.type is not supported`);
+    if (rule.share.type === "percentage") {
+      if (!Number.isSafeInteger(rule.share.valueBasisPoints)) throw new TypeError(`splitPlan.rules[${i}].share.valueBasisPoints is required`);
+      if (rule.share.valueBasisPoints < 0 || rule.share.valueBasisPoints > 10000) throw new TypeError("splitPlan share basis points must be 0..10000");
+    }
+    if (rule.share.type === "fixed") {
+      if (!Number.isSafeInteger(rule.share.valueCents)) throw new TypeError(`splitPlan.rules[${i}].share.valueCents is required`);
+    }
+    if (rule.share.type === "remainder") {
+      // no additional fields
+    }
+    if (rule.appliesTo !== undefined && rule.appliesTo !== null) {
+      assertNonEmptyString(rule.appliesTo, `splitPlan.rules[${i}].appliesTo`);
+      if (!allowedAppliesTo.has(rule.appliesTo)) throw new TypeError(`splitPlan.rules[${i}].appliesTo is not supported`);
+    }
+  }
+
+  return splitPlan;
+}
+
+export function hashSplitPlanV1(splitPlan) {
+  const normalized = normalizeForCanonicalJson(validateSplitPlanV1(splitPlan), { path: "$" });
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function normalizeContractDocumentV1(doc) {
+  validateContractDocumentV1(doc);
+  return normalizeForCanonicalJson(doc, { path: "$" });
+}
+
+export function hashContractDocumentV1(doc) {
+  const normalized = normalizeContractDocumentV1(doc);
+  return sha256Hex(canonicalJsonStringify(normalized));
+}
+
+export function contractDocumentV1FromLegacyContract(contract) {
+  if (!contract || typeof contract !== "object") throw new TypeError("contract is required");
+  const contractId = contract.contractId ?? contract.id ?? null;
+  const contractVersion = contract.contractVersion ?? contract.version ?? null;
+  const name = contract.name ?? contractId ?? null;
+  if (typeof contractId !== "string" || !contractId.trim()) throw new TypeError("contract.contractId is required");
+  if (!Number.isSafeInteger(contractVersion) || contractVersion <= 0) throw new TypeError("contract.contractVersion must be > 0");
+  if (typeof name !== "string" || !name.trim()) throw new TypeError("contract.name is required");
+
+  const doc = {
+    type: CONTRACT_DOCUMENT_TYPE_V1,
+    v: 1,
+    contractId: String(contractId),
+    contractVersion: Number(contractVersion),
+    name: String(name),
+    parties: {
+      platform: { partyId: "pty_platform", requiresSignature: false },
+      operator: { partyId: "pty_operator", requiresSignature: false },
+      customer: { partyId: "pty_customer", requiresSignature: false }
+    },
+    scope: {
+      customerId: contract.customerId ?? null,
+      siteId: contract.siteId ?? null,
+      templateId: contract.templateId ?? null,
+      zoneId: null,
+      skillId: null,
+      isDefault: contract.isDefault === true
+    },
+    policies: contract.policies ?? {}
+  };
+  return normalizeContractDocumentV1(doc);
+}