frontend-project-context 1.3.1 → 1.7.0

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

@@ -0,0 +1,543 @@
+import { canonicalJson, digestJson } from "./canonical-json.mjs";
+import { fail } from "./errors.mjs";
+import { readJsonFile } from "./io.mjs";
+import { resolveExistingInside } from "./path-policy.mjs";
+import { loadProject } from "./project-store.mjs";
+import {
+  finalizeTruthReviewBundle,
+  normalizeTruthReconciliationInput,
+  TRUTH_RECONCILIATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+  validateTruthReviewBundle,
+} from "./truth-reconciliation-schema.mjs";
+
+const RESOLUTIONS = Object.freeze({
+  duplicate: ["keep-current-baseline"],
+  "compatible-compose": ["compose-compatible-changes"],
+  "scope-split": ["split-scope-or-override"],
+  supersede: ["accept-branch-change", "replace-or-deprecate-source"],
+  "semantic-conflict": ["keep-current-baseline", "accept-branch-change", "defer-scoped-conflict"],
+  "implementation-only": ["external-implementation-fix-required"],
+});
+
+function uniqueSorted(values) {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function scopeKey(scope) {
+  return scope.kind === "project" ? "project" : `${scope.kind}:${scope.path}`;
+}
+
+function scopesOverlapPath(scope, target) {
+  if (scope.kind === "project") return true;
+  if (scope.kind === "file") return target === scope.path;
+  return target === scope.path || target.startsWith(`${scope.path}/`);
+}
+
+function isTaskRelated(scopes, taskPaths) {
+  return scopes.some((scope) => taskPaths.some((target) => scopesOverlapPath(scope, target)));
+}
+
+function invocation(root, command, args) {
+  return { command, args: ["--project", root, ...args] };
+}
+
+function recoveryPreviews(root, resolutionKinds, impacts, actualDigest) {
+  return resolutionKinds.map((resolutionKind) => {
+    if (resolutionKind === "accept-branch-change" && impacts.sourceIds.length === 1 && actualDigest) {
+      return {
+        resolutionKind,
+        invocation: invocation(root, "accept-source-change", [
+          "--id", impacts.sourceIds[0], "--expected-digest", actualDigest,
+          ...(impacts.itemIds.length > 0 ? ["--affected-items", ...impacts.itemIds] : []),
+        ]),
+      };
+    }
+    if (resolutionKind === "fix-source-and-rerun" || resolutionKind === "refresh-promotion-evidence") {
+      return { resolutionKind, externalAction: { kind: resolutionKind === "fix-source-and-rerun" ? "refresh-project-baseline-and-contract-state" : "refresh-host-promotion-evidence", affectedSourceIds: impacts.sourceIds, affectedItemIds: impacts.itemIds } };
+    }
+    if (resolutionKind === "replace-or-deprecate-source" && impacts.sourceIds.length === 1) {
+      return { resolutionKind, invocation: invocation(root, "review-source", ["--id", impacts.sourceIds[0]]) };
+    }
+    if (resolutionKind === "external-implementation-fix-required") {
+      return { resolutionKind, externalAction: { kind: "fix-implementation-outside-project-context", affectedPaths: impacts.scopes.map((scope) => scope.path ?? ".") } };
+    }
+    return { resolutionKind, requiredHumanInputs: resolutionKind === "compose-compatible-changes" ? ["composedValue", "sources", "scope"] : resolutionKind === "split-scope-or-override" ? ["scopes", "overrideIds"] : ["decisionRationale"] };
+  });
+}
+
+function finding(root, code, severity, impacts, options = {}) {
+  const normalized = {
+    sourceIds: uniqueSorted(impacts.sourceIds ?? []),
+    itemIds: uniqueSorted(impacts.itemIds ?? []),
+    subjects: uniqueSorted(impacts.subjects ?? []),
+    scopes: [...new Map((impacts.scopes ?? []).map((scope) => [scopeKey(scope), scope])).values()]
+      .sort((left, right) => scopeKey(left).localeCompare(scopeKey(right))),
+  };
+  const resolutionKinds = uniqueSorted(options.resolutionKinds ?? ["keep-current-baseline"]);
+  if (resolutionKinds.length === 0) {
+    return finding(root, "recovery-contract-incomplete", "blocked", normalized, {
+      resolutionKinds: ["fix-source-and-rerun"], blocksTask: true,
+    });
+  }
+  const base = {
+    code,
+    severity,
+    affectedSourceIds: normalized.sourceIds,
+    affectedItemIds: normalized.itemIds,
+    affectedSubjects: normalized.subjects,
+    affectedScopes: normalized.scopes,
+    baseline: {
+      expectedDigest: options.expectedDigest ?? null,
+      actualDigest: options.actualDigest ?? null,
+      expectedLabel: options.expectedLabel ?? null,
+      actualLabel: options.actualLabel ?? null,
+    },
+    blocksTask: options.blocksTask ?? false,
+    blocksExistingDelivery: false,
+    resolutionKinds,
+    recoveryPreviews: recoveryPreviews(root, resolutionKinds, normalized, options.actualDigest),
+    humanRoles: uniqueSorted(options.humanRoles ?? ["truth-maintainer"]),
+    validateAfterResolution: uniqueSorted(options.validateAfterResolution ?? ["reconcile-truth", "status", "check"]),
+    recomputeFromCurrentBaseline: true,
+  };
+  const previews = recoveryPreviews(root, resolutionKinds, normalized, options.actualDigest);
+  const resolutionState = resolutionKinds.includes("external-implementation-fix-required")
+    ? "external-fix-required"
+    : resolutionKinds.some((entry) => ["accept-branch-change", "compose-compatible-changes", "replace-or-deprecate-source", "split-scope-or-override"].includes(entry))
+      ? "contract-action-required"
+      : resolutionKinds.some((entry) => ["fix-source-and-rerun", "refresh-promotion-evidence"].includes(entry))
+        ? "revalidation-required"
+        : "needs-human-decision";
+  const resolutionContract = {
+    resolutionState,
+    resolutionKinds,
+    requiredHumanInputs: uniqueSorted(previews.flatMap((entry) => entry.requiredHumanInputs ?? [])),
+    nextActions: previews,
+    requiredPostResolutionEvidence: uniqueSorted(["current-project-snapshots", "current-source-and-item-baselines", "project-context-clean", ...(resolutionKinds.includes("external-implementation-fix-required") ? ["external-code-and-test-evidence"] : [])]),
+    completionCriteria: [
+      "previous-finding-absent-on-current-baseline",
+      "all-related-items-approved-and-effective",
+      "all-related-validation-current-and-passing",
+      "project-context-impact-closure-clean",
+      "no-replacement-blocked-finding-with-same-root-cause",
+    ],
+    recomputeFromCurrentBaseline: true,
+  };
+  const findingDigest = digestJson({ code: base.code, severity: base.severity, affectedSourceIds: base.affectedSourceIds, affectedItemIds: base.affectedItemIds, affectedSubjects: base.affectedSubjects, affectedScopes: base.affectedScopes, baseline: base.baseline, blocksTask: base.blocksTask });
+  return { ...base, findingDigest, resolutionContract };
+}
+
+function classifyChanges(changes) {
+  const digests = uniqueSorted(changes.map((entry) => entry.change.candidateDigest));
+  if (digests.length === 1) return "duplicate";
+  const classes = uniqueSorted(changes.map((entry) => entry.change.classification).filter((entry) => entry !== "duplicate"));
+  return classes.length === 1 ? classes[0] : "semantic-conflict";
+}
+
+function groupChanges(candidates, kind, keyOf) {
+  const groups = new Map();
+  for (const candidate of candidates) {
+    const changes = kind === "source" ? candidate.sourceChanges : candidate.itemChanges;
+    for (const change of changes) {
+      const key = keyOf(change);
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push({ candidateId: candidate.id, taskId: candidate.taskId, change });
+    }
+  }
+  return [...groups.entries()]
+    .filter(([, changes]) => new Set(changes.map((entry) => entry.candidateId)).size > 1)
+    .map(([key, changes]) => ({ kind, key, classification: classifyChanges(changes), changes }))
+    .sort((left, right) => `${left.kind}:${left.key}`.localeCompare(`${right.kind}:${right.key}`));
+}
+
+function groupSubjectChanges(candidates) {
+  const groups = new Map();
+  for (const candidate of candidates) {
+    for (const change of candidate.sourceChanges) {
+      for (const subject of change.subjects) {
+        if (!groups.has(subject)) groups.set(subject, []);
+        groups.get(subject).push({ candidateId: candidate.id, taskId: candidate.taskId, change });
+      }
+    }
+    for (const change of candidate.itemChanges) {
+      if (!groups.has(change.subject)) groups.set(change.subject, []);
+      groups.get(change.subject).push({ candidateId: candidate.id, taskId: candidate.taskId, change });
+    }
+  }
+  return [...groups.entries()]
+    .filter(([, changes]) => new Set(changes.map((entry) => entry.candidateId)).size > 1)
+    .map(([key, changes]) => ({ kind: "subject", key, classification: classifyChanges(changes), changes }))
+    .sort((left, right) => left.key.localeCompare(right.key));
+}
+
+function groupImpacts(group) {
+  const sourceIds = [];
+  const itemIds = [];
+  const subjects = [];
+  const scopes = [];
+  for (const { change } of group.changes) {
+    if (change.sourceId) sourceIds.push(change.sourceId);
+    if (change.itemId) itemIds.push(change.itemId);
+    sourceIds.push(...(change.sourceIds ?? []));
+    itemIds.push(...(change.affectedItemIds ?? []));
+    subjects.push(...(change.subjects ?? []), ...(change.subject ? [change.subject] : []));
+    scopes.push(...(change.scopes ?? []), ...(change.scope ? [change.scope] : []));
+  }
+  return { sourceIds, itemIds, subjects, scopes };
+}
+
+function snapshotsEqual(left, right) {
+  return canonicalJson(left) === canonicalJson(right);
+}
+
+function successfulEvidence(evidence) {
+  return evidence.verificationResults.length > 0 && evidence.verificationResults.every((result) => ["passed", "observed"].includes(result.status));
+}
+
+function promotionState(candidate) {
+  const applicable = candidate.promotionEvidence.filter((entry) => entry.taskId === candidate.taskId && successfulEvidence(entry));
+  const current = applicable.filter((entry) => (
+    entry.codeSnapshotDigest === candidate.currentCodeSnapshotDigest ||
+    entry.equivalentToCodeSnapshotDigest === candidate.currentCodeSnapshotDigest
+  ) && entry.sourceSnapshotDigest === candidate.currentSourceSnapshotDigest &&
+    entry.artifactDigest === candidate.currentArtifactDigest &&
+    entry.acceptanceSuiteDigest === candidate.currentAcceptanceSuiteDigest &&
+    snapshotsEqual(entry.projectSnapshots, candidate.expectedProjectSnapshots));
+  const stale = applicable.filter((entry) => !current.includes(entry));
+  const currentQa = current.filter((entry) => entry.stage === "qa");
+  const integration = current.filter((entry) => entry.integration && ["preproduction", "production"].includes(entry.stage));
+  return { applicable, current, stale, currentQa, integration };
+}
+
+function promotionBinding(value) {
+  return digestJson({
+    codeSnapshotDigest: value.codeSnapshotDigest ?? value.currentCodeSnapshotDigest,
+    sourceSnapshotDigest: value.sourceSnapshotDigest ?? value.currentSourceSnapshotDigest,
+    artifactDigest: value.artifactDigest ?? value.currentArtifactDigest,
+    acceptanceSuiteDigest: value.acceptanceSuiteDigest ?? value.currentAcceptanceSuiteDigest,
+    projectSnapshots: value.projectSnapshots ?? value.expectedProjectSnapshots,
+  });
+}
+
+function candidateImpacts(candidate) {
+  return {
+    sourceIds: candidate.sourceChanges.map((entry) => entry.sourceId),
+    itemIds: [
+      ...candidate.sourceChanges.flatMap((entry) => entry.affectedItemIds),
+      ...candidate.itemChanges.map((entry) => entry.itemId),
+    ],
+    subjects: [
+      ...candidate.sourceChanges.flatMap((entry) => entry.subjects),
+      ...candidate.itemChanges.map((entry) => entry.subject),
+    ],
+    scopes: [
+      ...candidate.sourceChanges.flatMap((entry) => entry.scopes),
+      ...candidate.itemChanges.map((entry) => entry.scope),
+    ],
+  };
+}
+
+function mergeInputs(inputs) {
+  const first = inputs[0];
+  for (const input of inputs.slice(1)) {
+    if (input.projectId !== first.projectId || canonicalJson(input.current) !== canonicalJson(first.current) || canonicalJson(input.task) !== canonicalJson(first.task)) {
+      fail("truth-reconciliation-input-invalid", "all reconciliation inputs must share one project, current baseline, and task");
+    }
+  }
+  const candidates = inputs.flatMap((input) => input.candidates);
+  const candidateIds = candidates.map((entry) => entry.id);
+  if (new Set(candidateIds).size !== candidateIds.length) fail("truth-reconciliation-input-invalid", "candidate ids must be unique across input files");
+  return {
+    ...first,
+    candidates: candidates.sort((left, right) => left.id.localeCompare(right.id)),
+    globalFindings: [...new Map(inputs.flatMap((input) => input.globalFindings).map((entry) => [canonicalJson(entry), entry])).values()]
+      .sort((left, right) => canonicalJson(left).localeCompare(canonicalJson(right))),
+  };
+}
+
+function findingRootKey(value) {
+  return canonicalJson({ code: value.code, affectedSourceIds: value.affectedSourceIds, affectedItemIds: value.affectedItemIds, affectedSubjects: value.affectedSubjects, affectedScopes: value.affectedScopes });
+}
+
+function validateResolutionAttempt(input, previousReview) {
+  const attempt = input.resolutionAttempt;
+  if (!attempt && previousReview) fail("truth-resolution-previous-unexpected", "initial reconciliation cannot use --previous-review");
+  if (attempt && !previousReview) fail("truth-resolution-previous-required", "resolution attempt requires --previous-review", { exitCode: 1 });
+  if (!attempt) return;
+  if (attempt.previousReviewDigest !== previousReview.bundleDigest) fail("truth-resolution-previous-digest-mismatch", "resolution attempt does not bind the supplied previous review", { exitCode: 1 });
+  if (previousReview.project.id !== input.projectId || previousReview.task.id !== input.task.id || canonicalJson(previousReview.task.paths) !== canonicalJson(input.task.paths)) {
+    fail("truth-resolution-previous-scope-mismatch", "previous review belongs to a different project, task, or scope", { exitCode: 1 });
+  }
+  const previousFindings = new Map(previousReview.findings.map((entry) => [entry.findingDigest, entry]));
+  for (const decision of attempt.decisions) {
+    const finding = previousFindings.get(decision.findingDigest);
+    if (!finding) fail("truth-resolution-finding-unavailable", "resolution decision references a finding not exposed by the previous review", { exitCode: 1 });
+    if (!finding.resolutionKinds.includes(decision.resolutionKind)) fail("truth-resolution-kind-unavailable", "resolution kind was not exposed by the previous finding", { exitCode: 1 });
+  }
+}
+
+function resolutionOutcomes(input, previousReview, currentFindings) {
+  if (!input.resolutionAttempt || !previousReview) return [];
+  const currentRoots = new Map(currentFindings.map((entry) => [findingRootKey(entry), entry]));
+  const previousByDigest = new Map(previousReview.findings.map((entry) => [entry.findingDigest, entry]));
+  return input.resolutionAttempt.decisions.map((decision) => {
+    const previous = previousByDigest.get(decision.findingDigest);
+    const stillOpen = currentRoots.get(findingRootKey(previous));
+    const replacement = currentFindings.find((entry) => entry.severity === "blocked" && entry.affectedSubjects.some((subject) => previous.affectedSubjects.includes(subject)));
+    let state = "revalidation-required";
+    let outcome = "open";
+    if (decision.resolutionKind === "defer-scoped-conflict") { state = "deferred-open"; outcome = "deferred"; }
+    else if (decision.resolutionKind === "external-implementation-fix-required" && !decision.externalAction?.completed) { state = "external-fix-required"; outcome = "open"; }
+    else if (!stillOpen && !replacement && input.resolutionAttempt.projectContextStatus === "clean") {
+      const discarded = input.candidates.length === 0 || input.candidates.every((candidate) => ["withdrawn", "rolled-back"].includes(candidate.lifecycle));
+      if (decision.resolutionKind !== "keep-current-baseline" || discarded) { state = "resolved"; outcome = decision.resolutionKind === "keep-current-baseline" ? "rejected" : "resolved"; }
+    }
+    return {
+      findingDigest: decision.findingDigest,
+      resolutionKind: decision.resolutionKind,
+      resolutionState: state,
+      outcome,
+      completionCriteriaMet: state === "resolved" ? [...previous.resolutionContract.completionCriteria] : [],
+      recomputedFromCurrentBaseline: true,
+    };
+  }).sort((left, right) => left.findingDigest.localeCompare(right.findingDigest));
+}
+
+export function buildTruthReconciliationReview(root, project, inputValues, options = {}) {
+  if (!Array.isArray(inputValues) || inputValues.length === 0) fail("truth-reconciliation-input-invalid", "at least one input is required");
+  const input = mergeInputs(inputValues.map(normalizeTruthReconciliationInput));
+  if (input.projectId !== project.contract.project.id) fail("truth-reconciliation-input-invalid", "input projectId does not match the initialized project");
+  const previousReview = options.previousReview ? validateTruthReviewBundle(options.previousReview) : null;
+  validateResolutionAttempt(input, previousReview);
+
+  const findings = [];
+  const currentSources = new Map(input.current.sources.map((entry) => [entry.id, entry.digest]));
+  const currentItems = new Map(input.current.items.map((entry) => [entry.id, entry]));
+  const liveSources = new Map(project.sourcesLock.sources.map((entry) => [entry.id, entry.digest]));
+  const liveItems = new Map(project.contract.items.map((entry) => [entry.id, entry]));
+  const actualSnapshots = {
+    contract: project.contractDigest,
+    sourcesLock: project.sourcesLockDigest,
+    projectionsLock: project.projectionsLockDigest,
+  };
+  let currentBaselineValid = snapshotsEqual(input.current.projectSnapshots, actualSnapshots);
+  if (!currentBaselineValid) {
+    findings.push(finding(root, "truth-current-baseline-invalid", "blocked", {}, {
+      expectedDigest: digestJson(input.current.projectSnapshots), actualDigest: digestJson(actualSnapshots), blocksTask: true,
+      resolutionKinds: ["fix-source-and-rerun"], humanRoles: ["truth-maintainer"],
+    }));
+  }
+  for (const source of input.current.sources) {
+    const actual = liveSources.get(source.id) ?? null;
+    if (actual === source.digest) continue;
+    currentBaselineValid = false;
+    findings.push(finding(root, "truth-current-baseline-invalid", "blocked", { sourceIds: [source.id] }, {
+      expectedDigest: source.digest, actualDigest: actual, blocksTask: true, resolutionKinds: ["fix-source-and-rerun"],
+      humanRoles: ["truth-maintainer"],
+    }));
+  }
+  for (const [sourceId, actual] of liveSources) {
+    if (currentSources.has(sourceId)) continue;
+    currentBaselineValid = false;
+    findings.push(finding(root, "truth-current-baseline-invalid", "blocked", { sourceIds: [sourceId] }, {
+      actualDigest: actual, blocksTask: true, resolutionKinds: ["fix-source-and-rerun"], humanRoles: ["truth-maintainer"],
+    }));
+  }
+  for (const item of input.current.items) {
+    const live = liveItems.get(item.id);
+    const actual = live ? digestJson(live) : null;
+    const metadataMatches = live && live.subject === item.subject && live.kind === item.kind && snapshotsEqual(live.scope, item.scope);
+    if (actual === item.digest && metadataMatches) continue;
+    currentBaselineValid = false;
+    findings.push(finding(root, "truth-current-baseline-invalid", "blocked", {
+      sourceIds: live?.sources ?? [], itemIds: [item.id], subjects: [item.subject], scopes: [item.scope],
+    }, {
+      expectedDigest: item.digest, actualDigest: actual, blocksTask: true, resolutionKinds: ["fix-source-and-rerun"],
+      humanRoles: ["truth-maintainer"],
+    }));
+  }
+  for (const [itemId, live] of liveItems) {
+    if (currentItems.has(itemId)) continue;
+    currentBaselineValid = false;
+    findings.push(finding(root, "truth-current-baseline-invalid", "blocked", {
+      sourceIds: live.sources, itemIds: [itemId], subjects: [live.subject], scopes: [live.scope],
+    }, {
+      actualDigest: digestJson(live), blocksTask: true, resolutionKinds: ["fix-source-and-rerun"], humanRoles: ["truth-maintainer"],
+    }));
+  }
+
+  const candidateOutcomes = [];
+  const eligible = [];
+  for (const candidate of input.candidates) {
+    const candidateFindings = [];
+    const impacts = candidateImpacts(candidate);
+    let stale = !currentBaselineValid || !snapshotsEqual(candidate.expectedProjectSnapshots, input.current.projectSnapshots);
+    if (!snapshotsEqual(candidate.expectedProjectSnapshots, input.current.projectSnapshots)) {
+      candidateFindings.push(finding(root, "truth-candidate-baseline-stale", "blocked", impacts, {
+        expectedDigest: digestJson(candidate.expectedProjectSnapshots), actualDigest: digestJson(input.current.projectSnapshots),
+        expectedLabel: candidate.baseRevision, actualLabel: input.current.revision, blocksTask: true,
+        resolutionKinds: ["fix-source-and-rerun"],
+      }));
+    }
+    for (const change of candidate.sourceChanges) {
+      const actual = currentSources.get(change.sourceId) ?? null;
+      if (actual !== change.expectedDigest) {
+        stale = true;
+        candidateFindings.push(finding(root, "truth-candidate-baseline-stale", "blocked", {
+          sourceIds: [change.sourceId], itemIds: change.affectedItemIds, subjects: change.subjects, scopes: change.scopes,
+        }, {
+          expectedDigest: change.expectedDigest, actualDigest: actual, expectedLabel: candidate.baseRevision,
+          actualLabel: input.current.revision, blocksTask: true, resolutionKinds: ["fix-source-and-rerun"],
+        }));
+      }
+    }
+    for (const change of candidate.itemChanges) {
+      const actual = currentItems.get(change.itemId)?.digest ?? null;
+      if (actual !== change.expectedDigest) {
+        stale = true;
+        candidateFindings.push(finding(root, "truth-candidate-baseline-stale", "blocked", {
+          sourceIds: change.sourceIds, itemIds: [change.itemId], subjects: [change.subject], scopes: [change.scope],
+        }, {
+          expectedDigest: change.expectedDigest, actualDigest: actual, expectedLabel: candidate.baseRevision,
+          actualLabel: input.current.revision, blocksTask: true, resolutionKinds: ["fix-source-and-rerun"],
+        }));
+      }
+    }
+
+    const promotion = promotionState(candidate);
+    if (candidate.targetStage !== "development" && promotion.applicable.length === 0) {
+      candidateFindings.push(finding(root, "promotion-code-snapshot-unbound", "blocked", impacts, {
+        actualDigest: candidate.currentCodeSnapshotDigest, blocksTask: true, resolutionKinds: ["refresh-promotion-evidence"],
+        humanRoles: ["qa-owner", "host-operator"], validateAfterResolution: ["reconcile-truth", "host-verification"],
+      }));
+    }
+    if (promotion.stale.length > 0) {
+      candidateFindings.push(finding(root, "promotion-evidence-stale", "blocked", impacts, {
+        expectedDigest: promotionBinding(promotion.stale[0]), actualDigest: promotionBinding(candidate),
+        blocksTask: candidate.targetStage !== "development", resolutionKinds: ["refresh-promotion-evidence"], humanRoles: ["qa-owner", "host-operator"],
+        validateAfterResolution: ["reconcile-truth", "host-verification"],
+      }));
+    }
+    if (["preproduction", "production"].includes(candidate.targetStage) && promotion.integration.length === 0) {
+      candidateFindings.push(finding(root, "promotion-integration-verification-required", "blocked", impacts, {
+        actualDigest: candidate.currentArtifactDigest, blocksTask: true, resolutionKinds: ["refresh-promotion-evidence"],
+        humanRoles: ["qa-owner", "release-owner", "host-operator"], validateAfterResolution: ["reconcile-truth", "integration-verification"],
+      }));
+    }
+    const discarded = ["withdrawn", "rolled-back"].includes(candidate.lifecycle);
+    if (discarded && candidate.decisionCandidateIds.length > 0) {
+      candidateFindings.push(finding(root, "truth-owner-review-required", "attention", {
+        itemIds: candidate.decisionCandidateIds,
+      }, {
+        blocksTask: false, resolutionKinds: ["keep-current-baseline"], humanRoles: ["truth-maintainer", "business-owner"],
+      }));
+    }
+    if (!stale && !discarded) eligible.push(candidate);
+    findings.push(...candidateFindings);
+    candidateOutcomes.push({
+      candidateId: candidate.id,
+      lifecycle: candidate.lifecycle,
+      baseline: stale ? "stale" : "current",
+      promotionEvidence: {
+        assurance: "host-asserted",
+        currentEvidenceCount: promotion.current.length,
+        staleEvidenceCount: promotion.stale.length,
+        localQaReusable: promotion.currentQa.length > 0,
+        integrationVerified: promotion.integration.length > 0,
+      },
+      decisionCandidates: discarded ? "discarded-not-promoted" : "authority-free-candidates",
+      eligibleForReconciliation: !stale && !discarded,
+    });
+  }
+
+  const collisionGroups = [
+    ...groupChanges(eligible, "source", (change) => change.sourceId),
+    ...groupChanges(eligible, "item", (change) => change.itemId),
+    ...groupSubjectChanges(eligible),
+  ].map((group) => {
+    const impacts = groupImpacts(group);
+    const code = group.kind === "source" ? "truth-source-collision" : group.kind === "item" ? "truth-item-collision" : "truth-subject-collision";
+    findings.push(finding(root, code, group.classification === "duplicate" ? "attention" : "conflict", impacts, {
+      blocksTask: isTaskRelated(impacts.scopes, input.task.paths), resolutionKinds: RESOLUTIONS[group.classification],
+      humanRoles: group.classification === "semantic-conflict" ? ["business-owner", "truth-maintainer"] : ["truth-maintainer"],
+    }));
+    return {
+      kind: group.kind,
+      key: group.key,
+      classification: group.classification,
+      candidateIds: uniqueSorted(group.changes.map((entry) => entry.candidateId)),
+      candidateDigests: uniqueSorted(group.changes.map((entry) => entry.change.candidateDigest)),
+      affectedSourceIds: uniqueSorted(impacts.sourceIds),
+      affectedItemIds: uniqueSorted(impacts.itemIds),
+      affectedSubjects: uniqueSorted(impacts.subjects),
+      affectedScopes: [...new Map(impacts.scopes.map((scope) => [scopeKey(scope), scope])).values()].sort((a, b) => scopeKey(a).localeCompare(scopeKey(b))),
+      resolutionKinds: [...RESOLUTIONS[group.classification]],
+      promoted: false,
+    };
+  }).sort((left, right) => `${left.kind}:${left.key}`.localeCompare(`${right.kind}:${right.key}`));
+
+  for (const signal of input.globalFindings) {
+    const related = isTaskRelated(signal.scopes, input.task.paths);
+    const mandatory = signal.itemKinds.some((kind) => ["policy", "validation-description"].includes(kind));
+    findings.push(finding(root, signal.code, signal.severity, {
+      sourceIds: signal.sourceIds, itemIds: signal.itemIds, subjects: signal.subjects, scopes: signal.scopes,
+    }, {
+      blocksTask: related && (mandatory || ["conflict", "blocked"].includes(signal.severity)),
+      resolutionKinds: related && mandatory ? ["fix-source-and-rerun", "defer-scoped-conflict"] : ["defer-scoped-conflict"],
+      humanRoles: mandatory ? ["subject-owner", "truth-maintainer"] : ["truth-maintainer"],
+    }));
+  }
+
+  const stableFindings = findings.sort((left, right) => {
+    const leftKey = `${left.code}:${left.affectedSourceIds.join(",")}:${left.affectedItemIds.join(",")}:${left.affectedSubjects.join(",")}`;
+    const rightKey = `${right.code}:${right.affectedSourceIds.join(",")}:${right.affectedItemIds.join(",")}:${right.affectedSubjects.join(",")}`;
+    return leftKey.localeCompare(rightKey);
+  });
+  const taskBlocked = stableFindings.some((entry) => entry.blocksTask);
+  const outcomes = resolutionOutcomes(input, previousReview, stableFindings);
+  return finalizeTruthReviewBundle({
+    schemaVersion: TRUTH_RECONCILIATION_REVIEW_BUNDLE_SCHEMA_VERSION,
+    kind: "truth-reconciliation-review-bundle",
+    project: { id: project.contract.project.id, name: project.contract.project.name },
+    current: { revision: input.current.revision, projectSnapshots: input.current.projectSnapshots },
+    task: input.task,
+    inputDigest: digestJson(input),
+    summary: {
+      candidates: input.candidates.length,
+      eligibleCandidates: eligible.length,
+      collisionGroups: collisionGroups.length,
+      findings: stableFindings.length,
+      taskHealth: taskBlocked ? "blocked" : "ready",
+      globalHealth: stableFindings.length > 0 ? "attention" : "clean",
+      existingDelivery: "not-blocked",
+    },
+    candidateOutcomes: candidateOutcomes.sort((left, right) => left.candidateId.localeCompare(right.candidateId)),
+    collisionGroups,
+    findings: stableFindings,
+    resolutionOutcomes: outcomes,
+    guarantees: {
+      projectContextVerified: ["schema", "canonical-digests", "project-snapshots", "scope-impact", "recovery-contract"],
+      hostAsserted: ["revision", "code-snapshot", "source-snapshot", "artifact", "verification-results", "content-equivalence"],
+      humanDecided: ["release", "long-term-semantics", "approval", "rollback"],
+    },
+    boundaries: {
+      readOnly: true, git: false, ciClient: false, network: false, provider: false, taskExecution: false,
+      automaticApproval: false, automaticPromotion: false, persistentQueue: false, blocksExistingDelivery: false,
+    },
+  });
+}
+
+export async function buildTruthReconciliationReviewFiles(root, inputPaths, options = {}) {
+  const project = await loadProject(root);
+  const values = [];
+  for (const inputPath of inputPaths) {
+    const resolved = await resolveExistingInside(root, inputPath);
+    values.push(await readJsonFile(resolved.absolute, "truth reconciliation input"));
+  }
+  let previousReview = null;
+  if (options.previousReviewPath) {
+    const resolved = await resolveExistingInside(root, options.previousReviewPath);
+    previousReview = validateTruthReviewBundle(await readJsonFile(resolved.absolute, "previous truth reconciliation review"));
+  }
+  return buildTruthReconciliationReview(root, project, values, { previousReview });
+}