@nextcommerce/campaigns-os 1.53.0 → 1.55.0

package/src/run-record.mjs

@@ -14,6 +14,8 @@ import { randomBytes } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, 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";
@@ -60,6 +62,14 @@ export const RUN_RECORD_REMIT_BASE_KINDS = ["canonical", "loopback", "proxy"];
 // to refuse re-posting a verdict the portal already holds.
 export const RUN_RECORD_QA_VERDICT_PUBLISH_STATES = ["skipped", "ok", "failed"];
 export const RUN_RECORD_QA_VERDICT_PUBLISHERS = ["qa run", "qa publish"];
+export const RUN_RECORD_QA_VERDICT_PUBLISH_REASONS = ["loopback_base_url", "portal_managed_default", "consent_off", "flag_opt_out", "flag_opt_in", "default", "local_spec"];
+export const RUN_RECORD_CLOSERS = ["run_end", "qa_auto_end", "stale_sweep", "manual"];
+const RUN_RECORD_FIELDS = new Set([
+  "schema_version", "run_id", "package_version", "surface_version", "toolkit_commit", "command", "argv_shape", "created_at",
+  "consent_state", "consent_source", "remit_attempted", "remit_ok", "remit_error", "remit_endpoint", "remit_state",
+  "remit_result", "remit_base_kind", "qa_verdict_publish", "closed_by", "identity", "artifacts", "observations",
+  "surfaces", "primary_surface", "surface_confidence", "lifecycle",
+]);
 
 // Required core. Strict here; permissive about optional sub-structures (the
 // validator checks shapes, not nested artifact bodies — those are referenced
@@ -105,6 +115,12 @@ export function validateRunRecord(record) {
   if (record.schema_version != null && record.schema_version !== RUN_RECORD_SCHEMA) {
     add("record.schema_version", `Expected schema_version "${RUN_RECORD_SCHEMA}".`);
   }
+  for (const key of Object.keys(record)) {
+    if (!RUN_RECORD_FIELDS.has(key)) add(`record.${key}`, `unknown Run Record field "${key}".`);
+  }
+  if (record.closed_by !== undefined && !RUN_RECORD_CLOSERS.includes(record.closed_by)) {
+    add("record.closed_by", `closed_by must be one of: ${RUN_RECORD_CLOSERS.join(", ")}.`);
+  }
 
   if (record.argv_shape == null || !isStringArray(record.argv_shape)) {
     add("record.argv_shape", "argv_shape is required and must be an array of strings (flag names, never values).");
@@ -215,25 +231,16 @@ export function validateRunRecord(record) {
         const q = obs.qa;
         if (typeof q !== "object" || Array.isArray(q)) {
           add("record.observations.qa", "qa must be an object.");
-        } else if (q.gap_classes != null && !isStringArray(q.gap_classes)) {
-          add("record.observations.qa.gap_classes", "gap_classes must be an array of strings.");
-        }
-      }
-    }
-  }
-
-  if (record.agent_usage != null) {
-    const usage = record.agent_usage;
-    if (typeof usage !== "object" || Array.isArray(usage)) {
-      add("record.agent_usage", "agent_usage must be an object when present.");
-    } else {
-      for (const field of ["input_tokens", "output_tokens", "tool_output_tokens", "total_tokens", "elapsed_ms"]) {
-        if (usage[field] != null && (!Number.isInteger(usage[field]) || usage[field] < 0)) {
-          add(`record.agent_usage.${field}`, `${field} must be a non-negative integer when present.`);
+        } else {
+          if (q.gap_classes != null && !isStringArray(q.gap_classes)) add("record.observations.qa.gap_classes", "gap_classes must be an array of strings.");
+          if (q.verdict_run_id != null && !isNonEmptyString(q.verdict_run_id)) add("record.observations.qa.verdict_run_id", "verdict_run_id must be a non-empty string or null.");
+          if (q.build_fingerprint != null && !isNonEmptyString(q.build_fingerprint)) add("record.observations.qa.build_fingerprint", "build_fingerprint must be a non-empty string or null.");
+          if (q.stale != null && typeof q.stale !== "boolean") add("record.observations.qa.stale", "stale must be a boolean or null.");
+          for (const key of Object.keys(q)) {
+            if (!["disposition", "gap_classes", "verdict_run_id", "build_fingerprint", "stale"].includes(key)) add(`record.observations.qa.${key}`, `unknown qa observation field "${key}".`);
+          }
         }
       }
-      if (usage.model != null && typeof usage.model !== "string") add("record.agent_usage.model", "model must be a string when present.");
-      if (usage.source != null && typeof usage.source !== "string") add("record.agent_usage.source", "source must be a string when present.");
     }
   }
 
