@tokenoftrust/storefront-runner 2.4.40 → 2.4.42

package/agency-kit/tools/lib/catalog-model/model.mjs

@@ -82,6 +82,18 @@ export const CATALOG_MODEL = {
       "unit?": "string",
     },
   },
+  CatalogSkuReference: {
+    union: [
+      { status: '"assigned" | "retired"', sku: "string", profileId: "string", profileVersion: "number",
+        acceptedRevisionId: "string", revisionStatus: '"current" | "historical"', itemId: "string",
+        provenance: '"catalog-reviewed-assignment"', findings: "string[]" },
+      { status: '"suggested"', sku: "string", profileId: "string", profileVersion: "number",
+        acceptedRevisionId: "string", itemId: "string", provenance: '"catalog-preview"', findings: "string[]" },
+      { status: '"review-needed"', sku: "null", profileId: "string | null", profileVersion: "number | null",
+        acceptedRevisionId: "string", itemId: "string", provenance: '"catalog-preview"', findings: "string[]" },
+    ],
+  },
+  MerchantSkuOrigin: { alias: '"tot-adopted" | "merchant-override"' },
   CatalogLink: {
     fields: {
       item_id: "string",
@@ -91,6 +103,7 @@ export const CATALOG_MODEL = {
       "locale?": "string",
       accepted_at: "string",
       facts: "CatalogFact[]",
+      "sku_reference?": "CatalogSkuReference",
       "setup_policy?": "CatalogSetupProvenance",
     },
   },
@@ -110,6 +123,7 @@ export const CATALOG_MODEL = {
       product_id: "string",
       source: "SourceRef",
       "sku?": "string",
+      "sku_origin?": "MerchantSkuOrigin",
       title: "string",
       price: "number",
       "compare_at_price?": "number",
@@ -288,6 +302,9 @@ function checkType(type, value, path, issues) {
     return;
   }
   switch (t) {
+    case "null":
+      if (value !== null) issues.push({ path, message: "expected null" });
+      return;
     case "unknown":
       return;
     case "string":

package/apps/storefront/package.json

@@ -14,7 +14,7 @@
     "preview": "wrangler dev",
     "typecheck": "astro check && tsc --noEmit",
     "astro": "astro",
-    "test": "NODE_OPTIONS=--experimental-sqlite vitest run && pnpm run test:pipeline && pnpm run test:pipeline-faults"
+    "test": "NODE_OPTIONS=--experimental-sqlite vitest run --exclude src/lib/apps/v84CleanCloneReplay.test.ts --exclude src/lib/apps/v84NonportableRouteDogfood.test.ts --exclude src/lib/apps/v84CloneLifecycleEvidence.test.ts && NODE_OPTIONS=--experimental-sqlite vitest run src/lib/apps/v84CleanCloneReplay.test.ts src/lib/apps/v84NonportableRouteDogfood.test.ts src/lib/apps/v84CloneLifecycleEvidence.test.ts --fileParallelism=false && pnpm run test:pipeline && pnpm run test:pipeline-faults"
   },
   "dependencies": {
     "@astrojs/cloudflare": "^14.0.1",

package/apps/storefront/src/lib/admin/catalogSettingsClient.ts

@@ -9,7 +9,6 @@ interface MethodOption { id: string; title: string; reason: string }
 interface SettingsResponse extends SettingsPayload {
   ok: true;
   pricingMethods: MethodOption[];
-  skuMethods: MethodOption[];
   history: Array<{ revision: number; savedAt: string; actor: string }>;
   historyUnavailable: boolean;
 }
@@ -19,10 +18,8 @@ interface PreviewResponse {
     price: number | null; cost: number | null; profit: number | null; margin: number | null;
     calculation: string; issues: string[]; ruleExplanation: string;
   } };
-  sku?: { status: string; value?: string };
 }
 type Child = Node | string | null | undefined | false;
-type Section = "pricing" | "sku";
 type RecordValue = Record<string, unknown>;
 
 function h<K extends keyof HTMLElementTagNameMap>(tag: K, attrs: Record<string, string | boolean | undefined> = {}, ...children: Child[]): HTMLElementTagNameMap[K] {
@@ -39,13 +36,12 @@ const METHOD_FIELDS: Record<string, [string, string, string]> = {
 };
 const METHOD_TITLES: Record<string, string> = {
   msrp: "Supplier MSRP", margin: "Target margin", markup: "Markup over cost", "msrp-adjustment": "Adjust MSRP", fixed: "Add a fixed amount",
-  sequential: "Simple numbers", family: "Product families", hybrid: "Category + number", attributes: "Product attributes", supplier: "Supplier codes", random: "Short random codes", deterministic: "Stable identity codes",
 };
 const FIELD_LABELS: Record<string, string> = {
   targetMargin: "Target gross margin", markup: "Markup over cost", msrpAdjustment: "MSRP adjustment", fixedMarkup: "Amount added to cost",
   additionalCost: "Additional cost per item", additionalCostPercent: "Additional cost percentage", minimumPrice: "Minimum price", maximumPrice: "Maximum price", minimumMargin: "Minimum gross margin",
   costBasis: "Cost basis", rounding: "Price format", increment: "Rounding increment", ending: "Price ending", direction: "Round direction", missingData: "Missing price source", fallbackMethod: "Fallback pricing method", updatePolicy: "Update preference",
-  startingNumber: "Starting number", prefix: "SKU prefix", separator: "SKU separator", method: "Method", productKey: "Product ID or SKU", selectedRuleId: "Matching rule",
+  method: "Method", productKey: "Product ID or SKU", selectedRuleId: "Matching rule",
   name: "Rule name", scope: "Match by", match: "Matching value", minimumCost: "Cost from", maximumCost: "Cost below", price: "Selling price",
   wholesale: "Wholesale cost", msrp: "Supplier MSRP", minimum: "Product minimum price", maximum: "Product maximum price",
 };
@@ -76,10 +72,8 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
   let state: SettingsEditorState | null = null;
   let storeCurrency = root.dataset.currency ?? "";
   let pricingMethods: MethodOption[] = [];
-  let skuMethods: MethodOption[] = [];
   let history: SettingsResponse["history"] = [];
   let historyUnavailable = false;
-  let activeTab: Section = window.location.hash === "#sku" ? "sku" : "pricing";
   let saving = false;
   let loading = false;
   let feedback = "";
@@ -93,19 +87,19 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
   const saveStatus = h("div", { class: "save-status", "aria-live": "polite" });
   const saveButton = h("button", { type: "button", class: "btn primary", "data-save": "true" }, "Save defaults");
   const discardButton = h("button", { type: "button", class: "btn secondary", "data-discard": "true" }, "Discard changes");
-  const tabs = h("div", { class: "settings-tabs", role: "tablist", "aria-label": "Catalog defaults" });
   const money = (value: number, currency = state?.currency ?? storeCurrency) => {
     try { return new Intl.NumberFormat(undefined, { style: "currency", currency }).format(value); }
     catch { return `${currency} ${value.toFixed(2)}`; }
   };
   const currencyMismatch = () => Boolean(state && storeCurrency && state.currency !== storeCurrency);
-  const isConfigured = (section: Section) => state?.draft[section === "pricing" ? "pricingConfigured" : "skuConfigured"] === true;
-  const methodTitle = (id: string) => METHOD_TITLES[id] ?? [...pricingMethods, ...skuMethods].find((method) => method.id === id)?.title ?? "Saved method";
+  const isConfigured = () => state?.draft.pricingConfigured === true;
+  const methodTitle = (id: string) => METHOD_TITLES[id] ?? pricingMethods.find((method) => method.id === id)?.title ?? "Saved method";
 
   function paintStatus(): void {
     if (!state) return;
     const dirty = draftIsDirty(state);
     const notices: Node[] = [];
+    if (state.savedEngineVersion && state.savedEngineVersion !== state.engineVersion) notices.push(h("p", { class: "notice", role: "status" }, "Saved pricing defaults use an older calculation engine. Review your pricing method before saving this revision under the current engine. Existing listings and merchant SKUs stay unchanged."));
     if (currencyMismatch()) notices.push(h("p", { class: "notice error", role: "alert" }, `Saved defaults use ${state.currency}; this store uses ${storeCurrency}. Saving and preview are paused. No currency conversion is applied.`));
     if (state.conflict) {
       const reload = h("button", { type: "button", class: "btn secondary", disabled: saving || loading, "data-reload": "true" }, "Load saved defaults");
@@ -163,45 +157,42 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
     const field = METHOD_FIELDS[fieldString(record, "method")];
     return field ? numberField(record, field[0], field[1], touch, field[2], `${prefix}${field[0]}`) : null;
   }
-  function examples(section: Section): Record<string, string> {
-    return section === "pricing" ? {
-      msrp: `${money(60)} MSRP → ${money(60)}`, margin: `${money(40)} cost · 40% → ${money(66.67)}`,
-      markup: `${money(40)} cost · 50% → ${money(60)}`, "msrp-adjustment": `${money(60)} MSRP · −10% → ${money(54)}`, fixed: `${money(40)} cost + ${money(15)} → ${money(55)}`,
-    } : { sequential: "SKU-004821", family: "P004821-V03", hybrid: "TSH-004821", attributes: "AC-TS42-BLK-M", supplier: "SUP7-AX204", random: "K7MX4R9T", deterministic: "P-7K3M9X2Q" };
-  }
-  function methodPicker(section: Section): HTMLElement {
+  function methodPicker(): HTMLElement {
     if (!state) return h("div");
-    const record = state.draft[section];
-    const configured = isConfigured(section);
-    const all = section === "pricing" ? pricingMethods : skuMethods;
-    const commonIds = section === "pricing" ? ["msrp", "margin", "markup"] : ["sequential", "family", "hybrid"];
-    const common = all.filter((method) => commonIds.includes(method.id));
-    const more = all.filter((method) => !commonIds.includes(method.id));
-    const sampleExamples = examples(section);
+    const record = state.draft.pricing;
+    const configured = isConfigured();
+    const commonIds = ["msrp", "margin", "markup"];
+    const common = pricingMethods.filter((method) => commonIds.includes(method.id));
+    const more = pricingMethods.filter((method) => !commonIds.includes(method.id));
+    const sampleExamples: Record<string, string> = {
+      msrp: `${money(60)} MSRP → ${money(60)}`, margin: `${money(40)} cost · 40% → ${money(66.67)}`,
+      markup: `${money(40)} cost · 50% → ${money(60)}`, "msrp-adjustment": `${money(60)} MSRP · −10% → ${money(54)}`,
+      fixed: `${money(40)} cost + ${money(15)} → ${money(55)}`,
+    };
     const reasons: Record<string, string> = {
-      msrp: "Start with the supplier’s suggested retail price.", margin: "Keep a consistent share of every sale.", markup: "Add a percentage to what you paid.", sequential: "A dependable format for any catalog.", family: "Keep related variants easy to recognize.", hybrid: "A readable prefix with a simple number.",
+      msrp: "Start with the supplier’s suggested retail price.", margin: "Keep a consistent share of every sale.", markup: "Add a percentage to what you paid.",
     };
     const card = (method: MethodOption) => {
       const selected = configured && record.method === method.id;
-      const radio = h("input", { type: "radio", name: `${section}-method`, value: method.id, "data-focus": `${section}-${method.id}` });
+      const radio = h("input", { type: "radio", name: "pricing-method", value: method.id, "data-focus": `pricing-${method.id}` });
       radio.checked = selected;
-      radio.addEventListener("change", () => { if (state) { selectDraftMethod(state, section, method.id); touch(); renderEditor(); } });
+      radio.addEventListener("change", () => { if (state) { selectDraftMethod(state, "pricing", method.id); touch(); renderEditor(); } });
       return h("label", { class: `method-card${selected ? " selected" : ""}` }, radio,
         h("span", { class: "method-title" }, methodTitle(method.id)), h("span", { class: "method-example" }, sampleExamples[method.id] ?? "Sample format"), h("span", { class: "method-reason" }, reasons[method.id] ?? method.reason));
     };
-    const manual = h("button", { type: "button", class: "text-button", "data-focus": `${section}-manual`, "aria-pressed": String(!configured) }, section === "pricing" ? "Use manual prices instead" : "Enter SKUs manually instead");
+    const manual = h("button", { type: "button", class: "text-button", "data-focus": "pricing-manual", "aria-pressed": String(!configured) }, "Use manual prices instead");
     manual.addEventListener("click", () => {
       if (!state) return;
-      state.draft[section === "pricing" ? "pricingConfigured" : "skuConfigured"] = false;
+      state.draft.pricingConfigured = false;
       touch(); renderEditor();
     });
-    return h("section", { class: "editor-panel method-panel", "aria-labelledby": `${section}-method-heading` },
-      h("div", { class: "section-heading" }, h("span", { class: "step-number", "aria-hidden": "true" }, "1"), h("h2", { id: `${section}-method-heading` }, section === "pricing" ? "Choose your pricing method" : "Choose your SKU format")),
-      h("p", { class: "section-intro" }, section === "pricing" ? "One starting point for every new product." : "An item code that works for the way you sell."),
-      !configured ? h("p", { class: "manual-note" }, section === "pricing" ? "Manual pricing is on. Choose a method to set a default." : "SKUs are entered manually. Choose a format to set a default.") : null,
+    return h("section", { class: "editor-panel method-panel", "aria-labelledby": "pricing-method-heading" },
+      h("div", { class: "section-heading" }, h("span", { class: "step-number", "aria-hidden": "true" }, "1"), h("h2", { id: "pricing-method-heading" }, "Choose your pricing method")),
+      h("p", { class: "section-intro" }, "One starting point for every new product."),
+      !configured ? h("p", { class: "manual-note" }, "Manual pricing is on. Choose a method to set a default.") : null,
       h("div", { class: "method-grid" }, ...common.map(card)),
-      disclosure(`${section}-more`, "More methods", section === "pricing" ? "Adjust MSRP or add a fixed amount" : "Attributes, suppliers and generated codes", [h("div", { class: "method-grid more-grid" }, ...more.map(card))], configured && more.some((method) => method.id === record.method)),
-      configured && section === "pricing" && METHOD_FIELDS[String(record.method)] ? h("div", { class: "method-parameter" }, parameter(record)) : null,
+      disclosure("pricing-more", "More methods", "Adjust MSRP or add a fixed amount", [h("div", { class: "method-grid more-grid" }, ...more.map(card))], configured && more.some((method) => method.id === record.method)),
+      configured && METHOD_FIELDS[String(record.method)] ? h("div", { class: "method-parameter" }, parameter(record)) : null,
       configured ? manual : null);
   }
 
@@ -225,7 +216,7 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
     }));
   }
   function pricingControls(): HTMLElement[] {
-    if (!state || !isConfigured("pricing")) return [];
+    if (!state || !isConfigured()) return [];
     const pricing = state.draft.pricing;
     const repaint = () => { touch(); renderEditor(); };
     const priceFormat = h("section", { class: "editor-panel" },
@@ -276,25 +267,6 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
     ]);
     return [priceFormat, advanced, rules];
   }
