@tokenoftrust/storefront-runner 4.5.0 → 4.6.1

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

@@ -18,8 +18,11 @@
  *   - `created_at` / `updated_at` / `migrated_at` / `source_checksum` are optional.
  *   - `variants[].inventory` is never read, and writers leave it out. Availability is hot data and
  *     lives behind the store's declared `inventory.provider`, never in a content file.
+ *   - `variants[].sku` follows the SKU contract (`./sku.mjs`): reader and writer trim it, a blank
+ *     one is no SKU, and one with a control character or over the length cap refuses the file.
  */
 import { validateRecord } from "./model.mjs";
+import { parseSku, skuFindings } from "./sku.mjs";
 
 /** Store-relative directories, one per record kind. */
 export const CATALOG_CONTENT_DIRS = {
@@ -66,14 +69,37 @@ export function classifyCatalogPath(relative) {
 
 // --- Writing ----------------------------------------------------------------------------------
 
-/** A record as its file holds it: every variant's `inventory` left out. */
+/**
+ * A variant's SKU in its stored form: trimmed, a blank one removed. A SKU the contract refuses is
+ * left as written so the validator names it.
+ */
+function storedSkuVariant(variant) {
+  if (!isObject(variant) || typeof variant.sku !== "string") return variant;
+  const parsed = parseSku(variant.sku);
+  if (parsed.ok) return parsed.sku === variant.sku ? variant : { ...variant, sku: parsed.sku };
+  if (parsed.reason !== "empty") return variant;
+  const { sku: _blank, ...rest } = variant;
+  return rest;
+}
+
+/** Every refused variant SKU in a product record, as validator issues. */
+function skuIssues(record) {
+  if (!isObject(record) || !Array.isArray(record.variants)) return [];
+  return record.variants.flatMap((variant, index) =>
+    isObject(variant) && variant.sku !== undefined
+      ? skuFindings(variant.sku).filter((f) => f.level === "error").map((f) => `variants[${index}].sku: ${f.message}`)
+      : [],
+  );
+}
+
+/** A record as its file holds it: every variant's `inventory` left out, every SKU stored form. */
 export function catalogFileRecord(kind, record) {
   if (kind !== "product" || !isObject(record) || !Array.isArray(record.variants)) return record;
   return {
     ...record,
     variants: record.variants.map((variant) => {
       if (!isObject(variant)) return variant;
-      const { inventory: _inventory, ...rest } = variant;
+      const { inventory: _inventory, ...rest } = storedSkuVariant(variant);
       return rest;
     }),
   };
@@ -157,7 +183,7 @@ function stamp(kind, doc, tenantScope, availability) {
     const productId = typeof doc.id === "string" ? doc.id : "";
     out.variants = doc.variants.map((variant) =>
       isObject(variant)
-        ? { ...variant, tenant_id: tenantScope, product_id: productId, inventory: { ...availability } }
+        ? { ...storedSkuVariant(variant), tenant_id: tenantScope, product_id: productId, inventory: { ...availability } }
         : variant,
     );
   }
@@ -185,6 +211,7 @@ function parse(relative, raw, tenantScope, availability) {
   const issues = validateRecord(where.kind === "product" ? "CatalogProduct" : "CatalogCollection", record).map(
     (i) => (i.path ? `${i.path}: ${i.message}` : i.message),
   );
+  if (where.kind === "product") issues.push(...skuIssues(record));
   if (isObject(doc) && typeof doc.handle === "string" && doc.handle !== where.handle) {
     issues.push(`handle: "${doc.handle}" does not match the file name "${where.handle}.json"`);
   }

package/agency-kit/tools/lib/catalog-model/sku.d.mts

@@ -0,0 +1,16 @@
+export const SKU_MAX_LENGTH: number;
+export const CHECKOUT_CODE_MAX_LENGTH: number;
+export const SKU_TOKEN_MAX_LENGTH: number;
+export type SkuRefusal = "not-string" | "empty" | "control-character" | "too-long";
+export function parseSku(value: unknown): { ok: true; sku: string } | { ok: false; reason: SkuRefusal };
+export function isStoredSku(value: unknown): value is string;
+export function skuKey(sku: string): string;
+export function skuToken(sku: string): string;
+export function skuFromToken(token: unknown): string | null;
+export interface SkuFinding {
+  level: "error" | "warning";
+  code: string;
+  message: string;
+}
+export function skuFindings(value: unknown): SkuFinding[];
+export function skuCollisions<T extends { sku: string }>(entries: Iterable<T>): Array<{ key: string; entries: T[] }>;

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

@@ -0,0 +1,146 @@
+/**
+ * The SKU contract: one rule for every reader and writer of a merchant's SKU.
+ *
+ * A SKU is merchant data, kept exactly as the merchant wrote it. The only rewrite is trimming
+ * leading and trailing whitespace on the way in. A SKU is refused only when it is empty, carries a
+ * control character, or is longer than {@link SKU_MAX_LENGTH} characters. Anything else, a space
+ * included, is a valid SKU; a space is a lint warning, never an error.
+ *
+ * Two SKUs are the same SKU when their {@link skuKey} is equal: trimmed, NBSP read as a space, and
+ * case-folded. The key is for comparison only and is never stored.
+ *
+ * A SKU is never used raw where a boundary needs a safe token (a path, a file name, a URL segment,
+ * a checkout product code). {@link skuToken} is the one encoding for those boundaries: reversible,
+ * injective, and the identity for a SKU of letters, digits, `.`, `_` and `-`.
+ *
+ * Pure: no filesystem, no network, no dependencies. `packages/cli/src/sku.mjs` is a byte-identical
+ * copy (the CLI installs without the kit), pinned by `packages/cli/test/sku-copy.test.mjs`.
+ */
+
+/** Longest SKU accepted, in characters (code points). */
+export const SKU_MAX_LENGTH = 250;
+/** The checkout provider's product-code limit; a longer {@link skuToken} is a lint warning. */
+export const CHECKOUT_CODE_MAX_LENGTH = 200;
+/** Longest {@link skuToken} any SKU can produce (four UTF-8 bytes, three characters each). */
+export const SKU_TOKEN_MAX_LENGTH = SKU_MAX_LENGTH * 12;
+
+const CONTROL = /\p{Cc}/u;
+const WHITESPACE = /\s/u;
+const TOKEN_SAFE = /^[A-Za-z0-9._-]$/;
+const TOKEN = /^(?:[A-Za-z0-9._-]|%[0-9A-F]{2})+$/;
+
+/**
+ * Read a SKU as it arrives from a merchant, a file or an import.
+ *
+ * @param {unknown} value
+ * @returns {{ ok: true, sku: string } | { ok: false, reason: "not-string" | "empty" | "control-character" | "too-long" }}
+ */
+export function parseSku(value) {
+  if (typeof value !== "string") return { ok: false, reason: "not-string" };
+  const sku = value.trim();
+  if (sku === "") return { ok: false, reason: "empty" };
+  if (CONTROL.test(sku)) return { ok: false, reason: "control-character" };
+  if ([...sku].length > SKU_MAX_LENGTH) return { ok: false, reason: "too-long" };
+  return { ok: true, sku };
+}
+
+/** True when `value` is a SKU in its stored form: valid and already trimmed. */
+export function isStoredSku(value) {
+  const parsed = parseSku(value);
+  return parsed.ok && parsed.sku === value;
+}
+
+/** The comparison key two SKUs share when they are the same SKU. Never stored. */
+export function skuKey(sku) {
+  return String(sku).replace(/ /g, " ").trim().toLowerCase();
+}
+
+/**
+ * The SKU as a token safe in a path, file name, URL segment or checkout product code. Letters,
+ * digits, `.`, `_` and `-` pass through; every other character is its UTF-8 bytes as `%XX`.
+ */
+export function skuToken(sku) {
+  let out = "";
+  for (const char of String(sku)) {
+    if (TOKEN_SAFE.test(char)) {
+      out += char;
+      continue;
+    }
+    for (const byte of new TextEncoder().encode(char)) out += `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+  }
+  return out;
+}
+
+/** The stored SKU a {@link skuToken} encodes, or null when `token` is not one. */
+export function skuFromToken(token) {
+  if (typeof token !== "string" || token.length > SKU_TOKEN_MAX_LENGTH || !TOKEN.test(token)) return null;
+  const bytes = [];
+  for (let i = 0; i < token.length; i += 1) {
+    if (token[i] === "%") {
+      bytes.push(Number.parseInt(token.slice(i + 1, i + 3), 16));
+      i += 2;
+    } else {
+      bytes.push(token.charCodeAt(i));
+    }
+  }
+  // Bytes that are not UTF-8 decode to U+FFFD, whose token differs, so the round trip refuses them.
+  const sku = new TextDecoder().decode(new Uint8Array(bytes));
+  return isStoredSku(sku) && skuToken(sku) === token ? sku : null;
+}
+
+const REASONS = {
+  "not-string": "a SKU must be text",
+  empty: "a SKU cannot be empty",
+  "control-character": "a SKU cannot contain a control character (tab, newline, ...)",
+  "too-long": `a SKU is at most ${SKU_MAX_LENGTH} characters`,
+};
+
+/**
+ * Lint findings for one SKU. `error` means the SKU is refused; `warning` means it works.
+ *
+ * @param {unknown} value
+ * @returns {Array<{ level: "error" | "warning", code: string, message: string }>}
+ */
+export function skuFindings(value) {
+  const parsed = parseSku(value);
+  if (!parsed.ok) return [{ level: "error", code: `sku-${parsed.reason}`, message: REASONS[parsed.reason] }];
+  /** @type {Array<{ level: "error" | "warning", code: string, message: string }>} */
+  const findings = [];
+  if (parsed.sku !== value) {
+    findings.push({ level: "warning", code: "sku-untrimmed", message: "leading or trailing whitespace is trimmed when the SKU is read" });
+  }
+  if (WHITESPACE.test(parsed.sku)) {
+    findings.push({
+      level: "warning",
+      code: "sku-whitespace",
+      message: "works, but we recommend against spaces in a SKU: spreadsheets, scanners and other systems often trim or split on them",
+    });
+  }
+  if (skuToken(parsed.sku).length > CHECKOUT_CODE_MAX_LENGTH) {
+    findings.push({
+      level: "warning",
+      code: "sku-checkout-code-long",
+      message: `its checkout product code is longer than ${CHECKOUT_CODE_MAX_LENGTH} characters, which the checkout provider may refuse`,
+    });
+  }
+  return findings;
+}
+
+/**
+ * SKUs that are the same SKU under {@link skuKey}. Each group lists every entry that shares a key.
+ *
+ * @template {{ sku: string }} T
+ * @param {Iterable<T>} entries
+ * @returns {Array<{ key: string, entries: T[] }>}
+ */
+export function skuCollisions(entries) {
+  /** @type {Map<string, T[]>} */
+  const groups = new Map();
+  for (const entry of entries) {
+    const key = skuKey(entry.sku);
+    const group = groups.get(key);
+    if (group) group.push(entry);
+    else groups.set(key, [entry]);
+  }
+  return [...groups].filter(([, group]) => group.length > 1).map(([key, group]) => ({ key, entries: group }));
+}

package/apps/storefront/src/lib/inventory/allocations.ts

@@ -15,12 +15,12 @@ import {
   type PaymentState,
   type StockState,
 } from "@tot/public-runtime";
+import { isStoredSku } from "@tot/public-runtime/sku";
 
 export const RESERVATION_AUTHORITY_HEADER = "x-tot-reservation-authority";
 export const RESERVATION_AUTHORITY_NONE = "none";
 export const VERIFICATION_PROVIDER_OWNER = "tot-9577-tot-verification-provider";
 
-const SKU_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
 const ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
 const TENANT_RE = /^[a-z0-9][a-z0-9.-]{0,253}$/;
 const LOCATION_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,80}$/;
@@ -153,7 +153,7 @@ export function readMirrorAuthority(value: unknown): MirrorStockAuthority | null
   const record = value as Record<string, unknown>;
   if (record.provider !== "mirror" || record.readable !== true) return null;
   if (typeof record.locationId !== "string" || !LOCATION_RE.test(record.locationId)) return null;
-  if (typeof record.sku !== "string" || !SKU_RE.test(record.sku)) return null;
+  if (typeof record.sku !== "string" || !isStoredSku(record.sku)) return null;
   if (typeof record.onHand !== "number" || !Number.isSafeInteger(record.onHand) || record.onHand < 0) return null;
   if (typeof record.asOf !== "string" || record.asOf.trim() === "" || record.asOf.length > 40) return null;
   return {
@@ -252,7 +252,7 @@ function reserveShape(input: ReserveInput): ReserveResult | null {
   if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor < 0) return { ok: false, finding: "malformed-request" };
   if (input.holds.length < 1) return { ok: false, finding: "malformed-request" };
   for (const hold of input.holds) {
-    if (!SKU_RE.test(hold.sku) || !LOCATION_RE.test(hold.locationId)) return { ok: false, finding: "malformed-request" };
+    if (!isStoredSku(hold.sku) || !LOCATION_RE.test(hold.locationId)) return { ok: false, finding: "malformed-request" };
     if (!Number.isSafeInteger(hold.quantity) || hold.quantity < 1) return { ok: false, finding: "malformed-request" };
     if (!Number.isSafeInteger(hold.onHand) || hold.onHand < 0) return { ok: false, finding: "malformed-request" };
   }

package/apps/storefront/src/lib/inventory/mirrorStock.ts

@@ -1,6 +1,7 @@
 /** Tenant-scoped inventory authority. Catalog availability never supplies a balance. */
 import type { Queryable } from "../catalog/d1/catalog.js";
 import type { CommerceStage } from "@tot/public-runtime";
+import { isStoredSku } from "@tot/public-runtime/sku";
 import type { MirrorStockAuthority } from "./allocations.js";
 
 const ID = /^[A-Za-z0-9._:-]{1,128}$/;
@@ -25,9 +26,10 @@ export interface MirrorMovement {
 }
 export async function appendMirrorMovement(db: Queryable, input: MirrorMovement): Promise<void> {
   if (
-    ![input.tenantId, input.source, input.sourceEventId, input.sku, input.locationId, input.actorId].every((v) =>
+    ![input.tenantId, input.source, input.sourceEventId, input.locationId, input.actorId].every((v) =>
       ID.test(v),
     ) ||
+    !isStoredSku(input.sku) ||
     !Number.isSafeInteger(input.quantityDelta) ||
     !Number.isFinite(Date.parse(input.asOf)) ||
     !["preview", "publication"].includes(input.stage)

package/apps/storefront/src/lib/orders/admin/orderSource.ts

@@ -0,0 +1,342 @@
+/**
+ * Where a tenant's admin reads its orders. Resolved once per request, so the Orders tab, the
+ * `/api/admin/orders` routes and the sidebar status always describe the same connection.
+ *
+ * A tenant admitted to the shared ToT checkout store (checkout's `admitSharedStoreTenant`, the
+ * same admission the signed order intake applies) has its paid orders forwarded into the platform
+ * ledger (`STOREFRONT_APPS_DB`, `scrappy_commerce_orders`) under this Worker's `COMMERCE_STAGE`.
+ * The shared store's partner API returns every tenant's transactions unfiltered, so the ledger is
+ * the only per-tenant record for that tenant. A tenant on its own FoxyCart store reads that
+ * store's partner API with `FOXY_ORDER_API_KEY`.
+ *
+ * The ledger carries no customer identity and no address (the intake refuses both), so a ledger
+ * order names no customer and has no shipping address here.
+ */
+import type {
+  CheckoutOrderDetail,
+  CheckoutOrderFulfillment,
+  CheckoutOrderListFilters,
+  CheckoutOrderListResponse,
+  CheckoutOrderPayment,
+  CheckoutOrderSummary,
+  CommerceScope,
+  CommerceStage,
+  CustomizationEnv,
+  PaymentState,
+} from "@tot/public-runtime";
+import { evidencePermitsRelease, paginateOrders } from "@tot/public-runtime";
+import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
+import { readD1, readEnv } from "@/lib/publication/shared/env";
+import { fromD1, type Queryable } from "@/lib/catalog/d1/catalog.js";
+import { ScrappyOrderLedger, type CommerceOrderBookEntry } from "../data/ordersStore.js";
+import { foldCommerceEvents, type CommerceSourceEvent } from "../data/orderMapper.js";
+import {
+  OrderApiError,
+  createCheckoutOrderClient,
+  orderApiBaseUrl,
+  type CheckoutOrderClient,
+} from "./orderClient";
+
+/** Why a tenant has no order source. Each names what connects it. */
+export type OrderSourceGap = "no-tenant" | "stage-unknown" | "ledger-unavailable" | "partner-key-missing";
+
+/** Ledger health: when the last paid order arrived, and reservations no payment has confirmed. */
+export interface LedgerSyncStatus {
+  orders: number;
+  lastOrderAt: string | null;
+  unconfirmed: { count: number; oldestAt: string | null };
+}
+
+/** Which FoxyCart store takes this tenant's payments, or null when no store is selected. */
+export type CheckoutStore = "shared-test-store" | "own-store" | null;
+
+export type OrderSource =
+  | {
+      kind: "ledger";
+      checkout: "shared-test-store";
+      scope: CommerceScope;
+      client: CheckoutOrderClient;
+      status: (now?: Date) => Promise<LedgerSyncStatus>;
+    }
+  | { kind: "partner-api"; checkout: "own-store"; scope: CommerceScope; client: CheckoutOrderClient }
+  | { kind: "not-connected"; checkout: CheckoutStore; gap: OrderSourceGap };
+
+export interface OrderSourceDeps {
+  admitSharedStoreTenant: (tenantId: string) => Promise<{ ok: boolean }>;
+  readEnv: (name: string) => Promise<string | undefined>;
+  readLedgerDb: () => Promise<Queryable | null>;
+}
+
+/**
+ * Worker deps. The caller passes checkout's `admitSharedStoreTenant`, the same admission the
+ * signed order intake applies, so reading and writing the ledger cannot disagree on who is in it.
+ */
+export function workerOrderSourceDeps(
+  admitSharedStoreTenant: OrderSourceDeps["admitSharedStoreTenant"],
+): OrderSourceDeps {
+  return {
+    admitSharedStoreTenant,
+    readEnv: async (name) => (await readEnv(name)) ?? undefined,
+    readLedgerDb: async () => {
+      const d1 = await readD1("STOREFRONT_APPS_DB");
+      return d1 ? fromD1(d1) : null;
+    },
+  };
+}
+
+export async function resolveOrderSource(
+  input: { tenantId: string; customizationEnv: CustomizationEnv | undefined },
+  deps: OrderSourceDeps,
+): Promise<OrderSource> {
+  const tenantId = input.tenantId.trim();
+  if (!tenantId) return { kind: "not-connected", checkout: null, gap: "no-tenant" };
+
+  if ((await deps.admitSharedStoreTenant(tenantId)).ok) {
+    const checkout = "shared-test-store";
+    const stage = await deps.readEnv("COMMERCE_STAGE");
+    if (stage !== "preview" && stage !== "publication") return { kind: "not-connected", checkout, gap: "stage-unknown" };
+    const db = await deps.readLedgerDb();
+    if (!db) return { kind: "not-connected", checkout, gap: "ledger-unavailable" };
+    const book = ledgerOrderBook(new ScrappyOrderLedger(db), { tenantId, stage });
+    return { kind: "ledger", checkout, scope: { tenantId, stage }, client: book.client, status: book.status };
+  }
+
+  const checkout = "own-store";
+  const stage = commerceStageForEnv(input.customizationEnv);
+  if (!stage) return { kind: "not-connected", checkout, gap: "stage-unknown" };
+  const bearer = await deps.readEnv("FOXY_ORDER_API_KEY");
+  if (!bearer) return { kind: "not-connected", checkout, gap: "partner-key-missing" };
+  return {
+    kind: "partner-api",
+    checkout,
+    scope: { tenantId, stage },
+    client: createCheckoutOrderClient({
+      baseUrl: orderApiBaseUrl(input.customizationEnv ?? "test"),
+      appDomain: tenantId,
+      bearer,
+    }),
+  };
+}
+
+/** Merchant copy for a gap: what is missing and who connects it. */
+export function orderSourceGapMessage(gap: OrderSourceGap): string {
+  switch (gap) {
+    case "no-tenant":
+      return "No store is selected.";
+    case "stage-unknown":
+      return "This environment does not declare a commerce stage, so it has no order record to read. Token of Trust support connects it.";
+    case "ledger-unavailable":
+      return "The platform order ledger is not bound in this environment. Token of Trust support connects it.";
+    case "partner-key-missing":
+      return "This store checks out on its own FoxyCart store, and its partner API key is not provisioned on the platform. Token of Trust support provisions it.";
+  }
+}
+
+export interface OrderSyncHealth {
+  value: "Not connected" | "Connected" | "Check";
+  detail: string;
+}
+
+/** The sidebar's order-sync row, from the same source the Orders tab reads. */
+export function orderSyncHealth(source: OrderSource, status: LedgerSyncStatus | null): OrderSyncHealth {
+  if (source.kind === "not-connected") return { value: "Not connected", detail: orderSourceGapMessage(source.gap) };
+  if (source.kind === "partner-api" || !status) return { value: "Connected", detail: "Reads this store's checkout orders." };
+  if (status.unconfirmed.count > 0) {
+    const n = status.unconfirmed.count;
+    return {
+      value: "Check",
+      detail: `${n} checkout${n === 1 ? "" : "s"} in the last 7 days passed final cart with no payment confirmation received.`,
+    };
+  }
+  return {
+    value: "Connected",
+    detail: status.lastOrderAt ? `Last paid order ${status.lastOrderAt}.` : "No paid orders yet.",
+  };
+}
+
+/** The sidebar's checkout row: which store takes this tenant's payments. */
+export function checkoutStoreLabel(checkout: CheckoutStore): string {
+  if (checkout === "shared-test-store") return "Test store";
+  if (checkout === "own-store") return "Own store";
+  return "Not connected";
+}
+
+/** The ledger's money is integer minor units of a two-decimal currency. */
+function toMajor(minor: number): number {
+  return minor / 100;
+}
+
+/** Provider timestamps arrive with a colonless offset; compare and page on one ISO form. */
+function isoInstant(value: string): string {
+  const parsed = new Date(value);
+  return Number.isNaN(parsed.getTime()) ? value : parsed.toISOString();
+}
+
+function paymentOf(payment: PaymentState): CheckoutOrderPayment {
+  if (payment === "captured") return "captured";
+  if (payment === "refunded" || payment === "refund_requested" || payment === "refund_unknown" || payment === "voided") {
+    return "refunded";
+  }
+  return "authorized";
+}
+
+interface LedgerOrder {
+  summary: CheckoutOrderSummary;
+  detail: CheckoutOrderDetail;
+}
+
+function ledgerOrder(entry: CommerceOrderBookEntry): LedgerOrder {
+  const placedAt = isoInstant(entry.placedAt);
+  const snapshot = entry.events.length > 0 ? foldCommerceEvents(entry.events) : null;
+  const payment = snapshot?.payment ?? entry.payment;
+  const fulfillment = snapshot?.fulfillment ?? entry.fulfillment;
+  const evidence = snapshot?.verificationDetail ?? { verification: "UNKNOWN", tax: "UNKNOWN", risk: "UNKNOWN", stock: "UNKNOWN" };
+  const totals = snapshot?.totals ?? { subtotalMinor: entry.amountMinor, shippingMinor: 0, taxMinor: 0, totalMinor: entry.amountMinor };
+  const lines =
+    [...entry.events].sort((a, b) => b.eventVersion - a.eventVersion).find((event) => event.lines?.length)?.lines ?? [];
+
+  const releasable = payment === "captured" && evidencePermitsRelease(evidence);
+  let state: CheckoutOrderFulfillment;
+  let blocker: string | null = null;
+  if (fulfillment === "handed_off") state = "completed";
+  else if (fulfillment === "cancelled") {
+    state = "completed";
+    blocker = "Cancelled";
+  } else if (fulfillment === "UNKNOWN") state = "unfulfilled";
+  else if (fulfillment === "ready" && releasable) state = "ready_to_ship";
+  else {
+    state = "hold_review_required";
+    blocker = payment !== "captured" ? "Payment capture" : evidencePermitsRelease(evidence) ? "Manual review" : "Evidence review";
+  }
+
+  const itemCount = lines.reduce((sum, line) => sum + line.quantity, 0);
+  const itemsSummary =
+    lines.length === 0 ? "Items not recorded" : lines.length === 1 ? lines[0]!.sku : `${lines[0]!.sku} +${lines.length - 1} more`;
+  const verification: Record<string, string> = {};
+  for (const key of ["verification", "tax", "risk", "stock"] as const) {
+    verification[key] = evidence[key];
+    verification[`${key}Source`] = "commerce-ledger";
+    verification[`${key}AsOf`] = placedAt;
+  }
+
+  const summary: CheckoutOrderSummary = {
+    id: entry.orderId,
+    placedAt,
+    currency: entry.currency,
+    customer: { id: null, name: "Checkout customer" },
+    itemsSummary,
+    itemCount,
+    total: toMajor(totals.totalMinor),
+    payment: paymentOf(payment),
+    fulfillment: state,
+    blocker,
+    verification,
+  };
+  return {
+    summary,
+    detail: {
+      ...summary,
+      lineItems: lines.map((line) => ({ sku: line.sku, name: line.sku, quantity: line.quantity, unitPrice: toMajor(line.unitMinor) })),
+      totals: {
+        subtotal: toMajor(totals.subtotalMinor),
+        shipping: toMajor(totals.shippingMinor),
+        estimatedTax: toMajor(totals.taxMinor),
+        taxesAndFees: 0,
+        total: toMajor(totals.totalMinor),
+      },
+      shippingAddress: null,
+      verificationDetail: { readinessChecks: [], evidenceTimeline: [] },
+    },
+  };
+}
+
+function matchesQueue(order: CheckoutOrderSummary, queue: string | undefined): boolean {
+  switch (queue) {
+    case undefined:
+    case "all":
+      return true;
+    case "needs_attention":
+      return order.fulfillment === "hold_review_required";
+    case "ready_to_ship":
+      return order.fulfillment === "ready_to_ship";
+    case "unfulfilled":
+      return order.fulfillment === "hold_review_required" || order.fulfillment === "ready_to_ship";
+    case "completed":
+      return order.fulfillment === "completed";
+    default:
+      return false;
+  }
+}
+
+function listLimit(limit: number | undefined): number {
+  if (limit === undefined || !Number.isFinite(limit)) return 25;
+  return Math.min(100, Math.max(1, Math.trunc(limit)));
+}
+
+/** A shopper who abandons at payment leaves a reservation too, so only recent ones are reported. */
+export const UNCONFIRMED_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+/**
+ * Paid orders and sync status over one tenant's ledger book, read once per request. A `scrappy`
+ * reservation is never listed as an order; one from the last seven days that no provider event
+ * has confirmed is reported as waiting on payment confirmation.
+ */
+export function ledgerOrderBook(
+  ledger: Pick<ScrappyOrderLedger, "readOrderBook">,
+  scope: { tenantId: string; stage: CommerceStage },
+): { client: CheckoutOrderClient; status: (now?: Date) => Promise<LedgerSyncStatus> } {
+  let loaded: Promise<{ orders: LedgerOrder[]; unconfirmed: CommerceOrderBookEntry[] }> | null = null;
+  const load = () =>
+    (loaded ??= ledger.readOrderBook(scope.tenantId, scope.stage).then((book) => {
+      const paid = book.filter((entry) => entry.source !== "scrappy");
+      const confirmed = new Set(
+        paid.flatMap((entry) => entry.events.map((event: CommerceSourceEvent) => event.admissionReference)).filter(Boolean),
+      );
+      return {
+        orders: paid.map(ledgerOrder),
+        unconfirmed: book.filter((entry) => entry.source === "scrappy" && !confirmed.has(entry.orderId)),
+      };
+    }));
+
+  const client: CheckoutOrderClient = {
+    async listOrders(filters?: CheckoutOrderListFilters): Promise<CheckoutOrderListResponse> {
+      const { orders } = await load();
+      const from = filters?.from ? isoInstant(filters.from) : null;
+      const to = filters?.to ? isoInstant(filters.to) : null;
+      const matching = orders
+        .map((order) => order.summary)
+        .filter((order) => matchesQueue(order, filters?.queue))
+        .filter((order) => !filters?.status || order.payment === filters.status)
+        .filter((order) => (!from || order.placedAt >= from) && (!to || order.placedAt < to));
+      const limit = listLimit(filters?.limit);
+      const page = paginateOrders(matching, limit, filters?.cursor ?? null);
+      return {
+        orders: page.orders,
+        page: { limit, cursor: filters?.cursor ?? null, nextCursor: page.nextCursor, total: matching.length },
+      };
+    },
+    async getOrder(orderId: string): Promise<CheckoutOrderDetail> {
+      const { orders } = await load();
+      const found = orders.find((order) => order.summary.id === orderId);
+      if (!found) throw new OrderApiError("order_not_found", 404);
+      return found.detail;
+    },
+  };
+
+  const status = async (now: Date = new Date()): Promise<LedgerSyncStatus> => {
+    const { orders, unconfirmed } = await load();
+    const placed = orders.map((order) => order.summary.placedAt).sort();
+    const since = new Date(now.getTime() - UNCONFIRMED_WINDOW_MS).toISOString();
+    const waiting = unconfirmed
+      .map((entry) => isoInstant(entry.placedAt))
+      .filter((at) => at >= since)
+      .sort();
+    return {
+      orders: orders.length,
+      lastOrderAt: placed[placed.length - 1] ?? null,
+      unconfirmed: { count: waiting.length, oldestAt: waiting[0] ?? null },
+    };
+  };
+
+  return { client, status };
+}

package/apps/storefront/src/lib/orders/admin/services/orders.ts

@@ -52,7 +52,7 @@ import type {
 } from "../viewmodels/orders";
 import type { CheckoutOrderClient } from "../orderClient";
 
-const EVIDENCE_STATES: readonly EvidenceState[] = ["fresh", "UNKNOWN", "stale", "unreadable", "absent"];
+const EVIDENCE_STATES: readonly EvidenceState[] = ["fresh", "not-required", "UNKNOWN", "stale", "unreadable", "absent"];
 const REFUND_PAYMENTS: ReadonlySet<PaymentState> = new Set(["refunded", "refund_requested", "refund_unknown"]);
 
 export interface SourcedState<T extends string = string> {

package/apps/storefront/src/lib/orders/data/orderMapper.ts

@@ -8,6 +8,7 @@
  * internals — and never lets a raw customer identifier leave this module:
  * customer identity is always the per-(tenant, install) `customerHash`.
  */
+import { skuFromToken } from "@tot/public-runtime/sku";
 import { customerHash } from "../../integrations/apps/orders/customerHash.js";
 import type { FoxyOrder, FoxyOrderLineItem } from "../providers/foxyOrderClient.js";
 import {
@@ -82,9 +83,10 @@ function toIsoDateTime(foxyDate: string): string {
   return Number.isNaN(parsed.getTime()) ? foxyDate : parsed.toISOString();
 }
 
+/** The provider carries the signed checkout product code; the order names the stored SKU it encodes. */
 function toContractLineItem(item: FoxyOrderLineItem): ContractOrderLineItem {
   return {
-    sku: item.sku,
+    sku: skuFromToken(item.sku) ?? item.sku,
     quantity: item.quantity,
     lineTotal: item.totalPrice,
   };
@@ -264,11 +266,15 @@ export function normalizeCommerceEvent(value: unknown): CommerceSourceEvent | "m
   if (!(STOCK_STATES as readonly string[]).includes(stock)) return "malformed";
   if (!(FULFILLMENT_STATES as readonly string[]).includes(fulfillment)) return "malformed";
   if (!(LABEL_STATES as readonly string[]).includes(label)) return "malformed";
-  const lines = value.lines;
-  if (lines !== undefined && (!Array.isArray(lines) || lines.some(line => !isRecord(line) ||
-      typeof line.sku !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(line.sku) ||
+  // A line's `sku` arrives as the signed checkout product code and is kept as the line key it
+  // encodes, the key the admission record and the stock allocations carry.
+  const rawLines = value.lines;
+  if (rawLines !== undefined && (!Array.isArray(rawLines) || rawLines.some(line => !isRecord(line) ||
+      skuFromToken(line.sku) === null ||
       !Number.isSafeInteger(line.quantity) || Number(line.quantity) < 1 ||
       !Number.isSafeInteger(line.unitMinor) || Number(line.unitMinor) < 0))) return "malformed";
+  const lines = rawLines === undefined ? undefined : (rawLines as Record<string, unknown>[]).map(line =>
+    ({ ...line, sku: skuFromToken(line.sku)! }));
   for (const key of ["admissionReference", "providerCartDigest", "destinationDigest"] as const) {
     if (value[key] !== undefined && (typeof value[key] !== "string" || !/^[A-Za-z0-9._:-]{1,128}$/.test(value[key] as string))) return "malformed";
   }

package/apps/storefront/src/lib/orders/data/ordersStore.ts

@@ -222,6 +222,18 @@ export interface CommerceOrderQueryRow {
   eventVersion: number;
 }
 
+/** One ledger order row and the source events recorded for it. */
+export interface CommerceOrderBookEntry {
+  orderId: string;
+  source: string;
+  placedAt: string;
+  currency: string;
+  payment: PaymentState;
+  fulfillment: CommerceSnapshot["fulfillment"];
+  amountMinor: number;
+  events: CommerceSourceEvent[];
+}
+
 export interface CommerceAggregate {
   count: number;
   amountMinor: number;
@@ -468,6 +480,42 @@ export class ScrappyOrderLedger {
     return { count, amountMinor, byPayment };
   }
 
+  /**
+   * Every order row for one tenant and stage, each with the source events recorded for it. Two
+   * reads, never one per order. A `scrappy` row is a final-cart reservation, not a paid order: a
+   * provider event names it in `admissionReference` once that payment reaches the ledger.
+   */
+  async readOrderBook(tenantId: string, stage: CommerceStage): Promise<CommerceOrderBookEntry[]> {
+    const rows = await this.db.all<CommerceOrderRow>(
+      `SELECT * FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ?`,
+      tenantId,
+      stage,
+    );
+    const payloads = await this.db.all<{ order_id: string; payload: string }>(
+      `SELECT order_id, payload FROM scrappy_commerce_outbox WHERE tenant_id = ? AND stage = ?`,
+      tenantId,
+      stage,
+    );
+    const events = new Map<string, CommerceSourceEvent[]>();
+    for (const row of payloads) {
+      const parsed = JSON.parse(row.payload) as StoredCommercePayload;
+      if (!parsed.source) continue;
+      const list = events.get(row.order_id) ?? [];
+      list.push(parsed.source);
+      events.set(row.order_id, list);
+    }
+    return rows.map((row) => ({
+      orderId: row.order_id,
+      source: row.source,
+      placedAt: row.placed_at,
+      currency: row.currency,
+      payment: row.payment_state,
+      fulfillment: row.fulfillment_state,
+      amountMinor: row.amount_minor,
+      events: events.get(row.order_id) ?? [],
+    }));
+  }
+
   /** Reset one outbox row for this tenant and stage. Does not write another order. */
   async replayOutbox(tenantId: string, stage: CommerceStage, outboxId: string, now: string): Promise<boolean> {
     const row = await this.db.first<{ outbox_id: string }>(

package/apps/storefront/src/pages/api/admin/orders/[id].ts

@@ -1,23 +1,16 @@
 /**
  * `GET /api/admin/orders/:id` — one order's full detail for the Orders tab.
  *
- * Server-side proxy to checkout `GET /commerce/orders/:orderId` for the
- * resolved tenant + env. Bearer stays server-side. Address is included only
- * for an owner of this tenant and stage. Readiness is assessed, not inferred.
- * Read-only.
+ * Reads one order from the source `resolveOrderSource` picks for the resolved tenant + env.
+ * Any bearer stays server-side. Address is included only for an owner of this tenant and stage.
+ * Readiness is assessed, not inferred. Read-only.
  */
 import type { APIContext } from "astro";
-import { readEnv } from "@/lib/publication/shared/env";
 import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
-import {
-  commerceActorForAdmin,
-  createCheckoutOrderClient,
-  orderApiBaseUrl,
-  OrderApiError,
-  projectCheckoutOrder,
-} from "@/lib/orders/admin/orderClient";
+import { commerceActorForAdmin, OrderApiError, projectCheckoutOrder } from "@/lib/orders/admin/orderClient";
+import { resolveOrderSource, workerOrderSourceDeps } from "@/lib/orders/admin/orderSource";
+import { admitSharedStoreTenant } from "@/lib/checkout/commerce/sharedStoreAdmission";
 import { assessCheckoutOrder } from "@/lib/orders/admin/services/orders";
-import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
 
 export const prerender = false;
 
@@ -43,29 +36,21 @@ export async function GET(context: APIContext): Promise<Response> {
   const orderId = context.params.id;
   if (!orderId) return jsonError("order_not_found", 404);
 
-  const bearer = await readEnv("FOXY_ORDER_API_KEY");
-  if (!bearer) return jsonError("not_provisioned", 503);
-
-  const stage = commerceStageForEnv(customizationEnv);
-  if (!stage) return jsonError("stage-unknown", 409);
-  const tenantId = tenant.appDomain.trim();
-  if (!tenantId) return jsonError("not_provisioned", 503);
-
-  const client = createCheckoutOrderClient({
-    baseUrl: orderApiBaseUrl(customizationEnv),
-    appDomain: tenantId,
-    bearer,
-  });
+  const source = await resolveOrderSource(
+    { tenantId: tenant.appDomain, customizationEnv },
+    workerOrderSourceDeps(admitSharedStoreTenant),
+  );
+  if (source.kind === "not-connected") return jsonError(source.gap, source.gap === "stage-unknown" ? 409 : 503);
 
   try {
-    const scope = { tenantId, stage };
+    const scope = source.scope;
     const actor = commerceActorForAdmin({
-      tenantId,
-      stage,
+      tenantId: scope.tenantId,
+      stage: scope.stage,
       owner: access.entry.isOwnerViewer,
       admitted: access.entry.admitted,
     });
-    const order = projectCheckoutOrder(await client.getOrder(orderId), actor, scope);
+    const order = projectCheckoutOrder(await source.client.getOrder(orderId), actor, scope);
     const readiness = assessCheckoutOrder(order, scope);
     return new Response(JSON.stringify({ order, readiness }), { headers: JSON_HEADERS });
   } catch (err) {

package/apps/storefront/src/pages/api/admin/orders.ts

@@ -1,23 +1,19 @@
 /**
  * `GET /api/admin/orders` — internal admin route backing the Orders tab.
  *
- * Server-side proxy to the checkout order READ API for the resolved tenant +
- * environment. The per-tenant bearer key stays on the Worker (never in the
- * response); the browser only ever sees order DTO JSON. Read-only (scope-locks).
+ * Reads the tenant's orders from the source `resolveOrderSource` picks (the platform ledger for
+ * a shared-checkout tenant, the store's partner API otherwise). Any partner bearer key stays on
+ * the Worker (never in the response); the browser only ever sees order DTO JSON. Read-only.
  * The admin UI consumes this and maps the DTO → OrdersViewModel.
  *
  * Access control matches the rest of the admin surface (owned by the admin
  * host/approver layer) — same posture as `api/evidence.json.ts`; no new gate here.
  */
 import type { APIContext } from "astro";
-import { readEnv } from "@/lib/publication/shared/env";
 import { requireAdminApiEntry } from "@/lib/access/auth/adminApiGuard";
-import {
-  createCheckoutOrderClient,
-  orderApiBaseUrl,
-  OrderApiError,
-} from "@/lib/orders/admin/orderClient";
-import { commerceStageForEnv } from "@/lib/fulfillment/fulfillmentService";
+import { OrderApiError } from "@/lib/orders/admin/orderClient";
+import { resolveOrderSource, workerOrderSourceDeps } from "@/lib/orders/admin/orderSource";
+import { admitSharedStoreTenant } from "@/lib/checkout/commerce/sharedStoreAdmission";
 import { assessCheckoutOrder, parseOrderFilters } from "@/lib/orders/admin/services/orders";
 
 export const prerender = false;
@@ -43,34 +39,21 @@ export async function GET(context: APIContext): Promise<Response> {
   const access = await requireAdminApiEntry(context);
   if (!access.ok) return jsonError(access.reason, access.status);
 
-  const bearer = await readEnv("FOXY_ORDER_API_KEY");
-  if (!bearer) {
-    // Worker secret not provisioned for this env — a config error, not the
-    // caller's fault. Never echo the (missing) key.
-    return jsonError("not_provisioned", 503);
-  }
-
-  const stage = commerceStageForEnv(customizationEnv);
-  if (!stage) return jsonError("stage-unknown", 409);
-  const tenantId = tenant.appDomain.trim();
-  if (!tenantId) return jsonError("not_provisioned", 503);
-
-  const url = new URL(context.request.url);
   // Tenant comes from the host, never from a query parameter.
-  const filters = parseOrderFilters(url.searchParams);
+  const source = await resolveOrderSource(
+    { tenantId: tenant.appDomain, customizationEnv },
+    workerOrderSourceDeps(admitSharedStoreTenant),
+  );
+  // An unconnected source is a config gap, not the caller's fault. Never echo a key.
+  if (source.kind === "not-connected") return jsonError(source.gap, source.gap === "stage-unknown" ? 409 : 503);
 
-  const client = createCheckoutOrderClient({
-    baseUrl: orderApiBaseUrl(customizationEnv),
-    appDomain: tenantId,
-    bearer,
-  });
+  const filters = parseOrderFilters(new URL(context.request.url).searchParams);
 
   try {
-    const data = await client.listOrders(filters);
-    const scope = { tenantId, stage };
+    const data = await source.client.listOrders(filters);
     const orders = data.orders.map((order) => ({
       ...order,
-      readiness: assessCheckoutOrder(order, scope),
+      readiness: assessCheckoutOrder(order, source.scope),
     }));
     return new Response(JSON.stringify({ ...data, orders }), { headers: JSON_HEADERS });
   } catch (err) {

package/apps/storefront/src/pages/api/commerce/final-cart-authorization.ts

@@ -2,10 +2,11 @@
 import type { APIContext } from "astro";
 import { createLocalJWKSet, decodeProtectedHeader, jwtVerify, type JSONWebKeySet } from "jose";
 import {
-  commerceTenantId, totalsMatch, shippingMinorFor, isContentVersionId, catalogPinDigestFinding, cartLineCode,
+  commerceTenantId, totalsMatch, shippingMinorFor, isContentVersionId, catalogPinDigestFinding, cartLineKey,
   type CallerToken, type CatalogProduct, type CatalogVariant, type CommerceEvidence, type CommerceEvidenceProvenance,
   type CommerceProviderCartSnapshot, type FinalCartBinding, type TenantConfig,
 } from "@tot/public-runtime";
+import { skuFromToken } from "@tot/public-runtime/sku";
 import { fromD1 } from "@/lib/catalog/d1/catalog.js";
 import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
 import { evaluateFinalCart, type RefusedLine, type SeamView } from "@/lib/checkout/commerce/finalCartAuthorization.js";
@@ -72,7 +73,7 @@ function readSnapshot(value: unknown): CommerceProviderCartSnapshot | null {
       typeof v.providerCartDigest !== "string" || !HEX.test(v.providerCartDigest) || typeof v.destinationDigest !== "string" || !HEX.test(v.destinationDigest) ||
       typeof v.tenantId !== "string" || !["preview", "publication"].includes(String(v.stage)) || typeof v.currency !== "string" || !/^[A-Z]{3}$/.test(v.currency) ||
       !Array.isArray(v.lines) || v.lines.length < 1 || v.lines.length > 50) return null;
-  if (v.lines.some(line => !line || typeof line !== "object" || typeof line.sku !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/.test(line.sku) ||
+  if (v.lines.some(line => !line || typeof line !== "object" || skuFromToken(line.sku) === null ||
       !Number.isSafeInteger(line.quantity) || line.quantity < 1 || line.quantity > 99 || !Number.isSafeInteger(line.unitMinor) || line.unitMinor < 0 ||
       Object.keys(line).some(k => !["sku", "quantity", "unitMinor"].includes(k)))) return null;
   if (!v.totals || typeof v.totals !== "object" || Object.keys(v.totals).length !== 4 ||
@@ -84,6 +85,15 @@ function readSnapshot(value: unknown): CommerceProviderCartSnapshot | null {
   if (!totalsMatch(snapshot.totals) || snapshot.lines.reduce((sum, line) => sum + line.quantity * line.unitMinor, 0) !== snapshot.totals.subtotalMinor) return null;
   return snapshot;
 }
+/**
+ * The snapshot with each line's checkout product code read back to its line key (the stored SKU,
+ * or the variant id for a variant with none). The provider digest covers the codes as the caller
+ * sent them; everything after it — catalog match, stock, holds, the admission record — is keyed
+ * by the line key, the same key inventory movements carry.
+ */
+function keyedLines(wire: CommerceProviderCartSnapshot): CommerceProviderCartSnapshot {
+  return { ...wire, lines: wire.lines.map(line => ({ ...line, sku: skuFromToken(line.sku)! })) };
+}
 /**
  * The compliance seam under the shared test store's policy. When verification is required the
  * cart's verification ref goes to preflight, whose live provider re-reads its real status
@@ -97,8 +107,8 @@ async function seam(context: APIContext, snapshot: CommerceProviderCartSnapshot,
       getProductByHandle: async (handle: string) => selected.get(handle) ?? null,
     } } } as APIContext, {
       lines: snapshot.lines.map(line => {
-        const product = products.find(p => p.variants.some(v => cartLineCode(v) === line.sku))!;
-        const variant = product.variants.find(v => cartLineCode(v) === line.sku)!;
+        const product = products.find(p => p.variants.some(v => cartLineKey(v) === line.sku))!;
+        const variant = product.variants.find(v => cartLineKey(v) === line.sku)!;
         return { handle: product.handle, variantId: variant.id, sku: line.sku, quantity: line.quantity };
       }),
       destination: snapshot.destination,
@@ -170,9 +180,10 @@ async function authorize(context: APIContext): Promise<Response> {
   if (Number(context.request.headers.get("content-length") ?? 0) > 65536) return deny("malformed-request");
   const raw = await context.request.text();
   if (raw.length > 65536) return deny("malformed-request");
-  let snapshot: CommerceProviderCartSnapshot | null;
-  try { snapshot = readSnapshot(JSON.parse(raw)); } catch { snapshot = null; }
-  if (!snapshot) return deny("malformed-request");
+  let wire: CommerceProviderCartSnapshot | null;
+  try { wire = readSnapshot(JSON.parse(raw)); } catch { wire = null; }
+  if (!wire) return deny("malformed-request");
+  const snapshot = keyedLines(wire);
   const jwks = publicJwks(await readEnv("COMMERCE_CALLER_JWKS"));
   const issuers = list(await readEnv("COMMERCE_CALLER_ISSUERS"));
   const audience = await readEnv("COMMERCE_CALLER_AUDIENCE");
@@ -212,7 +223,7 @@ async function authorize(context: APIContext): Promise<Response> {
     : createContentProvider(tenant, { get: kvGet, env: contentEnv });
   const tot = await createToTClient(tenant, await readD1("CATALOG_DB"), content);
   const authorityContext = { ...context, locals: { ...context.locals, tenant, tot, content } } as APIContext;
-  const catalogPin = await catalogPinDigestFinding(snapshot);
+  const catalogPin = await catalogPinDigestFinding(wire);
   if (catalogPin) return deny(catalogPin);
   let listing: CatalogProduct[];
   try { listing = await tot.getAllActiveProducts(); } catch { return deny("catalog-unavailable", 503); }
@@ -220,9 +231,9 @@ async function authorize(context: APIContext): Promise<Response> {
   const selected = new Map<string, CatalogProduct>();
   const mismatch = (check: string, line?: number) => refuse("catalog-cart-mismatch", line === undefined ? { check } : { check, line });
   if (snapshot.currency !== resolveStoreCurrency(tenant.currency)) return mismatch("store-currency");
-  // A line's `sku` is the product code the page signed (`cartLineCode`): the SKU, or the
-  // variant id for a variant with none.
-  const coded = (line: { sku: string }) => (variant: CatalogVariant | null | undefined) => !!variant && cartLineCode(variant) === line.sku;
+  // A line's `sku` is the line key the page's signed product code encodes (`cartLineKey`): the
+  // stored SKU, or the variant id for a variant with none.
+  const coded = (line: { sku: string }) => (variant: CatalogVariant | null | undefined) => !!variant && cartLineKey(variant) === line.sku;
   for (const [index, line] of snapshot.lines.entries()) {
     const matches = listing.flatMap(product => product && product.status === "active" && (!product.visibility || product.visibility === "public") && product.tenant_id === tenant.tot_data_scope && Array.isArray(product.variants)
       ? product.variants.filter(coded(line)).map(variant => ({ product, variant })) : []);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.5.0",
+  "version": "4.6.1",
   "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/package.json

@@ -26,6 +26,7 @@
     "./image-release-gate": "./src/image-release-gate.ts",
     "./pool-asset-headers": "./src/pool-asset-headers.ts",
     "./catalog-files": "./src/catalog-files.ts",
+    "./sku": "./src/sku.ts",
     "./embed-catalog": "./src/embed-catalog.mjs",
     "./retention-holds": "./src/retention-holds.ts",
     "./publication-content-redirects": "./src/publication-content-redirects.ts",

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

@@ -28,6 +28,7 @@ import { resolveStoreCurrency } from "./declared-tenant-config.mjs";
 import { DEFAULT_ONE_TIME_PURCHASE_OPTION } from "./product.js";
 import type { ShippingPolicy, TenantConfig } from "./tenant.js";
 import { isContentVersionId } from "./checkout-orders.js";
+import { skuToken } from "./sku.js";
 
 /** Stable commerce scope shared by signed carts, provider callers and operator authorization. */
 export function commerceTenantId(tenant: Pick<TenantConfig, "appDomain">): string {
@@ -501,13 +502,22 @@ export function resolveManagedCheckout(
 }
 
 /**
- * The checkout product code for a variant: its SKU, or its id when it has none. Every field
- * is hashed against it, and the final-cart authority finds a cart line's variant by it.
+ * The line identity of a variant across commerce: its stored SKU, or its id when it has none.
+ * Cart lines, holds, allocations and inventory movements are all keyed by it.
  */
-export function cartLineCode(variant: Pick<CatalogVariant, "id" | "sku">): string {
+export function cartLineKey(variant: Pick<CatalogVariant, "id" | "sku">): string {
   return variant.sku && variant.sku.length ? variant.sku : variant.id;
 }
 
+/**
+ * The checkout product code for a variant: its {@link cartLineKey} as a `skuToken`, so a SKU with
+ * a space or any other character still makes a token-safe code. Every field is hashed against it;
+ * the final-cart authority reads it back with `skuFromToken`.
+ */
+export function cartLineCode(variant: Pick<CatalogVariant, "id" | "sku">): string {
+  return skuToken(cartLineKey(variant));
+}
+
 /**
  * The raw (unsigned) cart fields for a variant: name, price, code, image, the
  * variant's options, and an editable quantity. `code` is the checkout product code

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

@@ -0,0 +1,19 @@
+/**
+ * The SKU contract for the platform. It lives once, in the agency kit's pure catalog module
+ * (`agency-kit/tools/lib/catalog-model/sku.mjs`), which the catalog file reader, the kit's tools
+ * and this runtime all import.
+ */
+export {
+  CHECKOUT_CODE_MAX_LENGTH,
+  SKU_MAX_LENGTH,
+  SKU_TOKEN_MAX_LENGTH,
+  isStoredSku,
+  parseSku,
+  skuCollisions,
+  skuFindings,
+  skuFromToken,
+  skuKey,
+  skuToken,
+  type SkuFinding,
+  type SkuRefusal,
+} from "../../../agency-kit/tools/lib/catalog-model/sku.mjs";

package/scripts/dev/catalog-preview-refresh.mjs

@@ -276,6 +276,10 @@ function assertFixtureTree(path) {
   if (info.isDirectory()) for (const name of readdirSync(path)) assertFixtureTree(join(path, name));
 }
 
+export function assertPreviewBuildConfig(config) {
+  if (config.targetEnvironment !== "preview" || config.no_bundle !== true) throw fixedError("refresh_build_config_invalid");
+}
+
 function embedsSha(path, sha) {
   for (const entry of readdirSync(path, { withFileTypes: true })) {
     const file = join(path, entry.name);
@@ -373,10 +377,10 @@ export const realEffects = {
     for (const [path, hash] of Object.entries(pin.files)) {
       if (digest(execFileSync("git", ["-C", catalog, "show", `${options.catalogSha}:${path}`], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: 8 * 1024 * 1024 })) !== hash) throw fixedError("refresh_contract_hash_mismatch");
     }
-    if (prior.storefrontSha === options.storefrontSha) return {};
     for (const rel of e2eCatalogFixtures(prior.preview)) {
       if (existsSync(join(prior.preview, rel)) && git(prior.preview, "ls-tree", "-r", "--name-only", options.storefrontSha, "--", rel)) throw fixedError("refresh_fixture_tracked_collision");
     }
+    if (prior.storefrontSha === options.storefrontSha) return {};
     let checkout;
     let catalogCheckout;
     try {
@@ -409,7 +413,7 @@ export const realEffects = {
       if (git(checkout, "rev-parse", "HEAD") !== options.storefrontSha || git(checkout, "status", "--porcelain", "--untracked-files=no")) throw fixedError("refresh_build_source_changed");
       const config = JSON.parse(readFileSync(join(checkout, "apps/storefront/dist/server/wrangler.json"), "utf8"));
       if (!embedsSha(join(checkout, "apps/storefront/dist/server"), options.storefrontSha)) throw fixedError("refresh_build_ref_missing");
-      if (config.no_bundle !== true) throw fixedError("refresh_build_config_invalid");
+      assertPreviewBuildConfig(config);
       const priorConfig = JSON.parse(readFileSync(join(prior.checkout, "apps/storefront/dist/server/wrangler.json"), "utf8"));
       for (const key of ["d1_databases", "kv_namespaces", "r2_buckets", "durable_objects", "migrations"]) {
         if (JSON.stringify(config[key] ?? null) !== JSON.stringify(priorConfig[key] ?? null)) throw fixedError("refresh_state_bindings_changed");