@nextcommerce/campaigns-os 1.59.0 → 1.61.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,7 @@ 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";
 
 export const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
 export const MAX_GIT_METADATA_BYTES = 64 * 1024;
@@ -942,7 +945,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 +1287,36 @@ 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"}`);
+  }
+  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 +1577,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 +1590,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 +1636,15 @@ 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.
+ * 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 +1662,9 @@ 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");
+  if ([evidenceDebt?.polish, evidenceDebt?.qa].some((stage) => stage?.status === "owed")) 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 +1699,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 +1718,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),
   };
 }
 
@@ -1853,7 +1896,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 +1928,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 +1936,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 +2030,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/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;

package/src/sdk-storage-compatibility.mjs

@@ -49,6 +49,9 @@ function normalizeScope(value) {
     throw new Error('Scope and exclusions must be literal repository-relative files or directories.');
   return value.replace(/^\.\//, '').replace(/\/$/, '') || '.';
 }
+const PREFIX_SCAN_REASONS = new Set(['dynamic-key', 'unsupported-storage-method', 'storage-object-escape']);
+const LOOPS = new Set(['ForStatement', 'ForInStatement', 'ForOfStatement', 'WhileStatement', 'DoWhileStatement']);
+const ITERATION_METHODS = new Set(['forEach', 'filter', 'map', 'flatMap', 'find', 'findIndex', 'some', 'every', 'reduce']);
 const inside = (path, scope) => scope === '.' || path === scope || path.startsWith(scope + '/');
 export function readStorageManifest(path) {
   const bytes = readFileSync(path);
@@ -219,7 +222,72 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
       else
         reason = 'literal-unaffected-key';
     }
-    emit(node, { operation, area: storage.name, key, status, reason, replacement });
+    const prefixScan = status === 'unknown' && !storage.shadowed && PREFIX_SCAN_REASONS.has(reason) ? sdkPrefixScan(storage.name, node) : null;
+    emit(node, { operation, area: storage.name, key, status, reason, replacement, ...(prefixScan && { prefixScan }) });
+  }
+  // A loop that matches storage keys by a scoped SDK key's prefix: its key()/getItem(k) lines stay unknown, but are named.
+  // A prefix test counts only when it tests a key the loop read from storage itself: a `k = storage.key(i)` binding,
+  // a for-of/for-in variable over `Object.keys(storage)` or `storage`, or the element parameter of an array callback
+  // chained on `Object.keys(storage)`. A line is named only when it is that key's source or reads that key.
+  // Names are matched within the loop, not resolved through scopes; it is a hint only.
+  const stack = [];
+  const prefixCache = new WeakMap();
+  const callName = call => call?.type === 'CallExpression' && call.callee.type === 'MemberExpression' ? (call.callee.computed ? literal(call.callee.property, scopes.get(call)) : call.callee.property.name) : null;
+  const keysOf = node => node?.type === 'CallExpression' && node.callee.type === 'MemberExpression' && node.callee.object.type === 'Identifier' && node.callee.object.name === 'Object' && callName(node) === 'keys' ? node.arguments[0] : null;
+  function keySource(node) {
+    // Object.keys(storage).filter(...).forEach(...): the chain bottoms out at Object.keys.
+    while (node?.type === 'CallExpression' && ITERATION_METHODS.has(callName(node)))
+      node = node.callee.object;
+    return keysOf(node);
+  }
+  function prefixTests(loop) {
+    if (prefixCache.has(loop)) return prefixCache.get(loop);
+    const keys = new Map(), sources = new Map(), tests = [];
+    // source: the storage reference the key came from (the key() call, or the storage in Object.keys(storage) / for-in).
+    const bind = (id, storageNode, source = storageNode) => {
+      const storage = storageNode && area(storageNode, scopes.get(storageNode));
+      if (id?.type !== 'Identifier' || !storage) return;
+      keys.set(id.name, storage.name);
+      sources.set(source, id.name);
+    };
+    const loopVariable = left => left?.type === 'VariableDeclaration' ? left.declarations[0]?.id : left;
+    (function walk(n) {
+      if (n.type === 'VariableDeclarator' && callName(n.init) === 'key')
+        bind(n.id, n.init.callee.object, n.init);
+      if (n.type === 'AssignmentExpression' && n.operator === '=' && callName(n.right) === 'key')
+        bind(n.left, n.right.callee.object, n.right);
+      if (n.type === 'ForOfStatement')
+        bind(loopVariable(n.left), keysOf(n.right));
+      if (n.type === 'ForInStatement')
+        bind(loopVariable(n.left), n.right);
+      if (n.type === 'CallExpression' && ITERATION_METHODS.has(callName(n)) && ['ArrowFunctionExpression', 'FunctionExpression'].includes(n.arguments[0]?.type))
+        bind(n.arguments[0].params[callName(n) === 'reduce' ? 1 : 0], keySource(n.callee.object));
+      if (callName(n) === 'startsWith')
+        tests.push({ receiver: n.callee.object, prefix: literal(n.arguments[0], scopes.get(n)) });
+      if (n.type === 'BinaryExpression' && ['===', '==', '!==', '!='].includes(n.operator))
+        for (const [call, zero] of [[n.left, n.right], [n.right, n.left]])
+          if (zero.type === 'Literal' && zero.value === 0 && callName(call) === 'indexOf' && call.arguments.length === 1)
+            tests.push({ receiver: call.callee.object, prefix: literal(call.arguments[0], scopes.get(call)) });
+      for (const child of children(n)) walk(child);
+    })(loop);
+    const prefixes = tests.filter(t => t.prefix && t.receiver.type === 'Identifier' && keys.has(t.receiver.name)).map(t => ({ name: t.receiver.name, prefix: t.prefix, area: keys.get(t.receiver.name) }));
+    const result = { prefixes, sources };
+    prefixCache.set(loop, result);
+    return result;
+  }
+  function sdkPrefixScan(storageName, node) {
+    // The key this line reads (getItem(k), storage[k]), if it is a plain name.
+    const argument = node.type === 'CallExpression' ? node.arguments[0] : node.type === 'MemberExpression' && node.computed ? node.property : null;
+    // Nearest matching loop wins; a loop that does not test this line's key passes to the one around it.
+    for (const loop of [...stack].reverse()) {
+      if (!LOOPS.has(loop.type) && !(loop.type === 'CallExpression' && ITERATION_METHODS.has(callName(loop)))) continue;
+      const { prefixes, sources } = prefixTests(loop);
+      const names = [sources.get(node), argument?.type === 'Identifier' ? argument.name : null];
+      const tested = prefixes.filter(t => t.area === storageName && names.includes(t.name)).map(t => t.prefix);
+      const entry = manifest.keys.find(e => e.scoped && e.areas.includes(storageName) && e.key.split('{')[0] && tested.includes(e.key.split('{')[0]));
+      if (entry) return { prefix: entry.key.split('{')[0], key: entry.key, replacement: entry.replacement ?? null };
+    }
+    return null;
   }
   const handled = new WeakSet();
   const aliasInitialization = (node, parent) => parent?.type === 'VariableDeclarator' && parent.init === node && parent.id.type === 'Identifier' && binding(parent.id.name, scopes.get(parent))?.init === node;