-  function skuControls(): HTMLElement[] {
-    if (!state || !isConfigured("sku")) return [];
-    const sku = state.draft.sku;
-    const numbered = ["sequential", "family", "hybrid"].includes(String(sku.method));
-    const separated = sku.method !== "random";
-    const hasPrefix = !["attributes", "random"].includes(String(sku.method));
-    return [h("section", { class: "editor-panel" },
-      h("div", { class: "section-heading" }, h("span", { class: "step-number", "aria-hidden": "true" }, "2"), h("h2", {}, "Fine-tune the format")),
-      h("div", { class: "fields-grid" },
-        hasPrefix ? textField(sku, "prefix", sku.method === "supplier" ? "Supplier prefix" : sku.method === "hybrid" ? "Category prefix" : "Prefix", touch, { maxlength: "12", spellcheck: "false" }) : null,
-        numbered ? numberField(sku, "startingNumber", "Starting number", touch, "A whole number. The preview pads it to six digits.") : null,
-        separated ? select(sku, "separator", "Separator", [{ value: "-", label: "Hyphen (–)" }, { value: "_", label: "Underscore (_)" }, { value: "", label: "None" }]) : null),
-      hasPrefix ? h("p", { class: "hint" }, "An optional prefix of up to 12 uppercase letters or digits, starting with a letter.") : null,
-      !separated ? h("p", { class: "hint" }, "No format options needed. Use eight uppercase letters and digits.") : null,
-      sku.method === "attributes" ? h("p", { class: "hint" }, "The sample illustrates brand, model, color and size abbreviations.") : null,
-      sku.method === "family" ? h("p", { class: "hint" }, "V03 illustrates a variant within a numbered product family.") : null,
-      sku.method === "supplier" ? h("p", { class: "hint" }, "AX204 illustrates a supplier’s item code.") : null,
-      sku.method === "deterministic" ? h("p", { class: "hint" }, "The sample uses a fixed item identity. Generated codes still need a uniqueness check.") : null)];
-  }
   function savedHistory(): HTMLElement {
     const entries: Node[] = [];
     if (historyUnavailable) entries.push(h("p", { class: "hint" }, "Saved history is unavailable."));
@@ -313,38 +285,16 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
     const focusKey = focused && editor.contains(focused) ? focused.dataset.focus : undefined;
     const selection: [number | null, number | null] | null = focused?.tagName === "INPUT" && ["text", "search"].includes(focused.type) ? [focused.selectionStart, focused.selectionEnd] : null;
     editor.replaceChildren(
-      h("div", { id: "settings-pricing-panel", role: "tabpanel", "aria-labelledby": "settings-pricing-tab", hidden: activeTab !== "pricing" }, methodPicker("pricing"), ...pricingControls()),
-      h("div", { id: "settings-sku-panel", role: "tabpanel", "aria-labelledby": "settings-sku-tab", hidden: activeTab !== "sku" }, methodPicker("sku"), ...skuControls()),
-      h("p", { class: "preserve-note" }, h("span", { "aria-hidden": "true" }, "✓"), " Saved listings keep their prices and SKUs. These defaults never overwrite them."), savedHistory());
+      h("div", { id: "settings-pricing-panel" }, methodPicker(), ...pricingControls()),
+      h("p", { class: "preserve-note" }, h("span", { "aria-hidden": "true" }, "✓"), " Saved listings keep their prices and merchant SKUs. Pricing defaults never overwrite them."), savedHistory());
     if (focusKey) {
       const control = Array.from(editor.querySelectorAll<HTMLElement>("[data-focus]")).find((node) => node.dataset.focus === focusKey);
       control?.focus({ preventScroll: true });
       if (selection && control instanceof HTMLInputElement) control.setSelectionRange(selection[0], selection[1]);
-      if (!control && focusKey.endsWith("-manual")) editor.querySelector<HTMLInputElement>(`input[name="${activeTab}-method"]`)?.focus({ preventScroll: true });
+      if (!control && focusKey.endsWith("-manual")) editor.querySelector<HTMLInputElement>(`input[name="pricing-method"]`)?.focus({ preventScroll: true });
     }
     refreshRuleChoices();
   }
