settld 0.1.0

package/src/core/proof-events.js

@@ -0,0 +1,88 @@
+import { canonicalizeMissingEvidenceList, canonicalizeMissingEvidenceToken, PROOF_STATUS } from "./proof.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 function validateProofEvaluatedPayload(payload) {
+  assertPlainObject(payload, "payload");
+  const allowed = new Set([
+    "jobId",
+    "evaluatedAt",
+    "evaluatedAtChainHash",
+    "evaluationId",
+    "customerPolicyHash",
+    "operatorPolicyHash",
+    "requiredZonesHash",
+    "factsHash",
+    "status",
+    "reasonCodes",
+    "missingEvidence",
+    "triggeredFacts",
+    "metrics"
+  ]);
+  for (const k of Object.keys(payload)) {
+    if (!allowed.has(k)) throw new TypeError(`payload contains unknown field: ${k}`);
+  }
+
+  assertNonEmptyString(payload.jobId, "payload.jobId");
+  assertNonEmptyString(payload.evaluatedAt, "payload.evaluatedAt");
+  assertNonEmptyString(payload.evaluatedAtChainHash, "payload.evaluatedAtChainHash");
+
+  if (payload.evaluationId !== undefined && payload.evaluationId !== null) {
+    assertNonEmptyString(payload.evaluationId, "payload.evaluationId");
+    const hex = String(payload.evaluationId).trim();
+    if (!/^[a-f0-9]{64}$/i.test(hex)) throw new TypeError("payload.evaluationId must be 64-hex");
+  }
+  if (payload.customerPolicyHash !== undefined && payload.customerPolicyHash !== null) assertNonEmptyString(payload.customerPolicyHash, "payload.customerPolicyHash");
+  if (payload.operatorPolicyHash !== undefined && payload.operatorPolicyHash !== null) assertNonEmptyString(payload.operatorPolicyHash, "payload.operatorPolicyHash");
+  if (payload.requiredZonesHash !== undefined && payload.requiredZonesHash !== null) assertNonEmptyString(payload.requiredZonesHash, "payload.requiredZonesHash");
+  if (payload.factsHash !== undefined && payload.factsHash !== null) {
+    assertNonEmptyString(payload.factsHash, "payload.factsHash");
+    const hex = String(payload.factsHash).trim();
+    if (!/^[a-f0-9]{64}$/i.test(hex)) throw new TypeError("payload.factsHash must be 64-hex");
+  }
+
+  assertNonEmptyString(payload.status, "payload.status");
+  if (!new Set(Object.values(PROOF_STATUS)).has(payload.status)) throw new TypeError("payload.status is not supported");
+
+  if (!Array.isArray(payload.reasonCodes)) throw new TypeError("payload.reasonCodes must be an array");
+  for (const c of payload.reasonCodes) assertNonEmptyString(c, "payload.reasonCodes[]");
+
+  if (payload.missingEvidence !== undefined && payload.missingEvidence !== null) {
+    if (!Array.isArray(payload.missingEvidence)) throw new TypeError("payload.missingEvidence must be an array");
+    for (const e of payload.missingEvidence) {
+      assertNonEmptyString(e, "payload.missingEvidence[]");
+      const canonical = canonicalizeMissingEvidenceToken(e);
+      if (canonical !== e) throw new TypeError("payload.missingEvidence must be canonical");
+    }
+    const canonicalList = canonicalizeMissingEvidenceList(payload.missingEvidence);
+    if (payload.missingEvidence.length !== canonicalList.length) throw new TypeError("payload.missingEvidence must be deduped");
+    for (let i = 0; i < canonicalList.length; i += 1) {
+      if (payload.missingEvidence[i] !== canonicalList[i]) throw new TypeError("payload.missingEvidence must be sorted");
+    }
+  }
+
+  if (!Array.isArray(payload.triggeredFacts)) throw new TypeError("payload.triggeredFacts must be an array");
+  for (const f of payload.triggeredFacts) {
+    assertPlainObject(f, "payload.triggeredFacts[]");
+    const allowedFact = new Set(["eventId", "type", "zoneId"]);
+    for (const k of Object.keys(f)) {
+      if (!allowedFact.has(k)) throw new TypeError("payload.triggeredFacts contains unknown field");
+    }
+    if (f.eventId !== null && f.eventId !== undefined) assertNonEmptyString(f.eventId, "triggeredFacts[].eventId");
+    assertNonEmptyString(f.type, "triggeredFacts[].type");
+    if (f.zoneId !== null && f.zoneId !== undefined) assertNonEmptyString(f.zoneId, "triggeredFacts[].zoneId");
+  }
+
+  assertPlainObject(payload.metrics ?? {}, "payload.metrics");
+
+  return payload;
+}

