@nextcommerce/campaigns-os 1.62.0 → 1.66.0

package/src/qa-commercial-parity.mjs

@@ -9,8 +9,12 @@ import {
 import {
   COMMERCIAL_PARITY_SCHEMA_VERSION,
   CommercialParityLimitError,
+  PACKAGE_PRICE_NOT_FILLED,
+  PACKAGE_PRICE_NOT_RENDERED,
+  PACKAGE_PRICE_UNRESOLVED,
   createCommercialParityReport,
   extractCommercialClaims,
+  packagePriceClaimCount,
   recurringClaimAbsences,
   recurringClaimAbsentAssertions,
 } from "./commercial-parity.mjs";
@@ -450,6 +454,7 @@ function catalogImportedAt(spec) {
 
 function captureClaimCount(capture) {
   return array(capture?.price_claims).length
+    + packagePriceClaimCount(capture)
     + array(capture?.recurrence_claims).length
     + array(capture?.vouchers).length;
 }
@@ -466,6 +471,108 @@ function captureIssues(captures) {
   return issues;
 }
 
+// One reason a run's commercial proof stopped short: what was not compared and
+// what to do about it, for an agent that reads only the exceptions list. Text
+// only, never a key or a URL: it is persisted.
+function cause(code, summary, fix, count = 1) {
+  return { code, count, summary, fix };
+}
+
+// What each reason a package.price went uncompared means for the operator.
+const PACKAGE_PRICE_CAUSES = Object.freeze({
+  [PACKAGE_PRICE_NOT_RENDERED]: {
+    summary: (count) => `${count} package.price claim(s) in the page source were not read from a rendered page, so they were not compared.`,
+    fix: "Run qa run with --browser. If it did, check that the tested URL served this page; prices hidden on purpose need no repair.",
+  },
+  [PACKAGE_PRICE_NOT_FILLED]: {
+    summary: (count) => `The SDK never filled ${count} visible package.price node(s), so a shopper may be reading the template's placeholder price.`,
+    fix: "Check that the SDK loaded and that the package ref is on the campaign, then re-run qa run.",
+  },
+  [PACKAGE_PRICE_UNRESOLVED]: {
+    summary: (count) => `${count} package.price claim(s) could not be tied to one calculated price: no package id around the node, no single exact row for the package on the page, or text that is not a money amount.`,
+    fix: "Put data-next-package-id around the price, or check it by hand.",
+  },
+});
+
+const OVER_LIMITS_FIX = "This funnel is over the check's limits, so no re-run will cover it: check these prices by hand and tell the operator.";
+
+/**
+ * The causes of an incomplete proof, the ones found while running first. Later
+ * causes stay quiet when an earlier one explains them, so a missing key does not
+ * also report every page as unpriced. Not every cause has a repair: a store
+ * coupon or a run in another currency only says what was not compared.
+ */
+function incompleteCauses(stopped, commercial, journey) {
+  const causes = [...stopped];
+  // A page whose capture was refused also counts as missing from the comparison.
+  const refused = new Set(array(commercial.invalid_captures).map((capture) => capture.page_id));
+  const unread = [
+    ...array(commercial.invalid_captures),
+    ...array(commercial.missing_pages).filter((page) => !refused.has(page.page_id)),
+  ];
+  if (unread.length) {
+    causes.push(cause(
+      "commercial_pages_unread",
+      `${unread.length} page(s) could not be read for commercial claims: ${unread.map((page) => page.page_id ?? "(no id)").join(", ")}.`,
+      "Fix the page's fetch failure, its URL in the spec or its malformed markup, then re-run qa run. A page over the claim limit needs its prices checked by hand.",
+      unread.length,
+    ));
+  }
+  if (causes.length) return causes;
+
+  const inexact = array(journey?.pages).filter((page) => page?.state !== PricingState.Exact);
+  if (inexact.length) {
+    const named = inexact.map((page) => `${page.page_id} (${page.reason || page.representative_total?.reason || page.state})`);
+    return [cause(
+      "commercial_page_not_exact",
+      `Calculate gave no exact total for ${inexact.length} page(s): ${named.join(", ")}.`,
+      "Correct the spec where the reason names it. A store coupon cannot be previewed, so check that page's prices by hand. Re-run qa run if the reason is Stale.",
+      inexact.length,
+    )];
+  }
+  if (present(commercial.unresolved_money_claims_reason)) {
+    const count = commercial.unresolved_price_claims + commercial.unresolved_recurrence_claims;
+    return [cause(
+      String(commercial.unresolved_money_claims_reason),
+      `${count} price claim(s) in the page source hold the Map currency's fallback text, so they were not compared with totals in the run currency.`,
+      "No page repair is owed. A qa run in the campaign's own currency compares them.",
+      count,
+    )];
+  }
+  const packagePrices = Object.entries(commercial.package_price_claims?.unresolved || {});
+  packagePrices.forEach(([code, count]) => {
+    causes.push(cause(code, PACKAGE_PRICE_CAUSES[code].summary(count), PACKAGE_PRICE_CAUSES[code].fix, count));
+  });
+  const unresolvedPrices = commercial.unresolved_price_claims - packagePrices.reduce((sum, [, count]) => sum + count, 0);
+  const unresolved = unresolvedPrices + commercial.unresolved_recurrence_claims + commercial.unresolved_voucher_claims;
+  if (unresolved > 0) {
+    causes.push(cause(
+      "commercial_claims_unresolved",
+      `${unresolved} claim(s) could not be tied to one calculated value (${unresolvedPrices} price, ${commercial.unresolved_recurrence_claims} recurring, ${commercial.unresolved_voucher_claims} voucher).`,
+      "A page with more than one bound bundle price, or a voucher the plan cannot price, stays uncompared: check these by hand, or declare the voucher in the spec.",
+      unresolved,
+    ));
+  }
+  return causes;
+}
+
+/** One warn row per named cause: what `exceptions[]` carries and the sidecar keeps. */
+function commercialIncompleteAssertions(reasons) {
+  return array(reasons).map((entry) => ({
+    id: `commercial-parity:incomplete:${entry.code}`,
+    family: "pricing",
+    page: "campaign",
+    status: "warn",
+    severity: "warn",
+    expected: "the page's commercial claims compared with calculated totals",
+    actual: `${entry.summary} Fix: ${entry.fix}`,
+    evidence: {
+      code: entry.code,
+      count: entry.count,
+    },
+  }));
+}
+
 function compactReport(report, journey, plan, executed, issues, observedClaims, claimLimit, plannedScenarioCount = plan.length) {
   const exactPages = array(journey?.pages).filter((page) => page?.state === PricingState.Exact).length;
   const stalePages = array(journey?.pages).filter((page) => page?.state === PricingState.Stale).length;
@@ -498,6 +605,7 @@ function compactReport(report, journey, plan, executed, issues, observedClaims,
     extracted_price_claims: report.extracted_price_claims,
     compared_price_claims: report.compared_price_claims,
     unresolved_price_claims: report.unresolved_price_claims,
+    package_price_claims: report.package_price_claims,
     extracted_recurrence_claims: report.extracted_recurrence_claims,
     compared_recurrence_claims: report.compared_recurrence_claims,
     unresolved_recurrence_claims: report.unresolved_recurrence_claims,
@@ -568,6 +676,7 @@ export function unavailableCommercialReport(code, { status = "not_run" } = {}) {
     extracted_price_claims: 0,
     compared_price_claims: 0,
     unresolved_price_claims: 0,
+    package_price_claims: { extracted: 0, compared: 0, unresolved: {} },
     extracted_recurrence_claims: 0,
     compared_recurrence_claims: 0,
     unresolved_recurrence_claims: 0,
@@ -586,6 +695,19 @@ export function unavailableCommercialReport(code, { status = "not_run" } = {}) {
   };
 }
 
+/** What a crash in the check reports: the same warn row as any other stop. */
+export function crashedCommercialResult() {
+  const reason = cause(
+    "commercial_runner_error",
+    "The commercial parity check crashed before it finished, so no price was compared.",
+    "Re-run qa run. If it crashes again, record it with findings add and tell the operator.",
+  );
+  return {
+    assertions: commercialIncompleteAssertions([reason]),
+    commercial: { ...unavailableCommercialReport(reason.code, { status: "incomplete" }), incomplete_reasons: [reason] },
+  };
+}
+
 // One blocker row per currency the calculate endpoint answered in other than
 // the run's: expected totals were asked for in `currency` and came back priced
 // in another one. Answered codes are compared and named upper-cased, so `usd`
@@ -641,13 +763,15 @@ export async function runCommercialParity({
   const observedClaims = array(captures).reduce((sum, capture) => sum + captureClaimCount(capture), 0);
   const aggregateClaimOverflow = observedClaims > limits.max_aggregate_claims;
   const orderedPreflightIssues = [
-    { exceeded: aggregateClaimOverflow, code: "commercial_aggregate_claim_limit" },
-    { exceeded: scenarioOverflow, code: "commercial_scenario_limit" },
-  ];
+    { exceeded: aggregateClaimOverflow, code: "commercial_aggregate_claim_limit", summary: `The funnel carries ${observedClaims} commercial claims, over the limit of ${limits.max_aggregate_claims}, so none were compared.` },
+    { exceeded: scenarioOverflow, code: "commercial_scenario_limit", summary: "The funnel plans more calculate scenarios than the limit, so none ran." },
+  ].filter((issue) => issue.exceeded);
   const issues = [
     ...captureIssues(captures),
-    ...orderedPreflightIssues.filter((issue) => issue.exceeded).map(({ code }) => ({ code })),
+    ...orderedPreflightIssues.map(({ code }) => ({ code })),
   ];
+  // Why calculate did not give this run its answers, said where it is found.
+  const stopped = orderedPreflightIssues.map(({ code, summary }) => cause(code, summary, OVER_LIMITS_FIX));
   const apiKeyResolution = resolveCommercialApiKey(resolved);
   const apiKey = apiKeyResolution.value;
   let executed = [];
@@ -657,8 +781,18 @@ export async function runCommercialParity({
     // preflight issues above remain visible when multiple ceilings are hit.
   } else if (apiKeyResolution.unsupported) {
     issues.push({ code: "unsupported_campaigns_api_key_source" });
+    stopped.push(cause(
+      "unsupported_campaigns_api_key_source",
+      `The packet's campaign.api_key_source names an environment variable QA refuses to read, so 0 of ${plan.length} planned calculate scenarios ran.`,
+      "Use env:CAMPAIGNS_API_KEY, or set campaign.campaigns_api_key in the CampaignSpec, then re-run qa run.",
+    ));
   } else if (plan.some((descriptor) => !descriptor?.unresolved) && !present(apiKey)) {
     issues.push({ code: "missing_campaigns_api_key" });
+    stopped.push(cause(
+      "missing_campaigns_api_key",
+      `No campaign key was resolved, so 0 of ${plan.length} planned calculate scenarios ran and no price was compared.`,
+      "Set campaign.campaigns_api_key in the CampaignSpec (or the Build Packet) to the campaign's API key, then re-run qa run.",
+    ));
   } else if (typeof fetchImpl !== "function") {
     issues.push({ code: "price_preview_fetch_unavailable" });
   } else {
@@ -669,9 +803,17 @@ export async function runCommercialParity({
       fetchImpl,
       limits,
     }));
-    executed.filter((entry) => entry?.ok === false).forEach((entry) => {
-      issues.push({ code: entry.error_code || "price_preview_failed" });
-    });
+    const failures = executed.filter((entry) => entry?.ok === false)
+      .map((entry) => entry.error_code || "price_preview_failed");
+    failures.forEach((code) => issues.push({ code }));
+    if (failures.length) {
+      stopped.push(cause(
+        "price_preview_failed",
+        `The calculate endpoint failed for ${failures.length} of ${plan.length} planned scenarios (${[...new Set(failures)].join(", ")}).`,
+        "Check that the key belongs to this campaign and that the proxy is reachable, then re-run qa run.",
+        failures.length,
+      ));
+    }
   }
 
   const journey = normalizeJourney(
@@ -715,17 +857,30 @@ export async function runCommercialParity({
     maxAssertions: Math.max(0, maxAssertions - parity.assertions.length),
   });
   parity.recurring_claim_absences = absences;
+  const commercial = compactReport(
+    parity,
+    parityJourney,
+    plan,
+    executed,
+    issues,
+    observedClaims,
+    limits.max_aggregate_claims,
+    commercialPlanning.observed_scenarios ?? plan.length,
+  );
+  const assertions = [...currencyAssertions, ...parity.assertions, ...absentAssertions];
+  if (commercial.status !== "incomplete") return { assertions, commercial };
+  // An incomplete run always names a cause in the exceptions list. A currency
+  // blocker or an absent rebill claim already wrote its own row.
+  const reasons = incompleteCauses(stopped, commercial, parityJourney);
+  if (!reasons.length && !currencyAssertions.length && !absentAssertions.length) {
+    reasons.push(cause(
+      "commercial_coverage_incomplete",
+      `Commercial parity stopped short: issues ${array(commercial.issues).map((issue) => issue.code).join(", ") || "none"}.`,
+      "Read verdict.commercial for what was and was not compared, and tell the operator.",
+    ));
+  }
   return {
-    assertions: [...currencyAssertions, ...parity.assertions, ...absentAssertions],
-    commercial: compactReport(
-      parity,
-      parityJourney,
-      plan,
-      executed,
-      issues,
-      observedClaims,
-      limits.max_aggregate_claims,
-      commercialPlanning.observed_scenarios ?? plan.length,
-    ),
+    assertions: [...assertions, ...commercialIncompleteAssertions(reasons)],
+    commercial: { ...commercial, incomplete_reasons: reasons },
   };
 }

package/src/qa-node.mjs

@@ -103,6 +103,7 @@ import {
 import {
   captureCommercialClaims,
   COMMERCIAL_QA_LIMITS,
+  crashedCommercialResult,
   mapConcurrent,
   createPageSourceLoader,
   planCommercialParity,
@@ -2609,8 +2610,10 @@ async function runResolvedQa(args, resolvedInputs, { runSessionActive = false, l
   const vendorBeacons = vendorBeaconRun ? createVendorBeaconLedger({ mode: vendorBeaconRun, analytics: resolved.spec?.analytics }) : null;
   if (vendorBeacons) args = { ...args, [QA_VENDOR_BEACONS]: vendorBeacons };
   const qcResults = [];
+  const renderedPackagePrices = new Map();
   if (args.browser === true) {
     const browserAssertions = await runBrowserChecks(resolved.topologies, args, {
+      renderedPackagePrices,
       brandContract: resolved.brandContract,
       // With no generatable brand theme on the local preview, the starter
       // template is the design: its residue is a warning (local-preview-policy.mjs).
@@ -2649,16 +2652,15 @@ async function runResolvedQa(args, resolvedInputs, { runSessionActive = false, l
   try {
     commercialResult = await runCommercialParity({
       resolved,
-      captures: [...capturesByPageId.values()],
+      captures: [...capturesByPageId.entries()].map(([pageId, capture]) => (renderedPackagePrices.has(pageId)
+        ? { ...capture, rendered_package_prices: renderedPackagePrices.get(pageId) }
+        : capture)),
       planning: commercialPlanning,
       maxAssertions: remainingAssertionBudget,
       currency,
     });
   } catch (error) {
-    commercialResult = {
-      assertions: [],
-      commercial: unavailableCommercialReport("commercial_runner_error"),
-    };
+    commercialResult = crashedCommercialResult();
     reportCommercialRunnerError(args, error);
   }
   assertions.push(...commercialResult.assertions);
@@ -3795,6 +3797,9 @@ function output(value, args) {
     printThemeGateLines(value.theme_gate, value.packet_path, value.report_path);
     if (value.commercial) {
       console.log(`Commercial parity: ${value.commercial.status} (${value.commercial.finding_count || 0} findings, ${value.commercial.checked_pages || 0} pages checked)`);
+      for (const entry of value.commercial.incomplete_reasons || []) {
+        console.log(`  ${entry.code}: ${entry.summary} Fix: ${entry.fix}`);
+      }
     }
     console.log(`Local copy: ${value.local_path}`);
     if (value.posted?.ok && value.dashboard_url) {

package/src/qa-verdict.mjs

@@ -88,7 +88,9 @@ export function computeDisposition(assertions) {
 function dispositionWithCommercial(assertions, commercial) {
   const disposition = computeDisposition(assertions);
   if (disposition === "blocked") return disposition;
-  return commercial?.status === "mismatch"
+  // Warn-only either way: a proven mismatch and a proof that stopped short are
+  // both things the operator has to hear about, and neither ever blocks.
+  return commercial?.status === "mismatch" || commercial?.status === "incomplete"
     ? "ready_with_exceptions"
     : disposition;
 }

package/src/readback.mjs

@@ -1310,6 +1310,7 @@ function renderEvidenceDebt(debt, lines) {
         : `evidence currency is unknown (${stage.reason}); absence of proof is not no debt`;
     lines.push(`  ${name}: ${stage.status} — ${explanation}`);
     lines.push(`    recorded: ${stage.recorded_build_fingerprint ?? "unknown"}; current: ${stage.current_build_fingerprint ?? "unknown"}`);
+    if (stage.baseline) lines.push(`    baseline: accepted by ${oneLine(stage.baseline.accepted_by)} at ${oneLine(stage.baseline.accepted_at)}, not tested; no purchase tested since`);
     if (stage.change) {
       const owes = stage.advisory ? "advisory: reported, not required"
         : stage.scope === "pages" ? `owed on ${stage.owed_pages.map((page) => oneLine(page.page_id)).join(", ")} (qa run --page)` : "the full stage is owed";

package/src/runtime-state-ignore.mjs

@@ -6,7 +6,10 @@
 //      second and later funnels) — current readback truth; docs/migration-sidecar-bundle.md
 //      names it and `bundle check` validates it. Committed by design.
 //   2. Handoff inputs and agent context (input/, theme/, agent-context/,
-//      setup-handoff.json) — durable build handoff. Committed by design.
+//      setup-handoff.json) and the CampaignSpec a Map intake fetched
+//      (fetched-specs/) — durable build handoff. The committed records are
+//      bound to that spec, and spec derive edits it, so another machine cannot
+//      get it back from the Map. Committed by design.
 //   3. Telemetry, sessions, caches, and evidence — per-machine, append-only,
 //      or carrying live URLs and absolute paths. Never meant for the repo, and
 //      nothing wrote a rule for them: three campaign repositories were found
@@ -32,7 +35,6 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
   // A project's second and later funnels keep their Run Records under their
   // own runtime directory (src/campaign-workspace.mjs).
   ".campaign-runtime/funnels/*/run-records/",
-  ".campaign-runtime/fetched-specs/",
   ".campaign-runtime/progress/",
   ".campaign-runtime/polish-evidence/",
   ".campaign-runtime/evidence/",
@@ -53,12 +55,17 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
 // present.
 export const RUNTIME_STATE_REQUIRED_IGNORED_PATHS = ["qa-output/", ".campaign-runtime/progress/", ".campaign-runtime/funnels/*/run-records/"];
 
+// Entries an earlier toolkit wrote into the managed block that are now meant
+// to be committed. They leave the managed block on the next setup command or
+// `spec fetch`; the same line elsewhere in the file is the operator's own.
+export const RUNTIME_STATE_RETIRED_IGNORED_PATHS = [".campaign-runtime/fetched-specs/"];
+
 export const RUNTIME_STATE_IGNORE_BLOCK = [
   RUNTIME_STATE_IGNORE_MARKER,
-  "# Sessions, journals, Run Records, spec caches, capture evidence, and full",
-  "# QA verdicts are per-machine. The readback bundle (build-context, assembly-report,",
-  "# doctor-output, qa-verdict), input/, theme/, and agent-context/ are meant",
-  "# to be committed and are deliberately not listed here.",
+  "# Sessions, journals, Run Records, capture evidence, and full QA verdicts are",
+  "# per-machine. The readback bundle (build-context, assembly-report, doctor-output,",
+  "# qa-verdict), fetched-specs/, input/, theme/, and agent-context/ are meant to be",
+  "# committed and are deliberately not listed here.",
   ...RUNTIME_STATE_IGNORED_PATHS,
 ].join("\n");
 
@@ -66,14 +73,29 @@ function ignoreRuleLines(text) {
   return new Set(text.split("\n").map((line) => line.trim()).filter((line) => line && !line.startsWith("#")));
 }
 
-// Append the missing required entries at the end of the managed block: after
-// the marker, up to the first blank line or the end of the file.
-function withRequiredEntries(existing, missing) {
-  const lines = existing.split("\n");
-  const markerIndex = lines.findIndex((line) => line.trim() === RUNTIME_STATE_IGNORE_MARKER);
+// The managed block spans the marker up to the first blank line or the end of
+// the file.
+function managedBlockEnd(lines, markerIndex) {
   let end = markerIndex + 1;
   while (end < lines.length && lines[end].trim() !== "") end += 1;
-  lines.splice(end, 0, ...missing);
+  return end;
+}
+
+function retiredEntriesInBlock(existing) {
+  const lines = existing.split("\n");
+  const markerIndex = lines.findIndex((line) => line.trim() === RUNTIME_STATE_IGNORE_MARKER);
+  return lines.slice(markerIndex + 1, managedBlockEnd(lines, markerIndex)).map((line) => line.trim())
+    .filter((line) => RUNTIME_STATE_RETIRED_IGNORED_PATHS.includes(line));
+}
+
+// Append the missing required entries at the end of the managed block and drop
+// the retired ones from it.
+function withBlockEntries(existing, missing) {
+  const lines = existing.split("\n");
+  const markerIndex = lines.findIndex((line) => line.trim() === RUNTIME_STATE_IGNORE_MARKER);
+  const end = managedBlockEnd(lines, markerIndex);
+  const block = lines.slice(markerIndex + 1, end).filter((line) => !RUNTIME_STATE_RETIRED_IGNORED_PATHS.includes(line.trim()));
+  lines.splice(markerIndex + 1, end - markerIndex - 1, ...block, ...missing);
   return lines.join("\n");
 }
 
@@ -81,10 +103,11 @@ function withRequiredEntries(existing, missing) {
  * Ensure the target's .gitignore carries the runtime-state block. Idempotent
  * on the marker line: an existing block, however edited beneath it, is left
  * alone — except for RUNTIME_STATE_REQUIRED_IGNORED_PATHS, which are appended
- * to an existing block when the file carries them nowhere. Never throws for
- * an unwritable target — the build must not fail on housekeeping — but
+ * to an existing block when the file carries them nowhere, and
+ * RUNTIME_STATE_RETIRED_IGNORED_PATHS, which are removed from it. Never throws
+ * for an unwritable target — the build must not fail on housekeeping — but
  * reports what happened so callers can surface it.
- * Returns `{ path, action: "added" | "updated" | "present" | "skipped", reason?, added_entries? }`.
+ * Returns `{ path, action: "added" | "updated" | "present" | "skipped", reason?, added_entries?, removed_entries? }`.
  */
 export function ensureRuntimeStateIgnored(targetRepo, { dryRun = false } = {}) {
   const path = join(resolve(targetRepo), ".gitignore");
@@ -98,14 +121,16 @@ export function ensureRuntimeStateIgnored(targetRepo, { dryRun = false } = {}) {
     if (existing.includes(RUNTIME_STATE_IGNORE_MARKER)) {
       const present = ignoreRuleLines(existing);
       const missing = RUNTIME_STATE_REQUIRED_IGNORED_PATHS.filter((entry) => !present.has(entry));
-      if (missing.length === 0) return { path, action: "present" };
-      if (dryRun) return { path, action: "updated", dry_run: true, added_entries: missing };
+      const retired = retiredEntriesInBlock(existing);
+      if (missing.length === 0 && retired.length === 0) return { path, action: "present" };
+      const changes = { added_entries: missing, ...(retired.length ? { removed_entries: retired } : {}) };
+      if (dryRun) return { path, action: "updated", dry_run: true, ...changes };
       try {
-        writeFileSync(path, withRequiredEntries(existing, missing));
+        writeFileSync(path, withBlockEntries(existing, missing));
       } catch (error) {
         return { path, action: "skipped", reason: `unwritable: ${error.message}` };
       }
-      return { path, action: "updated", added_entries: missing };
+      return { path, action: "updated", ...changes };
     }
   }
   if (dryRun) return { path, action: "added", dry_run: true };

package/src/stage-ledger.mjs

@@ -106,20 +106,23 @@ const HISTORY_ENTRY_FIELDS = Object.freeze([
   "build_fingerprint", "source_build_fingerprint", "source_package_material_fingerprint",
   "source_brief_material", "source_spec_material_hash",
   "verdict_run_id", "checked_at", "purchase_proof",
-  "outputs", "evidence",
+  "outputs", "evidence", "baseline_accepted_at",
 ]);
 // The entry fields that say what a record was, rather than when or by whom it
 // was written: a replacement equal on all of them is a re-record, not a new
 // chapter, and archives nothing.
 const HISTORY_IDENTITY_FIELDS = Object.freeze([
   "build_fingerprint", "source_build_fingerprint", "source_package_material_fingerprint",
-  "source_brief_material", "source_spec_material_hash", "verdict_run_id", "purchase_proof", "outputs", "evidence",
+  "source_brief_material", "source_spec_material_hash", "verdict_run_id", "purchase_proof", "outputs", "evidence", "baseline_accepted_at",
 ]);
-export const HISTORY_ARCHIVED_BY = Object.freeze(["record brief", "record spec", "record build", "record polish", "qa run", "prepare-build --force"]);
-export const HISTORY_REASON_CODES = Object.freeze(["brief_presentation_changed", "brief_qa_policy_changed", "spec_material_changed", "rerecorded", "force_reset", "build_output_changed"]);
+export const HISTORY_ARCHIVED_BY = Object.freeze(["record brief", "record spec", "record build", "record polish", "record baseline", "qa run", "prepare-build --force"]);
+export const HISTORY_REASON_CODES = Object.freeze(["brief_presentation_changed", "brief_qa_policy_changed", "spec_material_changed", "rerecorded", "force_reset", "build_output_changed", "baseline_accepted"]);
 const ARCHIVED_STAGE_KEYS = Object.freeze(["assembly", "polish", "qa"]);
 
 const isCompletedStatus = (status) => typeof status === "string" && status.startsWith("completed");
+// A record a later one replaces into history. A baseline counts here, and not
+// as completed: it never hands a campaign off or proves anything.
+const isReplacedRecord = (status) => isCompletedStatus(status) || status === "baseline_accepted";
 
 // What a record says about itself, compared for the dedup. Evidence reads
 // through meaningfulEvidence (an empty block is absent) and a verdict id is
@@ -168,7 +171,7 @@ function historyEntry(previous, { by, reason, at }) {
 // verdict identity or evidence, which the QA producer has always archived.
 function archivable(stageKey, previous) {
   if (!isPlainObject(previous)) return false;
-  if (isCompletedStatus(previous.status)) return true;
+  if (isReplacedRecord(previous.status)) return true;
   return stageKey === "qa" && Boolean(recordIdentity(previous).verdict_run_id || meaningfulEvidence(previous.evidence));
 }
 
@@ -200,6 +203,19 @@ export function archiveSupersededRecord(stage, previous, { by, reason, at }) {
   return appendHistoryEntry(isPlainObject(stage) ? { ...stage } : {}, historyEntry(previous, { by, reason, at }));
 }
 
+// The baseline QA rests on, or null. The marker on the record is the rule, not
+// its status: a blocked page-scoped run or an input change leaves QA resting on
+// the baseline, and only a completed full QA clears the marker.
+export function qaRestsOnBaseline(report) {
+  return report?.stages?.qa?.baseline_accepted_at && isPlainObject(report?.commerce_baseline) ? report.commerce_baseline : null;
+}
+
+// A stage's baseline record, with what the stage held moved to its history.
+export function archiveForBaseline(record, previous, { at }) {
+  const carried = Array.isArray(previous?.history) ? { ...record, history: previous.history } : record;
+  return archiveSupersededRecord(carried, previous, { by: "record baseline", reason: "baseline_accepted", at });
+}
+
 /**
  * #668: the Polish record a CampaignSpec change moved to `polish.history`,
  * restored as the live record stamped with `stamps` (the current inputs), or
@@ -241,6 +257,15 @@ export function campaignHandedOff(report) {
   return completedIn(report?.stages?.deploy) || completedIn(report?.stages?.qa);
 }
 
+// True when QA has ever completed, now or in the stage's history. Not
+// campaignHandedOff: a baseline stands in for a QA result, and a completed
+// deploy is not one.
+export function qaEverCompleted(report) {
+  const qa = report?.stages?.qa;
+  return isPlainObject(qa) && (isCompletedStatus(qa.status)
+    || (Array.isArray(qa.history) && qa.history.some((entry) => isPlainObject(entry) && isCompletedStatus(entry.status))));
+}
+
 /**
  * True when any stage of `report` carries a non-empty history: recorded
  * operator-visible state an intake must not silently drop.
@@ -301,7 +326,7 @@ export function archiveForForceReset(previousReport, nextReport, { now, detectCh
       continue;
     }
     if (Object.hasOwn(previous, "input_change")) reseeded.input_change = JSON.parse(JSON.stringify(previous.input_change));
-    if (isCompletedStatus(previous.status)) {
+    if (isReplacedRecord(previous.status)) {
       reseeded = archiveSupersededRecord(reseeded, previous, { by: "prepare-build --force", reason: "force_reset", at: now });
       const reason = typeof detectChange === "function" ? detectChange(key, previous) : null;
       if (reason) reseeded.input_change = inputChangeFor(key, previous, { at: now, reason });
@@ -405,7 +430,7 @@ export function recordProducerStageOutcome(report, {
     // A replaced completed record whose stamps differ from the current inputs
     // records the change; a verdict stamped with the current inputs then
     // clears it, the one it just recorded included; any other write carries it.
-    const detected = inputs && isCompletedStatus(previous.status) ? inputs.detectChange(previous) : null;
+    const detected = inputs && isReplacedRecord(previous.status) ? inputs.detectChange(previous) : null;
     if (detected) next.input_change = inputChangeFor("qa", previous, { at: timestamp, reason: detected });
     if (inputs && inputs.stampsCurrent(next)) delete next.input_change;
     const archived = archiveStageRecord(next, previous, next, { by: "qa run", reason: detected || "rerecorded", at: timestamp, stageKey: "qa" });
@@ -591,9 +616,10 @@ export function qaRecordedBuildFingerprint(report) {
 // #720: the build whose completed QA a page-scoped run extends. A completed
 // QA record extends its own build. A page-scoped run that did not complete
 // extends the build of the full QA it was based on, which was completed when
-// that run was accepted. Any other record (blocked or pending full QA, a
+// that run was accepted. A baseline extends its own build too, and has no
+// purchase proof to pass on. Any other record (blocked or pending full QA, a
 // skip, a required stage) extends nothing, so it owes a full QA run.
-const QA_EXTENDABLE_STATUSES = Object.freeze(["completed", "completed_with_warnings"]);
+const QA_EXTENDABLE_STATUSES = Object.freeze(["completed", "completed_with_warnings", "baseline_accepted"]);
 export function qaExtendedBuildFingerprint(report) {
   const qa = report?.stages?.qa;
   if (QA_EXTENDABLE_STATUSES.includes(qa?.status)) return qaRecordedBuildFingerprint(report);