-  function setTab(section: Section, focus = false, updateHash = false): void {
-    activeTab = section;
-    if (updateHash) window.history.replaceState(window.history.state, "", `#${section}`);
-    for (const tab of tabs.querySelectorAll<HTMLButtonElement>("[data-tab]")) {
-      const selected = tab.dataset.tab === section;
-      tab.setAttribute("aria-selected", String(selected)); tab.tabIndex = selected ? 0 : -1;
-      if (selected && focus) tab.focus();
-    }
-    for (const id of ["pricing", "sku"]) { const pane = editor.querySelector<HTMLElement>(`#settings-${id}-panel`); if (pane) pane.hidden = id !== section; }
-  }
-  for (const section of ["pricing", "sku"] as const) {
-    const tab = h("button", { type: "button", role: "tab", id: `settings-${section}-tab`, "data-tab": section, "aria-controls": `settings-${section}-panel` }, section === "pricing" ? "Pricing" : "SKUs");
-    tab.addEventListener("click", () => setTab(section, false, true));
-    tab.addEventListener("keydown", (event) => {
-      if (["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) {
-        event.preventDefault(); setTab(event.key === "Home" ? "pricing" : event.key === "End" ? "sku" : activeTab === "pricing" ? "sku" : "pricing", true, true);
-      }
-    });
-    tabs.append(tab);
-  }
-  window.addEventListener("hashchange", () => setTab(window.location.hash === "#sku" ? "sku" : "pricing"));
   const ruleSelect = select(sampleText, "selectedRuleId", "Matching rule", [{ value: "", label: "Automatically match" }, { value: "store", label: "Use store default" }], schedulePreview, "sample-selectedRuleId");
   function refreshRuleChoices(): void {
     const control = ruleSelect.querySelector("select");
@@ -363,7 +313,7 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
       h("div", { class: "fields-grid" }, numberField(sample, "minimum", "Product minimum price", schedulePreview, "", "sample-minimum"), numberField(sample, "maximum", "Product maximum price", schedulePreview, "", "sample-maximum")),
       textField(sampleText, "productKey", "Product ID or SKU", schedulePreview, {}, "sample-productKey"),
       ...["assortment", "category", "brand"].map((key) => textField(sampleText, key, key.charAt(0).toUpperCase() + key.slice(1), schedulePreview, {}, `sample-${key}`)), ruleSelect]),