package/src/core/proof-verifier.js

@@ -0,0 +1,261 @@
+import { canonicalJsonStringify, normalizeForCanonicalJson } from "./canonical-json.js";
+import { sha256Hex } from "./crypto.js";
+import { canonicalizeMissingEvidenceList, MISSING_EVIDENCE, PROOF_REASON_CODE, PROOF_STATUS } from "./proof.js";
+import { validateZoneSetV1 } from "./zoneset.js";
+
+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 safeIsoToMs(value) {
+  const t = Date.parse(String(value ?? ""));
+  return Number.isFinite(t) ? t : NaN;
+}
+
+function sliceThroughChainHash(events, atChainHash) {
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+  assertNonEmptyString(atChainHash, "atChainHash");
+  const idx = events.findIndex((e) => e?.chainHash === atChainHash);
+  if (idx === -1) throw new TypeError("evaluatedAtChainHash not found in stream");
+  return events.slice(0, idx + 1);
+}
+
+function latestCoverageByZone(events) {
+  const byZoneId = new Map();
+  for (const e of events) {
+    if (e?.type !== "ZONE_COVERAGE_REPORTED") continue;
+    const p = e.payload ?? null;
+    const zoneId = typeof p?.zoneId === "string" ? p.zoneId.trim() : "";
+    if (!zoneId) continue;
+    const endMs = safeIsoToMs(p?.window?.endAt);
+    const key = zoneId;
+    const prev = byZoneId.get(key) ?? null;
+    const prevEndMs = prev ? safeIsoToMs(prev?.payload?.window?.endAt) : NaN;
+    if (!prev) {
+      byZoneId.set(key, e);
+      continue;
+    }
+    // Prefer higher endAt, tie-break by event id to ensure deterministic selection.
+    if (Number.isFinite(endMs) && (!Number.isFinite(prevEndMs) || endMs > prevEndMs)) {
+      byZoneId.set(key, e);
+      continue;
+    }
+    if (endMs === prevEndMs) {
+      const prevId = String(prev?.id ?? "");
+      const nextId = String(e?.id ?? "");
+      if (nextId && (!prevId || nextId > prevId)) byZoneId.set(key, e);
+    }
+  }
+  return byZoneId;
+}
+
+function excusedZonesFromIncidents(events, { excuseIncidentTypes }) {
+  const excuseTypes = new Set(Array.isArray(excuseIncidentTypes) ? excuseIncidentTypes.map((t) => String(t)) : []);
+  const excused = new Set();
+  const triggeredFacts = [];
+  for (const e of events) {
+    if (e?.type !== "INCIDENT_REPORTED" && e?.type !== "INCIDENT_DETECTED") continue;
+    const p = e.payload ?? null;
+    const type = typeof p?.type === "string" ? p.type : null;
+    if (!type || !excuseTypes.has(type)) continue;
+    const zoneId = typeof p?.zoneId === "string" ? p.zoneId.trim() : "";
+    if (!zoneId) continue;
+    excused.add(zoneId);
+    triggeredFacts.push({ eventId: e.id ?? null, type: e.type, zoneId });
+  }
+  return { excused, triggeredFacts };
+}
+
+function missingEvidenceDetailFromZoneId(zoneId) {
+  const raw = typeof zoneId === "string" ? zoneId : String(zoneId ?? "");
+  const base = raw.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "");
+  const hash8 = sha256Hex(raw).slice(0, 8);
+  const prefix = base ? base.slice(0, 32) : "zone";
+  const detail = `${prefix}_${hash8}`.slice(0, 48);
+  return detail || `zone_${hash8}`;
+}
+
+export function verifyZoneCoverageProofV1({
+  job,
+  events,
+  evaluatedAtChainHash,
+  customerPolicyHash,
+  operatorPolicyHash
+} = {}) {
+  assertPlainObject(job, "job");
+  if (!Array.isArray(events)) throw new TypeError("events must be an array");
+  assertNonEmptyString(evaluatedAtChainHash, "evaluatedAtChainHash");
+
+  // Ensure anchor exists (even though we may incorporate evidence appended after completion).
+  // This makes "what are we proving?" stable while allowing late evidence to update the proof result.
+  sliceThroughChainHash(events, evaluatedAtChainHash);
+
+  const requiredZones = job?.booking?.requiredZones ?? null;
+  const requiredZonesHash = job?.booking?.requiredZonesHash ?? null;
+
+  const proofPolicy = job?.booking?.policySnapshot?.proofPolicy ?? job?.booking?.policySnapshot?.proof ?? null;
+  const zc = proofPolicy?.zoneCoverage ?? {};
+  const thresholdPct = Number.isSafeInteger(zc?.thresholdPct) ? zc.thresholdPct : 95;
+  const excuseIncidentTypes = Array.isArray(zc?.excuseIncidentTypes) ? zc.excuseIncidentTypes : ["BLOCKED_ZONE"];
+
+  if (!requiredZones || typeof requiredZones !== "object") {
+    const missingEvidence = canonicalizeMissingEvidenceList([MISSING_EVIDENCE.REQUIRED_ZONES]);
+    const factsHash = sha256Hex(
+      canonicalJsonStringify(
+        normalizeForCanonicalJson(
+          {
+            schemaVersion: "ZoneCoverageFacts.v1",
+            evaluatedAtChainHash,
+            requiredZonesHash: requiredZonesHash ?? null,
+            thresholdPct,
+            requiredZoneIds: [],
+            coverageByZone: [],
+            excusedZones: [],
+              excuseIncidentTypes: Array.from(new Set(excuseIncidentTypes.map((t) => String(t)))).sort()
+          },
+          { path: "$" }
+        )
+      )
+    );
+    return {
+      schemaVersion: "ProofResult.v1",
+      status: PROOF_STATUS.INSUFFICIENT_EVIDENCE,
+      reasonCodes: [PROOF_REASON_CODE.REQUIRED_ZONES_MISSING],
+      missingEvidence,
+      triggeredFacts: [],
+      metrics: { requiredZones: 0, reportedZones: 0, excusedZones: 0, belowThresholdZones: 0, minCoveragePct: null },
+      factsHash,
+      anchors: { evaluatedAtChainHash, customerPolicyHash: customerPolicyHash ?? null, operatorPolicyHash: operatorPolicyHash ?? null, requiredZonesHash: requiredZonesHash ?? null }
+    };
+  }
+
+  validateZoneSetV1(requiredZones);
+  const requiredZoneIds = requiredZones.zones.map((z) => String(z.zoneId));
+
+  // NOTE: Evidence may arrive after completion. We incorporate all evidence events in the stream,
+  // while still anchoring the proof to a specific completion chainHash.
+  const coverageByZone = latestCoverageByZone(events);
+  const excuseInfo = excusedZonesFromIncidents(events, { excuseIncidentTypes });
+
+  let minCoveragePct = null;
+  let belowThresholdZones = 0;
+  let missingZones = 0;
+  let excusedZones = 0;
+  const missingZoneIds = [];
+
+  const reasonCodes = new Set();
+  const triggeredFacts = [];
+
+  for (const z of requiredZoneIds) {
+    const excused = excuseInfo.excused.has(z);
+    const coverageEvent = coverageByZone.get(z) ?? null;
+
+    if (!coverageEvent) {
+      if (excused) {
+        excusedZones += 1;
+        reasonCodes.add(PROOF_REASON_CODE.ZONE_EXCUSED_BY_INCIDENT);
+        continue;
+      }
+      missingZones += 1;
+      missingZoneIds.push(z);
+      reasonCodes.add(PROOF_REASON_CODE.MISSING_ZONE_COVERAGE);
+      continue;
+    }
+
+    triggeredFacts.push({ eventId: coverageEvent.id ?? null, type: coverageEvent.type, zoneId: z });
+    const pct = Number.isSafeInteger(coverageEvent.payload?.coveragePct) ? coverageEvent.payload.coveragePct : null;
+    if (Number.isSafeInteger(pct)) {
+      if (minCoveragePct === null || pct < minCoveragePct) minCoveragePct = pct;
+      if (!excused && pct < thresholdPct) {
+        belowThresholdZones += 1;
+        reasonCodes.add(PROOF_REASON_CODE.ZONE_BELOW_THRESHOLD);
+      }
+    }
+  }
+
+  // Decide overall status with strict precedence:
+  // FAIL > INSUFFICIENT_EVIDENCE > PASS
+  let status = PROOF_STATUS.PASS;
+  if (belowThresholdZones > 0) status = PROOF_STATUS.FAIL;
+  else if (missingZones > 0) status = PROOF_STATUS.INSUFFICIENT_EVIDENCE;
+
+  const missingEvidence = [];
+  if (missingZones > 0) {
+    missingEvidence.push(MISSING_EVIDENCE.ZONE_COVERAGE);
+    for (const z of missingZoneIds) {
+      missingEvidence.push(`${MISSING_EVIDENCE.ZONE_COVERAGE}:${missingEvidenceDetailFromZoneId(z)}`);
+    }
+  }
+
+  for (const f of excuseInfo.triggeredFacts) triggeredFacts.push(f);
+
+  // Deterministic ordering for audit friendliness.
+  triggeredFacts.sort((a, b) => {
+    const at = String(a?.type ?? "");
+    const bt = String(b?.type ?? "");
+    if (at !== bt) return at < bt ? -1 : 1;
+    const az = String(a?.zoneId ?? "");
+    const bz = String(b?.zoneId ?? "");
+    if (az !== bz) return az < bz ? -1 : 1;
+    const ae = String(a?.eventId ?? "");
+    const be = String(b?.eventId ?? "");
+    if (ae !== be) return ae < be ? -1 : 1;
+    return 0;
+  });
+
+  const metrics = {
+    requiredZones: requiredZoneIds.length,
+    reportedZones: Array.from(new Set(requiredZoneIds.filter((z) => coverageByZone.has(z)))).length,
+    excusedZones,
+    belowThresholdZones,
+    minCoveragePct
+  };
+
+  const facts = normalizeForCanonicalJson(
+    {
+      schemaVersion: "ZoneCoverageFacts.v1",
+      evaluatedAtChainHash,
+      requiredZonesHash: requiredZonesHash ?? null,
+      thresholdPct,
+      requiredZoneIds: Array.from(new Set(requiredZoneIds)).sort(),
+      coverageByZone: Array.from(coverageByZone.entries())
+        .filter(([zoneId]) => requiredZoneIds.includes(zoneId))
+        .map(([zoneId, ev]) => ({
+          zoneId,
+          coveragePct: Number.isSafeInteger(ev?.payload?.coveragePct) ? ev.payload.coveragePct : null,
+          window: ev?.payload?.window ?? null,
+          eventId: ev?.id ?? null,
+          chainHash: ev?.chainHash ?? null,
+          at: ev?.at ?? null
+        }))
+        .sort((a, b) => String(a.zoneId).localeCompare(String(b.zoneId)) || String(a.eventId ?? "").localeCompare(String(b.eventId ?? ""))),
+      excusedZones: Array.from(excuseInfo.excused.values()).sort(),
+      excuseIncidentTypes: Array.from(new Set(excuseIncidentTypes.map((t) => String(t)))).sort()
+    },
+    { path: "$" }
+  );
+  const factsHash = sha256Hex(canonicalJsonStringify(facts));
+
+  return {
+    schemaVersion: "ProofResult.v1",
+    status,
+    reasonCodes: Array.from(reasonCodes.values()).sort(),
+    missingEvidence: canonicalizeMissingEvidenceList(missingEvidence),
+    triggeredFacts,
+    metrics,
+    factsHash,
+    anchors: {
+      evaluatedAtChainHash,
+      customerPolicyHash: customerPolicyHash ?? null,
+      operatorPolicyHash: operatorPolicyHash ?? null,
+      requiredZonesHash: requiredZonesHash ?? null
+    }
+  };
+}

