@nextcommerce/campaigns-os 1.61.0 → 1.62.0

package/src/qc-results.mjs

@@ -21,7 +21,7 @@ import { createHash } from "node:crypto";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { isAbsolute, relative, resolve } from "node:path";
 
-import { campaignSidecarPaths } from "./campaign-workspace.mjs";
+import { campaignSidecarPaths, packetRuntimeRelPath } from "./campaign-workspace.mjs";
 import { checkpointStateFingerprint } from "./checkpoint-waiver.mjs";
 import { contrastToolkit } from "./contrast.mjs";
 import { sameFile } from "./fs-identity.mjs";
@@ -299,10 +299,14 @@ export function readQaFullVerdict({ stage, targetRepo, packetPath = null, report
     const stats = statSync(real);
     if (!stats.isFile()) return null;
     if (!inside(realpathSync(outputDir), real)) return null;
+    // This funnel's default report and every other funnel's project-level
+    // one (#719): neither is a verdict.
+    const packet = isNonEmptyString(packetPath) ? readPacketForGuard(packetPath) : null;
     const forbidden = [
       reportPath,
       campaignSidecarPaths(targetRepo).reportPath,
-      isNonEmptyString(packetPath) ? sidecarPathForPacket(packetPath) : null,
+      packet ? campaignSidecarPaths(targetRepo, packetRuntimeRelPath(packet)).reportPath : null,
+      isNonEmptyString(packetPath) ? sidecarPathForPacket(packetPath, packet) : null,
       ...outputs.filter((path) => path !== candidates[0]),
     ].filter(isNonEmptyString);
     for (const path of forbidden) {
@@ -317,6 +321,15 @@ export function readQaFullVerdict({ stage, targetRepo, packetPath = null, report
   }
 }
 
+function readPacketForGuard(packetPath) {
+  try {
+    const parsed = JSON.parse(readFileSync(packetPath, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
 // `qaCurrency` is QA's read-time input currency
 // (derived.input_currency.stages.qa). While QA is owed again or its inputs
 // cannot be confirmed, every row that reproduces reads stale_binding, as a
@@ -1038,30 +1051,46 @@ function readabilityCropResolves(ref, targetRepo) {
 //    the record lacks, or one over the route cap, reads page_not_captured;
 //    a recorded route outside it, or different uncaptured routes or
 //    enumeration cap, → evidence_not_reproducible;
-// 4. the rows READABILITY_QC_RULES.evaluate derives from each cell.
+// 4. the rows READABILITY_QC_RULES.evaluate derives from each cell, and,
+//    for a record that stores layout_conventions, the layout.conventions
+//    rows LAYOUT_QC_RULES.evaluate derives from it.
 // `campaignSlug` is the packet's slug; a missing one never matches.
-export function readReadability({ record, pageLoad = null, currentBuild = null, currentSource = null, buildOutput = null, campaignSlug = null, targetRepo = null, qcStandIns = null, rederivers = null } = {}) {
+export function readReadability({ record, pageLoad = null, currentBuild = null, currentSource = null, buildOutput = undefined, campaignSlug = null, targetRepo = null, qcStandIns = null, rederivers = null } = {}) {
   if (record === undefined || record === null) return [];
-  const [check] = POLISH_RECORDS.readability.checks;
+  const [check, layoutCheck = null] = POLISH_RECORDS.readability.checks;
   const measuredAt = canonicalTime(record?.measured_at) ? record.measured_at : null;
   const cells = Array.isArray(record?.cells) ? record.cells.filter(isPlainObject) : [];
-  const subjectOf = (page, viewport, key) => ({ check, page, viewport, key });
-  const rowOf = (subject, reasonCode) => unreproducedRow({ subject, check }, reasonCode, { leg: "polish", measuredAt });
+  const subjectOf = (page, viewport, key, of = check) => ({ check: of, page, viewport, key });
+  const rowOf = (subject, reasonCode) => unreproducedRow({ subject, check: subject.check }, reasonCode, { leg: "polish", measuredAt });
   const unique = (rows) => [...new Map(rows.map((row) => [row.id, row])).values()];
   let rules = null;
+  // The layout check reads only a record that stores the conventions it was
+  // measured with; its rules load on their own.
+  const layoutRecorded = isPlainObject(record) && Object.hasOwn(record, "layout_conventions") && isNonEmptyString(layoutCheck);
+  const layoutResolved = layoutRecorded ? resolvePolishRules({ check: layoutCheck, qcStandIns, rederivers }) : { status: "missing" };
+  const layoutRules = layoutResolved.status === "loaded" ? layoutResolved.rules : null;
+  const layoutRead = layoutRecorded && layoutResolved.status !== "missing";
+  const namedKeys = (rowKeys, cell) => {
+    try {
+      const named = typeof rowKeys === "function" ? rowKeys(cell) : [];
+      return Array.isArray(named) ? named.filter(isNonEmptyString) : [];
+    } catch {
+      return [];
+    }
+  };
+  // A failed cell's layout rows: one per row the layout rules name for the
+  // cell (its `cell` row among them; none at a viewport no convention
+  // applies to), or its `cell` row when the rules did not load.
+  const failLayout = (cell) => (layoutRead
+    ? [...new Set(layoutRules ? namedKeys(layoutRules.rowKeys, cell) : ["cell"])].map((key) => rowOf(subjectOf(cell?.route ?? null, cell?.viewport ?? null, key, layoutCheck), E))
+    : []);
   // A failed cell: one result per row the cell names and its `cell` row, so
   // a failed cell is never silent and an accept of one of its rows lapses
   // rather than orphans. The keys come from rules.rowKeys, which reads
   // neither the record's thresholds nor any field the checks reject.
   const failCell = (cell) => {
-    let named = [];
-    try {
-      named = typeof rules?.rowKeys === "function" ? rules.rowKeys(cell) : [];
-    } catch {
-      named = [];
-    }
-    const keys = [...new Set([...(Array.isArray(named) ? named.filter(isNonEmptyString) : []), "cell"])];
-    return keys.map((key) => rowOf(subjectOf(cell?.route ?? null, cell?.viewport ?? null, key), E));
+    const keys = [...new Set([...namedKeys(rules?.rowKeys, cell), "cell"])];
+    return [...keys.map((key) => rowOf(subjectOf(cell?.route ?? null, cell?.viewport ?? null, key), E)), ...failLayout(cell)];
   };
   // A record-level failure: every listed cell fails; every route the subject
   // or a cell names, at every recorded or fixed viewport, that no cell lists
@@ -1124,7 +1153,8 @@ export function readReadability({ record, pageLoad = null, currentBuild = null,
     || typeof record.route_enumeration_capped !== "boolean"
     || !Array.isArray(record.cells)
     || cells.length !== record.cells.length
-    || !cells.every((cell) => rules.cellShapeOk(cell))) return failAll();
+    || !cells.every((cell) => rules.cellShapeOk(cell))
+    || (layoutRecorded && layoutRules && !sameJson(record.layout_conventions, layoutRules.thresholds))) return failAll();
   // The cell set is exactly routes × viewports: none missing, none added,
   // none twice, every cell's route and viewport in the subject.
   const gridKeys = declaredGrid(subject).map(({ route, viewport }) => cellKey(route, viewport));
@@ -1151,7 +1181,9 @@ export function readReadability({ record, pageLoad = null, currentBuild = null,
   const bound = isNonEmptyString(currentBuild)
     && subject.build_fingerprint === currentBuild
     && subject.source_package_material_fingerprint === (isNonEmptyString(currentSource) ? currentSource : null)
-    && !outputDrifted(buildOutput ?? null);
+    // As in the captures reader: no buildOutput (undefined) reads without the
+    // output check; null is drift.
+    && !outputDrifted(buildOutput);
 
   // 3. The recomputed route set, read only when the output is the build's.
   const results = [];
@@ -1182,22 +1214,37 @@ export function readReadability({ record, pageLoad = null, currentBuild = null,
     }
     const derived = evaluate(cell, cropAvailable);
     // Every derived subject is the cell's own page and viewport, each key once.
-    const keys = Array.isArray(derived) ? derived.map((item) => item?.subject?.key) : [];
-    if (!Array.isArray(derived) || new Set(keys).size !== keys.length || !derived.every((item) => item?.check === check
-      && validDerived(item, check)
-      && hasExactly(item.subject, ["check", "page", "viewport", "key"])
-      && item.subject.page === cell.route
-      && item.subject.viewport === cell.viewport
-      && isNonEmptyString(item.subject.key))) {
+    const derivedOk = (items, of) => {
+      const keys = Array.isArray(items) ? items.map((item) => item?.subject?.key) : [];
+      return Array.isArray(items) && new Set(keys).size === keys.length && items.every((item) => item?.check === of
+        && validDerived(item, of)
+        && hasExactly(item.subject, ["check", "page", "viewport", "key"])
+        && item.subject.page === cell.route
+        && item.subject.viewport === cell.viewport
+        && isNonEmptyString(item.subject.key));
+    };
+    if (!derivedOk(derived, check)) {
       results.push(...failCell(cell));
       continue;
     }
-    for (const item of derived) {
+    let layoutDerived = [];
+    if (layoutRead) {
+      try {
+        layoutDerived = layoutRules ? layoutRules.evaluate(cell, record.layout_conventions) : null;
+      } catch {
+        layoutDerived = null;
+      }
+      if (!derivedOk(layoutDerived, layoutCheck)) {
+        results.push(...failLayout(cell));
+        layoutDerived = [];
+      }
+    }
+    for (const item of [...derived, ...layoutDerived]) {
       const members = item.members ?? [];
       const row = {
         schema: QC_RESULT_SCHEMA,
         id: qcResultId(item.subject),
-        check,
+        check: item.check,
         leg: "polish",
         result: item.result,
         reason_code: item.result === "pass" ? null : item.reason_code,

package/src/readback.mjs

@@ -56,6 +56,8 @@ import { fileURLToPath } from "node:url";
 import { assessInputCurrency, currentPacketInputs, effectiveStageStatus } from "./input-currency.mjs";
 import { deriveAssemblyReportSummary } from "./stage-ledger.mjs";
 import { assessEvidenceDebt } from "./evidence-debt.mjs";
+import { RUNTIME_DIR_REL_PATH, packetRuntimeRelPath } from "./campaign-workspace.mjs";
+import { normalizePublicRouteSlug } from "./route-identity.mjs";
 
 export const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
 export const MAX_GIT_METADATA_BYTES = 64 * 1024;
@@ -193,7 +195,9 @@ export function readReflogTail(path) {
 
 // Artifact keys, in render order, with the default location of each artifact
 // relative to the target repository root. The packet lives at the root; the
-// sidecars live under .campaign-runtime/.
+// sidecars live under .campaign-runtime/, or under the runtime directory the
+// selected packet records (assembly.runtime_dir) when the project holds
+// several funnels.
 export const DEFAULT_RELATIVE_PATHS = {
   packet: "campaign-runtime.build.json",
   doctor: ".campaign-runtime/doctor-output.json",
@@ -221,8 +225,10 @@ export const RECOGNIZED_SCHEMA_VERSIONS = {
 };
 
 // Root-level Build Packets other than the default-named one. A second run in
-// the same repository leaves its record under a suffixed name; both shapes are
-// discovery candidates when no `--packet` was given.
+// the same repository leaves its record under a suffixed name, and every
+// funnel after a project's first has its packet at
+// campaign-runtime-<route>.build.json; both shapes are discovery candidates
+// when no `--packet` was given.
 const PACKET_CANDIDATE_PATTERN = /^campaign-runtime-.*\.build\.json$/;
 
 // Sidecar path some write-ends have used instead of the contracted root home.
@@ -1304,6 +1310,13 @@ 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.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";
+      lines.push(`    change since its build: ${stage.change.kind}; ${owes}`);
+      for (const page of stage.change.changed_pages) lines.push(`    changed page: ${oneLine(page.page_id)} (${oneLine(page.built_path)})`);
+      for (const reason of stage.change.reasons) lines.push(`    commerce: ${oneLine(reason.code)}${reason.path ? ` (${oneLine(reason.path)})` : ""}`);
+    }
   }
   const changes = debt.changes;
   lines.push(`  changes against assembly manifest: ${changes.status}${changes.reason ? ` (${changes.reason})` : ""}`);
@@ -1642,7 +1655,8 @@ export function serializeStaleness(staleness) {
  * or unrecognized one always is); the staleness comparison is computable and NO
  * loaded artifact is stale; NO loaded artifact recorded a `generated_at` this
  * readback could not parse; no cross-artifact divergence was found; and the
- * doctor output records zero errors; and no evidence-debt stage is owed.
+ * doctor output records zero errors; and no evidence-debt stage is owed
+ * (advisory Polish for a page-only change does not count).
  * Unknown build binding does not independently change this integrity flag;
  * callers must read evidence_debt rather than treating clean as no debt.
  *
@@ -1664,7 +1678,8 @@ export function serializeStaleness(staleness) {
  */
 export function computeClean(views, staleness, evidenceDebt) {
   if (evidenceDebt == null) throw new TypeError("computeClean requires an evidence-debt assessment");
-  if ([evidenceDebt?.polish, evidenceDebt?.qa].some((stage) => stage?.status === "owed")) return false;
+  // Advisory Polish (a page-only change) is reported, never required.
+  if ([evidenceDebt?.polish, evidenceDebt?.qa].some((stage) => stage?.status === "owed" && !stage.advisory)) return false;
   if (Object.values(views).some((view) => !CLEAN_ARTIFACT_STATES.has(view.state))) return false;
   if (!staleness || !staleness.computable || staleness.stale) return false;
   if (staleness.unparseable_keys.length) return false;
@@ -1835,6 +1850,18 @@ export function selectPacketPath(rootPath, override) {
 
   if (considered.length === 1) return chose(considered[0], "sole_candidate");
 
+  // Packets for different routes are different funnels, each with its own
+  // records: freshness would only say which funnel was set up last, so the
+  // caller names the one to project.
+  const routes = new Map(considered.map((name) => [name, normalizePublicRouteSlug(views.get(name).data?.campaign?.public_route_slug) || null]));
+  if (new Set(routes.values()).size > 1) {
+    const detail = considered.map((name) => `${name} (route ${routes.get(name) || "unnamed"})`).join(", ");
+    throw new ReadbackUsageError(
+      `the target root holds Build Packets for more than one funnel: ${detail}. ` +
+        "Pass --packet to name the funnel's Build Packet to project.",
+    );
+  }
+
   if (considered.some((name) => times.get(name) === null)) {
     const detail = considered
       .map((name) => {
@@ -1869,24 +1896,45 @@ export function selectPacketPath(rootPath, override) {
 /**
  * Return `{ paths, packetSelection, packetView }` for one target root.
  *
- * `packetView` is the Build Packet view discovery already loaded, ready to hand
- * to loadArtifacts as `preloaded` so no artifact is read twice; it is null when
- * discovery read no packet.
+ * `packetView` is the Build Packet view already loaded (by discovery, or here
+ * for an explicit `--packet` that names a file), ready to hand to
+ * loadArtifacts as `preloaded` so no artifact is read twice; it is null when
+ * there is no packet file to read. The sidecar paths sit under the runtime
+ * directory that packet records.
  */
 export function resolveProjection(root, overrides = {}) {
   const info = statOrNull(root);
   if (!info || !info.isDirectory()) {
     throw new ReadbackUsageError(`target repository root must name an existing directory: ${root}`);
   }
-  const { path: packetPath, selection, view } = selectPacketPath(root, overrides.packet);
+  const selected = selectPacketPath(root, overrides.packet);
+  const { path: packetPath, selection } = selected;
+  // The sidecars follow the packet: read it now when discovery did not, so
+  // its runtime directory is known and it is still read only once.
+  const view = selected.view || (isFilePath(packetPath) ? loadArtifact("packet", packetPath) : null);
+  const runtime = packetRuntimeDirFor(view);
   const paths = { packet: packetPath };
   for (const [key, relative] of Object.entries(DEFAULT_RELATIVE_PATHS)) {
     if (key === "packet") continue;
-    paths[key] = overrides[key] ? String(overrides[key]) : join(root, relative);
+    paths[key] = overrides[key] ? String(overrides[key]) : join(root, runtime, relative.slice(RUNTIME_DIR_REL_PATH.length + 1));
   }
   return { paths, packetSelection: selection, packetView: view };
 }
 
+// The runtime directory the selected packet records, relative to the root;
+// the project-level .campaign-runtime when there is no readable packet or it
+// records none. A value the packet may not carry leaves no way to know whose
+// records to show, and showing the project-level ones could project another
+// funnel's, so the readback cannot form a projection.
+function packetRuntimeDirFor(view) {
+  if (view?.state !== "loaded") return RUNTIME_DIR_REL_PATH;
+  try {
+    return packetRuntimeRelPath(view.data);
+  } catch (error) {
+    throw new ReadbackUsageError(`${view.path}: ${error.message}`);
+  }
+}
+
 /** The artifact paths to project; discovery result discarded. */
 export function resolvePaths(root, overrides = {}) {
   return resolveProjection(root, overrides).paths;

package/src/route-identity.mjs

@@ -39,6 +39,16 @@ export function normalizePageKitRoute(value) {
   return clean ? `${clean}/` : "";
 }
 
+// The public route slug a CampaignSpec names for itself, normalized:
+// spec_identity.public_route_slug, else campaign.slug, else campaign.id. One
+// reading for every command that checks a spec belongs to its packet.
+export function specPublicRouteSlug(spec) {
+  for (const value of [spec?.spec_identity?.public_route_slug, spec?.campaign?.slug, spec?.campaign?.id]) {
+    if (typeof value === "string" && value.trim()) return normalizePublicRouteSlug(value);
+  }
+  return "";
+}
+
 // The route with the slug prefix removed, when it carries one: "slug/checkout/"
 // → "checkout/", "slug/" → "", "checkout/" → "checkout/".
 export function stripPublicRoutePrefix(route, publicRouteSlug) {

package/src/run-record.mjs

@@ -12,13 +12,14 @@ import { localSpecIdentityFields, resolveCampaignIdentity } from "./spec-source-
 
 import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { ADAPTER_DECISION_STRATEGY_FIELDS } from "./adapter-decision-contract.mjs";
 import { currentBuildFingerprint } from "./polish-gate.mjs";
 import { qaRecordedBuildFingerprint, qaRecordedForCurrentBuild } from "./stage-ledger.mjs";
 
 export const RUN_RECORD_SCHEMA = "campaigns-os-run-record/v0";
 export const RUN_RECORDS_DIR_REL_PATH = ".campaign-runtime/run-records";
+const RUNTIME_DIR_REL_PATH = ".campaign-runtime";
 
 // Improvement-surface taxonomy: a list, not an enum — real signal is rarely
 // one surface (see Improvement-Surface Taxonomy in the design).
@@ -377,12 +378,19 @@ function sanitizeRunId(runId) {
 }
 
 /**
- * Resolve where a Run Record is written: <baseDir>/.campaign-runtime/
- * run-records/<run_id>.json. baseDir is the run root (the CLI passes the
- * packet's directory) so the records sit next to the findings journal.
+ * Resolve where a Run Record is written: <baseDir>/<runtime dir>/run-records/
+ * <run_id>.json. baseDir is the run root (the CLI passes the packet's
+ * directory) so the records sit next to the findings journal. The runtime
+ * directory is the packet's (packetRuntimeRelPath in campaign-workspace.mjs):
+ * `.campaign-runtime` unless the packet is one of several funnels in its
+ * project, so each funnel keeps its own records.
  */
-export function resolveRunRecordPath(runId, baseDir = process.cwd()) {
-  return join(resolve(baseDir), RUN_RECORDS_DIR_REL_PATH, `${sanitizeRunId(runId)}.json`);
+export function resolveRunRecordPath(runId, baseDir = process.cwd(), runtimeRelPath = RUNTIME_DIR_REL_PATH) {
+  return join(runRecordsDir(baseDir, runtimeRelPath), `${sanitizeRunId(runId)}.json`);
+}
+
+function runRecordsDir(baseDir, runtimeRelPath = RUNTIME_DIR_REL_PATH) {
+  return join(resolve(baseDir), runtimeRelPath, relative(RUNTIME_DIR_REL_PATH, RUN_RECORDS_DIR_REL_PATH));
 }
 
 function extractDoctorObservations(doctor) {
@@ -758,13 +766,13 @@ export function assembleRunRecord({
  * invalid record (a malformed manifest is a build-tooling bug, not run state
  * to swallow). Returns the written path.
  */
-export function writeRunRecord(record, { baseDir = process.cwd() } = {}) {
+export function writeRunRecord(record, { baseDir = process.cwd(), runtimeRelPath = RUNTIME_DIR_REL_PATH } = {}) {
   const validation = validateRunRecord(record);
   if (!validation.ok) {
     const detail = validation.errors.map((error) => `[${error.code}] ${error.message}`).join("; ");
     throw new Error(`Run Record failed validation; refusing to write: ${detail}`);
   }
-  const path = resolveRunRecordPath(record.run_id, baseDir);
+  const path = resolveRunRecordPath(record.run_id, baseDir, runtimeRelPath);
   mkdirSync(dirname(path), { recursive: true });
   const tmpPath = `${path}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
   writeFileSync(tmpPath, `${JSON.stringify(record, null, 2)}\n`);
@@ -831,9 +839,9 @@ export function orderRunRecordFileNames(names) {
   });
 }
 
-export function readRunRecordsForTarget(baseDir) {
+export function readRunRecordsForTarget(baseDir, runtimeRelPath = RUNTIME_DIR_REL_PATH) {
   try {
-    const dir = join(resolve(baseDir), RUN_RECORDS_DIR_REL_PATH);
+    const dir = runRecordsDir(baseDir, runtimeRelPath);
     if (!existsSync(dir) || !statSync(dir).isDirectory()) return [];
     const names = orderRunRecordFileNames(readdirSync(dir).filter((name) => RUN_RECORD_FILE_NAME_PATTERN.test(name)))
       .slice(0, RUN_RECORDS_SCAN_LIMIT);

package/src/runtime-state-ignore.mjs

@@ -2,7 +2,8 @@
 // history, and which are not. Three kinds share the directory:
 //
 //   1. The readback bundle (build-context, assembly-report, doctor-output,
-//      qa-verdict) — current readback truth; docs/migration-sidecar-bundle.md
+//      qa-verdict, at the top level or under funnels/<route>/ for a project's
+//      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.
@@ -28,6 +29,9 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
   ".campaign-runtime/agent-deviations.jsonl",
   ".campaign-runtime/workflow-findings.jsonl",
   ".campaign-runtime/run-records/",
+  // 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/",
@@ -47,7 +51,7 @@ export const RUNTIME_STATE_IGNORED_PATHS = [
 // must gain it on the next setup command rather than on the next accidental
 // commit. An entry an operator has placed anywhere else in the file counts as
 // present.
-export const RUNTIME_STATE_REQUIRED_IGNORED_PATHS = ["qa-output/", ".campaign-runtime/progress/"];
+export const RUNTIME_STATE_REQUIRED_IGNORED_PATHS = ["qa-output/", ".campaign-runtime/progress/", ".campaign-runtime/funnels/*/run-records/"];
 
 export const RUNTIME_STATE_IGNORE_BLOCK = [
   RUNTIME_STATE_IGNORE_MARKER,

package/src/sdk-storage-compatibility.mjs

@@ -7,6 +7,7 @@ import { readFileSync, lstatSync, realpathSync, statSync } from 'node:fs';
 import { resolve, relative, dirname, posix, sep } from 'node:path';
 import { createHash } from 'node:crypto';
 import { isUtf8 } from 'node:buffer';
+import { singleLineFragment } from './text-safety.mjs';
 const digest = value => createHash('sha256').update(value).digest('hex');
 const version = value => {
   if (typeof value !== 'string' || !/^\d+\.\d+\.\d+$/.test(value))
@@ -361,6 +362,19 @@ function frontmatterScripts(text) {
   // linePos is 1-based within the YAML block, which starts on the file's line 2.
   return { scripts: scripts.items.map(item => ({ value: item.value, line: lineCounter.linePos(item.range[0]).line + 1 })) };
 }
+const INVENTORY_MAX_BYTES = 256 * 1024 * 1024;
+const INVENTORY_DETAIL_MAX = 200;
+
+// A missing git already fails at rev-parse, above the inventory.
+export function inventoryFailure(error) {
+  if (error.code === 'ENOBUFS') return `the tracked-file list under --scope is larger than ${INVENTORY_MAX_BYTES / 1024 / 1024} MiB; narrow --scope.`;
+  const stderr = typeof error.stderr === 'string' ? error.stderr : error.stderr?.toString() ?? '';
+  const detail = singleLineFragment(stderr.trim().split('\n')[0], `git exited ${error.status ?? error.signal ?? error.code ?? 'abnormally'} with no message`);
+  const chars = Array.from(detail);
+  const bounded = chars.length > INVENTORY_DETAIL_MAX ? `${chars.slice(0, INVENTORY_DETAIL_MAX).join('')}…` : detail;
+  return `${bounded.replace(/\.$/, '')}.`;
+}
+
 export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVersion, manifestPath, scope, exclude = [] }) {
   version(targetSdkVersion);
   if (!Array.isArray(scope) || !scope.length)
@@ -375,9 +389,14 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
   if (rootIdentity.dev !== targetIdentity.dev || rootIdentity.ino !== targetIdentity.ino)
     throw new Error('--target must be the Git repository root.');
   const { value: manifest, evidence } = readStorageManifest(manifestPath);
+  // Inventory only the scope: a whole-repository list can pass Node's 1 MiB
+  // default buffer on a large repository (#717). Scopes are literal paths.
   let tracked;
-  try { tracked = execFileSync('git', ['-C', root, 'ls-files', '-z'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).split('\0').filter(Boolean); }
-  catch { throw new Error('Cannot inventory tracked Git source files.'); }
+  try {
+    tracked = execFileSync('git', ['--literal-pathspecs', '-C', root, 'ls-files', '-z', '--', ...scope], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: INVENTORY_MAX_BYTES }).split('\0').filter(Boolean);
+  } catch (error) {
+    throw new Error(`Cannot inventory tracked Git source files: ${inventoryFailure(error)}`);
+  }
   for (const item of scope)
     if (!tracked.some(p => inside(p, item)))
       throw new Error(`Scope has no tracked files: ${item}`);

package/src/source-html-intake.mjs

@@ -559,6 +559,20 @@ function addSpecHints(mapping, page) {
   if (variantLabels) mapping.variant_labels = variantLabels;
 }
 
+/**
+ * The page-kit projection of every page in `specPages` (a Map of page id to
+ * projection), as intake projects a mapped page: target path, public route,
+ * page_type and the frontmatter links to the other pages. `record spec`
+ * re-projects with it when routes move or, after handoff, when pages are
+ * added or removed (#531, #721); every page is re-projected because a page's
+ * next_url and decline_url read the routes of the pages it links to.
+ */
+export function projectPageKitTargets({ specPages = [], publicRouteSlug, outputDir }) {
+  const pages = Array.isArray(specPages) ? specPages : [];
+  const pageById = new Map(pages.map((page) => [page.id, page]));
+  return new Map(pages.map((page) => [page.id, pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir, specPages: pages })]));
+}
+
 function pageKitProjectionForPage(page, { pageById, publicRouteSlug, outputDir, specPages = [] }) {
   const specRoute = publicRouteForPage(page);
   const relativeRoute = stripPublicRoutePrefix(specRoute, publicRouteSlug);
@@ -707,7 +721,7 @@ function normalizeRootedRoute(value) {
   return normalized ? `/${normalized}` : "/";
 }
 
-function cpkPageTypeForSpecType(type) {
+export function cpkPageTypeForSpecType(type) {
   if (type === "presell" || type === "landing") return "product";
   if (type === "thankyou" || type === "receipt") return "receipt";
   if (type === "upsell" || type === "downsell") return "upsell";