@@ -301,7 +308,10 @@ export function validateQaVerdictPublish(block) {
   if (block.published_at != null && !isNonEmptyString(block.published_at)) {
     add("record.qa_verdict_publish.published_at", "published_at must be a non-empty string or null.");
   }
-  const allowed = new Set(["verdict_run_id", "publisher", "attempted", "ok", "error", "endpoint", "state", "result", "base_kind", "published_at"]);
+  if (block.reason != null && !RUN_RECORD_QA_VERDICT_PUBLISH_REASONS.includes(block.reason)) {
+    add("record.qa_verdict_publish.reason", `reason must be one of: ${RUN_RECORD_QA_VERDICT_PUBLISH_REASONS.join(", ")} (or null).`);
+  }
+  const allowed = new Set(["verdict_run_id", "publisher", "attempted", "ok", "error", "endpoint", "state", "result", "base_kind", "published_at", "reason"]);
   for (const key of Object.keys(block)) {
     if (!allowed.has(key)) add(`record.qa_verdict_publish.${key}`, `unknown qa_verdict_publish field "${key}".`);
   }
@@ -324,6 +334,9 @@ export function validateRunRecordLifecycle(lc) {
   if (lc.duration_ms != null && typeof lc.duration_ms !== "number") add("record.lifecycle.duration_ms", "duration_ms must be a number or null.");
   if (lc.wall_clock_duration_ms != null && typeof lc.wall_clock_duration_ms !== "number") add("record.lifecycle.wall_clock_duration_ms", "wall_clock_duration_ms must be a number or null.");
   if (lc.repair_loop_count != null && !Number.isInteger(lc.repair_loop_count)) add("record.lifecycle.repair_loop_count", "repair_loop_count must be an integer or null.");
+  for (const field of ["needs_input_count", "failure_count"]) {
+    if (lc[field] !== undefined && (!Number.isInteger(lc[field]) || lc[field] < 0)) add(`record.lifecycle.${field}`, `${field} must be a non-negative integer.`);
+  }
   if (lc.stages != null) {
     if (!Array.isArray(lc.stages)) {
       add("record.lifecycle.stages", "stages must be an array when present.");
@@ -334,6 +347,8 @@ export function validateRunRecordLifecycle(lc) {
         } else {
           if (stage.duration_ms != null && typeof stage.duration_ms !== "number") add(`record.lifecycle.stages[${index}].duration_ms`, "stage duration_ms must be a number or null.");
           if (stage.exit_status != null && !Number.isInteger(stage.exit_status)) add(`record.lifecycle.stages[${index}].exit_status`, "stage exit_status must be an integer or null.");
+          if (stage.wait_ms != null && (!Number.isInteger(stage.wait_ms) || stage.wait_ms < 0)) add(`record.lifecycle.stages[${index}].wait_ms`, "stage wait_ms must be a non-negative integer or null.");
+          if (stage.finding_codes !== undefined && (!isStringArray(stage.finding_codes) || stage.finding_codes.length > 5 || new Set(stage.finding_codes).size !== stage.finding_codes.length || !Number.isInteger(stage.exit_status) || stage.exit_status === 0)) add(`record.lifecycle.stages[${index}].finding_codes`, "finding_codes must have at most five distinct strings and require a non-zero exit_status.");
         }
       });
     }
@@ -395,8 +410,14 @@ function extractSpecValidationRuleIds(doctor) {
   return [...new Set(ids)];
 }
 
-function extractQaObservations(verdict) {
+function extractQaObservations(verdict, report) {
   if (!verdict || typeof verdict !== "object") return null;
+  const verdictRunId = isNonEmptyString(verdict.run_id) ? verdict.run_id : null;
+  // The verdict owns the disposition. The report owns QA's build stamp, so
+  // only bind the two when its QA stage names this exact verdict.
+  const sameVerdict = verdictRunId !== null && report?.stages?.qa?.verdict_run_id === verdictRunId;
+  const recorded = sameVerdict ? qaRecordedBuildFingerprint(report) : null;
+  const current = currentBuildFingerprint(report);
   const families = new Set();
   for (const exception of Array.isArray(verdict.exceptions) ? verdict.exceptions : []) {
     if (typeof exception?.family === "string") families.add(exception.family);
@@ -404,6 +425,9 @@ function extractQaObservations(verdict) {
   return {
     disposition: typeof verdict.disposition === "string" ? verdict.disposition : null,
     gap_classes: [...families],
+    verdict_run_id: verdictRunId,
+    build_fingerprint: recorded,
+    stale: recorded && current ? !qaRecordedForCurrentBuild(report, current) : null,
   };
 }
 
@@ -465,17 +489,6 @@ function normalizeRemitState(remit) {
   return "skipped";
 }
 
-function normalizeAgentUsage(usage) {
-  if (!usage || typeof usage !== "object" || Array.isArray(usage)) return null;
-  const out = {};
-  for (const field of ["input_tokens", "output_tokens", "tool_output_tokens", "total_tokens", "elapsed_ms"]) {
-    if (Number.isInteger(usage[field]) && usage[field] >= 0) out[field] = usage[field];
-  }
-  if (isNonEmptyString(usage.model)) out.model = usage.model.trim();
-  if (isNonEmptyString(usage.source)) out.source = usage.source.trim();
-  return Object.keys(out).length ? out : null;
-}
-
 const PRIMARY_SURFACE_PRIORITY = ["platform", "template", "design-source", "spec-rule", "cli", "skill", "docs"];
 
 const ADAPTER_DECISION_SURFACE_BY_FIELD = {
@@ -667,7 +680,7 @@ export function assembleRunRecord({
   primarySurface = null,
   surfaceConfidence = null,
   lifecycle = null,
-  agentUsage = null,
+  closedBy = null,
   qaVerdictPublish = null,
   now = new Date(),
 } = {}) {
@@ -679,7 +692,7 @@ export function assembleRunRecord({
   }
   const adapter = extractAdapterDecisions(selectAdapterDecisions({ packet, report, context }));
   if (adapter) observations.adapter_decisions = adapter;
-  const qaObs = extractQaObservations(qaVerdict);
+  const qaObs = extractQaObservations(qaVerdict, report);
   if (qaObs) observations.qa = qaObs;
   observations.finding_ids = selectRunFindingIds(journal, runId);
   const malformedJournalLines = Array.isArray(journal?.malformed)
@@ -732,8 +745,7 @@ export function assembleRunRecord({
   }
   if (surfaceConfidence) record.surface_confidence = surfaceConfidence;
   if (lifecycle && typeof lifecycle === "object" && !Array.isArray(lifecycle)) record.lifecycle = lifecycle;
-  const normalizedUsage = normalizeAgentUsage(agentUsage);
-  if (normalizedUsage) record.agent_usage = normalizedUsage;
+  if (RUN_RECORD_CLOSERS.includes(closedBy)) record.closed_by = closedBy;
   // Present only when a publish outcome is known: an absent block reads as
   // "nothing recorded", which is what every record before this field says.
   if (qaVerdictPublish && typeof qaVerdictPublish === "object" && !Array.isArray(qaVerdictPublish)) record.qa_verdict_publish = qaVerdictPublish;

package/src/sdk-attribute-index.mjs

@@ -1,25 +1,43 @@
 // The Campaign Cart SDK attribute index, vendored for the static SDK markup
 // checks (#303).
 //
-// Source: docs/attribute-index.md in NextCommerceCo/campaign-cart at tag
-// v0.4.38 (the SDK pin every certified starter family ships today), which is
-// generated from the feature manifests. 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.
+// Source: the SDK's own source in NextCommerceCo/campaign-cart at tag
+// v0.4.41 (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
+// 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.
 //
 // This is a hardcoded copy and says so, rather than restating the SDK in
 // prose that then drifts (the partner kit's mistake): the list is regenerated
-// whole from the index at a named tag, never edited by hand.
+// whole from the source at a named tag, never edited by hand.
 //
-//   git -C ../campaign-cart show v0.4.38:docs/attribute-index.md \
-//     | grep -oE '`data-[a-z0-9-]+(\s*/\s*data-[a-z0-9-]+)*`' \
-//     | tr -d '`' | tr '/' '\n' | tr -d ' ' | grep '^data-next-' | sort -u
+//   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.41 -- "${paths[@]}"
+//     git -C ../campaign-cart grep -h -oP 'dataset\.next[A-Z][A-Za-z0-9]*' v0.4.41 -- "${paths[@]}" \
+//       | sed 's/^dataset\.//' | perl -pe 's/([A-Z])/-\L$1/g; s/^/data-/'
+//   } | sort -u
+//
+// Up to v0.4.40 the list came from docs/attribute-index.md, which the SDK
+// generated from its feature manifests. v0.4.41 removed the manifests and the
+// index (campaign-cart 5d81b4eb), and its hand-written attribute docs
+// (docs/sdk-attributes.md, docs/guides/reference/data-attributes.md, each
+// feature's guide/) leave out names the source still reads, such as
+// data-next-package-selector and data-next-remove-item. Run at v0.4.40, the
+// source recipe returns every name the v0.4.40 index listed, plus names the
+// manifests never did (the address block's, data-next-i18n,
+// 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.
 //
 // A name ending in "-" (data-next-class-) is a prefix the SDK reads with any
 // suffix.
 
-export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.38";
+import { RELEASED_SDK_VERSION_PATTERN } from "../campaign-spec/dist/index.js";
+
+export const SDK_ATTRIBUTE_INDEX_VERSION = "0.4.41";
 
 export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion",
@@ -28,8 +46,15 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-accordion-trigger",
   "data-next-action",
   "data-next-active",
+  "data-next-address",
+  "data-next-address-api",
+  "data-next-address-field",
+  "data-next-address-lang",
+  "data-next-address-row",
+  "data-next-address-state",
   "data-next-await",
   "data-next-bump",
+  "data-next-bump-section",
   "data-next-bundle-card",
   "data-next-bundle-display",
   "data-next-bundle-id",
@@ -47,6 +72,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-bundle-template-id",
   "data-next-bundle-vouchers",
   "data-next-bundles",
+  "data-next-button-text",
   "data-next-cart-item-id",
   "data-next-cart-items",
   "data-next-cart-selector",
@@ -74,6 +100,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-fallback",
   "data-next-format",
   "data-next-hide",
+  "data-next-i18n",
   "data-next-id",
   "data-next-in-cart",
   "data-next-include-shipping",
@@ -98,6 +125,8 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-payment-form",
   "data-next-payment-method",
   "data-next-payment-state",
+  "data-next-phone-country",
+  "data-next-phone-e164",
   "data-next-product-sync",
   "data-next-property",
   "data-next-property-container",
@@ -138,6 +167,7 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-tooltip-offset",
   "data-next-tooltip-placement",
   "data-next-tracking-tag",
+  "data-next-unavailable",
   "data-next-upsell",
   "data-next-upsell-action",
   "data-next-upsell-action-for",
@@ -152,17 +182,21 @@ export const SDK_DATA_NEXT_ATTRIBUTES = Object.freeze([
   "data-next-url",
   "data-next-validate",
   "data-next-variant-code",
+  "data-next-variant-name",
   "data-next-variant-option",
   "data-next-variant-option-template-id",
   "data-next-variant-options",
   "data-next-variant-selector-template-id",
   "data-next-variant-selectors",
+  "data-next-variant-value",
 ]);
 
-// The fixed data-next-checkout-field names, from the same tag. The SDK maps a
-// field to the order by this value, so an unlisted name is a silent no-op: the
-// input renders, the shopper fills it, nothing reaches the order. Sources at
-// v0.4.38: src/features/checkout/README.md ("Standard field names"), the
+// The fixed data-next-checkout-field names. The SDK maps a field to the order
+// by this value, so an unlisted name is a silent no-op: the input renders, the
+// shopper fills it, nothing reaches the order. Taken at v0.4.38 and unchanged
+// through v0.4.41 (the README's "Standard field names" line is the same; the
+// names v0.4.39 and v0.4.41 added are the version-gated aliases below).
+// Sources: src/features/checkout/README.md ("Standard field names"), the
 // checkout-form enhancer and its validation/persistence tables, the hosted
 // payment field slots (cc-number, cvv, cc-month/cc-year and their exp-*
 // spellings), payment-method, and accepts_marketing. Billing fields are the
@@ -188,7 +222,7 @@ export const SDK_CHECKOUT_FIELD_NAMES = Object.freeze([
   "exp-month",
   "exp-year",
   "cvv",
-  // Legacy spellings the README at v0.4.38 still lists.
+  // Legacy spellings the README still lists at v0.4.41.
   "card-number",
   "card-expiry",
   "card-cvv",
@@ -197,6 +231,53 @@ export const SDK_CHECKOUT_FIELD_NAMES = Object.freeze([
 
 export const SDK_CHECKOUT_FIELD_PREFIXES = Object.freeze(["billing-"]);
 
+// Field names a later SDK added, each with the first version that maps it.
+// They are the orders API's own names, which the SDK reads as another
+// spelling of its older one (src/utils/checkout-field-names.ts, SDK_NAME):
+// first_name and last_name from v0.4.39 (v0.4.40 is the same SDK), and
+// phone_number from v0.4.41, whose data-attributes reference ("Field names")
+// makes these the names to write and says fname/lname/phone still work. The
+// older names stay in SDK_CHECKOUT_FIELD_NAMES and are valid on every
+// version. A page whose SDK version is unknown is judged as an earlier SDK:
+// the older name works on every version, so asking for it is always safe,
+// and accepting the newer name there could pass a field that never reaches
+// the order. Kept in step with version_gated_aliases in
+// contracts/campaign-cart-checkout-field-contract.v0.json (a test holds the
+// two equal).
+export const SDK_CHECKOUT_FIELD_NAMES_SINCE = Object.freeze({
+  first_name: Object.freeze({ since: "0.4.39", sdk_name: "fname" }),
+  last_name: Object.freeze({ since: "0.4.39", sdk_name: "lname" }),
+  phone_number: Object.freeze({ since: "0.4.41", sdk_name: "phone" }),
+});
+
+// Whether `version` is an exact released SDK version at or after `since`.
+// "Exact released" is campaign-spec's RELEASED_SDK_VERSION_PATTERN, the one
+// doctor's campaigns.json pin check uses, so doctor and standardize agree.
+// Anything else (null, a range, a prerelease, @latest, a v prefix) is not: a
+// prerelease sorts before its release, so 0.4.39-beta.1 does not carry
+// 0.4.39's names.
+export function sdkVersionAtLeast(version, since) {
+  const have = typeof version === "string" ? RELEASED_SDK_VERSION_PATTERN.exec(version) : null;
+  const need = typeof since === "string" ? RELEASED_SDK_VERSION_PATTERN.exec(since) : null;
+  if (!have || !need) return false;
+  for (let index = 1; index <= 3; index += 1) {
+    const diff = Number(have[index]) - Number(need[index]);
+    if (diff !== 0) return diff > 0;
+  }
+  return true;
+}
+
+// The version-gated entry for a field name, billing- prefix included
+// ("billing-first_name" → first_name's entry), or null.
+export function checkoutFieldNameSince(value) {
+  let name = String(value ?? "");
+  const prefix = SDK_CHECKOUT_FIELD_PREFIXES.find((candidate) => name.startsWith(candidate));
+  if (prefix) name = name.slice(prefix.length);
+  if (!Object.hasOwn(SDK_CHECKOUT_FIELD_NAMES_SINCE, name)) return null;
+  const entry = SDK_CHECKOUT_FIELD_NAMES_SINCE[name];
+  return { name, since: entry.since, sdk_name: `${prefix || ""}${entry.sdk_name}` };
+}
+
 const exact = new Set(SDK_DATA_NEXT_ATTRIBUTES.filter((name) => !name.endsWith("-")));
 const prefixes = SDK_DATA_NEXT_ATTRIBUTES.filter((name) => name.endsWith("-"));
 
@@ -205,15 +286,20 @@ export function isIndexedSdkAttribute(name) {
   return exact.has(value) || prefixes.some((prefix) => value.startsWith(prefix) && value.length > prefix.length);
 }
 
-export function isKnownCheckoutFieldName(value) {
+// Whether the SDK maps `value`. `sdkVersion` is the page's exact SDK
+// version; without one, a version-gated name is not known (see
+// SDK_CHECKOUT_FIELD_NAMES_SINCE).
+export function isKnownCheckoutFieldName(value, sdkVersion = null) {
   const name = String(value ?? "");
-  return SDK_CHECKOUT_FIELD_NAMES.includes(name)
-    || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length);
+  if (SDK_CHECKOUT_FIELD_NAMES.includes(name)
+    || SDK_CHECKOUT_FIELD_PREFIXES.some((prefix) => name.startsWith(prefix) && name.length > prefix.length)) return true;
+  const gated = checkoutFieldNameSince(name);
+  return Boolean(gated) && sdkVersionAtLeast(sdkVersion, gated.since);
 }
 
 // The Campaign Cart template placeholders, for the raw cart placeholder check
 // (built_output.cart_placeholders). Generated from the SDK renderers at the
-// same tag as the attribute index above, v0.4.38:
+// v0.4.38 (line numbers are at that tag):
 //
 //   src/features/cart/cart-summary/cart-summary.renderer.ts:46-83 (bare vars)
 //   src/features/cart/cart-summary/cart-summary.line-renderer.ts:150-173,
@@ -278,6 +364,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 and v0.4.40). 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"]);
+// v0.4.38 (git blob ids equal at v0.4.38, v0.4.39, v0.4.40 and v0.4.41, 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"]);

package/src/sdk-markup.mjs

@@ -22,7 +22,12 @@
 //   WRONG_FIELD_NAME           data-next-checkout-field with a value the SDK
 //                              does not map (firstName, lastName, zip …). The
 //                              input renders, the value never reaches the
-//                              order.
+//                              order. first_name, last_name and phone_number
+//                              are judged against the page's SDK version
+//                              (SDK_CHECKOUT_FIELD_NAMES_SINCE): the page's
+//                              own exact loader pin, else the campaign's
+//                              campaigns.json sdk_version, else unknown, which
+//                              is judged as an earlier SDK.
 //   MISSING_SELECTOR_ID_MATCH  an add-to-cart button whose data-next-selector-id
 //                              names no selector on the page. The button waits
 //                              for a selection that can never arrive.
@@ -64,8 +69,13 @@
 
 import { parse } from "parse5";
 
+// cart-placeholders.mjs imports this module's template constants as well;
+// both sides read the other's bindings only inside functions, so the cycle
+// is safe at load.
+import { readLoaderPin } from "./cart-placeholders.mjs";
 import {
   SDK_ATTRIBUTE_INDEX_VERSION,
+  checkoutFieldNameSince,
   isIndexedSdkAttribute,
   isKnownCheckoutFieldName,
 } from "./sdk-attribute-index.mjs";
@@ -78,6 +88,7 @@ export const SDK_MARKUP_CODES = Object.freeze({
   WRONG_FIELD_NAME: { code: `${SDK_MARKUP}.wrong_field_name`, severity: "error" },
   MISSING_SELECTOR_ID_MATCH: { code: `${SDK_MARKUP}.missing_selector_id_match`, severity: "error" },
   ORPHANED_UPSELL_ACTION: { code: `${SDK_MARKUP}.orphaned_upsell_action`, severity: "error" },
+  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" },
   // Unknown data-next-* names are not a finding and carry no code: they are
@@ -112,6 +123,31 @@ export const TEMPLATE_CONTAINER_ATTRIBUTES = [
 // Elements that ARE a selector an add-to-cart button can link to by id.
 const SELECTOR_ATTRIBUTES = ["data-next-bundle-selector", "data-next-package-selector", "data-next-cart-selector", "data-next-upsell-selector"];
 
+function cartVisibilityCondition(entry) {
+  return ["data-next-hide", "data-next-show"]
+    .find((name) => referencesCartState(entry.attrs.get(name))) || null;
+}
+
+function referencesCartState(condition) {
+  const source = String(condition || "");
+  let outside = "";
+  let quote = null;
+  for (let at = 0; at < source.length; at += 1) {
+    const char = source[at];
+    if (quote) {
+      if (char === "\\") at += 1;
+      else if (char === quote) quote = null;
+      outside += " ";
+    } else if (char === "'" || char === '"' || char === "`") {
+      quote = char;
+      outside += " ";
+    } else {
+      outside += char;
+    }
+  }
+  return /(?:^|[^\w.])cart\.[A-Za-z_$][\w$]*/i.test(outside);
+}
+
 function attrs(node) {
   const map = new Map();
   for (const attr of node.attrs || []) map.set(attr.name.toLowerCase(), attr.value);
@@ -158,10 +194,13 @@ function describe(entry) {
 /**
  * Scan one built page. Returns findings with { code_name, code, severity,
  * page_id, file, message, detail } and the set of unknown data-next-* names.
+ * `sdk_version` is the campaign's SDK pin, used when the page carries no
+ * exact loader pin of its own.
  */
-export function scanPageMarkup({ page_id, file = null, content = "" }) {
+export function scanPageMarkup({ page_id, file = null, content = "", sdk_version = null, page_type = null }) {
   const document = parse(String(content || ""));
   const where = file || page_id;
+  const sdk = resolvePageSdkVersion(document, sdk_version);
   const findings = [];
   const unknown = new Set();
 
@@ -170,6 +209,10 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
   const selectorIds = new Set(); // ids of elements that are themselves a selector
   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;
+  });
 
   walkElements(document, (entry) => {
     const { tag, attrs: a, ancestors } = entry;
@@ -187,10 +230,8 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
 
     if (a.has("data-next-checkout-field")) {
       const value = a.get("data-next-checkout-field") ?? "";
-      if (!isKnownCheckoutFieldName(value)) {
-        findings.push(finding("WRONG_FIELD_NAME", page_id, where,
-          `data-next-checkout-field="${value}" on ${where} is not a field name the SDK ${SDK_ATTRIBUTE_INDEX_VERSION} maps (${suggestFieldName(value)}). The input renders and the value never reaches the order.`,
-          { value, suggestion: suggestFieldName(value, true) }));
+      if (!isKnownCheckoutFieldName(value, sdk.version)) {
+        findings.push(wrongFieldName(page_id, where, value, sdk));
       }
     }
 
@@ -206,6 +247,16 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
         { tag, action: value }));
     }
 
+    if (receiptPage && a.has("data-next-order-items")) {
+      const holder = [entry, ...ancestors].find(cartVisibilityCondition);
+      if (holder) {
+        const conditionAttribute = cartVisibilityCondition(holder);
+        findings.push(finding("RECEIPT_ORDER_ITEMS_CART_VISIBILITY", page_id, where,
+          `${describe(entry)} on ${where} ${holder === entry ? "carries" : `is inside ${describe(holder)} with`} ${conditionAttribute}="${holder.attrs.get(conditionAttribute)}". After checkout the cart can be empty, so receipt order lines disappear. Remove the cart-state visibility condition from the order-items element and its ancestors.`,
+          { condition_attribute: conditionAttribute, condition: holder.attrs.get(conditionAttribute) }));
+      }
+    }
+
     const action = (a.get("data-next-action") || "").trim().toLowerCase();
     if (action === "add-to-cart") {
       addToCartButtons.push({ entry, selectorId: (a.get("data-next-selector-id") || "").trim() || null });
@@ -291,6 +342,32 @@ export function scanPageMarkup({ page_id, file = null, content = "" }) {
   return { page_id, file, findings, unknown_attributes: [...unknown].sort() };
 }
 
+// The SDK version a page runs: its own exact loader pin, else the campaign
+// pin handed in, else null (unknown).
+function resolvePageSdkVersion(document, campaignVersion) {
+  const page = readLoaderPin(document);
+  if (page) return { version: page, source: "loader" };
+  const campaign = typeof campaignVersion === "string" && campaignVersion.trim() ? campaignVersion.trim() : null;
+  if (campaign) return { version: campaign, source: "campaigns_json" };
+  return { version: null, source: null };
+}
+
+function wrongFieldName(page_id, where, value, sdk) {
+  const gated = checkoutFieldNameSince(value);
+  const versionDetail = { sdk_version: sdk.version, sdk_version_source: sdk.source };
+  if (!gated) {
+    return finding("WRONG_FIELD_NAME", page_id, where,
+      `data-next-checkout-field="${value}" on ${where} is not a field name the SDK ${SDK_ATTRIBUTE_INDEX_VERSION} maps (${suggestFieldName(value)}). The input renders and the value never reaches the order.`,
+      { value, suggestion: suggestFieldName(value, true), ...versionDetail });
+  }
+  const running = sdk.version
+    ? `this page loads SDK ${sdk.version} (${sdk.source === "loader" ? "its loader pin" : "the campaigns.json sdk_version"})`
+    : "this page's SDK version could not be read (no exact loader pin on the page and no sdk_version in campaigns.json), so it is judged as an earlier SDK";
+  return finding("WRONG_FIELD_NAME", page_id, where,
+    `data-next-checkout-field="${value}" on ${where} is a field name the SDK maps only from ${gated.since}, and ${running}. The input renders and the value never reaches the order. Use "${gated.sdk_name}", which every SDK version maps, or pin the SDK to ${gated.since} or later.`,
+    { value, suggestion: gated.sdk_name, since: gated.since, ...versionDetail });
+}
+
 function finding(codeName, page_id, file, message, detail = {}) {
   const { code, severity } = SDK_MARKUP_CODES[codeName];
   return { code_name: codeName, code, severity, page_id, file, message: `${codeName}: ${message}`, detail };
@@ -318,11 +395,13 @@ function suggestFieldName(value, bare = false) {
 /**
  * Evaluate the SDK markup family over built pages.
  *
- * @param {{ subject: object, pages: Array<{ page_id: string, file?: string|null, content: string }> }} input
+ * @param {{ subject: object, pages: Array<{ page_id: string, file?: string|null, content: string }>, sdkVersion?: string|null }} input
+ *   `sdkVersion` is the campaign's SDK pin (campaigns.json sdk_version), the
+ *   fallback for a page with no exact loader pin of its own.
  */
-export function evaluateSdkMarkup({ subject, pages = [] } = {}) {
+export function evaluateSdkMarkup({ subject, pages = [], sdkVersion = null } = {}) {
   const resolvedSubject = subject && typeof subject === "object" ? subject : {};
-  const base = { id: SDK_MARKUP, scope: SDK_MARKUP, waivable: false, subject: resolvedSubject, waiver: null, sdk_attribute_index_version: SDK_ATTRIBUTE_INDEX_VERSION };
+  const base = { id: SDK_MARKUP, scope: SDK_MARKUP, waivable: false, subject: resolvedSubject, waiver: null, sdk_attribute_index_version: SDK_ATTRIBUTE_INDEX_VERSION, campaign_sdk_version: typeof sdkVersion === "string" && sdkVersion.trim() ? sdkVersion.trim() : null };
   const list = Array.isArray(pages) ? pages : [];
 
   if (list.length === 0) {
@@ -333,7 +412,7 @@ export function evaluateSdkMarkup({ subject, pages = [] } = {}) {
   const warned = [];
   const unknown = new Map();
   for (const page of list) {
-    const scan = scanPageMarkup(page);
+    const scan = scanPageMarkup({ ...page, sdk_version: page?.sdk_version ?? sdkVersion });
     for (const item of scan.findings) (item.severity === "error" ? findings : warned).push(item);
     for (const name of scan.unknown_attributes) {
       if (!unknown.has(name)) unknown.set(name, []);