@@ -229,6 +297,7 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
     (['LabeledStatement', 'BreakStatement', 'ContinueStatement'].includes(parent?.type) && parent.label === node)
   );
   function visit(node, parent) {
+    stack.push(node);
     const scope = scopes.get(node);
     if (node.type === 'CallExpression' && node.callee.type === 'MemberExpression') {
       const member = node.callee, storage = area(member.object, scope), method = member.computed ? literal(member.property, scope) : member.property.name;
@@ -258,6 +327,7 @@ export function analyzeStorageJavaScript(source, { path = '<source>', lineOffset
     }
     for (const child of children(node))
       visit(child, node);
+    stack.pop();
   }
   visit(ast, null);
   return findings;
@@ -314,7 +384,8 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
   const selected = tracked.filter(p => /\.(?:html?|[cm]?js)$/i.test(p) && scope.some(s => inside(p, s)) && !exclude.some(s => inside(p, s))).sort();
   const files = [], findings = [];
   const unknown = (path, reason, detail, line = 1) => findings.push({ path, line, column: 1, operation: 'unknown', area: null, key: null, status: 'unknown', reason, detail, replacement: null });
-  if (compare(targetSdkVersion, manifest.supportedSdkVersions.min) < 0 || compare(targetSdkVersion, manifest.supportedSdkVersions.max) > 0)
+  const targetCovered = compare(targetSdkVersion, manifest.supportedSdkVersions.min) >= 0 && compare(targetSdkVersion, manifest.supportedSdkVersions.max) <= 0;
+  if (!targetCovered)
     unknown(evidence.path, 'target-outside-manifest-range', targetSdkVersion);
   if (!selected.length)
     unknown('.', 'empty-source-scope', 'No tracked HTML or JavaScript files selected.');
@@ -412,9 +483,28 @@ export function scanSdkStorageCompatibility({ cwd = process.cwd(), targetSdkVers
     html(document);
   }
   const status = findings.some(f => f.status === 'incompatible') ? 'incompatible' : findings.some(f => f.status === 'unknown') ? 'unknown' : 'source-compatible';
-  return { schemaVersion: 1, targetSdkVersion, manifest: evidence, scope, exclude, files, findings, status, evidenceBoundary: 'Static tracked source compatibility only; no browser, order, or analytics proof.' };
+  return { schemaVersion: 1, targetSdkVersion, targetCovered, manifest: evidence, scope, exclude, files, findings, status, evidenceBoundary: 'Static tracked source compatibility only; no browser, order, or analytics proof.' };
 }
+const sdkRange = ({ min, max }) => min === max ? min : `${min} to ${max}`;
 export function formatStorageCompatibilityReport(result) {
   const counts = status => result.findings.filter(f => f.status === status).length;
-  return [`SDK storage compatibility: ${result.status} (target ${result.targetSdkVersion})`, `${result.files.length} tracked source files; ${counts('incompatible')} incompatible, ${counts('unknown')} unknown, ${counts('unaffected')} unaffected storage accesses.`, `Manifest ${result.manifest.sha256} (${result.manifest.source.verification})`, ...result.findings.filter(f => f.status !== 'unaffected').map(f => `${f.path}:${f.line}:${f.column} ${f.status}: ${f.reason}${f.key ? ` (${f.key})` : ''}${f.detail ? ` — ${f.detail}` : ''}`), result.evidenceBoundary].join('\n');
+  const target = result.targetSdkVersion, covered = sdkRange(result.manifest.supportedSdkVersions);
+  const outside = result.targetCovered === false;
+  const header = outside
+    ? [`SDK storage compatibility: ${result.status} (checked against SDK ${covered}, not the requested target ${target})`, `The manifest (Campaign Cart ${result.manifest.sdkVersion}) declares support for SDK ${covered} only, so this report does not speak for ${target}.`]
+    : [`SDK storage compatibility: ${result.status} (target ${target})`];
+  const summary = `${result.files.length} tracked source files; ${counts('incompatible')} incompatible, ${counts('unknown')} unknown, ${counts('unaffected')} unaffected storage accesses${outside ? ` (against SDK ${covered}, not ${target})` : ''}.`;
+  const line = f => `${f.path}:${f.line}:${f.column} ${f.status}: ${f.reason}${f.key ? ` (${f.key})` : ''}${f.detail ? ` — ${f.detail}` : ''}${f.prefixScan ? ` [prefix loop: ${f.prefixScan.prefix}]` : ''}`;
+  return [...header, summary, `Manifest ${result.manifest.sha256} (${result.manifest.source.verification})`, ...result.findings.filter(f => f.status !== 'unaffected').map(line), ...prefixScanNote(result.findings), result.evidenceBoundary].join('\n');
+}
+// One note for every [prefix loop] line, so a reader can tell them from unknowns with no known shape.
+function prefixScanNote(findings) {
+  const scans = findings.filter(f => f.prefixScan);
+  if (!scans.length) return [];
+  const prefixes = [...new Set(scans.map(f => f.prefixScan.prefix))];
+  const replacements = [...new Map(scans.filter(f => f.prefixScan.replacement).map(f => [f.prefixScan.prefix, f.prefixScan.replacement])).entries()];
+  return [
+    `${scans.length} unknown ${scans.length === 1 ? 'line is' : 'lines are'} [prefix loop]: a loop that matches storage keys starting with ${prefixes.join(', ')}. Such a loop finds the SDK key with or without its scope suffix, so the scoping rename alone does not break it. It stays unknown because on an origin shared with another campaign, or another top folder of this one, the same prefix also matches that copy; check which key the loop takes.`,
+    ...replacements.map(([prefix, r]) => `For ${prefix}, the manifest names the public ${r.export} export instead (${r.guide}).`),
+  ];
 }

package/src/source-html-manifest.mjs

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { normalizeDesignFileReference } from "./design-file-reference.mjs";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { resolve } from "node:path";
 
@@ -165,6 +166,12 @@ function validateManifestPage(entry, index, add, addWarning = () => {}) {
     }
   }
   warnOnUnusableScreenshotRecords(entry, location, addWarning);
+  if (Object.hasOwn(entry, "design_file")) {
+    const { declaration, warnings } = normalizeDesignFileReference(entry.design_file);
+    for (const detail of warnings) {
+      addWarning(`${location}.design_file`, `${location}.design_file (page_id ${JSON.stringify(entry.page_id)}) ${declaration ? "has an ignored frame" : "is ignored as a design-file declaration"}: ${detail}. The rest of the manifest is used as written.`);
+    }
+  }
 }
 
 // Screenshot records are optional proof, so a malformed one is not a reason to

