@tokenoftrust/storefront-runner 2.4.90 → 2.5.0

package/apps/storefront/.runner-dependency-cruiser.cjs

@@ -0,0 +1,38 @@
+module.exports = {
+  "forbidden": [
+    {
+      "name": "renderer-no-controlplane",
+      "severity": "error",
+      "from": {},
+      "to": {
+        "path": "(^|/)packages/private-controlplane/|^@tot/private-controlplane(/|$)|^@tokenoftrust/private-apps-devkit(/|$)"
+      }
+    }
+  ],
+  "options": {
+    "tsConfig": {
+      "fileName": "tsconfig.json"
+    },
+    "tsPreCompilationDeps": true,
+    "doNotFollow": {
+      "path": "node_modules"
+    },
+    "enhancedResolveOptions": {
+      "exportsFields": [
+        "exports"
+      ],
+      "conditionNames": [
+        "import",
+        "types",
+        "node",
+        "default"
+      ],
+      "extensions": [
+        ".ts",
+        ".tsx",
+        ".js",
+        ".mjs"
+      ]
+    }
+  }
+};

package/apps/storefront/migrations-apps/0017_commerce_durable_projection.sql

@@ -0,0 +1,28 @@
+-- Append-only mirrored stock and trusted checkout admission receipts.
+CREATE TABLE commerce_inventory_movements (
+ tenant_id TEXT NOT NULL, stage TEXT NOT NULL CHECK(stage IN ('preview','publication')),
+ source TEXT NOT NULL, source_event_id TEXT NOT NULL, sku TEXT NOT NULL,
+ location_id TEXT NOT NULL DEFAULT 'unspecified', quantity_delta INTEGER NOT NULL,
+ as_of TEXT NOT NULL, actor_id TEXT NOT NULL,
+ PRIMARY KEY(tenant_id,stage,source,source_event_id,sku,location_id)
+);
+CREATE INDEX commerce_inventory_scope ON commerce_inventory_movements(tenant_id,stage,sku,location_id,as_of);
+CREATE TABLE commerce_admission_snapshots (
+ tenant_id TEXT NOT NULL, stage TEXT NOT NULL CHECK(stage IN ('preview','publication')),
+ authorization_id TEXT NOT NULL, snapshot_json TEXT NOT NULL,
+ provider_cart_digest TEXT NOT NULL, expires_at TEXT NOT NULL,
+ linked_order_id TEXT,
+ PRIMARY KEY(tenant_id,stage,authorization_id),
+ UNIQUE(tenant_id,stage,linked_order_id),
+ FOREIGN KEY(tenant_id,stage,authorization_id) REFERENCES scrappy_final_cart_authorizations(tenant_id,stage,authorization_id)
+);
+CREATE TABLE commerce_projection_checkpoints (
+ tenant_id TEXT NOT NULL, stage TEXT NOT NULL CHECK(stage IN ('preview','publication')),
+ order_id TEXT NOT NULL, source_version INTEGER NOT NULL, projected_at TEXT NOT NULL,
+ PRIMARY KEY(tenant_id,stage,order_id)
+);
+CREATE TABLE commerce_recovery_runs (
+ run_id TEXT PRIMARY KEY, tenant_id TEXT NOT NULL, stage TEXT NOT NULL,
+ started_at TEXT NOT NULL, completed_at TEXT, deployed_sha TEXT NOT NULL,
+ delivered INTEGER NOT NULL DEFAULT 0, retried INTEGER NOT NULL DEFAULT 0, dead INTEGER NOT NULL DEFAULT 0
+);

package/apps/storefront/migrations-apps/0018_commerce_provider_cart_identity.sql

@@ -0,0 +1,13 @@
+-- A provider cart has one immutable admission until authoritative unpaid supersession exists.
+CREATE TABLE commerce_provider_carts (
+ tenant_id TEXT NOT NULL, stage TEXT NOT NULL CHECK(stage IN ('preview','publication')),
+ provider TEXT NOT NULL CHECK(provider='foxycart'), provider_cart_id TEXT NOT NULL,
+ provider_cart_digest TEXT NOT NULL, authorization_id TEXT NOT NULL,
+ PRIMARY KEY(tenant_id,stage,provider,provider_cart_id),
+ UNIQUE(tenant_id,stage,authorization_id)
+);
+-- Conflicting persisted identities refuse migration rather than select an arbitrary receipt.
+INSERT INTO commerce_provider_carts
+ (tenant_id,stage,provider,provider_cart_id,provider_cart_digest,authorization_id)
+ SELECT tenant_id,stage,json_extract(snapshot_json,'$.provider'),json_extract(snapshot_json,'$.providerCartId'),provider_cart_digest,authorization_id
+ FROM commerce_admission_snapshots;

