@tokenoftrust/storefront-runner 2.4.90 → 2.5.0

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

@@ -0,0 +1,65 @@
+import { ScrappyOrderLedger } from "../orders/data/ordersStore.js";
+/** Production destination handler: delivery succeeds only after the persisted desk projection succeeds. */
+import { COMMERCE_SCHEDULER, type CommerceStage } from "@tot/public-runtime";
+import type { Queryable } from "../catalog/d1/catalog.js";
+import { sweepDurableCommerce } from "../integrations/webhooks/deliveryEngine.js";
+import { projectCommerceOrder } from "./commerceProjection.js";
+
+export async function recoverTenantCommerce(
+  db: Queryable,
+  tenantId: string,
+  now: string,
+  deployedSha: string,
+): Promise<number | null> {
+  for (const stage of ["preview", "publication"] as const) {
+    const runId = crypto.randomUUID();
+    await db.run(
+      `INSERT INTO commerce_recovery_runs(run_id,tenant_id,stage,started_at,deployed_sha) VALUES(?,?,?,?,?)`,
+      runId,
+      tenantId,
+      stage,
+      now,
+      deployedSha,
+    );
+    const result = await sweepDurableCommerce({
+      db,
+      scheduler: COMMERCE_SCHEDULER,
+      now,
+      tenantId,
+      stage,
+      deliver: async (_event, row) => {
+        if (row.stage !== "preview" && row.stage !== "publication") throw new Error("invalid-stage");
+        await projectCommerceOrder(db, {
+          tenantId: row.tenant_id,
+          stage: row.stage as CommerceStage,
+          orderId: row.order_id,
+          now,
+        });
+      },
+    });
+    if (!result.ok) throw new Error("scheduler-unavailable");
+    await db.run(
+      `UPDATE commerce_recovery_runs SET completed_at=?,delivered=?,retried=?,dead=? WHERE run_id=?`,
+      now,
+      result.delivered,
+      result.retried,
+      result.dead,
+      runId,
+    );
+  }
+  const due = await db.first<{ available_at: string }>(
+    `SELECT MIN(available_at) available_at FROM scrappy_commerce_outbox WHERE tenant_id=? AND state='pending'`,
+    tenantId,
+  );
+  return due?.available_at ? Math.max(Date.parse(now) + 1000, Date.parse(due.available_at)) : null;
+}
+
+export async function replayCommerceOrder(
+  db: Queryable,
+  tenantId: string,
+  stage: CommerceStage,
+  outboxId: string,
+  now: string,
+): Promise<boolean> {
+  return new ScrappyOrderLedger(db).replayOutbox(tenantId, stage, outboxId, now);
+}

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

@@ -0,0 +1,13 @@
+/** Commerce reaches the existing tenant scheduler through its own narrow RPC interface. */
+import { getWorkerEnv } from "../publication/shared/runtimeEnv.js";
+import type { CommerceCallerConfig, SignedCommerceResult } from "../orders/data/orderForwardReceiver.js";
+export interface CommercePipeline {
+  commerceReceive(body: unknown, token: string, config: CommerceCallerConfig): Promise<SignedCommerceResult>;
+  commerceReplay(tenantId: string, stage: "preview" | "publication", outboxId: string): Promise<boolean>;
+}
+export async function commercePipelineFor(tenantId: string): Promise<CommercePipeline | null> {
+  const namespace = (await getWorkerEnv())?.TENANT_PIPELINE as
+    | { idFromName(name: string): unknown; get(id: unknown): CommercePipeline }
+    | undefined;
+  return namespace && typeof namespace.idFromName === "function" ? namespace.get(namespace.idFromName(tenantId)) : null;
+}

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