package/src/source-html-server.mjs

@@ -0,0 +1,129 @@
+import { createServer } from "node:http";
+import { constants, openSync, fstatSync, readSync, closeSync, realpathSync, lstatSync } from "node:fs";
+import { realpath, stat, lstat, open } from "node:fs/promises";
+import { resolve, relative, isAbsolute, extname } from "node:path";
+import { VISUAL_MAX_REFERENCE_BYTES } from "./png-header.mjs";
+
+// Declared inputs (packet, manifest and campaign files) are opened without
+// blocking and read only when the opened descriptor is a regular file within
+// `maxBytes`: a FIFO, socket, device or directory is refused before any read,
+// so no declared path can hold the event loop ahead of a deadline.
+// With a `root`, the path is opened first and only then resolved: the
+// descriptor must be the very file (dev and ino) the contained realpath names,
+// so a path replaced between the open and the check is refused, never read.
+// `noFollow` also refuses a final component that is a link.
+export const DECLARED_INPUT_MAX_BYTES = VISUAL_MAX_REFERENCE_BYTES;
+const READ_FLAGS = constants.O_RDONLY | (constants.O_NONBLOCK ?? 0);
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const refusal = (code) => Object.assign(new Error(code), { code });
+const inside = (root, path) => { const rel = relative(root, path); return !isAbsolute(rel) && rel !== ".." && !rel.startsWith("../"); };
+// The resolved target is read with lstat: a final component swapped for a link
+// after resolution is that link's own inode, which no opened file matches.
+const sameFile = (info, target) => !target.isSymbolicLink() && info.dev === target.dev && info.ino === target.ino;
+export function readRegularFileSync(path, { maxBytes = DECLARED_INPUT_MAX_BYTES, statOnly = false, root = null, noFollow = false } = {}) {
+  const fd = openSync(path, READ_FLAGS | (noFollow ? NO_FOLLOW : 0));
+  try {
+    const info = fstatSync(fd);
+    if (!info.isFile()) throw refusal("not_regular_file");
+    if (root !== null) {
+      const resolved = realpathSync(path);
+      if (!inside(realpathSync(root), resolved) || !sameFile(info, lstatSync(resolved))) throw refusal("outside_root");
+    }
+    if (info.size > maxBytes) throw refusal("too_large");
+    if (statOnly) return null;
+    const chunks = [];
+    let length = 0;
+    while (length <= maxBytes) {
+      const chunk = Buffer.alloc(Math.min(65536, maxBytes + 1 - length));
+      const n = readSync(fd, chunk, 0, chunk.length, null);
+      if (!n) break;
+      chunks.push(chunk.subarray(0, n)); length += n;
+    }
+    if (length > maxBytes) throw refusal("too_large");
+    return Buffer.concat(chunks, length);
+  } finally { closeSync(fd); }
+}
+// Whether a read of `path` would reach its bytes; the size is not judged here.
+export const isRegularFileSync = (path, { root = null } = {}) => {
+  try { readRegularFileSync(path, { statOnly: true, maxBytes: Infinity, root }); return true; } catch { return false; }
+};
+// The server's read: open, fstat, then resolve and match the descriptor against
+// the contained target. Returns the resolved path (for the type) and the bytes.
+async function readContainedFile(base, path, { maxBytes, statOnly }) {
+  const handle = await open(path, READ_FLAGS);
+  try {
+    const info = await handle.stat();
+    if (!info.isFile() || info.size > maxBytes) throw refusal("not_served");
+    const resolved = await realpath(path);
+    if (!inside(base, resolved) || !sameFile(info, await lstat(resolved))) throw refusal("not_served");
+    if (statOnly) return { resolved, bytes: null };
+    const chunks = [];
+    let length = 0;
+    while (length <= maxBytes) {
+      const { bytesRead, buffer } = await handle.read(Buffer.alloc(Math.min(65536, maxBytes + 1 - length)));
+      if (!bytesRead) break;
+      chunks.push(buffer.subarray(0, bytesRead)); length += bytesRead;
+    }
+    if (length > maxBytes) throw refusal("not_served");
+    return { resolved, bytes: Buffer.concat(chunks, length) };
+  } finally { await handle.close(); }
+}
+
+const TYPES = Object.freeze({ ".html": "text/html; charset=utf-8", ".css": "text/css", ".js": "text/javascript",
+  ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif", ".svg": "image/svg+xml",
+  ".webp": "image/webp", ".avif": "image/avif", ".woff": "font/woff", ".woff2": "font/woff2", ".ttf": "font/ttf",
+  ".ico": "image/x-icon", ".json": "application/json" });
+// This listener is also the sealed browser's refusing proxy. There is no
+// outbound client: even absolute-form requests to our own origin are refused.
+export async function startSourceHtmlServer({ root, signal, maxBytes = DECLARED_INPUT_MAX_BYTES } = {}) {
+  const base = await realpath(root);
+  if (!(await stat(base)).isDirectory()) throw new Error("source_root_unavailable");
+  if (signal?.aborted) throw signal.reason;
+  const refusals = new Map();
+  let totalRefusals = 0;
+  const record = (target, connect = false) => {
+    totalRefusals++;
+    try {
+      const origin = new URL(connect ? `https://${target}` : target).origin;
+      if (refusals.has(origin) || refusals.size < 32) refusals.set(origin, (refusals.get(origin) || 0) + 1);
+    } catch { /* never persist a malformed target */ }
+  };
+  const server = createServer(async (req, res) => {
+    res.setHeader("cache-control", "no-store");
+    const end = (code) => { res.statusCode = code; res.end(); };
+    if (!req.url.startsWith("/") || req.url.startsWith("//")) { record(req.url); return end(403); }
+    if (!["GET", "HEAD"].includes(req.method)) return end(405);
+    try {
+      const pathname = decodeURIComponent(req.url.split("?")[0]);
+      if (pathname.includes("\0") || pathname.includes("\\")) return end(404);
+      const { resolved, bytes } = await readContainedFile(base, resolve(base, `.${pathname}`), { maxBytes, statOnly: req.method === "HEAD" });
+      res.setHeader("content-type", TYPES[extname(resolved).toLowerCase()] || "application/octet-stream");
+      res.statusCode = 200;
+      res.end(bytes);
+    } catch { end(404); }
+  });
+  server.on("connect", (req, socket) => {
+    record(req.url, true);
+    socket.end("HTTP/1.1 403 Forbidden\r\nCache-Control: no-store\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+  });
+  server.on("upgrade", (req, socket) => {
+    record(req.url);
+    socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n");
+  });
+  server.requestTimeout = 5_000;
+  server.headersTimeout = 5_000;
+  const sockets = new Set();
+  server.on("connection", (socket) => { sockets.add(socket); socket.on("close", () => sockets.delete(socket)); });
+  await new Promise((done, reject) => { server.once("error", reject); server.listen(0, "127.0.0.1", done); });
+  let closing;
+  const close = () => closing ||= new Promise((done, reject) => {
+    server.close((error) => error ? reject(error) : done());
+    for (const socket of sockets) socket.destroy();
+  });
+  signal?.addEventListener("abort", () => { void close().catch(() => {}); }, { once: true });
+  if (signal?.aborted) { await close(); throw signal.reason; }
+  const port = server.address().port;
+  return { origin: `http://127.0.0.1:${port}`, port,
+    refusedTotal: () => totalRefusals,
+    refused: () => [...refusals].sort(([a], [b]) => a.localeCompare(b)).map(([origin, count]) => ({ origin, count })), close };
+}