package/apps/storefront/package.json

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

package/apps/storefront/src/config/declaredTenantConfig.ts

@@ -44,6 +44,11 @@ export function checkoutTotConfigs(): Map<string, Record<string, unknown>> {
   return map;
 }
 
+/** Only the local renderer's scaffold declaration selects the hosted sample handoff. */
+export function isLocalSampleCheckout(tenantId: string): boolean {
+  return import.meta.env.DEV && checkoutTotConfigs().get(tenantId)?.sample === true;
+}
+
 /** The declaration in the checkout's own `.tot/config.json`, or `{}` when it has none. */
 export function checkoutDeclaredTenantConfig(tenantId: string): DeclaredTenantConfig {
   return declaredTenantConfig(checkoutConfigFiles[`../../../../tenants/${tenantId}/.tot/config.json`]

package/apps/storefront/src/config/devTenantSeed.ts

@@ -94,8 +94,9 @@ export function synthesizeDevTenant(
     ...(integrations.length > 0 ? { integrations } : {}),
     ...(euUkVisitors ? { euUkVisitors } : {}),
   };
-  // Cart wires to the shared ToT demo checkout store (test mode, no secret), the
-  // same as the bundled demo tenants — and the SAME constant the hosted QA/test
+  // Cart wires to the shared ToT demo checkout store (`tot-preview`, signed:
+  // HMAC cart validation required; FOXY_CART_SECRET must be set before carts
+  // are served), the same as the bundled demo tenants — and the SAME constant the hosted QA/test
   // tier's demo-checkout fallback reuses (checkoutCommerce.ts), so both surfaces
   // stay wired to one definition. A marketing tenant never resolves it (the
   // render chain gates on features.catalog); a commerce one gets its cart

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

@@ -0,0 +1,108 @@
+/** Trusted admission is written in the reservation transaction, never reconstructed from a paid callback. */
+import {
+  canonicalJson,
+  type CommerceAdmissionSnapshot,
+  type CommerceStage,
+  type MinorTotals,
+} from "@tot/public-runtime";
+import type { Queryable, QueryStatement } from "../../catalog/d1/catalog.js";
+export type { CommerceAdmissionSnapshot } from "@tot/public-runtime";
+export function admissionSnapshotStatement(
+  input: CommerceAdmissionSnapshot,
+): QueryStatement & { params: readonly unknown[] } {
+  if (
+    !/^[a-f0-9]{64}$/.test(input.providerCartDigest) ||
+    !/^[a-f0-9]{64}$/.test(input.destinationDigest) ||
+    Object.values(input.provenance).some(
+      (v) => !v || !v.source || !v.policyRevision || !Number.isFinite(Date.parse(v.expiresAt)),
+    ) ||
+    !Number.isFinite(Date.parse(input.expiresAt))
+  )
+    throw new Error("invalid-admission");
+  return {
+    sql: `INSERT INTO commerce_admission_snapshots
+    (tenant_id,stage,authorization_id,snapshot_json,provider_cart_digest,expires_at)
+    SELECT ?,?,?,?,?,? WHERE EXISTS(SELECT 1 FROM scrappy_final_cart_authorizations
+      WHERE tenant_id=? AND stage=? AND authorization_id=? AND cart_digest=? AND state='active')
+    ON CONFLICT DO NOTHING`,
+    params: [
+      input.tenantId,
+      input.stage,
+      input.authorizationId,
+      JSON.stringify(input),
+      input.providerCartDigest,
+      input.expiresAt,
+      input.tenantId,
+      input.stage,
+      input.authorizationId,
+      input.cartDigest,
+    ],
+  };
+}
+export async function readCommerceAdmission(
+  db: Queryable,
+  tenantId: string,
+  stage: CommerceStage,
+  authorizationId: string,
+): Promise<CommerceAdmissionSnapshot | null> {
+  const row = await db.first<{ snapshot_json: string }>(
+    `SELECT snapshot_json FROM commerce_admission_snapshots WHERE tenant_id=? AND stage=? AND authorization_id=?`,
+    tenantId,
+    stage,
+    authorizationId,
+  );
+  if (!row) return null;
+  try {
+    const snapshot = JSON.parse(row.snapshot_json) as CommerceAdmissionSnapshot;
+    if (
+      snapshot.tenantId !== tenantId ||
+      snapshot.stage !== stage ||
+      snapshot.authorizationId !== authorizationId ||
+      !Array.isArray(snapshot.lines) ||
+      !snapshot.lines.length ||
+      !snapshot.totals ||
+      !snapshot.evidence ||
+      !snapshot.provenance ||
+      !/^[a-f0-9]{64}$/.test(snapshot.providerCartDigest) ||
+      !/^[a-f0-9]{64}$/.test(snapshot.destinationDigest) ||
+      !Number.isFinite(Date.parse(snapshot.expiresAt))
+    )
+      return null;
+    for (const field of ["verification", "tax", "risk", "stock"] as const) {
+      const proof = snapshot.provenance[field];
+      if (
+        !proof ||
+        !proof.source ||
+        !proof.policyRevision ||
+        !Number.isFinite(Date.parse(proof.expiresAt)) ||
+        !["required", "not-required"].includes(proof.requirement) ||
+        !["satisfied", "not-required"].includes(proof.state)
+      )
+        return null;
+    }
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+export function admissionMatches(
+  snapshot: CommerceAdmissionSnapshot,
+  event: {
+    currency: string;
+    totals: MinorTotals;
+    lines?: readonly { sku: string; quantity: number; unitMinor: number }[];
+    providerCartDigest?: string;
+    destinationDigest?: string;
+  },
+): boolean {
+  const sort = (lines: readonly { sku: string; quantity: number; unitMinor: number }[]) =>
+    [...lines].sort((a, b) => a.sku.localeCompare(b.sku));
+  return (
+    event.providerCartDigest === snapshot.providerCartDigest &&
+    event.destinationDigest === snapshot.destinationDigest &&
+    event.currency === snapshot.currency &&
+    canonicalJson(event.totals) === canonicalJson(snapshot.totals) &&
+    Array.isArray(event.lines) &&
+    canonicalJson(sort(event.lines)) === canonicalJson(sort(snapshot.lines))
+  );
+}

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

@@ -92,7 +92,7 @@ function evidenceFinding(evidence: CommerceEvidence | null): string | null {
   if (!evidence) return "missing-evidence";
   for (const field of EVIDENCE_FIELDS) {
     const state: EvidenceState | string = evidence[field];
-    if (state === "fresh") continue;
+    if (state === "fresh" || (field !== "stock" && state === "not-required")) continue;
     if (state === "UNKNOWN") return `evidence-${field}-unknown`;
     if (state === "stale" || state === "unreadable" || state === "absent") return `evidence-${field}-${state}`;
     return `evidence-${field}-unreadable`;

package/apps/storefront/src/lib/checkout/shared/checkoutCommerce.ts

@@ -9,8 +9,8 @@
  *   - `FOXY_STORE_SUBDOMAIN` overrides the tenant's default subdomain (one
  *     env var points every commerce tenant at our shared demo store).
  *   - `FOXY_CART_SECRET` is the cart-validation secret used only in `signed`
- *     mode; the `unsigned-demo` mode never reads it (validation is OFF), which
- *     is what lets a developer run the whole cart locally with zero secrets.
+ *     mode; `unsigned-demo` never reads it. Local sample carts use the hosted
+ *     identifier-only handoff, so developers receive no shared signing key.
  *
  * `COMMERCE_DEMO_CHECKOUT_TIER` gates a FALLBACK for a commerce tenant that has
  * no `commerce.checkout` of its own (e.g. a staff-provisioned store —
@@ -28,6 +28,7 @@ import {
   CART_SIGNING_OPERATOR_ERROR,
   resolveManagedCheckout,
   SHARED_DEMO_CHECKOUT,
+  isManagedCheckoutMode,
 } from "@tot/public-runtime";
 import { readEnv } from "@/lib/publication/shared/runtimeEnv";
 
@@ -40,7 +41,7 @@ export async function resolveTenantCommerce(
   tenant: TenantConfig,
 ): Promise<ResolvedManagedCheckout | null> {
   const checkout = tenant.commerce?.checkout ?? (await demoCheckoutFallback());
-  if (!checkout) return null;
+  if (!checkout || !isManagedCheckoutMode(checkout.mode)) return null;
   // Per-environment overrides so the SAME tenant can point at different stores /
   // checkout hosts by env: FOXY_STORE_SUBDOMAIN picks the checkout store;
   // FOXY_STORE_DOMAIN sets a branded custom checkout domain (e.g. checkout.preview.
@@ -127,7 +128,8 @@ export interface CartSigningResolution {
 export async function resolveCartSigning(
   commerce: ResolvedManagedCheckout,
 ): Promise<CartSigningResolution> {
-  if (commerce.mode !== "signed") return { enabled: true };
+  if (!isManagedCheckoutMode(commerce.mode)) return { enabled: false, operatorError: CART_SIGNING_OPERATOR_ERROR };
+  if (commerce.mode === "unsigned-demo") return { enabled: true };
   const secret = await readCartSecret(commerce);
   if (secret) return { enabled: true, secret };
   console.error(

package/apps/storefront/src/lib/fulfillment/admin/commerceDesk.ts

@@ -0,0 +1,111 @@
+/** Operational browser client. All authority and state changes remain in the authenticated APIs. */
+import type { FulfillmentView } from "../fulfillmentService.js";
+export function mountCommerceDesk(root: HTMLElement): void {
+  const status = root.querySelector<HTMLElement>("[data-desk-status]")!;
+  const rows = root.querySelector<HTMLElement>("[data-desk-orders]")!;
+  const next = root.querySelector<HTMLButtonElement>("[data-desk-next]")!;
+  let cursor: string | null = null;
+  async function request(url: string, body?: unknown): Promise<unknown> {
+    const response = await fetch(url, {
+      credentials: "same-origin",
+      cache: "no-store",
+      ...(body ? { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) } : {}),
+    });
+    const value = await response.json();
+    if (!response.ok) throw new Error("request-refused");
+    return value;
+  }
+  function text(tag: string, value: string, parent: HTMLElement): HTMLElement {
+    const node = document.createElement(tag);
+    node.textContent = value;
+    parent.append(node);
+    return node;
+  }
+  function render(order: FulfillmentView): void {
+    const card = document.createElement("section");
+    card.dataset.orderId = order.orderId;
+    rows.append(card);
+    text("h3", order.orderId, card);
+    text("p", `${order.payment} · ${order.fulfillment} · ${order.batch?.phase ?? "unclaimed"}`, card);
+    text("p", order.lines.map((line) => `${line.sku} × ${line.quantity}`).join(", ") || "No verified line items", card);
+    text("p", order.holds.length ? `Held: ${order.holds.join(", ")}` : "Ready", card);
+    const actions = order.batch
+      ? [
+          ["pick", "Confirm pick"],
+          ["pack", "Confirm pack"],
+        ]
+      : [["claim", "Build pick list"]];
+    actions.push(["hold", "Hold"], ["clear-hold", "Clear operator hold"]);
+    for (const [action, label] of actions) {
+      const button = text("button", label!, card) as HTMLButtonElement;
+      button.type = "button";
+      button.disabled = (action === "pick" || action === "pack" || action === "claim") && order.holds.length > 0;
+      button.onclick = async () => {
+        button.disabled = true;
+        try {
+          await request(
+            action === "claim"
+              ? "/api/admin/fulfillment/batches"
+              : `/api/admin/fulfillment/orders/${encodeURIComponent(order.orderId)}`,
+            action === "claim"
+              ? { orderIds: [order.orderId], expectedVersions: { [order.orderId]: order.eventVersion } }
+              : { action, expectedVersion: order.eventVersion, scope: "whole-order" },
+          );
+          await load(null);
+        } catch {
+          status.textContent = "The order could not be updated. Refresh and try again.";
+          button.disabled = false;
+        }
+      };
+    }
+    if (order.packingSlip) {
+      const slip = document.createElement("div");
+      slip.dataset.packingSlip = order.orderId;
+      card.append(slip);
+      text("h4", "Packing slip", slip);
+      for (const line of order.packingSlip.lines) text("p", `${line.sku} × ${line.quantity}`, slip);
+      const print = text("button", "Print packing slip", slip) as HTMLButtonElement;
+      print.type = "button";
+      print.onclick = () => {
+        const page = window.open("", "_blank");
+        if (!page) return;
+        page.opener = null;
+        const title = page.document.createElement("h1");
+        title.textContent = `Packing slip ${order.orderId}`;
+        page.document.body.append(title);
+        for (const line of order.packingSlip!.lines) {
+          const item = page.document.createElement("p");
+          item.textContent = `${line.sku} × ${line.quantity}`;
+          page.document.body.append(item);
+        }
+        page.print();
+      };
+    }
+  }
+  async function load(after: string | null): Promise<void> {
+    status.textContent = "Loading orders…";
+    try {
+      const page = (await request(
+        `/api/admin/fulfillment/orders?limit=25${after ? `&cursor=${encodeURIComponent(after)}` : ""}`,
+      )) as { tenantId: string; orders: FulfillmentView[]; nextCursor: string | null };
+      if (page.tenantId !== root.dataset.targetTenant) {
+        rows.replaceChildren();
+        next.hidden = true;
+        status.textContent = "Open the selected store to view its fulfillment orders.";
+        return;
+      }
+      rows.replaceChildren();
+      page.orders.forEach(render);
+      cursor = page.nextCursor;
+      next.hidden = !cursor;
+      status.textContent = page.orders.length ? `${page.orders.length} orders` : "No received orders.";
+    } catch {
+      rows.replaceChildren();
+      next.hidden = true;
+      status.textContent = "Orders are unavailable. Refresh and try again.";
+    }
+  }
+  root.querySelector<HTMLButtonElement>("[data-desk-refresh]")!.onclick = () => void load(null);
+  next.onclick = () => void load(cursor);
+  void load(null);
+}

package/apps/storefront/src/lib/fulfillment/admin/viewmodels/fulfillment.ts

@@ -262,7 +262,7 @@ export function holdReasons(order: {
   if (order.fulfillment === "UNKNOWN") reasons.push("Fulfillment is unknown. Reconcile before shipping.");
   if (order.manualException) reasons.push(`Manual exception: ${order.manualException}.`);
   if (order.adultSignature === "refused") reasons.push("Adult signature was refused. The order does not ship.");
-  const stale = (["verification", "tax", "risk", "stock"] as const).filter((key) => order.evidence[key] !== "fresh");
+  const stale = (["verification", "tax", "risk", "stock"] as const).filter((key) => order.evidence[key] !== "fresh" && order.evidence[key] !== "not-required");
   if (stale.length > 0) {
     reasons.push(`Evidence is not fresh: ${stale.map((key) => `${key} ${order.evidence[key]}`).join(", ")}.`);
   }

package/apps/storefront/src/lib/fulfillment/commerceProjection.ts

@@ -0,0 +1,146 @@
+/** Durable receipt outbox is the recovery authority for the operational order projection. */
+import { type CommerceEvidence, type CommerceStage } from "@tot/public-runtime";
+import type { Queryable } from "../catalog/d1/catalog.js";
+import { foldCommerceEvents, type StoredCommercePayload } from "../orders/data/orderMapper.js";
+import { admissionMatches, readCommerceAdmission } from "../checkout/commerce/commerceAdmission.js";
+import { FulfillmentService } from "./fulfillmentService.js";
+import { fulfillmentDbFromQueryable } from "./store.js";
+const UNKNOWN: CommerceEvidence = { verification: "UNKNOWN", tax: "UNKNOWN", risk: "UNKNOWN", stock: "UNKNOWN" };
+
+export async function projectCommerceOrder(
+  db: Queryable,
+  input: { tenantId: string; stage: CommerceStage; orderId: string; now: string },
+): Promise<void> {
+  const rows = await db.all<{ payload: string }>(
+    `SELECT payload FROM scrappy_commerce_outbox WHERE tenant_id=? AND stage=? AND order_id=?`,
+    input.tenantId,
+    input.stage,
+    input.orderId,
+  );
+  const events = rows.map((row) => (JSON.parse(row.payload) as StoredCommercePayload).source);
+  if (!events.length) throw new Error("source-unavailable");
+  const snapshot = foldCommerceEvents(events);
+  const commandRank = { observe: 0, capture: 1, refund: 2, cancel: 3 };
+  const sorted = [...events].sort(
+    (a, b) =>
+      b.eventVersion - a.eventVersion ||
+      commandRank[b.command] - commandRank[a.command] ||
+      b.sourceEventId.localeCompare(a.sourceEventId),
+  );
+  // A paid/cart snapshot owns all of its binding fields together. A status-only
+  // update can retain those immutable facts, but cannot replace any of them.
+  const currentCart = sorted.find(
+    (event) =>
+      event.command === "capture" ||
+      event.lines !== undefined ||
+      event.admissionReference !== undefined ||
+      event.providerCartDigest !== undefined ||
+      event.destinationDigest !== undefined,
+  );
+  const lines = currentCart?.lines ?? [];
+  const admission = currentCart?.admissionReference
+    ? await readCommerceAdmission(db, input.tenantId, input.stage, currentCart.admissionReference)
+    : null;
+  const sameSourceOrder = events.every(
+    (event) => event.source === snapshot.source && event.sourceOrderId === snapshot.sourceOrderId,
+  );
+  let trusted = false;
+  if (
+    admission &&
+    currentCart &&
+    sameSourceOrder &&
+    admissionMatches(admission, {
+      currency: snapshot.currency,
+      totals: snapshot.totals,
+      lines,
+      providerCartDigest: currentCart.providerCartDigest,
+      destinationDigest: currentCart.destinationDigest,
+    }) &&
+    Date.parse(currentCart.placedAt) <= Date.parse(admission.expiresAt)
+  ) {
+    if (!db.batchResults) throw new Error("transaction-required");
+    const results = await db.batchResults([
+      {
+        sql: `UPDATE commerce_admission_snapshots SET linked_order_id=?
+        WHERE tenant_id=? AND stage=? AND authorization_id=? AND (linked_order_id IS NULL OR linked_order_id=?)
+        AND EXISTS(SELECT 1 FROM scrappy_final_cart_authorizations WHERE tenant_id=? AND stage=? AND authorization_id=? AND state IN ('active','consumed'))
+        AND NOT EXISTS(SELECT 1 FROM json_each(commerce_admission_snapshots.snapshot_json,'$.lines') line
+          WHERE NOT EXISTS(SELECT 1 FROM scrappy_allocations allocation WHERE allocation.tenant_id=commerce_admission_snapshots.tenant_id
+            AND allocation.stage=commerce_admission_snapshots.stage AND allocation.order_id IN (commerce_admission_snapshots.authorization_id,?)
+            AND allocation.sku=json_extract(line.value,'$.sku') AND allocation.quantity=json_extract(line.value,'$.quantity')
+            AND allocation.state IN ('reserved','confirmed')))
+        RETURNING authorization_id`,
+        params: [
+          input.orderId,
+          input.tenantId,
+          input.stage,
+          admission.authorizationId,
+          input.orderId,
+          input.tenantId,
+          input.stage,
+          admission.authorizationId,
+          input.orderId,
+        ],
+      },
+      {
+        sql: `UPDATE scrappy_allocations SET order_id=?,state='confirmed'
+        WHERE tenant_id=? AND stage=? AND order_id=? AND state='reserved'
+        AND EXISTS(SELECT 1 FROM commerce_admission_snapshots WHERE tenant_id=? AND stage=? AND authorization_id=? AND linked_order_id=?)`,
+        params: [
+          input.orderId,
+          input.tenantId,
+          input.stage,
+          admission.authorizationId,
+          input.tenantId,
+          input.stage,
+          admission.authorizationId,
+          input.orderId,
+        ],
+      },
+      {
+        sql: `UPDATE scrappy_final_cart_authorizations SET state='consumed'
+        WHERE tenant_id=? AND stage=? AND authorization_id=? AND state='active'
+        AND EXISTS(SELECT 1 FROM commerce_admission_snapshots WHERE tenant_id=? AND stage=? AND authorization_id=? AND linked_order_id=?)`,
+        params: [
+          input.tenantId,
+          input.stage,
+          admission.authorizationId,
+          input.tenantId,
+          input.stage,
+          admission.authorizationId,
+          input.orderId,
+        ],
+      },
+    ]);
+    trusted = Boolean(results[0]?.results.length);
+  }
+  const evidence = trusted && admission ? admission.evidence : UNKNOWN;
+  const service = new FulfillmentService(fulfillmentDbFromQueryable(db), {
+    policy: { adultSignatureRequired: false, prohibitedCarriers: [], carrierAccountId: null },
+    now: () => input.now,
+  });
+  const applied = await service.applySourceSnapshot(
+    { role: "owner", actorId: "commerce-source", tenantId: input.tenantId, stage: input.stage },
+    {
+      ...snapshot,
+      ...input,
+      sourceVersion: events.length,
+      amountMinor: snapshot.totals.totalMinor,
+      evidence,
+      ...(admission
+        ? {
+            evidenceExpiresAt: new Date(
+              Math.min(...Object.values(admission.provenance).map((proof) => Date.parse(proof.expiresAt))),
+            ).toISOString(),
+          }
+        : {}),
+      lines,
+      address: null,
+      compliance: trusted ? snapshot.compliance : "UNKNOWN",
+      stock: trusted && snapshot.payment === "captured" ? "confirmed" : "UNKNOWN",
+      fulfillment:
+        snapshot.fulfillment === "UNKNOWN" ? "UNKNOWN" : snapshot.fulfillment === "cancelled" ? "cancelled" : "held",
+    },
+  );
+  if (!applied.ok) throw new Error("projection-failed");
+}

package/apps/storefront/src/lib/fulfillment/commerceReadback.ts

@@ -0,0 +1,60 @@
+import type { Queryable } from "../catalog/d1/catalog.js";
+import type { CommerceStage } from "@tot/public-runtime";
+/** Readback reports projection health; it does not certify external payment reconciliation. */
+export async function readCommerceDurability(
+  db: Queryable,
+  tenantId: string,
+  stage: CommerceStage,
+  now: string,
+  deployedSha: string,
+) {
+  const run = await db.first<{
+    run_id: string;
+    started_at: string;
+    completed_at: string | null;
+    deployed_sha: string;
+    delivered: number;
+    retried: number;
+    dead: number;
+  }>(
+    `SELECT * FROM commerce_recovery_runs WHERE tenant_id=? AND stage=? ORDER BY started_at DESC,run_id DESC LIMIT 1`,
+    tenantId,
+    stage,
+  );
+  const queue = await db.first<{ pending: number; dead: number; delivered: number }>(
+    `SELECT
+    SUM(CASE WHEN state='pending' THEN 1 ELSE 0 END) pending,
+    SUM(CASE WHEN state='dead' THEN 1 ELSE 0 END) dead,
+    SUM(CASE WHEN state='delivered' THEN 1 ELSE 0 END) delivered FROM scrappy_commerce_outbox WHERE tenant_id=? AND stage=?`,
+    tenantId,
+    stage,
+  );
+  const pending = Number(queue?.pending ?? 0),
+    dead = Number(queue?.dead ?? 0),
+    delivered = Number(queue?.delivered ?? 0);
+  const stale = Boolean(run?.completed_at && Date.parse(now) - Date.parse(run.completed_at) > 24 * 60 * 60 * 1000);
+  const readiness = !deployedSha ? "unreadable" : !run
+    ? "absent"
+    : !run.completed_at || pending || dead
+      ? "failed"
+      : stale || run.deployed_sha !== deployedSha
+        ? "stale"
+        : delivered > 0
+          ? "exercised"
+          : "configured-only";
+  return {
+    schema: "commerce-durability-v1",
+    readiness,
+    healthy: readiness === "exercised",
+    tenantId,
+    stage,
+    pending,
+    dead,
+    delivered,
+    run: run
+      ? { id: run.run_id, startedAt: run.started_at, completedAt: run.completed_at, deployedSha: run.deployed_sha }
+      : null,
+    paymentReconciliation: "not-measured",
+    labelAndPostageCompared: false,
+  };
+}