frontend-project-context 1.3.1 → 1.7.0

package/src/project-context/truth-reconciliation-schema.mjs

@@ -0,0 +1,488 @@
+import { canonicalValue, digestJson, validateJsonValue } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { normalizeRelativePath } from "./path-policy.mjs";
+
+export const HOST_PROMOTION_EVIDENCE_SCHEMA_VERSION = 1;
+export const TRUTH_RECONCILIATION_INPUT_SCHEMA_VERSION = 2;
+export const TRUTH_RECONCILIATION_REVIEW_BUNDLE_SCHEMA_VERSION = 2;
+
+const ID = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u;
+const SHA256 = /^sha256:[a-f0-9]{64}$/u;
+const ITEM_KINDS = new Set(["fact", "policy", "reference", "validation-description"]);
+const STAGES = new Set(["qa", "preproduction", "production", "withdrawn", "rollback"]);
+const TARGET_STAGES = new Set(["development", "qa", "preproduction", "production"]);
+const LIFECYCLES = new Set(["active", "released", "withdrawn", "rolled-back"]);
+const VERIFICATION_STATUSES = new Set(["passed", "failed", "skipped", "observed"]);
+const CHANGE_CLASSES = new Set([
+  "duplicate", "compatible-compose", "scope-split", "supersede", "semantic-conflict", "implementation-only",
+]);
+const SEVERITIES = new Set(["attention", "conflict", "blocked"]);
+const RESOLUTION_KINDS = new Set([
+  "accept-branch-change", "compose-compatible-changes", "defer-scoped-conflict", "external-implementation-fix-required",
+  "fix-source-and-rerun", "keep-current-baseline", "refresh-promotion-evidence", "replace-or-deprecate-source", "split-scope-or-override",
+]);
+
+function invalid(message, details) {
+  fail("truth-reconciliation-input-invalid", message, { details });
+}
+
+function object(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) invalid(`${label} must be an object`);
+}
+
+function exactKeys(value, keys, label) {
+  for (const key of Object.keys(value)) if (!keys.has(key)) invalid(`${label} contains unknown field: ${key}`);
+}
+
+function requiredKeys(value, keys, label) {
+  for (const key of keys) if (!Object.hasOwn(value, key)) invalid(`${label}.${key} is required`);
+}
+
+function string(value, label) {
+  if (typeof value !== "string" || value.length === 0) invalid(`${label} must be a non-empty string`);
+}
+
+function id(value, label) {
+  string(value, label);
+  if (!ID.test(value)) invalid(`${label} must use stable lowercase dot/kebab naming`);
+  return value;
+}
+
+function digest(value, label) {
+  string(value, label);
+  if (!SHA256.test(value)) invalid(`${label} must be sha256`);
+  return value;
+}
+
+function enumeration(value, allowed, label) {
+  if (!allowed.has(value)) invalid(`${label} is invalid`);
+  return value;
+}
+
+function array(value, label, max = 256) {
+  if (!Array.isArray(value)) invalid(`${label} must be an array`);
+  if (value.length > max) invalid(`${label} exceeds ${max} entries`);
+}
+
+function uniqueSorted(values, label, normalize, identity = (value) => JSON.stringify(value)) {
+  array(values, label);
+  const entries = values.map((value, index) => normalize(value, `${label}[${index}]`));
+  const byIdentity = new Map();
+  for (const entry of entries) {
+    const key = identity(entry);
+    if (byIdentity.has(key)) invalid(`${label} contains duplicate entry: ${key}`);
+    byIdentity.set(key, entry);
+  }
+  return [...byIdentity.values()].sort((left, right) => identity(left).localeCompare(identity(right)));
+}
+
+function ids(value, label) {
+  return uniqueSorted(value, label, id, (entry) => entry);
+}
+
+function paths(value, label) {
+  return uniqueSorted(value, label, (entry, entryLabel) => {
+    try {
+      return normalizeRelativePath(entry, { allowRoot: true, label: entryLabel });
+    } catch (error) {
+      invalid(`${entryLabel} must stay inside the project`, { path: entry, reason: error.code ?? "invalid-path" });
+    }
+  }, (entry) => entry);
+}
+
+export function normalizeTruthScope(value, label) {
+  object(value, label);
+  exactKeys(value, new Set(["kind", "path"]), label);
+  requiredKeys(value, ["kind"], label);
+  if (!new Set(["project", "path-prefix", "file"]).has(value.kind)) invalid(`${label}.kind is invalid`);
+  if (value.kind === "project") {
+    if (value.path !== undefined && value.path !== ".") invalid(`${label}.path must be omitted or '.' for project scope`);
+    return { kind: "project" };
+  }
+  try {
+    return { kind: value.kind, path: normalizeRelativePath(value.path, { label: `${label}.path` }) };
+  } catch (error) {
+    invalid(`${label}.path must stay inside the project`, { path: value.path, reason: error.code ?? "invalid-path" });
+  }
+}
+
+export function normalizeTruthSnapshots(value, label) {
+  object(value, label);
+  const keys = new Set(["contract", "sourcesLock", "projectionsLock"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  return {
+    contract: digest(value.contract, `${label}.contract`),
+    sourcesLock: digest(value.sourcesLock, `${label}.sourcesLock`),
+    projectionsLock: digest(value.projectionsLock, `${label}.projectionsLock`),
+  };
+}
+
+function normalizeVerificationResult(value, label) {
+  object(value, label);
+  const keys = new Set(["id", "status"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  return { id: id(value.id, `${label}.id`), status: enumeration(value.status, VERIFICATION_STATUSES, `${label}.status`) };
+}
+
+export function normalizeHostPromotionEvidence(value, label = "host promotion evidence") {
+  object(value, label);
+  const keys = new Set([
+    "schemaVersion", "kind", "taskId", "stage", "baseRevision", "candidateRevision", "codeSnapshotDigest",
+    "sourceSnapshotDigest", "artifactDigest", "changedPaths", "projectSnapshots", "acceptanceSuiteDigest",
+    "verificationResults", "integration", "equivalentToCodeSnapshotDigest",
+  ]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, [
+    "schemaVersion", "kind", "taskId", "stage", "baseRevision", "candidateRevision", "codeSnapshotDigest",
+    "sourceSnapshotDigest", "artifactDigest", "changedPaths", "projectSnapshots", "acceptanceSuiteDigest", "verificationResults",
+  ], label);
+  if (value.schemaVersion !== HOST_PROMOTION_EVIDENCE_SCHEMA_VERSION) invalid(`${label}.schemaVersion must be 1`);
+  if (value.kind !== "host-promotion-evidence") invalid(`${label}.kind must be host-promotion-evidence`);
+  if (value.integration !== undefined && typeof value.integration !== "boolean") invalid(`${label}.integration must be boolean`);
+  return {
+    schemaVersion: HOST_PROMOTION_EVIDENCE_SCHEMA_VERSION,
+    kind: "host-promotion-evidence",
+    taskId: id(value.taskId, `${label}.taskId`),
+    stage: enumeration(value.stage, STAGES, `${label}.stage`),
+    baseRevision: (string(value.baseRevision, `${label}.baseRevision`), value.baseRevision),
+    candidateRevision: (string(value.candidateRevision, `${label}.candidateRevision`), value.candidateRevision),
+    codeSnapshotDigest: digest(value.codeSnapshotDigest, `${label}.codeSnapshotDigest`),
+    sourceSnapshotDigest: digest(value.sourceSnapshotDigest, `${label}.sourceSnapshotDigest`),
+    artifactDigest: digest(value.artifactDigest, `${label}.artifactDigest`),
+    changedPaths: paths(value.changedPaths, `${label}.changedPaths`),
+    projectSnapshots: normalizeTruthSnapshots(value.projectSnapshots, `${label}.projectSnapshots`),
+    acceptanceSuiteDigest: digest(value.acceptanceSuiteDigest, `${label}.acceptanceSuiteDigest`),
+    verificationResults: uniqueSorted(value.verificationResults, `${label}.verificationResults`, normalizeVerificationResult, (entry) => entry.id),
+    integration: value.integration ?? false,
+    ...(value.equivalentToCodeSnapshotDigest !== undefined
+      ? { equivalentToCodeSnapshotDigest: digest(value.equivalentToCodeSnapshotDigest, `${label}.equivalentToCodeSnapshotDigest`) }
+      : {}),
+  };
+}
+
+function normalizeCurrentSource(value, label) {
+  object(value, label);
+  exactKeys(value, new Set(["id", "digest"]), label);
+  requiredKeys(value, ["id", "digest"], label);
+  return { id: id(value.id, `${label}.id`), digest: digest(value.digest, `${label}.digest`) };
+}
+
+function normalizeCurrentItem(value, label) {
+  object(value, label);
+  exactKeys(value, new Set(["id", "digest", "subject", "kind", "scope"]), label);
+  requiredKeys(value, ["id", "digest", "subject", "kind", "scope"], label);
+  return {
+    id: id(value.id, `${label}.id`), digest: digest(value.digest, `${label}.digest`),
+    subject: id(value.subject, `${label}.subject`), kind: enumeration(value.kind, ITEM_KINDS, `${label}.kind`),
+    scope: normalizeTruthScope(value.scope, `${label}.scope`),
+  };
+}
+
+function normalizeSourceChange(value, label) {
+  object(value, label);
+  const keys = new Set(["sourceId", "expectedDigest", "candidateDigest", "affectedItemIds", "subjects", "scopes", "classification"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  return {
+    sourceId: id(value.sourceId, `${label}.sourceId`),
+    expectedDigest: digest(value.expectedDigest, `${label}.expectedDigest`),
+    candidateDigest: digest(value.candidateDigest, `${label}.candidateDigest`),
+    affectedItemIds: ids(value.affectedItemIds, `${label}.affectedItemIds`),
+    subjects: ids(value.subjects, `${label}.subjects`),
+    scopes: uniqueSorted(value.scopes, `${label}.scopes`, normalizeTruthScope),
+    classification: enumeration(value.classification, CHANGE_CLASSES, `${label}.classification`),
+  };
+}
+
+function normalizeItemChange(value, label) {
+  object(value, label);
+  const keys = new Set(["itemId", "expectedDigest", "candidateDigest", "sourceIds", "subject", "kind", "scope", "classification"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  return {
+    itemId: id(value.itemId, `${label}.itemId`),
+    expectedDigest: digest(value.expectedDigest, `${label}.expectedDigest`),
+    candidateDigest: digest(value.candidateDigest, `${label}.candidateDigest`),
+    sourceIds: ids(value.sourceIds, `${label}.sourceIds`),
+    subject: id(value.subject, `${label}.subject`),
+    kind: enumeration(value.kind, ITEM_KINDS, `${label}.kind`),
+    scope: normalizeTruthScope(value.scope, `${label}.scope`),
+    classification: enumeration(value.classification, CHANGE_CLASSES, `${label}.classification`),
+  };
+}
+
+function normalizeCandidate(value, label) {
+  object(value, label);
+  const keys = new Set([
+    "id", "taskId", "lifecycle", "targetStage", "baseRevision", "expectedProjectSnapshots", "currentCodeSnapshotDigest",
+    "currentSourceSnapshotDigest", "currentArtifactDigest", "currentAcceptanceSuiteDigest", "changedPaths", "sourceChanges", "itemChanges",
+    "decisionCandidateIds", "promotionEvidence",
+  ]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  return {
+    id: id(value.id, `${label}.id`), taskId: id(value.taskId, `${label}.taskId`),
+    lifecycle: enumeration(value.lifecycle, LIFECYCLES, `${label}.lifecycle`),
+    targetStage: enumeration(value.targetStage, TARGET_STAGES, `${label}.targetStage`),
+    baseRevision: (string(value.baseRevision, `${label}.baseRevision`), value.baseRevision),
+    expectedProjectSnapshots: normalizeTruthSnapshots(value.expectedProjectSnapshots, `${label}.expectedProjectSnapshots`),
+    currentCodeSnapshotDigest: digest(value.currentCodeSnapshotDigest, `${label}.currentCodeSnapshotDigest`),
+    currentSourceSnapshotDigest: digest(value.currentSourceSnapshotDigest, `${label}.currentSourceSnapshotDigest`),
+    currentArtifactDigest: digest(value.currentArtifactDigest, `${label}.currentArtifactDigest`),
+    currentAcceptanceSuiteDigest: digest(value.currentAcceptanceSuiteDigest, `${label}.currentAcceptanceSuiteDigest`),
+    changedPaths: paths(value.changedPaths, `${label}.changedPaths`),
+    sourceChanges: uniqueSorted(value.sourceChanges, `${label}.sourceChanges`, normalizeSourceChange, (entry) => entry.sourceId),
+    itemChanges: uniqueSorted(value.itemChanges, `${label}.itemChanges`, normalizeItemChange, (entry) => entry.itemId),
+    decisionCandidateIds: ids(value.decisionCandidateIds, `${label}.decisionCandidateIds`),
+    promotionEvidence: uniqueSorted(value.promotionEvidence, `${label}.promotionEvidence`, normalizeHostPromotionEvidence, (entry) => `${entry.stage}:${entry.candidateRevision}:${entry.artifactDigest}`),
+  };
+}
+
+function normalizeGlobalFinding(value, label) {
+  object(value, label);
+  const keys = new Set(["code", "severity", "sourceIds", "itemIds", "subjects", "scopes", "itemKinds"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  return {
+    code: id(value.code, `${label}.code`), severity: enumeration(value.severity, SEVERITIES, `${label}.severity`),
+    sourceIds: ids(value.sourceIds, `${label}.sourceIds`), itemIds: ids(value.itemIds, `${label}.itemIds`),
+    subjects: ids(value.subjects, `${label}.subjects`),
+    scopes: uniqueSorted(value.scopes, `${label}.scopes`, normalizeTruthScope),
+    itemKinds: uniqueSorted(value.itemKinds, `${label}.itemKinds`, (entry, entryLabel) => enumeration(entry, ITEM_KINDS, entryLabel), (entry) => entry),
+  };
+}
+
+function normalizeResolutionDecision(value, label) {
+  object(value, label);
+  const keys = new Set(["findingDigest", "resolutionKind", "humanInputs", "externalAction"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, ["findingDigest", "resolutionKind", "humanInputs"], label);
+  if (value.humanInputs === null || typeof value.humanInputs !== "object" || Array.isArray(value.humanInputs)) invalid(`${label}.humanInputs must be an object`);
+  for (const [key, entry] of Object.entries(value.humanInputs)) {
+    string(key, `${label}.humanInputs key`);
+    try { validateJsonValue(entry); } catch (error) { invalid(`${label}.humanInputs.${key} must be JSON-compatible`); }
+  }
+  if (value.externalAction !== undefined) {
+    object(value.externalAction, `${label}.externalAction`);
+    exactKeys(value.externalAction, new Set(["kind", "completed", "evidenceDigests"]), `${label}.externalAction`);
+    requiredKeys(value.externalAction, ["kind", "completed", "evidenceDigests"], `${label}.externalAction`);
+    string(value.externalAction.kind, `${label}.externalAction.kind`);
+    if (typeof value.externalAction.completed !== "boolean") invalid(`${label}.externalAction.completed must be boolean`);
+  }
+  return canonicalValue({
+    findingDigest: digest(value.findingDigest, `${label}.findingDigest`),
+    resolutionKind: enumeration(value.resolutionKind, RESOLUTION_KINDS, `${label}.resolutionKind`),
+    humanInputs: value.humanInputs,
+    ...(value.externalAction !== undefined ? { externalAction: { kind: value.externalAction.kind, completed: value.externalAction.completed, evidenceDigests: uniqueSorted(value.externalAction.evidenceDigests, `${label}.externalAction.evidenceDigests`, digest, (entry) => entry) } } : {}),
+  });
+}
+
+function normalizeResolutionAttempt(value, label) {
+  if (value === null) return null;
+  object(value, label);
+  const keys = new Set(["previousReviewDigest", "decisions", "projectContextStatus"]);
+  exactKeys(value, keys, label);
+  requiredKeys(value, keys, label);
+  if (!new Set(["clean", "attention", "conflict", "invalid", "partial"]).has(value.projectContextStatus)) invalid(`${label}.projectContextStatus is invalid`);
+  return {
+    previousReviewDigest: digest(value.previousReviewDigest, `${label}.previousReviewDigest`),
+    decisions: uniqueSorted(value.decisions, `${label}.decisions`, normalizeResolutionDecision, (entry) => entry.findingDigest),
+    projectContextStatus: value.projectContextStatus,
+  };
+}
+
+export function normalizeTruthReconciliationInput(input) {
+  try { validateJsonValue(input); } catch (error) { invalid("truth reconciliation input must be JSON-compatible", { reason: error.message }); }
+  object(input, "truth reconciliation input");
+  const keys = new Set(["schemaVersion", "kind", "projectId", "current", "task", "candidates", "globalFindings", "resolutionAttempt"]);
+  exactKeys(input, keys, "truth reconciliation input");
+  requiredKeys(input, keys, "truth reconciliation input");
+  if (input.schemaVersion !== TRUTH_RECONCILIATION_INPUT_SCHEMA_VERSION) invalid("truth reconciliation input.schemaVersion must be 2");
+  if (input.kind !== "truth-reconciliation-input") invalid("truth reconciliation input.kind must be truth-reconciliation-input");
+  object(input.current, "current");
+  exactKeys(input.current, new Set(["revision", "projectSnapshots", "sources", "items"]), "current");
+  requiredKeys(input.current, ["revision", "projectSnapshots", "sources", "items"], "current");
+  object(input.task, "task");
+  exactKeys(input.task, new Set(["id", "paths"]), "task");
+  requiredKeys(input.task, ["id", "paths"], "task");
+  const normalized = {
+    schemaVersion: 2, kind: "truth-reconciliation-input", projectId: id(input.projectId, "projectId"),
+    current: {
+      revision: (string(input.current.revision, "current.revision"), input.current.revision),
+      projectSnapshots: normalizeTruthSnapshots(input.current.projectSnapshots, "current.projectSnapshots"),
+      sources: uniqueSorted(input.current.sources, "current.sources", normalizeCurrentSource, (entry) => entry.id),
+      items: uniqueSorted(input.current.items, "current.items", normalizeCurrentItem, (entry) => entry.id),
+    },
+    task: { id: id(input.task.id, "task.id"), paths: paths(input.task.paths, "task.paths") },
+    candidates: uniqueSorted(input.candidates, "candidates", normalizeCandidate, (entry) => entry.id),
+    globalFindings: uniqueSorted(input.globalFindings, "globalFindings", normalizeGlobalFinding, (entry) => `${entry.code}:${JSON.stringify(entry.scopes)}`),
+    resolutionAttempt: normalizeResolutionAttempt(input.resolutionAttempt, "resolutionAttempt"),
+  };
+  return canonicalValue(normalized);
+}
+
+export function finalizeTruthReviewBundle(bundleWithoutDigest) {
+  const canonical = canonicalValue(bundleWithoutDigest);
+  return canonicalValue({ ...canonical, bundleDigest: digestJson(canonical) });
+}
+
+function reviewBoolean(value, expected, label) {
+  if (typeof value !== "boolean" || (expected !== undefined && value !== expected)) invalid(`${label} is invalid`);
+}
+function reviewStrings(value, label, { idsOnly = false, nonEmpty = false } = {}) {
+  array(value, label);
+  if (nonEmpty && value.length === 0) invalid(`${label} must not be empty`);
+  const seen = new Set();
+  value.forEach((entry, index) => {
+    if (idsOnly) id(entry, `${label}[${index}]`); else string(entry, `${label}[${index}]`);
+    if (seen.has(entry)) invalid(`${label} contains duplicate entry: ${entry}`);
+    seen.add(entry);
+  });
+}
+function reviewBaseline(value, label) {
+  object(value, label);
+  const keys = new Set(["actualDigest", "actualLabel", "expectedDigest", "expectedLabel"]);
+  exactKeys(value, keys, label); requiredKeys(value, keys, label);
+  for (const key of ["actualDigest", "expectedDigest"]) if (value[key] !== null) digest(value[key], `${label}.${key}`);
+  for (const key of ["actualLabel", "expectedLabel"]) if (value[key] !== null) string(value[key], `${label}.${key}`);
+}
+function reviewInvocation(value, label) {
+  object(value, label); exactKeys(value, new Set(["args", "command"]), label); requiredKeys(value, ["args", "command"], label);
+  id(value.command, `${label}.command`);
+  array(value.args, `${label}.args`);
+  value.args.forEach((entry, index) => { if (typeof entry !== "string") invalid(`${label}.args[${index}] must be a string`); });
+}
+function reviewPreview(value, label) {
+  object(value, label);
+  exactKeys(value, new Set(["externalAction", "invocation", "requiredHumanInputs", "resolutionKind"]), label);
+  requiredKeys(value, ["resolutionKind"], label);
+  enumeration(value.resolutionKind, RESOLUTION_KINDS, `${label}.resolutionKind`);
+  if (value.invocation !== undefined) reviewInvocation(value.invocation, `${label}.invocation`);
+  if (value.requiredHumanInputs !== undefined) reviewStrings(value.requiredHumanInputs, `${label}.requiredHumanInputs`);
+  if (value.externalAction !== undefined) {
+    object(value.externalAction, `${label}.externalAction`);
+    exactKeys(value.externalAction, new Set(["affectedItemIds", "affectedPaths", "affectedSourceIds", "kind"]), `${label}.externalAction`);
+    requiredKeys(value.externalAction, ["kind"], `${label}.externalAction`);
+    string(value.externalAction.kind, `${label}.externalAction.kind`);
+    if (value.externalAction.affectedSourceIds !== undefined) reviewStrings(value.externalAction.affectedSourceIds, `${label}.externalAction.affectedSourceIds`, { idsOnly: true });
+    if (value.externalAction.affectedItemIds !== undefined) reviewStrings(value.externalAction.affectedItemIds, `${label}.externalAction.affectedItemIds`, { idsOnly: true });
+    if (value.externalAction.affectedPaths !== undefined) paths(value.externalAction.affectedPaths, `${label}.externalAction.affectedPaths`);
+  }
+}
+function reviewResolutionContract(value, label) {
+  object(value, label);
+  const keys = new Set(["completionCriteria", "nextActions", "recomputeFromCurrentBaseline", "requiredHumanInputs", "requiredPostResolutionEvidence", "resolutionKinds", "resolutionState"]);
+  exactKeys(value, keys, label); requiredKeys(value, keys, label);
+  enumeration(value.resolutionState, new Set(["needs-human-decision", "contract-action-required", "external-fix-required", "revalidation-required", "resolved", "deferred-open"]), `${label}.resolutionState`);
+  reviewStrings(value.resolutionKinds, `${label}.resolutionKinds`, { nonEmpty: true });
+  value.resolutionKinds.forEach((entry) => enumeration(entry, RESOLUTION_KINDS, `${label}.resolutionKinds entry`));
+  reviewStrings(value.requiredHumanInputs, `${label}.requiredHumanInputs`);
+  array(value.nextActions, `${label}.nextActions`); if (value.nextActions.length === 0) invalid(`${label}.nextActions must not be empty`);
+  value.nextActions.forEach((entry, index) => reviewPreview(entry, `${label}.nextActions[${index}]`));
+  reviewStrings(value.requiredPostResolutionEvidence, `${label}.requiredPostResolutionEvidence`, { nonEmpty: true });
+  reviewStrings(value.completionCriteria, `${label}.completionCriteria`, { nonEmpty: true });
+  reviewBoolean(value.recomputeFromCurrentBaseline, true, `${label}.recomputeFromCurrentBaseline`);
+}
+
+export function validateTruthReviewBundle(input) {
+  try { validateJsonValue(input); } catch (error) { invalid("truth review bundle must be JSON-compatible", { reason: error.message }); }
+  object(input, "truth review bundle");
+  const keys = new Set(["schemaVersion", "kind", "project", "current", "task", "inputDigest", "summary", "candidateOutcomes", "collisionGroups", "findings", "resolutionOutcomes", "guarantees", "boundaries", "bundleDigest"]);
+  exactKeys(input, keys, "truth review bundle");
+  requiredKeys(input, keys, "truth review bundle");
+  if (input.schemaVersion !== 2 || input.kind !== "truth-reconciliation-review-bundle") invalid("truth review bundle identity is invalid");
+  digest(input.bundleDigest, "truth review bundle.bundleDigest");
+  const copy = structuredClone(input);
+  delete copy.bundleDigest;
+  if (digestJson(canonicalValue(copy)) !== input.bundleDigest) invalid("truth review bundle.bundleDigest does not match canonical content");
+  object(input.project, "truth review bundle.project");
+  exactKeys(input.project, new Set(["id", "name"]), "truth review bundle.project"); requiredKeys(input.project, ["id", "name"], "truth review bundle.project");
+  id(input.project.id, "truth review bundle.project.id"); string(input.project.name, "truth review bundle.project.name");
+  object(input.current, "truth review bundle.current");
+  exactKeys(input.current, new Set(["projectSnapshots", "revision"]), "truth review bundle.current"); requiredKeys(input.current, ["projectSnapshots", "revision"], "truth review bundle.current");
+  string(input.current.revision, "truth review bundle.current.revision"); normalizeTruthSnapshots(input.current.projectSnapshots, "truth review bundle.current.projectSnapshots");
+  object(input.task, "truth review bundle.task");
+  exactKeys(input.task, new Set(["id", "paths"]), "truth review bundle.task"); requiredKeys(input.task, ["id", "paths"], "truth review bundle.task");
+  id(input.task.id, "truth review bundle.task.id"); paths(input.task.paths, "truth review bundle.task.paths");
+  digest(input.inputDigest, "truth review bundle.inputDigest");
+  object(input.summary, "truth review bundle.summary");
+  const summaryKeys = new Set(["candidates", "collisionGroups", "eligibleCandidates", "existingDelivery", "findings", "globalHealth", "taskHealth"]);
+  exactKeys(input.summary, summaryKeys, "truth review bundle.summary"); requiredKeys(input.summary, summaryKeys, "truth review bundle.summary");
+  for (const key of ["candidates", "collisionGroups", "eligibleCandidates", "findings"]) if (!Number.isSafeInteger(input.summary[key]) || input.summary[key] < 0) invalid(`truth review bundle.summary.${key} is invalid`);
+  enumeration(input.summary.taskHealth, new Set(["ready", "blocked"]), "truth review bundle.summary.taskHealth");
+  enumeration(input.summary.globalHealth, new Set(["clean", "attention"]), "truth review bundle.summary.globalHealth");
+  if (input.summary.existingDelivery !== "not-blocked") invalid("truth review bundle.summary.existingDelivery is invalid");
+  array(input.candidateOutcomes, "truth review bundle.candidateOutcomes");
+  for (const [index, outcome] of input.candidateOutcomes.entries()) {
+    const label = `truth review bundle.candidateOutcomes[${index}]`;
+    object(outcome, label);
+    const outcomeKeys = new Set(["baseline", "candidateId", "decisionCandidates", "eligibleForReconciliation", "lifecycle", "promotionEvidence"]);
+    exactKeys(outcome, outcomeKeys, label); requiredKeys(outcome, outcomeKeys, label);
+    id(outcome.candidateId, `${label}.candidateId`); enumeration(outcome.lifecycle, LIFECYCLES, `${label}.lifecycle`);
+    enumeration(outcome.baseline, new Set(["current", "stale"]), `${label}.baseline`);
+    enumeration(outcome.decisionCandidates, new Set(["authority-free-candidates", "discarded-not-promoted"]), `${label}.decisionCandidates`);
+    reviewBoolean(outcome.eligibleForReconciliation, undefined, `${label}.eligibleForReconciliation`);
+    object(outcome.promotionEvidence, `${label}.promotionEvidence`);
+    const promotionKeys = new Set(["assurance", "currentEvidenceCount", "integrationVerified", "localQaReusable", "staleEvidenceCount"]);
+    exactKeys(outcome.promotionEvidence, promotionKeys, `${label}.promotionEvidence`); requiredKeys(outcome.promotionEvidence, promotionKeys, `${label}.promotionEvidence`);
+    if (outcome.promotionEvidence.assurance !== "host-asserted") invalid(`${label}.promotionEvidence.assurance is invalid`);
+    for (const key of ["currentEvidenceCount", "staleEvidenceCount"]) if (!Number.isSafeInteger(outcome.promotionEvidence[key]) || outcome.promotionEvidence[key] < 0) invalid(`${label}.promotionEvidence.${key} is invalid`);
+    reviewBoolean(outcome.promotionEvidence.localQaReusable, undefined, `${label}.promotionEvidence.localQaReusable`);
+    reviewBoolean(outcome.promotionEvidence.integrationVerified, undefined, `${label}.promotionEvidence.integrationVerified`);
+  }
+  array(input.collisionGroups, "truth review bundle.collisionGroups");
+  for (const [index, group] of input.collisionGroups.entries()) {
+    const label = `truth review bundle.collisionGroups[${index}]`;
+    object(group, label);
+    const groupKeys = new Set(["affectedItemIds", "affectedScopes", "affectedSourceIds", "affectedSubjects", "candidateDigests", "candidateIds", "classification", "key", "kind", "promoted", "resolutionKinds"]);
+    exactKeys(group, groupKeys, label); requiredKeys(group, groupKeys, label);
+    enumeration(group.kind, new Set(["source", "item", "subject"]), `${label}.kind`); id(group.key, `${label}.key`); enumeration(group.classification, CHANGE_CLASSES, `${label}.classification`);
+    for (const key of ["candidateIds", "affectedSourceIds", "affectedItemIds", "affectedSubjects"]) reviewStrings(group[key], `${label}.${key}`, { idsOnly: true });
+    reviewStrings(group.candidateDigests, `${label}.candidateDigests`); group.candidateDigests.forEach((entry) => digest(entry, `${label}.candidateDigests entry`));
+    array(group.affectedScopes, `${label}.affectedScopes`); group.affectedScopes.forEach((entry, scopeIndex) => normalizeTruthScope(entry, `${label}.affectedScopes[${scopeIndex}]`));
+    reviewStrings(group.resolutionKinds, `${label}.resolutionKinds`, { nonEmpty: true }); group.resolutionKinds.forEach((entry) => enumeration(entry, RESOLUTION_KINDS, `${label}.resolutionKinds entry`));
+    reviewBoolean(group.promoted, false, `${label}.promoted`);
+  }
+  array(input.findings, "truth review bundle.findings");
+  array(input.resolutionOutcomes, "truth review bundle.resolutionOutcomes");
+  for (const [index, finding] of input.findings.entries()) {
+    const label = `truth review bundle.findings[${index}]`;
+    object(finding, label);
+    const findingKeys = new Set(["affectedItemIds", "affectedScopes", "affectedSourceIds", "affectedSubjects", "baseline", "blocksExistingDelivery", "blocksTask", "code", "findingDigest", "humanRoles", "recomputeFromCurrentBaseline", "recoveryPreviews", "resolutionContract", "resolutionKinds", "severity", "validateAfterResolution"]);
+    exactKeys(finding, findingKeys, label); requiredKeys(finding, findingKeys, label);
+    id(finding.code, `${label}.code`); enumeration(finding.severity, SEVERITIES, `${label}.severity`);
+    for (const key of ["affectedSourceIds", "affectedItemIds", "affectedSubjects", "humanRoles", "validateAfterResolution"]) reviewStrings(finding[key], `${label}.${key}`, { idsOnly: true });
+    array(finding.affectedScopes, `${label}.affectedScopes`); finding.affectedScopes.forEach((entry, scopeIndex) => normalizeTruthScope(entry, `${label}.affectedScopes[${scopeIndex}]`));
+    reviewBaseline(finding.baseline, `${label}.baseline`);
+    reviewBoolean(finding.blocksTask, undefined, `${label}.blocksTask`); reviewBoolean(finding.blocksExistingDelivery, false, `${label}.blocksExistingDelivery`);
+    reviewStrings(finding.resolutionKinds, `${label}.resolutionKinds`, { nonEmpty: true }); finding.resolutionKinds.forEach((entry) => enumeration(entry, RESOLUTION_KINDS, `${label}.resolutionKinds entry`));
+    array(finding.recoveryPreviews, `${label}.recoveryPreviews`); if (finding.recoveryPreviews.length === 0) invalid(`${label}.recoveryPreviews must not be empty`);
+    finding.recoveryPreviews.forEach((entry, previewIndex) => reviewPreview(entry, `${label}.recoveryPreviews[${previewIndex}]`));
+    reviewBoolean(finding.recomputeFromCurrentBaseline, true, `${label}.recomputeFromCurrentBaseline`);
+    digest(finding.findingDigest, `${label}.findingDigest`);
+    reviewResolutionContract(finding.resolutionContract, `${label}.resolutionContract`);
+  }
+  for (const [index, outcome] of input.resolutionOutcomes.entries()) {
+    const label = `truth review bundle.resolutionOutcomes[${index}]`;
+    object(outcome, label);
+    const outcomeKeys = new Set(["completionCriteriaMet", "findingDigest", "outcome", "recomputedFromCurrentBaseline", "resolutionKind", "resolutionState"]);
+    exactKeys(outcome, outcomeKeys, label); requiredKeys(outcome, outcomeKeys, label);
+    digest(outcome.findingDigest, `${label}.findingDigest`); enumeration(outcome.resolutionKind, RESOLUTION_KINDS, `${label}.resolutionKind`);
+    enumeration(outcome.resolutionState, new Set(["revalidation-required", "external-fix-required", "resolved", "deferred-open"]), `${label}.resolutionState`);
+    enumeration(outcome.outcome, new Set(["open", "deferred", "resolved", "rejected"]), `${label}.outcome`);
+    reviewStrings(outcome.completionCriteriaMet, `${label}.completionCriteriaMet`);
+    reviewBoolean(outcome.recomputedFromCurrentBaseline, true, `${label}.recomputedFromCurrentBaseline`);
+  }
+  object(input.guarantees, "truth review bundle.guarantees");
+  exactKeys(input.guarantees, new Set(["hostAsserted", "humanDecided", "projectContextVerified"]), "truth review bundle.guarantees");
+  requiredKeys(input.guarantees, ["hostAsserted", "humanDecided", "projectContextVerified"], "truth review bundle.guarantees");
+  for (const key of ["hostAsserted", "humanDecided", "projectContextVerified"]) reviewStrings(input.guarantees[key], `truth review bundle.guarantees.${key}`, { idsOnly: true });
+  object(input.boundaries, "truth review bundle.boundaries");
+  const boundaryKeys = new Set(["automaticApproval", "automaticPromotion", "blocksExistingDelivery", "ciClient", "git", "network", "persistentQueue", "provider", "readOnly", "taskExecution"]);
+  exactKeys(input.boundaries, boundaryKeys, "truth review bundle.boundaries"); requiredKeys(input.boundaries, boundaryKeys, "truth review bundle.boundaries");
+  reviewBoolean(input.boundaries.readOnly, true, "truth review bundle.boundaries.readOnly");
+  for (const key of [...boundaryKeys].filter((entry) => entry !== "readOnly")) reviewBoolean(input.boundaries[key], false, `truth review bundle.boundaries.${key}`);
+  return canonicalValue(input);
+}