@tokenoftrust/storefront-runner 4.2.1 → 4.2.3

package/apps/storefront/src/components/content/storefront/chrome/SiteFooter.astro

@@ -122,7 +122,7 @@ const collapsible = variant === "light-collapsible";
             <div class="mt-4 flex items-center gap-3">
               {social.map((s) => (
                 <a
-                  href={s.href}
+                  href={withBase(basePath, s.href)}
                   aria-label={s.label}
                   rel="noopener noreferrer"
                   class="text-muted transition-colors hover:text-primary"

package/apps/storefront/src/components/content/storefront/chrome/SiteHeader.astro

@@ -90,6 +90,7 @@ const {
 
 const { basePath } = Astro.locals;
 const homeHref = withBase(basePath, brandHref ?? "/");
+const searchFormAction = searchAction ? withBase(basePath, searchAction) : undefined;
 const showLogo = !!logo && /^(https?:|\/)/.test(logo.src);
 const dark = variant === "dark";
 const minimal = layout === "minimal";
@@ -205,11 +206,11 @@ const currentPath = Astro.url.pathname;
 
       <!-- Search (live typeahead island) -->
       {
-        !minimal && !compact && searchAction && (
+        !minimal && !compact && searchFormAction && (
           <div class="hidden flex-1 md:flex">
             <SearchTypeahead
               client:idle
-              action={searchAction}
+              action={searchFormAction}
               placeholder={searchPlaceholder}
               label={searchLabel}
             />
@@ -220,9 +221,9 @@ const currentPath = Astro.url.pathname;
       <!-- Actions: saved items + marketing CTAs + auth + account + cart (link only) + mobile menu -->
       <div class:list={["flex items-center gap-1", compact ? "col-start-3 justify-self-end" : "ml-auto"]}>
         {
-          compact && searchAction && (
+          compact && searchFormAction && (
             <a
-              href={withBase(basePath, searchAction)}
+              href={searchFormAction}
               aria-label={searchLabel ?? "Search"}
               class="hidden h-9 w-9 place-items-center rounded-full text-text transition-colors hover:text-accent-ink md:grid"
             >
@@ -281,7 +282,7 @@ const currentPath = Astro.url.pathname;
         {
           authLink && (
             <a data-mobile-menu-action
-              href={authLink.href}
+              href={withBase(basePath, authLink.href)}
               class="inline-flex shrink-0 items-center rounded-full border border-current px-4 py-2 font-display text-sm font-medium transition-opacity hover:opacity-80"
             >
               {authLink.label}
@@ -338,11 +339,11 @@ const currentPath = Astro.url.pathname;
   </div>
 
   {
-    compact && searchAction && (
+    compact && searchFormAction && (
       <div class="border-b border-border bg-surface px-4 py-2 md:hidden" data-header-phone-search>
         <SearchTypeahead
           client:idle
-          action={searchAction}
+          action={searchFormAction}
           placeholder={searchPlaceholder}
           label={searchLabel}
         />
@@ -387,8 +388,8 @@ const currentPath = Astro.url.pathname;
   compact && (
     <nav class:list={["fixed inset-x-0 bottom-0 z-50 grid h-[62px] border-t border-border bg-surface shadow-[0_-3px_14px_color-mix(in_srgb,var(--color-text)_10%,transparent)] md:hidden", cartHref ? "grid-cols-4" : "grid-cols-3"]} aria-label="Quick links">
       <a href={homeHref} class="flex flex-col items-center justify-center gap-0.5 text-[0.65rem] text-text">Home</a>
-      <a href={withBase(basePath, searchAction ?? "/search")} class="flex flex-col items-center justify-center gap-0.5 text-[0.65rem] text-text">Search</a>
-      <a href={accountHref ? withBase(basePath, accountHref) : (authLink?.href ?? "/auth/login")} class="flex flex-col items-center justify-center gap-0.5 text-[0.65rem] text-text">Account</a>
+      <a href={searchFormAction ?? withBase(basePath, "/search")} class="flex flex-col items-center justify-center gap-0.5 text-[0.65rem] text-text">Search</a>
+      <a href={withBase(basePath, accountHref ?? authLink?.href ?? "/auth/login")} class="flex flex-col items-center justify-center gap-0.5 text-[0.65rem] text-text">Account</a>
       {cartHref && <a href={withBase(basePath, cartHref)} class="flex flex-col items-center justify-center gap-0.5 text-[0.65rem] text-text">Cart</a>}
     </nav>
   )

package/apps/storefront/src/components/content/storefront/chrome/UtilityNav.astro

@@ -64,7 +64,7 @@ const linkStamp = (l: ChromeLink, index: number) =>
           <span class="flex items-center gap-3">
             {social.map((s) => (
               <a
-                href={s.href}
+                href={withBase(basePath, s.href)}
                 aria-label={s.label}
                 rel="noopener noreferrer"
                 class="transition-colors hover:text-primary"

package/apps/storefront/src/layouts/Layout.astro

@@ -29,7 +29,8 @@ import { organizationLd, websiteLd } from "@/lib/content/shared/jsonld";
 import { composeStructuredData, structuredDataProfile, type StructuredDataPage } from "@/lib/content/seo/structuredData";
 import { canonicalUrl } from "@/lib/content/seo/urlForm";
 import { documentTitle } from "@/lib/content/seo/documentTitle";
-import { nonceInlineTags, prefixApiFormActions, CHROME_BODY_MARKER } from "@/lib/content/shared/rawMarketingHtml";
+import { nonceInlineTags, prefixSharedChrome, CHROME_BODY_MARKER } from "@/lib/content/shared/rawMarketingHtml";
+import { withBase } from "@/lib/publication/shared/basePath";
 import { CHROME_BEHAVIOR_JS, CHROME_HEAD_JS, sanitizeSharedChromeFragment } from "@/lib/content/shared/rawChrome";
 import { ASYNC_CSS_SWAP_JS } from "@/lib/content/shared/asyncCss";
 import { reportTrackingChainHealth } from "@/lib/measurement/tracking/interactionHealth";
@@ -196,17 +197,19 @@ if (chromeHtml && chromeHtml.includes(CHROME_BODY_MARKER)) {
   const bodyEnd = chromeHtml.lastIndexOf("</body>");
   sharedChrome = {
     header: nonceInlineTags(
-      prefixApiFormActions(
+      prefixSharedChrome(
         sanitizeSharedChromeFragment(chromeHtml.slice(bodyOpen, marker)),
+        basePath,
         apiBasePath,
       ),
       cspNonce,
     ),
     footer: nonceInlineTags(
-      prefixApiFormActions(
+      prefixSharedChrome(
         sanitizeSharedChromeFragment(
           chromeHtml.slice(marker + CHROME_BODY_MARKER.length, bodyEnd >= 0 ? bodyEnd : undefined),
         ),
+        basePath,
         apiBasePath,
       ),
       cspNonce,
@@ -394,7 +397,9 @@ const footerWidgets = await renderWidgetSlot(
             layout={resolvedHeaderVariant}
             announcement={chrome.header.announcement?.messages[0]}
             searchAction={
-              features.productSearch ? (chrome.header.search?.action ?? "/search") : undefined
+              features.productSearch
+                ? withBase(basePath, chrome.header.search?.action ?? "/search")
+                : undefined
             }
             searchPlaceholder={chrome.header.search?.placeholder}
             searchLabel={chrome.header.search?.label}

package/apps/storefront/src/lib/catalog/tot/ToTClient.ts

@@ -29,6 +29,7 @@ import { fromD1, type D1Like } from "../d1/catalog.js";
 import { buildSearchIndex, type SearchIndex } from "../search/index.js";
 import type { ToTClient } from "./totClientInterface.js";
 import { readTenantCatalogFiles, type CatalogArtifactSource } from "./tenantCatalog.js";
+import { overlayProductInventory, type MirrorInventoryOverlay } from "../../inventory/mirrorStock.js";
 
 // The contract lives in its own module so d1Client can implement it without a
 // circular edge back to this file (which imports D1ToTClient for the factory).
@@ -192,6 +193,42 @@ class DeferredToTClient implements ToTClient {
   async getReviews(handle: string) { return (await this.resolved()).getReviews(handle); }
 }
 
+/** Applies an already-resolved ledger snapshot to every product the catalog client returns. */
+export function overlayCatalogClient(client: ToTClient, overlay: MirrorInventoryOverlay): ToTClient {
+  return new MirrorStockClient(client, overlay);
+}
+
+class MirrorStockClient implements ToTClient {
+  constructor(
+    private readonly inner: ToTClient,
+    private readonly overlay: MirrorInventoryOverlay,
+  ) {}
+
+  private product(product: CatalogProduct | null): CatalogProduct | null {
+    return product ? overlayProductInventory(product, this.overlay) : null;
+  }
+
+  private products(products: CatalogProduct[]): CatalogProduct[] {
+    return products.map((product) => overlayProductInventory(product, this.overlay));
+  }
+
+  async listProducts(query?: ListProductsQuery): Promise<ListProductsResponse> {
+    const page = await this.inner.listProducts(query);
+    return { ...page, products: this.products(page.products) };
+  }
+
+  async getProductByHandle(handle: string): Promise<CatalogProduct | null> {
+    return this.product(await this.inner.getProductByHandle(handle));
+  }
+
+  async listCollections() { return this.inner.listCollections(); }
+  async getCollectionByHandle(handle: string) { return this.inner.getCollectionByHandle(handle); }
+  async search(q: string, limit?: number) { return this.products(await this.inner.search(q, limit)); }
+  async getFeatured(limit?: number) { return this.products(await this.inner.getFeatured(limit)); }
+  async getAllActiveProducts() { return this.products(await this.inner.getAllActiveProducts()); }
+  async getReviews(handle: string) { return this.inner.getReviews(handle); }
+}
+
 /**
  * The tenant's catalog, selected by its declared `catalog.serving` (ADR 0033):
  *
@@ -209,24 +246,29 @@ export async function createToTClient(
   tenant: TenantConfig,
   d1?: D1Like,
   content?: CatalogArtifactSource,
+  overlay?: MirrorInventoryOverlay | null,
 ): Promise<ToTClient> {
+  let client: ToTClient;
   if (tenant.catalog?.serving === "d1") {
-    if (d1) return new D1ToTClient(fromD1(d1));
-    return new DeferredToTClient(async () => {
-      throw new Error(
-        `catalog: ${tenant.tenant_id} declares catalog.serving: "d1", and this render has no ` +
-          `D1 serving projection (public and static renders never read D1 per request, ADR 0013).`,
-      );
+    client = d1
+      ? new D1ToTClient(fromD1(d1))
+      : new DeferredToTClient(async () => {
+          throw new Error(
+            `catalog: ${tenant.tenant_id} declares catalog.serving: "d1", and this render has no ` +
+              `D1 serving projection (public and static renders never read D1 per request, ADR 0013).`,
+          );
+        });
+  } else {
+    client = new DeferredToTClient(async () => {
+      const files = await readTenantCatalogFiles(tenant, content);
+      if (files) {
+        return new FixtureToTClient(
+          files.products, files.collections, tenant.tot_data_scope, {}, files.productDetail,
+        );
+      }
+      const { products, collections, reviews } = await loadFixtures(tenant.tot_data_scope);
+      return new FixtureToTClient(products, collections, tenant.tot_data_scope, reviews);
     });
   }
-  return new DeferredToTClient(async () => {
-    const files = await readTenantCatalogFiles(tenant, content);
-    if (files) {
-      return new FixtureToTClient(
-        files.products, files.collections, tenant.tot_data_scope, {}, files.productDetail,
-      );
-    }
-    const { products, collections, reviews } = await loadFixtures(tenant.tot_data_scope);
-    return new FixtureToTClient(products, collections, tenant.tot_data_scope, reviews);
-  });
+  return overlay ? overlayCatalogClient(client, overlay) : client;
 }

package/apps/storefront/src/lib/checkout/commerce/checkoutHandoffRoute.ts

@@ -44,6 +44,9 @@ import {
 import { resolveCheckoutHandoffCorrelation } from "@/lib/checkout/commerce/checkoutHandoffCorrelation";
 import { bindCartSession, CART_UNAVAILABLE_MESSAGE, withCartSession } from "@/lib/checkout/commerce/cartSession";
 import { resolveCartSigning, shopperCartDenialMessage } from "@/lib/checkout/shared/checkoutCommerce";
+import { fromD1 } from "@/lib/catalog/d1/catalog";
+import { readD1 } from "@/lib/publication/shared/env";
+import { handoffStockFinding, MIRROR_LOCATION_UNSPECIFIED, readMirrorBalance } from "@/lib/inventory/mirrorStock";
 
 export type SampleProductReader = (tenant: TenantConfig, handle: string, commerce: ResolvedManagedCheckout) => Promise<CatalogProduct | null>;
 
@@ -125,6 +128,42 @@ async function sessionedCartLocation(
   return foxyCartRedirectUrl(withCartSession(commerce.cartUrl, fcsid), kept);
 }
 
+function ledgerStage(env: string | undefined): "preview" | "publication" | null {
+  if (env === "live") return "publication";
+  if (env === "test") return "preview";
+  return null;
+}
+
+function submittedCode(fields: readonly { name: string; value: string }[]): string | undefined {
+  return fields.find((field) => field.name.split("||")[0] === "code")?.value;
+}
+
+function stockUnavailable(): Response {
+  return new Response(JSON.stringify({ finding: "stock-unavailable" }), {
+    status: 409,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      "x-tot-payment-authorized": "false",
+    },
+  });
+}
+
+/** A non-positive ledger balance refuses the handoff. No stage, no sku, or no rows does not. */
+async function refuseSoldOut(context: APIContext, tenant: TenantConfig, sku: string | undefined): Promise<Response | null> {
+  const stage = ledgerStage(context.locals.customizationEnv);
+  if (!stage || !sku) return null;
+  const database = await readD1("STOREFRONT_APPS_DB");
+  if (!database) return null;
+  const reading = await readMirrorBalance(fromD1(database), {
+    tenantId: commerceTenantId(tenant),
+    stage,
+    sku,
+    locationId: MIRROR_LOCATION_UNSPECIFIED,
+  });
+  return handoffStockFinding(reading ? reading.balance : null) ? stockUnavailable() : null;
+}
+
 /**
  * The page the shopper submitted from, when it is served by this request's host or the tenant's
  * declared domain. The browser's Referer is the only source; a foreign or absent one yields none.
@@ -171,6 +210,8 @@ async function cartFormPost(context: APIContext): Promise<Response> {
     const status = result.code === "signing-unavailable" ? 503 : 422;
     return cartDenial(result.code, shopperCartDenialMessage(result.code, result.message), status);
   }
+  const soldOut = await refuseSoldOut(context, tenant, submittedCode(result.fields));
+  if (soldOut) return soldOut;
   const verified = await withVerificationRef(result.fields, { mode: commerce.mode, secret: signing.secret, ref });
   const shippable = await boundShippingPolicy(verified, tenant, commerce.mode, signing.secret);
   if (!shippable) return cartDenial("shipping", SHIPPING_UNAVAILABLE_CART_MESSAGE, 409);
@@ -271,8 +312,11 @@ export async function sampleCartGet(
     const product = await readProduct(tenant, productId, commerce);
     const variant = product?.variants.find(v => v.id === variantId);
     if (!product || product.status !== "active" || product.visibility === "hidden" || product.visibility === "unlisted" ||
-        !variant || !variant.inventory.available || product.tenant_id !== tenant.tot_data_scope ||
+        !variant || product.tenant_id !== tenant.tot_data_scope ||
         variant.tenant_id !== tenant.tot_data_scope) return invalid();
+    const soldOut = await refuseSoldOut(context, tenant, variant.sku);
+    if (soldOut) return soldOut;
+    if (!variant.inventory.available) return invalid();
     const signing = await resolveCartSigning(commerce);
     if (!signing.enabled) return sampleResponse('{"error":"sample_unavailable"}', 503);
     const payload = await buildVariantCartPayload(product, variant, {

package/apps/storefront/src/lib/content/shared/rawMarketingHtml.ts

@@ -3,11 +3,13 @@
  *
  * A marketing tenant can ship a self-contained document (`content/<tenant>/home.html`
  * or `content/<tenant>/pages-html/<slug>.html`) that we serve VERBATIM, bypassing the
- * block Layout. Two transforms are applied at serve time:
+ * block Layout. Three transforms are applied at serve time:
  *   1. nonce-stamp the document's inline <style>/<script> so a strict CSP admits them;
  *   2. under path-prefix tenant routing (locals.basePath set), prefix same-origin
- *      root-absolute anchor hrefs with the base path so navigation stays in-tenant —
- *      the raw doc bypasses the Layout's client base-path fixer, so we do it here.
+ *      root-absolute anchor hrefs and page form actions with the base path so
+ *      navigation stays in-tenant — the raw doc bypasses the Layout's client
+ *      base-path fixer, so we do it here;
+ *   3. prefix `/api` form actions with apiBasePath, never a preview pin.
  *
  * Single home for both routes (`index.astro`, `[...slug].astro`).
  *
@@ -24,7 +26,7 @@ import {
 } from "@tot/public-runtime";
 import { reportTrackingChainHealth } from "../../measurement/tracking/interactionHealth.js";
 import { ASYNC_CSS_SWAP_JS } from "./asyncCss.js";
-import { ROOT_SERVED_HREF_NAMESPACES } from "../../publication/shared/basePath.js";
+import { ROOT_SERVED_HREF_NAMESPACES, withBase } from "../../publication/shared/basePath.js";
 
 export { rawHtmlPolicy } from "@tot/public-runtime";
 
@@ -205,6 +207,44 @@ export function prefixApiFormActions(html: string, apiBasePath: string): string
   return html.replace(API_FORM_ACTION_RE, (_match, attr: string) => `${attr}="${apiBasePath}/api/`);
 }
 
+/** True when a form target is an `/api` route. Those use {@link prefixApiFormActions}. */
+function isApiFormTarget(href: string): boolean {
+  if (!href.startsWith("/")) return false;
+  const path = href.slice(1).split(/[?#]/, 1)[0] ?? "";
+  return path === "api" || path.startsWith("api/");
+}
+
+const PAGE_FORM_ACTION_RE = /\b(action|formaction)=("([^"]*)"|'([^']*)')/g;
+
+/**
+ * Prefix same-origin page form targets (`action`/`formaction`) with `basePath`
+ * via {@link withBase}. A preview pin's header search (`/search`) stays inside
+ * that pin. `/api` targets are left for {@link prefixApiFormActions}. No-op
+ * when `basePath` is empty.
+ */
+export function prefixPageFormActions(html: string, basePath: string): string {
+  if (!basePath) return html;
+  return html.replace(PAGE_FORM_ACTION_RE, (full, attr: string, _quoted: string, dq: string | undefined, sq: string | undefined) => {
+    const href = dq ?? sq ?? "";
+    if (isApiFormTarget(href)) return full;
+    const next = withBase(basePath, href);
+    if (next === href) return full;
+    const quote = dq !== undefined ? '"' : "'";
+    return `${attr}=${quote}${next}${quote}`;
+  });
+}
+
+/**
+ * Serve-time prefix for chrome HTML on both mounts (raw documents and Layout's
+ * shared-chrome splice). Anchors go through {@link prefixTenantLinks}. Page
+ * form actions go through {@link prefixPageFormActions} (`withBase`). `/api`
+ * form actions go through {@link prefixApiFormActions} and `apiBasePath`, never
+ * a preview pin.
+ */
+export function prefixSharedChrome(html: string, basePath: string, apiBasePath: string): string {
+  return prefixApiFormActions(prefixPageFormActions(prefixTenantLinks(html, basePath), basePath), apiBasePath);
+}
+
 /** Raw pages with a robots `noindex` directive remain routable but stay out of discovery. */
 export function isIndexableHtml(html: string): boolean {
   for (const match of html.matchAll(/<meta\b([^>]*)>/gi)) {
@@ -397,10 +437,7 @@ export function rawHtmlResponse(
   composed = injectBodyEnd(composed, interactionTrackingScript(opts.nonce));
   composed = injectBodyEnd(composed, asyncCssSwapScript(opts.nonce));
   composed = resolveCanonicalHref(composed, opts.canonicalUrl);
-  const doc = prefixApiFormActions(
-    prefixTenantLinks(composed, opts.basePath),
-    opts.apiBasePath ?? "",
-  );
+  const doc = prefixSharedChrome(composed, opts.basePath, opts.apiBasePath ?? "");
   return new Response(doc, {
     headers: { "content-type": "text/html; charset=utf-8" },
   });

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

@@ -0,0 +1,45 @@
+/** KV projection of mirror balances. This module opens neither D1 nor env. */
+
+export interface MirrorBalanceProjection {
+  balance: number;
+  asOf: string;
+}
+
+export function mirrorBalanceKey(tenantId: string, stage: "preview" | "publication"): string {
+  return `mirror-balance:${stage}:${tenantId}`;
+}
+
+export function publicMirrorStage(input: { previewHost: boolean; previewToken: boolean }): "preview" | "publication" {
+  return input.previewHost || input.previewToken ? "preview" : "publication";
+}
+
+export function parseMirrorBalances(raw: string | null | undefined): Map<string, MirrorBalanceProjection> | null {
+  if (raw == null || raw === "") return null;
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    parsed = null;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const body = parsed as Record<string, unknown>;
+  if (body.v !== 1 || !Array.isArray(body.lines) || Object.keys(body).some((key) => key !== "v" && key !== "lines")) return null;
+  const map = new Map<string, MirrorBalanceProjection>();
+  for (const line of body.lines) {
+    if (!line || typeof line !== "object" || Array.isArray(line)) return null;
+    const row = line as Record<string, unknown>;
+    if (Object.keys(row).some((key) => key !== "sku" && key !== "balance" && key !== "asOf")) return null;
+    const balance = row.balance;
+    if (typeof row.sku !== "string" || !row.sku || typeof row.asOf !== "string" || typeof balance !== "number" || !Number.isSafeInteger(balance)) return null;
+    if (!Number.isFinite(Date.parse(row.asOf)) || map.has(row.sku)) return null;
+    map.set(row.sku, { balance, asOf: row.asOf });
+  }
+  return map;
+}
+
+export function serializeMirrorBalances(map: ReadonlyMap<string, MirrorBalanceProjection>): string {
+  const lines = [...map.entries()]
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([sku, row]) => ({ sku, balance: row.balance, asOf: row.asOf }));
+  return JSON.stringify({ v: 1, lines });
+}

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

@@ -119,3 +119,155 @@ export async function readMirrorStock(
     asOf: row.as_of,
   };
 }
+
+export const MIRROR_FRESH_MS = 15 * 60_000;
+export const MIRROR_LOCATION_UNSPECIFIED = "unspecified";
+export const CATALOG_IMPORT_ACTOR_ID = "catalog-import";
+export const CATALOG_IMPORT_SOURCE = "catalog-import";
+
+export interface MirrorBalance {
+  balance: number;
+  asOf: string;
+}
+
+export interface MirrorInventoryOverlay {
+  balances: ReadonlyMap<string, MirrorBalance>;
+  now: string;
+  maxAgeMs?: number;
+}
+
+interface BalanceKey {
+  tenantId: string;
+  stage: CommerceStage;
+  sku: string;
+  locationId: string;
+}
+
+/** Sum of movements, including a non-positive or stale balance. No rows is null, not zero. */
+export async function readMirrorBalance(db: Queryable, input: BalanceKey): Promise<MirrorBalance | null> {
+  const row = await db.first<{ balance: number | null; as_of: string | null }>(
+    `SELECT SUM(quantity_delta) balance, MAX(as_of) as_of FROM commerce_inventory_movements
+     WHERE tenant_id=? AND stage=? AND sku=? AND location_id=?`,
+    input.tenantId,
+    input.stage,
+    input.sku,
+    input.locationId,
+  );
+  if (!row || row.as_of == null || row.balance == null || !Number.isSafeInteger(Number(row.balance))) return null;
+  return { balance: Number(row.balance), asOf: row.as_of };
+}
+
+export async function readMirrorBalances(
+  db: Queryable,
+  input: { tenantId: string; stage: CommerceStage; locationId: string },
+): Promise<Map<string, MirrorBalance>> {
+  const rows = await db.all<{ sku: string; balance: number | null; as_of: string | null }>(
+    `SELECT sku, SUM(quantity_delta) balance, MAX(as_of) as_of FROM commerce_inventory_movements
+     WHERE tenant_id=? AND stage=? AND location_id=? GROUP BY sku`,
+    input.tenantId,
+    input.stage,
+    input.locationId,
+  );
+  const balances = new Map<string, MirrorBalance>();
+  for (const row of rows) {
+    if (row.as_of == null || row.balance == null || !Number.isSafeInteger(Number(row.balance))) continue;
+    balances.set(row.sku, { balance: Number(row.balance), asOf: row.as_of });
+  }
+  return balances;
+}
+
+/**
+ * One source on-hand observation. The stored delta is on-hand minus the sum of every other
+ * movement, so a replay of this event does not add the snapshot twice.
+ */
+export async function appendSourceOnHand(
+  db: Queryable,
+  input: Omit<MirrorMovement, "quantityDelta"> & { onHand: number },
+): Promise<void> {
+  if (!Number.isSafeInteger(input.onHand)) throw new InventoryMovementError("invalid-movement");
+  const prior = await db.first<{ quantity_delta: number }>(
+    `SELECT quantity_delta FROM commerce_inventory_movements
+     WHERE tenant_id=? AND stage=? AND source=? AND source_event_id=? AND sku=? AND location_id=?`,
+    input.tenantId,
+    input.stage,
+    input.source,
+    input.sourceEventId,
+    input.sku,
+    input.locationId,
+  );
+  const reading = await readMirrorBalance(db, input);
+  const currentSum = reading?.balance ?? 0;
+  const existingDelta = prior ? Number(prior.quantity_delta) : 0;
+  const { onHand, ...movement } = input;
+  await appendMirrorMovement(db, { ...movement, quantityDelta: onHand - (currentSum - existingDelta) });
+}
+
+export async function catalogImportEventId(runId: string, sku: string, onHand: number): Promise<string> {
+  const quantity = onHand < 0 ? `n${-onHand}` : String(onHand);
+  const raw = `import.${runId}.${sku}.${quantity}`;
+  if (ID.test(raw)) return raw;
+  const bytes = new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(raw)));
+  const hex = [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+  return `import.${hex.slice(0, 40)}`;
+}
+
+export async function importSourceOnHand(
+  db: Queryable,
+  input: {
+    tenantId: string;
+    stage: CommerceStage;
+    lines: readonly { sku: string; onHand: number }[];
+    runId: string;
+    asOf: string;
+  },
+): Promise<void> {
+  for (const line of input.lines) {
+    await appendSourceOnHand(db, {
+      tenantId: input.tenantId,
+      stage: input.stage,
+      sku: line.sku,
+      locationId: MIRROR_LOCATION_UNSPECIFIED,
+      source: CATALOG_IMPORT_SOURCE,
+      sourceEventId: await catalogImportEventId(input.runId, line.sku, line.onHand),
+      onHand: line.onHand,
+      asOf: input.asOf,
+      actorId: CATALOG_IMPORT_ACTOR_ID,
+    });
+  }
+}
+
+export function handoffStockFinding(balance: number | null): "stock-unavailable" | null {
+  return balance !== null && balance <= 0 ? "stock-unavailable" : null;
+}
+
+/** Ledger wins over the catalog stamp. A positive stale balance leaves the stamp alone. */
+export function overlayMirrorInventory<T extends { available: boolean; quantity?: number }>(
+  stamp: T,
+  reading: MirrorBalance | null | undefined,
+  now: string,
+  maxAgeMs = MIRROR_FRESH_MS,
+): T {
+  if (!reading) return stamp;
+  if (reading.balance <= 0) return { ...stamp, available: false, quantity: reading.balance };
+  const age = Date.parse(now) - Date.parse(reading.asOf);
+  const fresh = Number.isFinite(age) && age >= 0 && Number.isFinite(maxAgeMs) && maxAgeMs >= 0 && age <= maxAgeMs;
+  if (fresh) return { ...stamp, available: true, quantity: reading.balance };
+  return stamp;
+}
+
+export function overlayProductInventory<T extends { variants: readonly { sku?: string | null; inventory: { available: boolean; quantity?: number } }[] }>(
+  product: T,
+  overlay: MirrorInventoryOverlay,
+): T {
+  return {
+    ...product,
+    variants: product.variants.map((variant) => {
+      const reading = variant.sku ? overlay.balances.get(variant.sku) : undefined;
+      if (!reading) return variant;
+      return {
+        ...variant,
+        inventory: overlayMirrorInventory(variant.inventory, reading, overlay.now, overlay.maxAgeMs),
+      };
+    }),
+  };
+}

package/apps/storefront/src/middleware/controlPlane.ts

@@ -2,16 +2,18 @@
  * The control-plane branch: everything a route reaches only with authorization,
  * plus every route on a login-gated host.
  *
- * It owns the three request-time D1 reads (managed installs, consent, the catalog
- * edge replica), the sign-in gate and its admin landing, and the `/dev` alias —
- * then delegates to the shared render chain with those values supplied.
+ * It owns the request-time D1 reads (managed installs, consent, the catalog
+ * edge replica, and mirror-stock balances for this branch's catalog overlay),
+ * the sign-in gate and its admin landing, and the `/dev` alias — then delegates
+ * to the shared render chain with those values supplied.
  */
 import type { APIContext, MiddlewareNext } from "astro";
 import { readEnv, readD1, readKv } from "@/lib/publication/shared/env";
 import { fromD1, type D1Like } from "@/lib/catalog/d1/catalog";
 import { readCurrentTenantConsentConfig } from "@/lib/measurement/consent/consentConfigRead";
 import { loadActiveManagedInstallDeclarations } from "@/lib/integrations/integration/managedInstallDeclarations";
-import { buildTenantConsentBroker, verifyPreviewToken, storefrontModeRequiresSignIn } from "@tot/public-runtime";
+import { buildTenantConsentBroker, commerceTenantId, verifyPreviewToken, storefrontModeRequiresSignIn } from "@tot/public-runtime";
+import { MIRROR_LOCATION_UNSPECIFIED, readMirrorBalances as readLedgerBalances } from "@/lib/inventory/mirrorStock";
 import { tenantIsDeclaredPublic } from "@/config/tenants";
 import type {
   ConsentSnapshot,
@@ -288,6 +290,14 @@ export async function serveControlPlane(input: ControlPlaneInput): Promise<Respo
     // The public branch never resolves it at all — see `publicRender`.
     readCatalogD1: async (): Promise<D1Like | undefined> =>
       tenant.catalog?.serving === "d1" ? await readD1("CATALOG_DB") : undefined,
+    readMirrorBalances: async (stage) => {
+      if (!appsD1) return null;
+      return readLedgerBalances(fromD1(appsD1), {
+        tenantId: commerceTenantId(tenant),
+        stage,
+        locationId: MIRROR_LOCATION_UNSPECIFIED,
+      });
+    },
     internalContentGrant: input.internalContentGrant,
   });
 }

package/apps/storefront/src/middleware/index.ts

@@ -25,7 +25,7 @@ import { getTenantResolver } from "@/config/resolver";
 import { readEnv, readKv, readR2 } from "@/lib/publication/shared/runtimeEnv";
 import { resolveCdnForwardRouting, resolveTenantRouting } from "@/lib/access/shared/tenantRouting";
 import { crossSiteFormRefusal, verifyCdnForward } from "@/lib/publication/shared/cdnForward";
-import { SAMPLE_CART_HANDOFF_URL, compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 , storefrontModeRequiresSignIn } from "@tot/public-runtime";
+import { SAMPLE_CART_HANDOFF_URL, commerceTenantId, compileRouteTierIndexV1, resolvePublicationRoutePlanV1, type RouteTierIndexV1 , storefrontModeRequiresSignIn } from "@tot/public-runtime";
 import type { PublicationArtifactBucketV1, TenantConfig } from "@tot/public-runtime";
 import { HTML_CACHE_POLICY_CAPTURE_PROBE } from "@tot/public-runtime";
 import type { RenditionRegistryBucket } from "@/lib/assets/registeredRenditions";
@@ -48,6 +48,7 @@ import {
   resolveMiddlewareBranchV1,
 } from "./routeBranch.js";
 import { servePublicRender } from "./publicRender.js";
+import { mirrorBalanceKey, parseMirrorBalances, publicMirrorStage } from "@/lib/inventory/mirrorBalanceProjection";
 import { serveControlPlane } from "./controlPlane.js";
 import { KvSessionStore, SESSION_COOKIE } from "@/lib/access/auth/session";
 import { mintOpaqueBrokerAssertion } from "@/lib/access/auth/brokerAssertion";
@@ -368,6 +369,18 @@ async function serveRequest(
   const publicationSourcePath = discoveryRoot?.action === "render" ? "/" : renderPath;
 
   if (branch === "public-render") {
+    const mirrorStage = publicMirrorStage({
+      previewHost: host.toLowerCase().startsWith("preview."),
+      previewToken: url.searchParams.has("__preview") || !!context.cookies.get("tot_preview")?.value,
+    });
+    let mirrorBalances: ReturnType<typeof parseMirrorBalances> = null;
+    if (kv) {
+      try {
+        mirrorBalances = parseMirrorBalances(await kv.get(mirrorBalanceKey(commerceTenantId(tenant), mirrorStage)));
+      } catch {
+        mirrorBalances = null;
+      }
+    }
     return await servePublicRender({
       context,
       next,
@@ -384,6 +397,7 @@ async function serveRequest(
       publicationBucket: discoveryRoot?.action === "render"
         ? await readR2("TENANT_ASSETS") as unknown as PublicationArtifactBucketV1 | undefined
         : publicationBucket,
+      mirrorBalances,
     });
   }
 

package/apps/storefront/src/middleware/publicRender.ts

@@ -4,7 +4,8 @@
  *
  * This module's whole job is to hand the shared chain the empty forms of every
  * D1-derived input, so a control-plane read cannot reach the public path by
- * accident. That absence is the contract, and it is held structurally rather
+ * accident. Mirror balances are not a read: the caller passes a map it already
+ * resolved, or nothing. That absence of a D1 read is the contract, and it is held structurally rather
  * than by review: `public-render-no-request-time-d1` (.dependency-cruiser.cjs)
  * fails `pnpm run check` if ANY module reachable from this one reaches
  * `lib/publication/shared/env.ts`, the sole accessor for a live D1 handle. The public path reaches
@@ -25,19 +26,25 @@
  *     snapshot reaches a public page baked into the static bundle (the signed
  *     materialize-mode header the shared chain still honors).
  *   - catalog — the bundled JSON snapshot, never the D1 edge replica.
+ *   - mirror balances — only a map the caller already resolved (KV). This module
+ *     never opens D1. A missing map leaves the file stamp unchanged.
  */
 import { runRenderChain, type RenderChainInput } from "./renderChain.js";
 
 export type PublicRenderInput = Omit<
   RenderChainInput,
-  "managedIntegrationDeclarations" | "readTenantConsentSnapshot" | "readCatalogD1"
->;
+  "managedIntegrationDeclarations" | "readTenantConsentSnapshot" | "readCatalogD1" | "readMirrorBalances"
+> & {
+  mirrorBalances?: ReadonlyMap<string, { balance: number; asOf: string }> | null;
+};
 
 export function servePublicRender(input: PublicRenderInput): Promise<Response> {
+  const { mirrorBalances = null, ...rest } = input;
   return runRenderChain({
-    ...input,
+    ...rest,
     managedIntegrationDeclarations: [],
     readTenantConsentSnapshot: null,
     readCatalogD1: null,
+    readMirrorBalances: mirrorBalances ? async () => mirrorBalances : null,
   });
 }

package/apps/storefront/src/middleware/renderChain.ts

@@ -171,6 +171,11 @@ export interface RenderChainInput {
    * parameter rather than the D1 module, so this file names no D1 type at all.
    */
   readCatalogD1: (() => Promise<Parameters<typeof createToTClient>[1]>) | null;
+  /**
+   * Already-resolved mirror balances for this commerce stage. Null on the public
+   * branch: that render has no ledger handle, and publication HTML is CDN to storage.
+   */
+  readMirrorBalances?: ((stage: "preview" | "publication") => Promise<ReadonlyMap<string, { balance: number; asOf: string }> | null>) | null;
   /** Exact per-request grant for an F2-selected internal publication space. */
   internalContentGrant?: InternalContentGrant;
   /** Pin already verified for this tenant by the control-plane login gate. */
@@ -710,8 +715,15 @@ export async function runRenderChain(input: RenderChainInput): Promise<Response>
   // are read through the SAME content source just resolved, so they follow the
   // request's selected version exactly as pages and the blog do. Only the control
   // plane supplies the D1 projection; the public branch never reads D1.
+  let mirrorOverlay: Parameters<typeof createToTClient>[3] = null;
+  if (input.readMirrorBalances) {
+    try {
+      const balances = await input.readMirrorBalances(customization.env === "live" ? "publication" : "preview");
+      if (balances) mirrorOverlay = { balances, now: new Date().toISOString() };
+    } catch { mirrorOverlay = null; }
+  }
   locals.tot = await timed(timing, "catalog", async () =>
-    createToTClient(tenant, await input.readCatalogD1?.(), locals.content));
+    createToTClient(tenant, await input.readCatalogD1?.(), locals.content, mirrorOverlay));
   locals.themeStyle = themeToCssVars(theme);
   locals.canonicalBase = canonicalBase;
   locals.customizationEnv = customization.env;

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

@@ -10,7 +10,7 @@ import { fromD1 } from "@/lib/catalog/d1/catalog.js";
 import { readD1, readEnv, readKv } from "@/lib/publication/shared/env";
 import { evaluateFinalCart, type SeamView } from "@/lib/checkout/commerce/finalCartAuthorization.js";
 import { d1CommerceRunner, reserveAllocation } from "@/lib/inventory/allocations.js";
-import { readMirrorStock } from "@/lib/inventory/mirrorStock.js";
+import { readMirrorBalance, readMirrorStock } from "@/lib/inventory/mirrorStock.js";
 import { admissionMatches, readCommerceAdmission, admissionSnapshotStatement } from "@/lib/checkout/commerce/commerceAdmission.js";
 import { evaluatePreflight } from "../compliance/preflight.js";
 import {
@@ -225,6 +225,12 @@ async function authorize(context: APIContext): Promise<Response> {
   if (tenant.inventory?.provider && tenant.inventory.provider !== "mirror") return deny("authority-unavailable");
   const now = new Date().toISOString();
   const queryable = fromD1(database);
+  for (const line of snapshot.lines) {
+    const reading = await readMirrorBalance(queryable, {
+      tenantId: snapshot.tenantId, stage: snapshot.stage, sku: line.sku, locationId: "unspecified",
+    });
+    if (reading && reading.balance <= 0) return deny("stock-unavailable");
+  }
   const prior = await queryable.first<{ authorization_id: string; state: string }>(
     `SELECT s.authorization_id,a.state FROM commerce_admission_snapshots s JOIN scrappy_final_cart_authorizations a
      ON a.tenant_id=s.tenant_id AND a.stage=s.stage AND a.authorization_id=s.authorization_id
@@ -240,8 +246,8 @@ async function authorize(context: APIContext): Promise<Response> {
   const requirements = await readCheckoutRequirements(tenant.tenant_id, contentEnv);
   if (!requirements) return deny("checkout-requirements-unreadable", 503);
   const policy = testStoreEvidencePolicy(requirements);
-  // Stock is tracked only for a tenant that declares the `mirror` provider. An undeclared tenant
-  // has no balance to read, so its stock evidence is honestly `not-required`, not a refusal.
+  // A declared mirror provider is admitted only against a fresh positive balance. An undeclared
+  // tenant with no movements records stock as `not-required`. A non-positive balance already refused.
   const stockTracked = tenant.inventory?.provider === "mirror";
   const authorities = [];
   if (stockTracked) {

package/package.json

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