@nextcommerce/campaigns-os 1.60.0 → 1.62.0

package/src/readback.mjs

@@ -10,7 +10,9 @@
  * usually subdirectories of their enclosing campaign repository — to locate the
  * Git directory, and that directory's `logs/HEAD` reflog), plus the CampaignSpec
  * and normalized Campaign Build Brief the Build Packet names, whose current
- * content decides each stage's effective status. It writes nothing,
+ * content decides each stage's effective status. It also hashes built output
+ * and maps file drift against the recorded assembly manifest to evidence debt.
+ * It writes nothing,
  * starts no process, and touches no network. That contract is why the CLI
  * exempts `readback` from lifecycle-journal capture the way it exempts doctor
  * inspection: a command declared read-only must not append a journal entry.
@@ -53,6 +55,9 @@ 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;
@@ -190,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",
@@ -218,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.
@@ -942,7 +951,7 @@ function renderStaleness(staleness, lines) {
       for (const key of staleness.stale_keys) {
         lines.push(`    ${ARTIFACT_TITLES[key]} (generated ${formatUtc(staleness.artifacts[key].generated_at)})`);
       }
-      lines.push("  Every section below describes the repository as it was when the artifacts");
+      lines.push("  Recorded artifact sections describe the repository as it was when the artifacts");
       lines.push("  were generated, not necessarily as it is now; a new run must regenerate");
       lines.push("  them before this view is current.");
     } else {
@@ -1284,6 +1293,43 @@ export function readbackInputs(views) {
   return currentPacketInputs({ packet, packetPath: resolve(views.packet.path) });
 }
 
+function readbackEvidenceDebt(views) {
+  return assessEvidenceDebt({
+    packet: artifactData(views, "packet"),
+    packetPath: views.packet?.path,
+    report: artifactData(views, "report"),
+  });
+}
+
+function renderEvidenceDebt(debt, lines) {
+  lines.push("EVIDENCE DEBT  [the readback's own projection layer: recorded build bindings versus built output]");
+  for (const name of ["polish", "qa"]) {
+    const stage = debt[name];
+    const explanation = stage.status === "current" ? "recorded build matches the current build"
+      : stage.status === "owed" ? "evidence is owed for the current build"
+        : `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})` : ""}`);
+  lines.push(`    recorded: ${changes.recorded_build_fingerprint ?? "unknown"}; current: ${changes.current_build_fingerprint ?? "unknown"}`);
+  for (const page of changes.changed_pages) lines.push(`    changed page: ${oneLine(page.page_id)} (${oneLine(page.built_path)})`);
+  for (const path of changes.unmapped_files) lines.push(`    unmapped file: ${oneLine(path)}`);
+  for (const kind of ["extra", "missing", "changed"]) {
+    if (changes[kind].length) lines.push(`    ${kind} files: ${changes[kind].map(oneLine).join(", ")}`);
+  }
+  if (changes.status === "known" && !changes.changed_pages.length && !changes.unmapped_files.length) lines.push("    no files differ from the recorded assembly manifest");
+  lines.push("  Page changes use the assembly baseline; older stage manifests are not reconstructed.", "");
+}
+
 // Superseded records shown per stage, newest last (the report keeps five).
 const HISTORY_RENDER_CAP = 5;
 
@@ -1544,7 +1590,7 @@ function renderFindings(views, lines) {
  * `inputs` is readbackInputs(views); when omitted, every input reads as not
  * readable, so a build, Polish or QA record reads unknown.
  */
-export function projectReadback(views, staleness = null, packetSelection = null, inputs = null) {
+export function projectReadback(views, staleness = null, packetSelection = null, inputs = null, evidenceDebt = assessEvidenceDebt()) {
   const lines = [
     "CAMPAIGNS OS RUN-ARTIFACT READBACK",
     "A read-only projection of this run's emitted artifacts. Campaigns OS",
@@ -1557,6 +1603,7 @@ export function projectReadback(views, staleness = null, packetSelection = null,
   renderArtifactTable(views, lines, packetSelection);
   renderIdentity(views, lines);
   renderStages(views, lines, inputs);
+  renderEvidenceDebt(evidenceDebt, lines);
   renderContext(views, lines);
   renderDoctor(views, lines);
   renderVerdict(views, lines);
@@ -1602,13 +1649,16 @@ export function serializeStaleness(staleness) {
 /**
  * Whether this projection shows nothing the readback can call wrong.
  *
- * True only when all five conditions hold: every artifact the readback found is
+ * True only when all six conditions hold: every artifact the readback found is
  * loaded and recognized (absent artifacts are not counted against it — a run
  * that emitted no findings export is not thereby unclean, while an unreadable
  * 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.
+ * 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.
  *
  * The fourth of those is the unknown-age rule: an artifact whose recorded age
  * did not parse was never shown to be current, and `clean` states that the
@@ -1626,7 +1676,10 @@ export function serializeStaleness(staleness) {
  * OS recorded. docs/readback.md states the rule and its limits for callers
  * gating on it.
  */
-export function computeClean(views, staleness) {
+export function computeClean(views, staleness, evidenceDebt) {
+  if (evidenceDebt == null) throw new TypeError("computeClean requires an evidence-debt assessment");
+  // 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;
@@ -1661,8 +1714,12 @@ function artifactRowDetail(view, staleness) {
  *
  * `packet_selection` and `staleness` are `null` when a programmatic caller
  * builds a payload without them; the CLI always supplies both.
+ * `evidenceDebt` is projectTarget's or projectExample's assessment. The default
+ * calls assessEvidenceDebt with no packet inputs, which returns unknown with
+ * packet_unavailable before any filesystem access. Callers with loaded packet
+ * data must supply their computed assessment; this serializer never hashes files.
  */
-export function buildJsonPayload(views, staleness = null, packetSelection = null) {
+export function buildJsonPayload(views, staleness = null, packetSelection = null, evidenceDebt = assessEvidenceDebt()) {
   return {
     schema_version: JSON_SCHEMA_VERSION,
     artifacts: Object.values(views).map((view) => ({
@@ -1676,7 +1733,8 @@ export function buildJsonPayload(views, staleness = null, packetSelection = null
     doctor: computeDoctorSummary(views),
     skip_cascades: computeSkipCascades(views),
     divergences: computeDivergences(views),
-    clean: computeClean(views, staleness),
+    evidence_debt: evidenceDebt,
+    clean: computeClean(views, staleness, evidenceDebt),
   };
 }
 
@@ -1792,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) => {
@@ -1826,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;
@@ -1853,7 +1944,7 @@ export function resolvePaths(root, overrides = {}) {
 export function projectTarget(root, overrides = {}) {
   const { paths, packetSelection, packetView } = resolveProjection(root, overrides);
   const views = loadArtifacts(paths, { packet: packetView });
-  return { views, staleness: assessStaleness(root, views), packetSelection, inputs: readbackInputs(views) };
+  return { views, staleness: assessStaleness(root, views), packetSelection, inputs: readbackInputs(views), evidenceDebt: readbackEvidenceDebt(views) };
 }
 
 // The bundled synthetic sample `--example` projects. It is already on the
@@ -1885,6 +1976,7 @@ export function projectExample() {
   const { paths, packetSelection, packetView } = resolveProjection(EXAMPLE_ROOT, {});
   const views = loadArtifacts(paths, { packet: packetView });
   const inputs = readbackInputs(views);
+  const evidenceDebt = readbackEvidenceDebt(views);
   for (const view of Object.values(views)) {
     const within = view.path.slice(EXAMPLE_ROOT.length).replace(/\\/g, "/").replace(/^\/+/, "");
     view.path = `${EXAMPLE_RELATIVE_ROOT}/${within}`;
@@ -1892,7 +1984,7 @@ export function projectExample() {
   const staleness = assessStaleness(EXAMPLE_ROOT, views, {
     headMovement: { time: null, detail: EXAMPLE_HEAD_DETAIL },
   });
-  return { views, staleness, packetSelection, inputs };
+  return { views, staleness, packetSelection, inputs, evidenceDebt };
 }
 
 const OVERRIDE_FLAGS = {
@@ -1986,9 +2078,9 @@ export function runReadbackCommand(args) {
     if (error instanceof ReadbackUsageError) return { exitCode: 2, text: `${error.message}\n` };
     throw error;
   }
-  const { views, staleness, packetSelection, inputs } = projection;
+  const { views, staleness, packetSelection, inputs, evidenceDebt } = projection;
   const text = request.json
-    ? `${JSON.stringify(buildJsonPayload(views, staleness, packetSelection), null, 2)}\n`
-    : projectReadback(views, staleness, packetSelection, inputs);
+    ? `${JSON.stringify(buildJsonPayload(views, staleness, packetSelection, evidenceDebt), null, 2)}\n`
+    : projectReadback(views, staleness, packetSelection, inputs, evidenceDebt);
   return { exitCode: 0, text };
 }

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-attribute-index.mjs

@@ -2,10 +2,10 @@
 // checks (#303).
 //
 // Source: the SDK's own source in NextCommerceCo/campaign-cart at tag
-// v0.4.42 (the SDK pin every certified starter family ships today): every
-// data-next-* name the SDK's non-test TypeScript names as a string, plus every
-// `dataset.next*` property it reads or writes, turned back into its
-// attribute. Only the data-next-* names are kept: the checks that read this
+// v0.4.43; the certified starter families and the SDK support policy still
+// name 0.4.42, whose names are the same: every data-next-* name the SDK's non-test TypeScript names as a
+// string, plus every `dataset.next*` property it reads or writes, turned back
+// into its attribute. Only the data-next-* names are kept: the checks that read this
 // list ask "does the SDK read this data-next-* attribute at all", and the
 // SDK's other attribute families (data-item-*, data-package-*, plain data-*)
 // are not what an agent kit misspells.
@@ -15,8 +15,8 @@
 // whole from the source at a named tag, never edited by hand.
 //
 //   paths=('src/**/*.ts' ':!src/**/*.test.ts' ':!src/**/tests/**' ':!src/docs/**')
-//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.42 -- "${paths[@]}"
-//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.42 -- "${paths[@]}" \
+//   { git -C ../campaign-cart grep -h -oP 'data-next-[a-z0-9]+(?:-[a-z0-9]+)*-?' v0.4.43 -- "${paths[@]}"
+//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.43 -- "${paths[@]}" \
 //       | sed 's/^dataset\.//' | perl -pe 's/([A-Z])/-\L$1/g; s/^/data-/'
 //   } | sort -u
 //
@@ -31,14 +31,14 @@
 // data-next-bump-section, data-next-button-text, the variant option state).
 // At v0.4.41 it returns every name of the v0.4.38 list this replaces, plus
 // those and data-next-phone-e164 / data-next-phone-country. At v0.4.42 it
-// returns the same 149 names as at v0.4.41.
+// returns the same 149 names as at v0.4.41, and at v0.4.43 the same again.
 //
 // A name ending in "-" (data-next-class-) is a prefix the SDK reads with any
 // suffix.
 
 import { RELEASED_SDK_VERSION_PATTERN } from "../campaign-spec/dist/index.js";
 
-export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.42";
+export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.43";
 
 export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion",
@@ -365,8 +365,8 @@ export const SDK_TEMPLATE_PLACEHOLDERS = Object.freeze({
 });
 
 // The SDK versions whose renderer files above were verified unchanged from
-// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40, v0.4.41 and v0.4.42, for
-// the eight renderer files cited above plus cart-item-list.enhancer.ts and
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40, v0.4.41, v0.4.42 and
+// v0.4.43, for the eight renderer files cited above plus cart-item-list.enhancer.ts and
 // order-item-list.enhancer.ts). A page whose loader pins another version
 // cannot pass the placeholder check.
-export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41", "0.4.42"]);
+export const SDK_TEMPLATE_PLACEHOLDERS_VERIFIED_PINS = Object.freeze(["0.4.38", "0.4.39", "0.4.40", "0.4.41", "0.4.42", "0.4.43"]);

package/src/sdk-markup.mjs

@@ -45,6 +45,18 @@
 //   TEMPLATE_DOUBLE_BRACE      `{{` inside an SDK-owned <template>. SDK tokens
 //                              are single-brace and conditions are no-brace;
 //                              a double brace renders literally.
+//   PAGE_TYPE_ATTRIBUTE        data-next-page-type on a page with no
+//                              <meta name="next-page-type"> (campaigns-os#683).
+//                              The SDK never reads the attribute. The meta tag
+//                              is the source every reader uses; a
+//                              window.nextConfig.pageType reaches the config
+//                              store only, not the upsell page view, so it
+//                              does not stand in for the meta here.
+//   UPSELL_PAGE_TYPE_MISSING   a data-next-upsell container on a page whose
+//                              next-page-type meta is not "upsell". The SDK
+//                              records the upsell page view only from that meta
+//                              tag, so reports show the purchase with no upsell
+//                              view before it.
 //
 //   Not a finding: data-next-is-upsell="true" on a checkout order bump. The
 //   selected bump is a line item on the checkout order, tagged as an upsell so
@@ -91,10 +103,34 @@ export const SDK_MARKUP_CODES = Object.freeze({
   RECEIPT_ORDER_ITEMS_CART_VISIBILITY: { code: `${SDK_MARKUP}.receipt_order_items_cart_visibility`, severity: "error" },
   DOUBLE_SELECTED: { code: `${SDK_MARKUP}.double_selected`, severity: "warning" },
   TEMPLATE_DOUBLE_BRACE: { code: `${SDK_MARKUP}.template_double_brace`, severity: "warning" },
+  PAGE_TYPE_ATTRIBUTE: { code: `${SDK_MARKUP}.page_type_attribute`, severity: "warning" },
+  UPSELL_PAGE_TYPE_MISSING: { code: `${SDK_MARKUP}.upsell_page_type_missing`, severity: "warning" },
   // Unknown data-next-* names are not a finding and carry no code: they are
   // information on the gate (unknown_attributes[]) and one advisory ready line.
 });
 
+// The page types the SDK has (Campaign Cart v0.4.42 `PageType`), so a remedy
+// never proposes a value the SDK does not have.
+export const SDK_PAGE_TYPES = Object.freeze(["product", "cart", "checkout", "upsell", "receipt"]);
+// Campaign page-type names this repository already reads as one of those, and
+// only those; anything else is left for the operator to name. Sources:
+// - downsell: a post-purchase page (POST_PURCHASE_PAGE_TYPES in
+//   upsell-selector-scope.mjs); the SDK records its page view only as upsell.
+// - thank-you, thankyou, confirmation: the receipt role (normalizedPageRole in
+//   design-source-package.mjs).
+// - presell, landing, advertorial: pre-checkout pages whose SDK page type is
+//   product (PRE_CHECKOUT_PAGE_TYPES in doctor/checks.mjs; normalizedPageRole).
+export const SDK_PAGE_TYPE_ALIASES = Object.freeze({
+  downsell: "upsell",
+  "thank-you": "receipt", thankyou: "receipt", confirmation: "receipt",
+  presell: "product", landing: "product", advertorial: "product",
+});
+
+function sdkPageType(value) {
+  const key = String(value || "").trim().toLowerCase();
+  return SDK_PAGE_TYPES.includes(key) ? key : SDK_PAGE_TYPE_ALIASES[key] || null;
+}
+
 // Attributes whose value names a <template> by id. The SDK reads the template
 // they point at, so that template is SDK-owned wherever it sits.
 export const TEMPLATE_ID_ATTRIBUTES = /^data-(?:next-)?[a-z0-9-]*template-id$/;
@@ -210,9 +246,48 @@ export function scanPageMarkup({ page_id, file = null, content = "", sdk_version
   const templates = []; // { entry, sdkOwned }
   const referencedTemplateIds = new Set();
   let receiptPage = String(page_type || "").trim().toLowerCase() === "receipt";
-  walkElements(document, ({ tag, attrs: a }) => {
-    if (tag === "meta" && a.get("name")?.toLowerCase() === "next-page-type" && a.get("content")?.trim().toLowerCase() === "receipt") receiptPage = true;
+  // The page's own next-page-type meta (first one, as querySelector reads it),
+  // the first data-next-page-type element and the first upsell container.
+  let pageTypeMeta = null;
+  let pageTypeAttribute = null;
+  let upsellContainer = null;
+  walkElements(document, (entry) => {
+    const { tag, attrs: a } = entry;
+    if (tag === "meta" && a.get("name")?.trim().toLowerCase() === "next-page-type") {
+      if (a.get("content")?.trim().toLowerCase() === "receipt") receiptPage = true;
+      if (pageTypeMeta === null) pageTypeMeta = (a.get("content") || "").trim();
+    }
+    if (!pageTypeAttribute && a.has("data-next-page-type")) pageTypeAttribute = entry;
+    if (!upsellContainer && a.has("data-next-upsell")) upsellContainer = entry;
   });
+  // The meta value the remedy names: a receipt is "receipt" and an upsell
+  // offer page "upsell", whatever the attribute says; otherwise the
+  // attribute's SDK page type, or none when it has no SDK name.
+  let attributeNamesUpsell = false;
+  if (pageTypeAttribute && pageTypeMeta === null) {
+    const value = (pageTypeAttribute.attrs.get("data-next-page-type") || "").trim();
+    const fromValue = sdkPageType(value);
+    const mapped = receiptPage ? "receipt" : upsellContainer ? "upsell" : fromValue;
+    attributeNamesUpsell = mapped === "upsell";
+    const note = !mapped || !value || value.toLowerCase() === mapped
+      ? ""
+      : fromValue === mapped
+        ? ` (the SDK's name for "${value}" is "${mapped}")`
+        : ` (this page is ${receiptPage ? "a receipt" : "an upsell offer, with a data-next-upsell container"}, so its SDK page type is "${mapped}")`;
+    const remedy = mapped
+      ? `Add <meta name="next-page-type" content="${mapped}"> to the page head${note}.`
+      : `Add <meta name="next-page-type"> to the page head with the SDK page type this page is: one of ${SDK_PAGE_TYPES.join(", ")}.`;
+    findings.push(finding("PAGE_TYPE_ATTRIBUTE", page_id, where,
+      `${describe(pageTypeAttribute)} on ${where} carries data-next-page-type="${value}", which the SDK does not read, and the page has no <meta name="next-page-type">. The SDK takes the page type from that meta tag, so this page runs as the default "product" step${attributeNamesUpsell ? " and the upsell page view is never recorded" : ""}. ${remedy}`,
+      { value, suggested: mapped, element: pageTypeAttribute.tag }));
+  }
+  // One finding per root cause: skipped only when the attribute finding
+  // above already names the upsell meta.
+  if (upsellContainer && !attributeNamesUpsell && (pageTypeMeta || "").toLowerCase() !== "upsell" && !receiptPage) {
+    findings.push(finding("UPSELL_PAGE_TYPE_MISSING", page_id, where,
+      `${describe(upsellContainer)} on ${where} is an upsell offer (data-next-upsell), but the page's next-page-type meta is ${pageTypeMeta === null ? "missing" : `"${pageTypeMeta}"`}. The SDK records the upsell page view only from <meta name="next-page-type" content="upsell">, so reports show the purchase with no upsell view before it. Add that meta tag to the page head.`,
+      { meta_content: pageTypeMeta }));
+  }
 
   walkElements(document, (entry) => {
     const { tag, attrs: a, ancestors } = entry;