@@ -61,6 +61,8 @@ export interface FulfillmentActor extends CommerceActor {
 }
 
 export interface SourceOrderSnapshot {
+  sourceVersion?: number;
+  evidenceExpiresAt?: string;
   tenantId: string;
   stage: CommerceStage;
   orderId: string;
@@ -117,6 +119,10 @@ export interface FulfillmentView {
   batch: { batchId: string; phase: BatchPhase } | null;
   shipment: ShipmentIntentView | null;
   packingSlip: PackingSlip | null;
+  lines: {sku:string;quantity:number}[];
+  evidence: CommerceEvidence;
+  placedAt: string;
+  currency: string;
 }
 
 export interface FulfillmentBatch {
@@ -291,9 +297,9 @@ function observedEvent(input: {
 }
 
 function mergePayment(local: PaymentState | null, source: PaymentState): PaymentState {
-  if (local === "refund_requested" && (source === "captured" || source === "authorized" || source === "pending")) {
-    return "refund_requested";
-  }
+  if (local && ["refund_requested", "refund_unknown", "refunded", "voided"].includes(local) &&
+      ["UNKNOWN", "pending", "authorized", "captured", "capture_unknown"].includes(source)) return local;
+  if (local === "refunded") return local;
   return source;
 }
 
@@ -542,6 +548,19 @@ export class FulfillmentService {
     return state ? ok(state.view) : refuse("not-found");
   }
 
+  async list(actor: FulfillmentActor, input: {limit:number;cursor:string|null}): Promise<FulfillmentResult<{orders:FulfillmentView[];nextCursor:string|null}>> {
+    const scope=this.commandScope(actor);
+    if (!scope) return refuse("denied");
+    const limit=Math.max(1,Math.min(50,input.limit));
+    const cursor=input.cursor ?? "";
+    if (cursor && !isOpaqueId(cursor)) return refuse("malformed");
+    const rows=await this.db.all<{order_id:string}>(`SELECT order_id FROM scrappy_commerce_orders
+      WHERE tenant_id=? AND stage=? AND order_id>? AND source != 'scrappy' ORDER BY order_id LIMIT ?`,[scope.tenantId,scope.stage,cursor,limit+1]);
+    const selected=rows.slice(0,limit); const orders:FulfillmentView[]=[];
+    for (const row of selected) { const state=await this.load(scope.tenantId,scope.stage,row.order_id); if(state) orders.push(state.view); }
+    return ok({orders,nextCursor:rows.length>limit ? selected[selected.length-1]?.order_id ?? null:null});
+  }
+
   async batch(actor: FulfillmentActor, batchId: string): Promise<FulfillmentResult<FulfillmentBatch>> {
     const scope = this.commandScope(actor);
     if (!scope) return refuse("denied");
@@ -980,6 +999,7 @@ export class FulfillmentService {
       const wantSlip = phase === "packed" && !state.packingSlip;
       const readiness = this.readiness(state);
       const releasable = canRelease(readiness);
+      if (raising && !releasable) return {type:"refuse",code:releaseHolds(readiness)[0] ?? "held",holds:releaseHolds(readiness)};
       const labelAcceptsIntent = state.order.label === "none" || state.order.label === "voided" || state.order.label === "intent";
       const wantIntent = (phase === null || phase === "picked" || phase === "packed") && releasable && !state.shipment && labelAcceptsIntent;
       if (phase === null && !state.shipment && !wantIntent) {
@@ -1170,6 +1190,7 @@ export class FulfillmentService {
         eventVersion: version,
       },
     };
+    if (snapshot.evidenceExpiresAt) statements.push(gatedAudit(stub, actor.actorId, "evidence-expires", "none", snapshot.evidenceExpiresAt, stamp(this.now(), 6), gate, gateParams));
     statements.push(
       gatedAudit(stub, actor.actorId, "evidence", "none", jsonText(snapshot.evidence), at, gate, gateParams),
       gatedAudit(stub, actor.actorId, "lines", "none", jsonText(snapshot.lines), stamp(this.now(), 2), gate, gateParams),
@@ -1199,6 +1220,7 @@ export class FulfillmentService {
         gateParams,
       ),
     );
+    if (snapshot.sourceVersion !== undefined) statements.push(projectionCheckpoint(snapshot,version,this.now()));
     const changes = await this.write(statements);
     if (!changes) return refuse("unavailable");
     if ((changes[0] ?? 0) !== 1) return "exists";
@@ -1211,7 +1233,11 @@ export class FulfillmentService {
     _existing: LoadedOrder,
     snapshot: SourceOrderSnapshot,
   ): Promise<FulfillmentResult<FulfillmentView>> {
-    return this.commit(actor, snapshot.orderId, undefined, (state) => {
+    return this.commit(actor, snapshot.orderId, undefined, async (state) => {
+      if (snapshot.sourceVersion !== undefined) {
+        const checkpoint=await this.db.get<{source_version:number}>(`SELECT source_version FROM commerce_projection_checkpoints WHERE tenant_id=? AND stage=? AND order_id=?`,[snapshot.tenantId,snapshot.stage,snapshot.orderId]);
+        if (checkpoint && Number(checkpoint.source_version)>=snapshot.sourceVersion) return {type:"done",view:state.view};
+      }
       const payment = mergePayment(state.order.payment, snapshot.payment);
       const label = mergeLabel(state.order.label, snapshot.label);
       const confirmedCancel = snapshot.fulfillment === "cancelled" || payment === "voided" || payment === "refunded";
@@ -1243,6 +1269,10 @@ export class FulfillmentService {
       ];
       let n = state.auditCount;
       const nextVersion = version;
+      if(snapshot.evidenceExpiresAt) {
+        n+=1; statements.push(auditStatement(state,actor.actorId,"evidence-expires","source",snapshot.evidenceExpiresAt,version,stamp(this.now(),n)));
+      }
+
       n += 1;
       statements.push(auditStatement(state, actor.actorId, "evidence", "source", jsonText(snapshot.evidence), nextVersion, stamp(this.now(), n)));
       n += 1;
@@ -1308,6 +1338,7 @@ export class FulfillmentService {
         n += 1;
         statements.push(auditStatement(state, actor.actorId, "pending-cancel", "open", "confirmed", nextVersion, stamp(this.now(), n)));
       }
+      if (snapshot.sourceVersion !== undefined) statements.push(projectionCheckpoint(snapshot,nextVersion,this.now()));
       return { type: "write", statements, minimumChanges: 1 };
     });
   }
@@ -1354,6 +1385,7 @@ export class FulfillmentService {
       [tenantId, stage, orderId],
     );
     let evidence = FAIL_CLOSED_EVIDENCE;
+    let evidenceExpiresAt:string|null=null;
     let lines: { sku: string; quantity: number }[] = [];
     let totals: MinorTotals | null = null;
     let batch: { batchId: string; phase: BatchPhase } | null = null;
@@ -1366,6 +1398,7 @@ export class FulfillmentService {
     let intentAdult = this.policy.adultSignatureRequired;
     for (const audit of audits) {
       if (audit.kind === "evidence") evidence = parseEvidence(parseJson(audit.to_state)) ?? FAIL_CLOSED_EVIDENCE;
+      else if (audit.kind === "evidence-expires") evidenceExpiresAt=audit.to_state;
       else if (audit.kind === "lines") lines = parseLines(parseJson(audit.to_state)) ?? [];
       else if (audit.kind === "totals") totals = parseTotals(parseJson(audit.to_state));
       else if (audit.kind === "batch") batch = parseBatchState(audit.to_state);
@@ -1384,6 +1417,9 @@ export class FulfillmentService {
         }
       }
     }
+    if(evidenceExpiresAt && (!Number.isFinite(Date.parse(evidenceExpiresAt)) || Date.parse(evidenceExpiresAt)<=Date.parse(this.now()))) {
+      evidence={verification:"stale",tax:"stale",risk:"stale",stock:"stale"};
+    }
     const provider = pickProvider(providers);
     const order = {
       tenantId,
@@ -1435,6 +1471,7 @@ export class FulfillmentService {
         batch,
         shipment: null,
         packingSlip,
+        lines, evidence, placedAt:order.placedAt, currency:order.currency,
       },
     };
     const readiness = this.readiness(loaded);
@@ -1564,6 +1601,7 @@ function projectedFromSnapshot(
   cancelPending: boolean,
 ): FulfillmentState {
   if (current === "handed_off") return "handed_off";
+  if (current === "cancelled") return "cancelled";
   if (snapshot.fulfillment === "cancelled" || payment === "voided" || payment === "refunded") return "cancelled";
   if (snapshot.fulfillment === "UNKNOWN") return "UNKNOWN";
   const holds = releaseHolds({
@@ -1650,3 +1688,11 @@ function pickProvider(rows: readonly { purchase_id: string; outcome: string }[])
   if (!chosen || !oneOf(chosen.outcome, ["intent", "accepted", "unknown", "voided", "refunded"] as const)) return null;
   return { purchaseId: chosen.purchase_id, outcome: chosen.outcome };
 }
+
+function projectionCheckpoint(snapshot:SourceOrderSnapshot,version:number,at:string):SqlStatement {
+ return {sql:`INSERT INTO commerce_projection_checkpoints(tenant_id,stage,order_id,source_version,projected_at)
+   SELECT ?,?,?,?,? WHERE EXISTS(SELECT 1 FROM scrappy_commerce_orders WHERE tenant_id=? AND stage=? AND order_id=? AND event_version=?)
+   ON CONFLICT(tenant_id,stage,order_id) DO UPDATE SET source_version=excluded.source_version,projected_at=excluded.projected_at
+   WHERE excluded.source_version>commerce_projection_checkpoints.source_version`,
+   params:[snapshot.tenantId,snapshot.stage,snapshot.orderId,snapshot.sourceVersion,at,snapshot.tenantId,snapshot.stage,snapshot.orderId,version]};
+}

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

@@ -62,6 +62,7 @@ export interface ReadinessInput {
 
 const EVIDENCE_HOLDS: Record<EvidenceState, ReleaseHold | null> = {
   fresh: null,
+  "not-required": null,
   UNKNOWN: "evidence-unknown",
   stale: "evidence-stale",
   unreadable: "evidence-unreadable",

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

@@ -107,3 +107,18 @@ export function fulfillmentDbFromD1(db: D1Like): FulfillmentDatabase {
     },
   };
 }
+
+/** Reuses Queryable's transactional D1 batch and keeps affected-row checks inside that transaction. */
+export function fulfillmentDbFromQueryable(db: import("../catalog/d1/catalog.js").Queryable): FulfillmentDatabase {
+  return {
+    get: async (sql,params=[]) => (await db.first(sql,...params) ?? undefined) as never,
+    all: (sql,params=[]) => db.all(sql,...params),
+    async batch(statements) {
+      if (!db.batchResults) throw new Error("transaction-results-required");
+      const results=await db.batchResults(statements.flatMap(statement=>[
+        {sql:statement.sql,params:statement.params},{sql:"SELECT changes() AS affected"},
+      ]));
+      return statements.map((_,index)=>Number(results[index*2+1]?.results[0]?.affected ?? 0));
+    },
+  };
+}

package/apps/storefront/src/lib/integrations/webhooks/deliveryEngine.ts

@@ -328,7 +328,7 @@ export type CommerceSweepResult =
   | { ok: true; delivered: number; retried: number; dead: number }
   | { ok: false; reason: "scheduler" };
 
-export type CommerceDeliver = (event: Record<string, unknown>) => Promise<void>;
+export type CommerceDeliver = (event: Record<string, unknown>, row: CommerceOutboxDue) => Promise<void>;
 
 /**
  * Deliver due commerce outbox rows. A scheduler other than the declared alarm
@@ -339,10 +339,12 @@ export async function sweepDurableCommerce(input: {
   scheduler: string;
   now: string;
   deliver?: CommerceDeliver;
+  tenantId?: string;
+  stage?: string;
 }): Promise<CommerceSweepResult> {
   if (input.scheduler !== COMMERCE_SCHEDULER) return { ok: false, reason: "scheduler" };
   const port = new ScrappyCommerceOutbox(input.db);
-  const due = await port.due(input.now);
+  const due = await port.due(input.now,input.tenantId,input.stage);
   let delivered = 0;
   let retried = 0;
   let dead = 0;
@@ -375,7 +377,8 @@ async function settleCommerceRow(
     return "dead";
   }
   try {
-    if (deliver) await deliver(event);
+    if (!deliver) throw new Error("delivery-unconfigured");
+    await deliver(event,row);
     await port.markDelivered(row.outbox_id);
     return "delivered";
   } catch {

package/apps/storefront/src/lib/integrations/webhooks/deliveryStore.ts

@@ -667,6 +667,7 @@ export class WebhookDeliveryStore {
 }
 
 export interface CommerceOutboxDue {
+  order_id: string;
   outbox_id: string;
   tenant_id: string;
   stage: string;
@@ -679,13 +680,13 @@ export interface CommerceOutboxDue {
 export class ScrappyCommerceOutbox {
   constructor(private readonly db: Queryable) {}
 
-  async due(now: string): Promise<CommerceOutboxDue[]> {
+  async due(now: string, tenantId?: string, stage?: string): Promise<CommerceOutboxDue[]> {
     const rows = await this.db.all<CommerceOutboxDue>(
-      `SELECT outbox_id, tenant_id, stage, payload, attempt_count, available_at
+      `SELECT outbox_id, tenant_id, stage, order_id, payload, attempt_count, available_at
          FROM scrappy_commerce_outbox
-        WHERE state = 'pending' AND available_at <= ?
-        ORDER BY available_at`,
-      now,
+        WHERE state = 'pending' AND available_at <= ? AND (? IS NULL OR tenant_id=?) AND (? IS NULL OR stage=?)
+        ORDER BY available_at LIMIT 100`,
+      now, tenantId ?? null, tenantId ?? null, stage ?? null, stage ?? null,
     );
     return rows.map((row) => ({ ...row, attempt_count: Number(row.attempt_count) }));
   }

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

@@ -22,6 +22,7 @@ export const VERIFICATION_PROVIDER_OWNER = "tot-9577-tot-verification-provider";
 
 const SKU_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$/;
 const ID_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
+const TENANT_RE = /^[a-z0-9][a-z0-9.-]{0,253}$/;
 const LOCATION_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,80}$/;
 const ISSUER_RE = /^[A-Za-z0-9._:/?#&=%+-]{1,200}$/;
 const JTI_RE = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,128}$/;
@@ -83,11 +84,15 @@ export interface ReserveInput {
   issuer: string;
   jti: string;
   holds: readonly ReserveHold[];
+  /** Trusted server snapshot committed in the same transaction as the stock holds. */
+  admissionStatement?: SqlStatement;
+  /** Immutable provider identity, claimed atomically with its receipt and holds. */
+  providerCart?: { provider: "foxycart"; id: string; digest: string; expectedAuthorizationId?: string };
 }
 
 export type ReserveResult =
   | { ok: true; authorizationId: string; repeated: boolean; expiresAt: string }
-  | { ok: false; finding: "caller-replay" | "stock-unavailable" | "malformed-request" };
+  | { ok: false; finding: "caller-replay" | "stock-unavailable" | "malformed-request" | "provider-cart-conflict" | "admission-consumed" | "admission-expired" };
 
 export interface PolicyResult {
   released: number;
@@ -235,7 +240,7 @@ function text(row: Record<string, unknown>, key: string): string {
 }
 
 function reserveShape(input: ReserveInput): ReserveResult | null {
-  if (!ID_RE.test(input.tenantId) || !ID_RE.test(input.orderId)) return { ok: false, finding: "malformed-request" };
+  if (!TENANT_RE.test(input.tenantId) || !ID_RE.test(input.orderId)) return { ok: false, finding: "malformed-request" };
   if (input.stage !== "preview" && input.stage !== "publication") return { ok: false, finding: "malformed-request" };
   if (!DIGEST_RE.test(input.cartDigest) || !/^[A-Z]{3}$/.test(input.currency)) return { ok: false, finding: "malformed-request" };
   if (!ISSUER_RE.test(input.issuer) || !JTI_RE.test(input.jti)) return { ok: false, finding: "malformed-request" };
@@ -256,7 +261,10 @@ function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string
       WHERE (
         SELECT COALESCE(SUM(quantity), 0) FROM scrappy_allocations
         WHERE tenant_id = ? AND stage = ? AND sku = ? AND location_id = ? AND state IN ('reserved', 'confirmed')
-      ) + ? <= ?
+      ) + ? <= ${input.admissionStatement
+        ? `(SELECT COALESCE(SUM(quantity_delta), 0) FROM commerce_inventory_movements
+            WHERE tenant_id = ? AND stage = ? AND sku = ? AND location_id = ?)`
+        : "?"}
       AND NOT EXISTS (
         SELECT 1 FROM scrappy_allocations
         WHERE tenant_id = ? AND stage = ? AND order_id = ? AND sku = ? AND location_id = ?
@@ -274,6 +282,7 @@ function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string
         SELECT 1 FROM scrappy_commerce_orders
         WHERE tenant_id = ? AND stage = ? AND order_id = ?
       )
+      ${input.providerCart ? `AND EXISTS (SELECT 1 FROM commerce_provider_carts WHERE tenant_id=? AND stage=? AND provider=? AND provider_cart_id=? AND authorization_id=? AND provider_cart_digest=?)` : ""}
       ON CONFLICT DO NOTHING
       RETURNING order_id`,
     params: [
@@ -288,7 +297,9 @@ function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string
       hold.sku,
       hold.locationId,
       hold.quantity,
-      hold.onHand,
+      ...(input.admissionStatement
+        ? [input.tenantId, input.stage, hold.sku, hold.locationId]
+        : [hold.onHand]),
       input.tenantId,
       input.stage,
       input.orderId,
@@ -305,6 +316,7 @@ function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string
       input.tenantId,
       input.stage,
       input.orderId,
+      ...(input.providerCart ? [input.tenantId,input.stage,input.providerCart.provider,input.providerCart.id,input.orderId,input.providerCart.digest] : []),
     ],
   };
 }
@@ -313,6 +325,10 @@ function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string
 export async function reserveAllocation(runner: StatementRunner, input: ReserveInput): Promise<ReserveResult> {
   const malformed = reserveShape(input);
   if (malformed) return malformed;
+  const cart = input.providerCart;
+  if (!!cart !== !!input.admissionStatement) return { ok: false, finding: "malformed-request" };
+  if (cart && (!input.admissionStatement || cart.provider !== "foxycart" || !/^[a-zA-Z0-9._:-]{1,128}$/.test(cart.id) || !DIGEST_RE.test(cart.digest) ||
+      (cart.expectedAuthorizationId !== undefined && !ID_RE.test(cart.expectedAuthorizationId)))) return { ok: false, finding: "malformed-request" };
   const seen = await runner.all(
     `SELECT jti FROM scrappy_caller_replay WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ?`,
     [input.tenantId, input.stage, input.issuer, input.jti],
@@ -339,6 +355,12 @@ export async function reserveAllocation(runner: StatementRunner, input: ReserveI
         RETURNING order_id`,
       params: [input.tenantId, input.stage, input.orderId, input.orderId, input.currency, input.now, input.amountMinor],
     },
+    ...(cart ? [{
+      sql: `INSERT INTO commerce_provider_carts (tenant_id,stage,provider,provider_cart_id,provider_cart_digest,authorization_id)
+        SELECT ?,?,?,?,?,? WHERE ?='' AND EXISTS (SELECT 1 FROM scrappy_caller_replay WHERE tenant_id=? AND stage=? AND issuer=? AND jti=? AND seen_at=?)
+        ON CONFLICT DO NOTHING RETURNING authorization_id`,
+      params: [input.tenantId,input.stage,cart.provider,cart.id,cart.digest,input.orderId,cart.expectedAuthorizationId ?? "",input.tenantId,input.stage,input.issuer,input.jti,seenAt],
+    }] : []),
     ...holds.map((hold) => allocationInsert(input, hold, seenAt)),
     {
       sql: `INSERT INTO scrappy_final_cart_authorizations (
@@ -379,13 +401,14 @@ export async function reserveAllocation(runner: StatementRunner, input: ReserveI
         seenAt,
       ],
     },
+    ...(input.admissionStatement ? [input.admissionStatement] : []),
     {
       sql: `UPDATE scrappy_allocations
         SET state = 'released'
         WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'reserved'
           AND NOT EXISTS (
             SELECT 1 FROM scrappy_final_cart_authorizations
-            WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state = 'active'
+            WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state IN ('active', 'consumed')
           )
         RETURNING quantity`,
       params: [input.tenantId, input.stage, input.orderId, input.tenantId, input.stage, input.orderId],
@@ -410,10 +433,30 @@ export async function reserveAllocation(runner: StatementRunner, input: ReserveI
     },
   ];
 
+  if (cart) statements.push({
+    sql: `DELETE FROM commerce_provider_carts WHERE tenant_id=? AND stage=? AND provider=? AND provider_cart_id=? AND authorization_id=?
+      AND NOT EXISTS (SELECT 1 FROM commerce_admission_snapshots WHERE tenant_id=? AND stage=? AND authorization_id=?)`,
+    params: [input.tenantId,input.stage,cart.provider,cart.id,input.orderId,input.tenantId,input.stage,input.orderId],
+  }, {
+    sql: `SELECT p.authorization_id,p.provider_cart_digest,a.expires_at,a.state,s.authorization_id receipt_id FROM commerce_provider_carts p
+      LEFT JOIN scrappy_final_cart_authorizations a ON a.tenant_id=p.tenant_id AND a.stage=p.stage AND a.authorization_id=p.authorization_id
+      LEFT JOIN commerce_admission_snapshots s ON s.tenant_id=p.tenant_id AND s.stage=p.stage AND s.authorization_id=p.authorization_id
+      WHERE p.tenant_id=? AND p.stage=? AND p.provider=? AND p.provider_cart_id=?`,
+    params: [input.tenantId,input.stage,cart.provider,cart.id],
+  });
   const results = await runner.batch(statements);
   const replayRows = results[0] ?? [];
-  const authRows = results[2 + holds.length] ?? [];
+  const authRows = results[2 + holds.length + (cart ? 1 : 0)] ?? [];
   const selected = results[results.length - 1] ?? [];
+  if (cart && replayRows.length > 0) {
+    const current = selected[0];
+    if (!current) return { ok: false, finding: cart.expectedAuthorizationId ? "provider-cart-conflict" : "stock-unavailable" };
+    if (text(current,"provider_cart_digest") !== cart.digest || (cart.expectedAuthorizationId && text(current,"authorization_id") !== cart.expectedAuthorizationId)) return { ok: false, finding: "provider-cart-conflict" };
+    if (!text(current,"receipt_id")) return { ok: false, finding: "provider-cart-conflict" };
+    if (text(current,"state") !== "active") return { ok: false, finding: "admission-consumed" };
+    if (text(current,"expires_at") <= input.now) return { ok: false, finding: "admission-expired" };
+    return { ok: true, authorizationId: text(current,"authorization_id"), repeated: authRows.length === 0, expiresAt: text(current,"expires_at") };
+  }
   if (authRows.length > 0) {
     return { ok: true, authorizationId: input.orderId, repeated: false, expiresAt: input.expiresAt };
   }
@@ -446,9 +489,11 @@ export async function releaseHoldOnce(
     {
       sql: `UPDATE scrappy_final_cart_authorizations
         SET state = ?
-        WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state IN ('active', 'consumed')
+        WHERE tenant_id = ? AND stage = ? AND (authorization_id = ? OR authorization_id IN (
+          SELECT authorization_id FROM commerce_admission_snapshots WHERE tenant_id=? AND stage=? AND linked_order_id=?
+        )) AND state IN ('active', 'consumed')
         RETURNING authorization_id`,
-      params: [input.authState, ...scope],
+      params: [input.authState, ...scope, ...scope],
     },
     {
       sql: `UPDATE scrappy_allocations
@@ -529,7 +574,11 @@ export async function releaseOrphanAllocations(
             SELECT 1 FROM scrappy_final_cart_authorizations AS auth
             WHERE auth.tenant_id = scrappy_allocations.tenant_id
               AND auth.stage = scrappy_allocations.stage
-              AND auth.authorization_id = scrappy_allocations.order_id
+              AND (auth.authorization_id = scrappy_allocations.order_id OR EXISTS (
+                SELECT 1 FROM commerce_admission_snapshots admission WHERE admission.tenant_id=auth.tenant_id
+                  AND admission.stage=auth.stage AND admission.authorization_id=auth.authorization_id
+                  AND admission.linked_order_id=scrappy_allocations.order_id
+              ))
               AND auth.state IN ('active', 'consumed')
           )
         RETURNING quantity`,

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

@@ -0,0 +1,121 @@
+/** Tenant-scoped inventory authority. Catalog availability never supplies a balance. */
+import type { Queryable } from "../catalog/d1/catalog.js";
+import type { CommerceStage } from "@tot/public-runtime";
+import type { MirrorStockAuthority } from "./allocations.js";
+
+const ID = /^[A-Za-z0-9._:-]{1,128}$/;
+/** Stable caller-visible failures; storage errors retain no public text. */
+export class InventoryMovementError extends Error {
+  constructor(readonly code: "invalid-movement" | "conflict") {
+    super(code === "conflict" ? "inventory-event-conflict" : "invalid-inventory-movement");
+    this.name = "InventoryMovementError";
+  }
+}
+
+export interface MirrorMovement {
+  tenantId: string;
+  stage: CommerceStage;
+  source: string;
+  sourceEventId: string;
+  sku: string;
+  locationId: string;
+  quantityDelta: number;
+  asOf: string;
+  actorId: string;
+}
+export async function appendMirrorMovement(db: Queryable, input: MirrorMovement): Promise<void> {
+  if (
+    ![input.tenantId, input.source, input.sourceEventId, input.sku, input.locationId, input.actorId].every((v) =>
+      ID.test(v),
+    ) ||
+    !Number.isSafeInteger(input.quantityDelta) ||
+    !Number.isFinite(Date.parse(input.asOf)) ||
+    !["preview", "publication"].includes(input.stage)
+  )
+    throw new InventoryMovementError("invalid-movement");
+  const prior = await db.first<{ quantity_delta: number; as_of: string; actor_id: string }>(
+    `SELECT quantity_delta,as_of,actor_id 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,
+  );
+  if (
+    prior &&
+    (Number(prior.quantity_delta) !== input.quantityDelta ||
+      prior.as_of !== input.asOf ||
+      prior.actor_id !== input.actorId)
+  )
+    throw new InventoryMovementError("conflict");
+  await db.run(
+    `INSERT INTO commerce_inventory_movements
+    (tenant_id,stage,source,source_event_id,sku,location_id,quantity_delta,as_of,actor_id)
+    VALUES(?,?,?,?,?,?,?,?,?) ON CONFLICT DO NOTHING`,
+    input.tenantId,
+    input.stage,
+    input.source,
+    input.sourceEventId,
+    input.sku,
+    input.locationId,
+    input.quantityDelta,
+    input.asOf,
+    input.actorId,
+  );
+  const actual = await db.first<{ quantity_delta: number; as_of: string; actor_id: string }>(
+    `SELECT quantity_delta,as_of,actor_id 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,
+  );
+  if (
+    !actual ||
+    Number(actual.quantity_delta) !== input.quantityDelta ||
+    actual.as_of !== input.asOf ||
+    actual.actor_id !== input.actorId
+  )
+    throw new InventoryMovementError("conflict");
+}
+export async function readMirrorStock(
+  db: Queryable,
+  input: {
+    tenantId: string;
+    stage: CommerceStage;
+    sku: string;
+    locationId: string;
+    now: string;
+    maxAgeMs: number;
+  },
+): Promise<MirrorStockAuthority | null> {
+  const row = await db.first<{ balance: number; as_of: string }>(
+    `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 || !Number.isSafeInteger(Number(row.balance)) || Number(row.balance) < 0) return null;
+  const age = Date.parse(input.now) - Date.parse(row.as_of);
+  if (
+    !Number.isFinite(age) ||
+    age < 0 ||
+    !Number.isFinite(input.maxAgeMs) ||
+    input.maxAgeMs < 0 ||
+    age > input.maxAgeMs
+  )
+    return null;
+  return {
+    provider: "mirror",
+    readable: true,
+    sku: input.sku,
+    locationId: input.locationId,
+    onHand: Number(row.balance),
+    asOf: row.as_of,
+  };
+}

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

@@ -363,20 +363,20 @@ function deriveReadinessChecks(d: CheckoutOrderDetail, scope: CommerceScope): Or
       label: "Tax and fees",
       value: tax.state,
       detail: `Tax evidence is ${tax.state}.`,
-      tone: tax.state === "fresh" ? "blue" : "amber",
+      tone: ["fresh", "not-required"].includes(tax.state) ? "blue" : "amber",
       action: "View total",
-      blocking: tax.state !== "fresh",
+      blocking: !["fresh", "not-required"].includes(tax.state),
     },
     {
       key: "identity_and_age",
       label: "Identity and age",
       value: ageHold ? "Needs review" : verification.state,
-      detail: verification.state === "fresh"
-        ? "Verification evidence is fresh."
+      detail: ["fresh", "not-required"].includes(verification.state)
+        ? `Verification evidence is ${verification.state}.`
         : "Verification evidence does not clear this order.",
-      tone: verification.state === "fresh" && !ageHold ? "green" : "amber",
+      tone: ["fresh", "not-required"].includes(verification.state) && !ageHold ? "green" : "amber",
       action: "View evidence",
-      blocking: ageHold || verification.state !== "fresh",
+      blocking: ageHold || !["fresh", "not-required"].includes(verification.state),
     },
     {
       key: "address",
@@ -392,9 +392,9 @@ function deriveReadinessChecks(d: CheckoutOrderDetail, scope: CommerceScope): Or
     columnCheck(column("risk"), {
       label: "Risk",
       detail: `Risk evidence is ${column("risk").state}.`,
-      tone: column("risk").state === "fresh" ? "green" : "amber",
+      tone: ["fresh", "not-required"].includes(column("risk").state) ? "green" : "amber",
       action: "View evidence",
-      blocking: column("risk").state !== "fresh",
+      blocking: !["fresh", "not-required"].includes(column("risk").state),
     }),
     columnCheck(column("stock"), {
       label: "Stock",