@tokenoftrust/storefront-runner 4.2.0 → 4.2.2

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/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 {
@@ -167,13 +167,19 @@ async function authorize(context: APIContext): Promise<Response> {
   const kv = await readKv("TENANT_CACHE");
   const kvGet = async (key: string): Promise<string | null> => kv ? kv.get(key) : null;
   const contentEnv = snapshot.stage === "publication" ? "live" : "test";
+  const contentVersionId = snapshot.stage === "preview" && snapshot.contentVersionId ? snapshot.contentVersionId : undefined;
   let tenant: TenantConfig;
-  try { tenant = await withDeclaredTenantConfig(registered, kvGet, { env: contentEnv }); } catch (err) {
+  try {
+    tenant = await withDeclaredTenantConfig(registered, kvGet, {
+      env: contentEnv,
+      ...(contentVersionId ? { pinnedVersionId: contentVersionId } : {}),
+    });
+  } catch (err) {
     if (err instanceof DeclaredTenantConfigUnreadError) return deny("config-unreadable", 503);
     throw err;
   }
-  const content = snapshot.stage === "preview" && snapshot.contentVersionId
-    ? createContentProvider(tenant, undefined, { get: kvGet, versionId: snapshot.contentVersionId })
+  const content = contentVersionId
+    ? createContentProvider(tenant, undefined, { get: kvGet, versionId: contentVersionId })
     : 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;
@@ -219,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
@@ -234,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.0",
+  "version": "4.2.2",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",