-    h("p", { class: "preview-footnote" }, "A sample, not a catalog change. The SKU shown has not been reserved."));
+    h("p", { class: "preview-footnote" }, "A sample price; saving it does not change catalog references or existing listings."));
 
   function paintPreview(result: PreviewStatus<PreviewResponse>): void {
     previewOut.setAttribute("aria-busy", String(result.status === "waiting" || result.status === "loading"));
@@ -385,8 +335,7 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
     previewOut.replaceChildren(
       h("div", { class: "preview-result" }, h("span", { class: "result-label" }, "Selling price"),
         h("strong", { class: `sample-price${!calculated ? " manual-result" : ""}` }, calculated ? calculated.price === null ? "Needs review" : money(calculated.price, body.currency) : "Manual price"),
-        h("span", { class: "result-method" }, calculated ? "Your draft price" : "Choose a pricing method to calculate"), metrics,
-        h("div", { class: "sku-result" }, h("span", { class: "result-label" }, "Sample SKU"), h("strong", {}, body.sku?.status === "ok" ? body.sku.value ?? "—" : "Entered manually"))),
+        h("span", { class: "result-method" }, calculated ? "Your draft price" : "Choose a pricing method to calculate"), metrics),
       ...(calculated?.calculation ? [h("p", { class: "calculation hint" }, calculated.calculation)] : []),
       ...(calculated?.ruleExplanation && calculated.ruleExplanation !== "Store default" ? [h("p", { class: "hint applied-rule" }, calculated.ruleExplanation)] : []),
       ...(calculated?.issues ?? []).map((issue) => h("p", { class: "notice review-note" }, issue)));