package/src/core/proof.js

@@ -0,0 +1,46 @@
+export const PROOF_STATUS = Object.freeze({
+  PASS: "PASS",
+  FAIL: "FAIL",
+  INSUFFICIENT_EVIDENCE: "INSUFFICIENT_EVIDENCE"
+});
+
+export const PROOF_REASON_CODE = Object.freeze({
+  REQUIRED_ZONES_MISSING: "REQUIRED_ZONES_MISSING",
+  MISSING_ZONE_COVERAGE: "MISSING_ZONE_COVERAGE",
+  ZONE_BELOW_THRESHOLD: "ZONE_BELOW_THRESHOLD",
+  ZONE_EXCUSED_BY_INCIDENT: "ZONE_EXCUSED_BY_INCIDENT"
+});
+
+// This is a requirements taxonomy (what evidence class is missing), not an outcome taxonomy.
+// It should be treated as a closed set: stable, searchable, and safe for downstream automation.
+export const MISSING_EVIDENCE = Object.freeze({
+  REQUIRED_ZONES: "REQUIRED_ZONES",
+  ZONE_COVERAGE: "ZONE_COVERAGE",
+  WITNESS: "WITNESS"
+});
+
+export const MISSING_EVIDENCE_SET = new Set(Object.values(MISSING_EVIDENCE));
+
+export function canonicalizeMissingEvidenceToken(token) {
+  if (typeof token !== "string") throw new TypeError("missingEvidence token must be a string");
+  const raw = token.trim();
+  if (!raw) throw new TypeError("missingEvidence token must be non-empty");
+  const colon = raw.indexOf(":");
+  const kindRaw = colon === -1 ? raw : raw.slice(0, colon);
+  const detailRaw = colon === -1 ? null : raw.slice(colon + 1);
+  const kind = kindRaw.toUpperCase();
+  if (!MISSING_EVIDENCE_SET.has(kind)) throw new TypeError("missingEvidence kind is not supported");
+  if (detailRaw === null) return kind;
+  if (detailRaw.includes(":")) throw new TypeError("missingEvidence detail must not include ':'");
+  const detail = detailRaw.toLowerCase();
+  if (!/^[a-z0-9][a-z0-9_-]{0,47}$/.test(detail)) throw new TypeError("missingEvidence detail has invalid characters");
+  return `${kind}:${detail}`;
+}
+
+export function canonicalizeMissingEvidenceList(list) {
+  if (list === null || list === undefined) return [];
+  if (!Array.isArray(list)) throw new TypeError("missingEvidence must be an array");
+  const out = [];
+  for (const t of list) out.push(canonicalizeMissingEvidenceToken(t));
+  return Array.from(new Set(out.values())).sort();
+}

