@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/src/doctor-sidecar.mjs

@@ -73,8 +73,9 @@ export function writeDoctorSidecar(path, doctor, { command, targetRepo = null }
 // qa policy set) stamp the retained snapshot stale instead of leaving a green
 // lie on disk, while commands that DO recompute (doctor, prepare-build/start,
 // next) rewrite the sidecar wholesale — which clears any stale stamp.
-export function markDoctorSidecarStale(targetBaseDir, { command = null, reason = null } = {}) {
-  const path = doctorSidecarPath(targetBaseDir);
+// `path` is the funnel's own sidecar (campaign-workspace.mjs doctorOutPath);
+// without it, the project-level one under `targetBaseDir`.
+export function markDoctorSidecarStale(targetBaseDir, { command = null, reason = null, path = doctorSidecarPath(targetBaseDir) } = {}) {
   if (!existsSync(path)) return null;
   let sidecar;
   try {

package/src/evidence-debt.mjs

@@ -0,0 +1,159 @@
+// Read-only build binding projection, shared by readback and other readers.
+// No stage verdicts, clocks, Git metadata, processes, writes or network calls.
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import {
+  computeBuildFingerprint,
+  describeBuildOutputDrift,
+  pageIdForRoute,
+  resolveBuiltSiteScope,
+  routeForFile,
+} from "./built-site-scope.mjs";
+import { changeSince, classifyDrift } from "./change-scope.mjs";
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
+import { isFileReadFailure } from "./cart-placeholders.mjs";
+import { polishReviewedBuild, qaExtendedBuildFingerprint, qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "./stage-ledger.mjs";
+
+export const EVIDENCE_DEBT_STATUSES = Object.freeze(["current", "owed", "unknown"]);
+
+const fingerprint = (value) => typeof value === "string" && value.trim() ? value.trim() : null;
+const portable = (value) => value.split(sep).join("/");
+
+/**
+ * Compare recorded Polish/QA build bindings with bytes under _site/<slug>.
+ * `changes` is explicitly against the assembly manifest, which need not be
+ * the build an older stage reviewed. We cannot reconstruct an older manifest.
+ * Missing build inputs remain unknown; lifecycle-required stages are owed
+ * even without a stage binding. A matching binding alone is not a verdict.
+ *
+ * Each owed stage also carries `change`: what changed since the build that
+ * stage reviewed (change-scope.mjs), read from the rebuilds `record build`
+ * kept plus the drift on disk. A page-only change makes owed Polish
+ * `advisory` and owed QA `scope: "pages"` on `owed_pages`; anything else
+ * owes the full stage.
+ */
+export function assessEvidenceDebt({ packet = null, packetPath = null, report = null } = {}) {
+  const assembly = report?.stages?.assembly;
+  const recordedBuild = fingerprint(assembly?.build_fingerprint);
+  // Match polish-gate's sourceBuildFingerprint precedence without reading the
+  // capture package (often absent in a fresh checkout).
+  const polishBuild = fingerprint(report?.stages?.polish?.source_build_fingerprint)
+    || fingerprint(report?.stages?.polish?.evidence?.source_build_fingerprint);
+  const qaBuild = qaRecordedBuildFingerprint(report);
+  let current = null;
+  let scope = null;
+  let outputRoot = null;
+  let reason = null;
+  let scopeReason = null;
+  let targetRepo = null;
+  const target = fingerprint(packet?.assembly?.target_repo);
+  const slug = normalizePublicRouteSlug(packet?.campaign?.public_route_slug);
+  if (!packet || !packetPath) reason = "packet_unavailable";
+  else if (!target || !slug) reason = "build_output_location_unknown";
+  else {
+    targetRepo = resolve(dirname(resolve(packetPath)), target);
+    outputRoot = join(targetRepo, "_site", slug);
+    try {
+      current = computeBuildFingerprint(outputRoot);
+      if (!current.ok) reason = "build_output_missing";
+      // Resolve only the chosen built directory: never discover another
+      // campaign, or fall back to source HTML when _site is absent.
+      else {
+        scope = resolveBuiltSiteScope(outputRoot);
+        if (!scope.ok) scopeReason = "build_output_pages_unresolved";
+      }
+    } catch (error) {
+      if (!isFileReadFailure(error)) throw error;
+      reason = "build_output_unreadable";
+      current = null;
+    }
+  }
+  const currentBuild = current?.ok ? current.fingerprint : null;
+  const drift = currentBuild ? describeBuildOutputDrift(assembly, current) : null;
+  const manifestKnown = drift?.manifest === "recorded";
+  // A missing manifest hides page changes, never a known stage binding.
+  const bindingReason = reason || (!recordedBuild ? "assembly_build_fingerprint_missing" : null);
+  const changesReason = bindingReason || scopeReason || (!manifestKnown ? "build_manifest_unavailable" : null);
+  const stage = (stageRecord, recorded, matches) => {
+    // src/stage-record.mjs writes required_by: build; the dependency map in
+    // src/input-currency.mjs supplies brief/spec for input-change demotions.
+    // This is lifecycle debt even when retained evidence matches the output.
+    const required = stageRecord?.status === "required";
+    const requiredReason = ["build", "brief", "spec"].includes(stageRecord?.required_by)
+      ? `stage_required_by_${stageRecord.required_by}` : "stage_required";
+    return {
+      status: bindingReason ? "unknown" : required ? "owed" : !recorded ? "unknown" : matches ? "current" : "owed",
+      matches_current_build: recorded && currentBuild ? matches : null,
+      recorded_build_fingerprint: recorded,
+      current_build_fingerprint: currentBuild,
+      reason: bindingReason || (required ? requiredReason : !recorded ? "stage_build_fingerprint_missing" : matches ? null : "build_fingerprint_changed"),
+    };
+  };
+
+  const changes = {
+    status: changesReason ? "unknown" : "known",
+    reason: changesReason,
+    recorded_build_fingerprint: recordedBuild,
+    current_build_fingerprint: currentBuild,
+    changed_pages: [],
+    unmapped_files: [],
+    extra: manifestKnown ? drift.extra : [],
+    missing: manifestKnown ? drift.missing : [],
+    changed: manifestKnown ? drift.changed : [],
+  };
+  if (manifestKnown && scope?.ok) {
+    const pages = new Map((scope?.pages || []).map((page) => [
+      portable(relative(outputRoot, page.built_path)),
+      { page_id: page.page_id, built_path: portable(relative(outputRoot, page.built_path)) },
+    ]));
+    // Deleted HTML no longer appears in the disk map. Reuse its route/id
+    // projection for those manifest entries, without reading nonexistent files.
+    for (const path of drift.missing) {
+      if (!path.toLowerCase().endsWith(".html") || path.split("/").some((part) => part.startsWith(".") || part.startsWith("_") || part === "node_modules")) continue;
+      pages.set(path, { page_id: pageIdForRoute(routeForFile(outputRoot, join(outputRoot, path))), built_path: path });
+    }
+    const paths = [...new Set([...drift.extra, ...drift.missing, ...drift.changed])].sort();
+    for (const path of paths) {
+      const page = pages.get(path);
+      if (page) changes.changed_pages.push(page);
+      else changes.unmapped_files.push(path);
+    }
+  }
+  const driftClassification = classifyDrift({ changes, baseline: assembly, outputRoot, targetRepo, publicRouteSlug: slug });
+  changes.kind = driftClassification.kind;
+  changes.reasons = driftClassification.reasons;
+  const changeFor = (anchor) => changeSince(anchor, { assembly, drift: changes, driftClassification });
+
+  // Polish reviewed the build a terminal record is bound to; once `record
+  // build` has made it required, the build it reviewed is kept as
+  // owed_since_build_fingerprint (polishReviewedBuild). Only a Polish that
+  // reviewed a build can be advisory: a blocked or pending one, or one a
+  // brief or spec change made required, owes the full stage, before and
+  // after record build alike.
+  const polishRecord = report?.stages?.polish;
+  const polish = stage(polishRecord, polishBuild, Boolean(polishBuild && currentBuild && polishBuild === currentBuild));
+  if (polish.status === "owed") {
+    const reviewed = polishReviewedBuild(polishRecord);
+    polish.change = changeFor(reviewed || polishBuild || fingerprint(polishRecord?.owed_since_build_fingerprint));
+    polish.advisory = Boolean(reviewed) && polish.change.kind === "page_only";
+  } else {
+    polish.change = null;
+    polish.advisory = false;
+  }
+  // QA on the changed pages only extends a completed QA: the change is read
+  // from the build that QA checked (qaExtendedBuildFingerprint). A blocked,
+  // pending or skipped full run extends nothing and owes the full stage.
+  const qaRecord = report?.stages?.qa;
+  const qa = stage(qaRecord, qaBuild, qaRecordedForCurrentBuild(report, currentBuild));
+  if (qa.status === "owed") {
+    const extended = qaExtendedBuildFingerprint(report);
+    qa.change = changeFor(extended || qaBuild);
+    qa.scope = extended && qaRecord?.status !== "required" && qa.change.kind === "page_only" ? "pages" : "full";
+    qa.owed_pages = qa.scope === "pages" ? qa.change.changed_pages : [];
+  } else {
+    qa.change = null;
+    qa.scope = null;
+    qa.owed_pages = [];
+  }
+  return { polish, qa, changes };
+}

package/src/finding-cause.mjs

@@ -330,7 +330,8 @@ import { iterateQaVerdicts } from "./qa-verdict-discovery.mjs";
 import { readRunRecordsForTarget } from "./run-record.mjs";
 
 /**
- * The most recent Run Record for the same campaign identity under `baseDir`,
+ * The most recent Run Record for the same campaign identity under `baseDir`
+ * (in the packet's runtime directory, `runtimeRelPath`, when one is given),
  * or null. Records are discovered newest-first, and the current run's record
  * does not exist yet at classification time (both `qa run` and `doctor`
  * complete before `run-record` assembles anything), so the first identity
@@ -341,9 +342,9 @@ import { readRunRecordsForTarget } from "./run-record.mjs";
  * against a non-adjacent one and report findings introduced in between as
  * pre-existing.
  */
-export function findPriorRunRecord({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+export function findPriorRunRecord({ baseDir, runtimeRelPath = undefined, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   if (!text(baseDir)) return null;
-  for (const entry of readRunRecordsForTarget(baseDir)) {
+  for (const entry of readRunRecordsForTarget(baseDir, runtimeRelPath)) {
     const record = entry?.record;
     if (!record || typeof record !== "object" || Array.isArray(record)) continue;
     if (currentRunId && record.run_id === currentRunId) continue;
@@ -448,8 +449,8 @@ function locateExternalPriorVerdict({ targetRepo, record, ref }) {
  * The single-record boundary is unchanged: this still reads the final attempt
  * of exactly one earlier run, never a merged view across runs.
  */
-export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, localSpecId, currentRunId });
+export function loadPriorQaVerdict({ baseDir, runtimeRelPath = undefined, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, runtimeRelPath, mapId, localSpecId, currentRunId });
   if (!record) return { verdict: null, record: null, path: null, reason: "no_prior_run" };
   const ref = (Array.isArray(record.artifacts) ? record.artifacts : []).findLast((artifact) => artifact?.kind === "qa_verdict");
   const refPath = text(ref?.path);
@@ -472,8 +473,8 @@ export function loadPriorQaVerdict({ baseDir, targetRepo = null, mapId = null, l
  * carries these, so doctor cause labels work against existing history with no
  * upgrade window. Returns `{ prior, record, reason }`.
  */
-function loadPriorDoctorFindings({ baseDir, mapId = null, localSpecId = null, currentRunId = null } = {}) {
-  const record = findPriorRunRecord({ baseDir, mapId, localSpecId, currentRunId });
+function loadPriorDoctorFindings({ baseDir, runtimeRelPath = undefined, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+  const record = findPriorRunRecord({ baseDir, runtimeRelPath, mapId, localSpecId, currentRunId });
   if (!record) return { prior: null, record: null, reason: "no_prior_run" };
   const prior = priorSetFromRunRecordDoctor(record);
   if (!prior) return { prior: null, record, reason: "prior_run_without_doctor_observations" };
@@ -496,9 +497,9 @@ function loadPriorDoctorFindings({ baseDir, mapId = null, localSpecId = null, cu
  * raw map id) have no Run Record home, so they get `unknown` / `no_prior_run`
  * throughout — which is the truth, not a silence.
  */
-export function annotateQaAssertionCauses(assertions, { baseDir = null, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null, isFinding } = {}) {
+export function annotateQaAssertionCauses(assertions, { baseDir = null, runtimeRelPath = undefined, targetRepo = null, mapId = null, localSpecId = null, currentRunId = null, isFinding } = {}) {
   const lookup = baseDir
-    ? loadPriorQaVerdict({ baseDir, targetRepo, mapId, localSpecId, currentRunId })
+    ? loadPriorQaVerdict({ baseDir, runtimeRelPath, targetRepo, mapId, localSpecId, currentRunId })
     : { verdict: null, record: null, path: null, reason: "no_prior_run" };
   const prior = lookup.verdict ? priorSetFromVerdict(lookup.verdict, { isFinding }) : null;
   const noPriorReason = lookup.reason || "no_prior_run";
@@ -532,9 +533,9 @@ const CAUSE_SUMMARY_SCHEMA = "campaigns-os-finding-cause/v0";
  * The doctor twin. `errors` and `warnings` are the doctor output's own arrays;
  * both are stamped in place. Returns the same summary shape.
  */
-export function annotateDoctorIssueCauses({ errors = [], warnings = [], baseDir = null, mapId = null, localSpecId = null, currentRunId = null } = {}) {
+export function annotateDoctorIssueCauses({ errors = [], warnings = [], baseDir = null, runtimeRelPath = undefined, mapId = null, localSpecId = null, currentRunId = null } = {}) {
   const lookup = baseDir
-    ? loadPriorDoctorFindings({ baseDir, mapId, localSpecId, currentRunId })
+    ? loadPriorDoctorFindings({ baseDir, runtimeRelPath, mapId, localSpecId, currentRunId })
     : { prior: null, record: null, reason: "no_prior_run" };
   const noPriorReason = lookup.reason || "no_prior_run";
   const findings = [];