@@ -405,8 +354,8 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
     preview.schedule({ ...draft, sample: { ...sample, ...Object.fromEntries(Object.entries(sampleText).filter(([, value]) => value !== "")) } });
   }
   function mount(): void {
-    panel.replaceChildren(tabs, status, h("div", { class: "settings-layout" }, editor, previewPanel), h("div", { class: "save-bar" }, h("div", { class: "save-bar-inner" }, saveStatus, h("div", { class: "save-actions" }, discardButton, saveButton))));
-    renderEditor(); setTab(activeTab); paintStatus(); schedulePreview();
+    panel.replaceChildren(status, h("div", { class: "settings-layout" }, editor, previewPanel), h("div", { class: "save-bar" }, h("div", { class: "save-bar-inner" }, saveStatus, h("div", { class: "save-actions" }, discardButton, saveButton))));
+    renderEditor(); paintStatus(); schedulePreview();
   }
   async function load(): Promise<void> {
     if (saving || loading) return;
@@ -416,7 +365,7 @@ export function initCatalogSettingsPage(root: HTMLElement): void {
       const response = await fetch(api, { headers: { accept: "application/json" } });
       const body = await response.json() as SettingsResponse & { message?: string };
       if (!response.ok || !body.ok) throw new Error(body.message || "Your defaults could not be loaded. Try again.");
-      pricingMethods = body.pricingMethods; skuMethods = body.skuMethods; history = body.history; historyUnavailable = body.historyUnavailable;
+      pricingMethods = body.pricingMethods; history = body.history; historyUnavailable = body.historyUnavailable;
       state = editorFromPayload(body);
       if (typeof body.storeCurrency === "string") storeCurrency = body.storeCurrency;
       const badge = previewPanel.querySelector(".currency-badge"); if (badge) badge.textContent = state.currency;

package/apps/storefront/src/lib/admin/catalogSettingsState.ts

@@ -14,6 +14,7 @@ export interface SettingsPayload {
   currency: string;
   storeCurrency?: string;
   engineVersion: string;
+  savedEngineVersion?: string | null;
   revision: number | null;
   pricing: SettingsSection | null;
   sku: SettingsSection | null;
@@ -33,6 +34,7 @@ export interface SettingsEditorState {
   savedRevision: number | null;
   currency: string;
   engineVersion: string;
+  savedEngineVersion: string | null;
   draft: CalculationDraft;
   saved: CalculationDraft | null;
   conflict: { revision: number | null; message: string } | null;
@@ -61,6 +63,7 @@ export function editorFromPayload(payload: SettingsPayload): SettingsEditorState
     savedRevision: payload.revision,
     currency: payload.currency,
     engineVersion: payload.engineVersion,
+    savedEngineVersion: payload.revision === null ? null : payload.savedEngineVersion ?? payload.engineVersion,
     draft,
     saved: structuredClone(draft),
     conflict: null,
@@ -114,6 +117,7 @@ export function applySaveResult(state: SettingsEditorState, result: SaveOutcome)
       contractRevision: state.contractRevision,
       currency: state.currency,
       engineVersion: state.engineVersion,
+      savedEngineVersion: state.engineVersion,
       revision: result.revision,
       pricing: result.pricing,
       sku: result.sku,

package/apps/storefront/src/lib/admin/productsTabClient.ts

@@ -4,6 +4,16 @@
  * explicitly as a draft change. Catalog text is set as text, never parsed as HTML.
  */
 
+/** The fields this review renders; the public runner does not bundle catalog setup. */
+interface CatalogReferenceView {
+  status: "assigned" | "retired" | "suggested" | "review-needed";
+  sku: string | null;
+  profileId: string | null;
+  profileVersion: number | null;
+  revisionStatus?: "current" | "historical";
+  findings: string[];
+}
+
 interface UpdatePlanProduct {
   handle: string;
   baseRevision: string;
@@ -14,6 +24,13 @@ interface UpdatesResponse {
   ok: boolean;
   message?: string;
   updates: Array<{ title: string; acceptedRevisionId: string; latestRevisionId: string }>;
+  referenceUpdates: Array<{
+    itemId: string;
+    title: string;
+    acceptedRevisionId: string;
+    saved: CatalogReferenceView | null;
+    incoming: CatalogReferenceView;
+  }>;
   unavailable?: Array<{ title: string; message: string }>;
   request?: Record<string, unknown>;
   plan: { products: UpdatePlanProduct[] } | null;
@@ -35,6 +52,15 @@ function el(tag: string, attrs: Record<string, string> = {}, ...children: Array<
   return node;
 }
 
+function referenceLabel(reference: CatalogReferenceView | null): string {
+  if (!reference) return "none saved";
+  const code = reference.sku ?? "no approved code";
+  const status = reference.status === "suggested" ? "preview only" : reference.status.replace("-", " ");
+  const revision = reference.revisionStatus ? `, ${reference.revisionStatus} revision` : "";
+  const method = reference.profileId ? `, ${reference.profileId} v${reference.profileVersion}` : "";
+  return `${code} (${status}${revision}${method})`;
+}
+
 export function initProductsTab(root: HTMLElement): void {
   const api = root.dataset.productsApi ?? "";
   const statusSelect = root.querySelector<HTMLSelectElement>("[data-products-status-select]");
@@ -81,21 +107,31 @@ export function initProductsTab(root: HTMLElement): void {
         return;
       }
       const nodes: Node[] = [];
+      const referenceUpdates = body.referenceUpdates ?? [];
       if (body.unavailable?.length) {
         nodes.push(el("p", { class: "subtle" }, `Not checked: ${body.unavailable.map((u) => `${u.title} (${u.message})`).join("; ")}.`));
       }
-      if (body.updates.length === 0) {
-        nodes.push(el("p", {}, "Every listed package is at the catalog's latest revision."));
+      if (body.updates.length === 0 && referenceUpdates.length === 0) {
+        nodes.push(el("p", {}, body.unavailable?.length
+          ? "No catalog update was found among the packages that could be checked."
+          : "Every listed package is at the catalog's latest revision."));
         box.replaceChildren(...nodes);
         return;
       }
-      nodes.push(
+      if (body.updates.length) nodes.push(
         el("strong", {}, `${body.updates.length} package(s) have a newer catalog revision`),
-        el(
-          "ul",
-          { class: "update-list" },
-          ...body.updates.map((u) => el("li", {}, `${u.title}: revision ${u.acceptedRevisionId.slice(0, 8)} → ${u.latestRevisionId.slice(0, 8)}`)),
-        ),
+        el("ul", { class: "update-list" },
+          ...body.updates.map((u) => el("li", {}, `${u.title}: revision ${u.acceptedRevisionId.slice(0, 8)} → ${u.latestRevisionId.slice(0, 8)}`))),
+      );
+      if (referenceUpdates.length) nodes.push(
+        el("strong", {}, `${referenceUpdates.length} catalog reference ${referenceUpdates.length === 1 ? "update" : "updates"} to review`),
+        el("ul", { class: "update-list" }, ...referenceUpdates.map((update) => el("li", {},
+          `${update.title}: ${referenceLabel(update.saved)} → ${referenceLabel(update.incoming)}. `,
+          `Exact package revision ${update.acceptedRevisionId.slice(0, 8)}.`,
+          ...(update.incoming.findings.length
+            ? [el("ul", {}, ...update.incoming.findings.map((finding) => el("li", {}, finding)))]
+            : []),
+        ))),
       );
       const plan = body.plan;
       if (!plan || !body.request) {
@@ -116,7 +152,8 @@ export function initProductsTab(root: HTMLElement): void {
         );
       }
       nodes.push(el("p", { class: "subtle" }, "Your SKUs, prices and the fields you set are kept. Accepting opens a draft change; nothing is published."));
-      const accept = el("button", { type: "button", class: "btn primary" }, "Accept update as a draft") as HTMLButtonElement;
+      const accept = el("button", { type: "button", class: "btn primary" }, referenceUpdates.length && !body.updates.length
+        ? "Accept catalog reference update as a draft" : "Accept update as a draft") as HTMLButtonElement;
       accept.addEventListener("click", async () => {
         accept.disabled = true;
         const expected = Object.fromEntries(plan.products.map((p) => [p.handle, p.baseRevision]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "2.4.40",
+  "version": "2.4.42",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",

package/packages/public-runtime/src/product.ts

@@ -158,6 +158,19 @@ export interface CatalogFact {
  * accepted. One variant lists exactly one packaged item. The accepted facts are stored here
  * so the product previews and publishes with the catalog unavailable.
  */
+/** Server-verified shared catalog code at the exact accepted item revision. */
+export type CatalogSkuReference =
+  | { status: "assigned" | "retired"; sku: string; profileId: string; profileVersion: number;
+      acceptedRevisionId: string; revisionStatus: "current" | "historical"; itemId: string;
+      provenance: "catalog-reviewed-assignment"; findings: string[] }
+  | { status: "suggested"; sku: string; profileId: string; profileVersion: number;
+      acceptedRevisionId: string; itemId: string; provenance: "catalog-preview"; findings: string[] }
+  | { status: "review-needed"; sku: null; profileId: string | null; profileVersion: number | null;
+      acceptedRevisionId: string; itemId: string; provenance: "catalog-preview"; findings: string[] };
+
+/** Merchant's operational choice; it never changes the shared catalog reference. */
+export type MerchantSkuOrigin = "tot-adopted" | "merchant-override";
+
 export interface CatalogLink {
   item_id: string;
   accepted_revision_id: string;
@@ -168,6 +181,8 @@ export interface CatalogLink {
   /** ISO 8601. */
   accepted_at: string;
   facts: CatalogFact[];
+  /** Independent of editable merchant SKU and revocable setup-policy acceptance. */
+  sku_reference?: CatalogSkuReference;
   /** Server-verified defaults adopted by the merchant; replayable without the current policy. */
   setup_policy?: CatalogSetupProvenance;
 }
@@ -204,6 +219,7 @@ export interface CatalogVariant {
   product_id: string;
   source: SourceRef;
   sku?: string;
+  sku_origin?: MerchantSkuOrigin;
   title: string;
   price: number;
   compare_at_price?: number;