package/src/core/protocol.js

@@ -0,0 +1,105 @@
+import fs from "node:fs";
+
+function assertNonEmptyString(value, name) {
+  if (typeof value !== "string" || value.trim() === "") throw new TypeError(`${name} must be a non-empty string`);
+}
+
+export const SETTLD_PROTOCOL_CURRENT = "1.0";
+
+export function parseProtocolVersion(text) {
+  assertNonEmptyString(text, "protocol");
+  const raw = String(text).trim();
+  const m = raw.match(/^(\d+)\.(\d+)$/);
+  if (!m) throw new TypeError("protocol must be major.minor (e.g. 1.0)");
+  const major = Number(m[1]);
+  const minor = Number(m[2]);
+  if (!Number.isSafeInteger(major) || major < 0) throw new TypeError("protocol major must be a non-negative integer");
+  if (!Number.isSafeInteger(minor) || minor < 0) throw new TypeError("protocol minor must be a non-negative integer");
+  return { major, minor, raw: `${major}.${minor}` };
+}
+
+export function compareProtocolVersions(a, b) {
+  const pa = typeof a === "string" ? parseProtocolVersion(a) : a;
+  const pb = typeof b === "string" ? parseProtocolVersion(b) : b;
+  if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+  if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+  return 0;
+}
+
+export function listSupportedProtocols({ min, max }) {
+  const pMin = parseProtocolVersion(min);
+  const pMax = parseProtocolVersion(max);
+  if (compareProtocolVersions(pMin, pMax) > 0) throw new TypeError("min protocol must be <= max protocol");
+
+  // Simple enumerator: only expands contiguous minor versions within the same major.
+  if (pMin.major !== pMax.major) return [pMin.raw, pMax.raw];
+  const out = [];
+  for (let m = pMin.minor; m <= pMax.minor; m += 1) out.push(`${pMin.major}.${m}`);
+  return out;
+}
+
+export function loadProtocolDeprecations(filePath) {
+  if (filePath === null || filePath === undefined) return { byVersion: new Map() };
+  const p = String(filePath).trim();
+  if (!p) return { byVersion: new Map() };
+  if (!fs.existsSync(p)) throw new Error(`PROXY_PROTOCOL_DEPRECATIONS file not found: ${p}`);
+  const raw = fs.readFileSync(p, "utf8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`invalid PROXY_PROTOCOL_DEPRECATIONS JSON: ${err?.message ?? "parse error"}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new TypeError("PROXY_PROTOCOL_DEPRECATIONS must be a JSON object");
+
+  const byVersion = new Map();
+  for (const [ver, v] of Object.entries(parsed)) {
+    if (!ver) continue;
+    const norm = parseProtocolVersion(ver).raw;
+    const cutoff = v?.cutoff ?? v?.cutoffAt ?? v?.cutoff_at ?? null;
+    if (cutoff === null || cutoff === undefined || String(cutoff).trim() === "") continue;
+    const cutoffIso = new Date(String(cutoff)).toISOString();
+    byVersion.set(norm, { cutoffAt: cutoffIso });
+  }
+  return { byVersion };
+}
+
+export function resolveProtocolPolicy({
+  current = SETTLD_PROTOCOL_CURRENT,
+  min = null,
+  max = null,
+  requireHeader = null,
+  buildId = null,
+  deprecationsPath = null
+} = {}) {
+  const nodeEnv = typeof process !== "undefined" ? (process.env.NODE_ENV ?? "development") : "development";
+  const envMin = typeof process !== "undefined" ? (process.env.PROXY_PROTOCOL_MIN ?? null) : null;
+  const envMax = typeof process !== "undefined" ? (process.env.PROXY_PROTOCOL_MAX ?? null) : null;
+  const envDep = typeof process !== "undefined" ? (process.env.PROXY_PROTOCOL_DEPRECATIONS ?? null) : null;
+  const envBuild =
+    typeof process !== "undefined"
+      ? (process.env.PROXY_BUILD ?? process.env.SETTLD_BUILD ?? process.env.GIT_SHA ?? process.env.SOURCE_VERSION ?? null)
+      : null;
+
+  const effectiveMin = (min ?? (envMin && String(envMin).trim() ? String(envMin).trim() : null) ?? current).trim();
+  const effectiveMax = (max ?? (envMax && String(envMax).trim() ? String(envMax).trim() : null) ?? current).trim();
+
+  const supported = listSupportedProtocols({ min: effectiveMin, max: effectiveMax });
+  const parsedCurrent = parseProtocolVersion(current).raw;
+  const requireInProdDefault = nodeEnv === "production";
+  const effectiveRequireHeader = requireHeader === null || requireHeader === undefined ? requireInProdDefault : Boolean(requireHeader);
+
+  const depPath = deprecationsPath ?? (envDep && String(envDep).trim() ? String(envDep).trim() : null);
+  const deprecations = loadProtocolDeprecations(depPath);
+
+  return {
+    current: parsedCurrent,
+    min: parseProtocolVersion(effectiveMin).raw,
+    max: parseProtocolVersion(effectiveMax).raw,
+    supported,
+    requireHeader: effectiveRequireHeader,
+    buildId: buildId ?? (envBuild && String(envBuild).trim() ? String(envBuild).trim() : null),
+    deprecations
+  };
+}
+

package/src/core/quotas.js

@@ -0,0 +1,32 @@
+function assertSafeInt(value, name) {
+  if (!Number.isSafeInteger(value)) throw new TypeError(`${name} must be a safe integer`);
+}
+
+export function clampQuota({ tenantLimit = null, defaultLimit = 0, maxLimit = 0 } = {}) {
+  if (tenantLimit !== null && tenantLimit !== undefined) assertSafeInt(tenantLimit, "tenantLimit");
+  assertSafeInt(defaultLimit, "defaultLimit");
+  assertSafeInt(maxLimit, "maxLimit");
+  if (tenantLimit !== null && tenantLimit !== undefined && tenantLimit < 0) throw new TypeError("tenantLimit must be >= 0");
+  if (defaultLimit < 0) throw new TypeError("defaultLimit must be >= 0");
+  if (maxLimit < 0) throw new TypeError("maxLimit must be >= 0");
+
+  let limit = tenantLimit === null || tenantLimit === undefined ? defaultLimit : tenantLimit;
+
+  // Convention: 0 means "unlimited", but the platform may cap it.
+  if (maxLimit > 0) {
+    if (limit === 0) return maxLimit;
+    return Math.min(limit, maxLimit);
+  }
+
+  return limit;
+}
+
+export function isQuotaExceeded({ current, limit }) {
+  assertSafeInt(current, "current");
+  assertSafeInt(limit, "limit");
+  if (current < 0) throw new TypeError("current must be >= 0");
+  if (limit < 0) throw new TypeError("limit must be >= 0");
+  if (limit === 0) return false;
+  return current >= limit;
+}
+