@tokenoftrust/storefront-runner 2.4.50 → 2.4.52

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

@@ -0,0 +1,749 @@
+/**
+ * Mirror-stock allocations for a final cart. Catalog availability is not a hold.
+ * One allocation per tenant, stage, order, sku, and location. Payment confirmation
+ * moves `reserved` to `confirmed` once; that quantity stays the decrement.
+ * Expiry and timeout release only `reserved`. Cancel before handoff releases once.
+ * A refund does not restock. There is no on-hand ledger in this schema; `onHand`
+ * is the mirror balance the caller resolved, never a catalog quantity.
+ */
+import {
+  decideCommerceCommand,
+  type CommerceEvidence,
+  type CommerceStage,
+  type FulfillmentState,
+  type LabelState,
+  type PaymentState,
+  type StockState,
+} from "@tot/public-runtime";
+
+export const RESERVATION_AUTHORITY_HEADER = "x-tot-reservation-authority";
+export const RESERVATION_AUTHORITY_NONE = "none";
+/** Catalog `available` / `quantity` never authorizes a hold. */
+export const CATALOG_IS_RESERVATION_AUTHORITY = false;
+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 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}$/;
+const DIGEST_RE = /^[a-f0-9]{64}$/;
+
+export interface SqlStatement {
+  sql: string;
+  params: readonly unknown[];
+}
+
+export interface StatementRunner {
+  all(sql: string, params: readonly unknown[]): Promise<readonly Record<string, unknown>[]>;
+  batch(statements: readonly SqlStatement[]): Promise<readonly (readonly Record<string, unknown>[])[]>;
+}
+
+interface SqliteStatement {
+  all(...params: unknown[]): unknown[];
+}
+
+export interface SqliteDatabase {
+  exec(sql: string): void;
+  prepare(sql: string): SqliteStatement;
+}
+
+interface D1Bound {
+  all(): Promise<unknown>;
+}
+
+export interface D1CommerceDatabase {
+  prepare(sql: string): { bind(...vals: unknown[]): D1Bound };
+  batch?(statements: unknown[]): Promise<unknown[]>;
+}
+
+export interface MirrorStockAuthority {
+  provider: "mirror";
+  readable: true;
+  locationId: string;
+  sku: string;
+  onHand: number;
+  asOf: string;
+}
+
+export interface ReserveHold {
+  sku: string;
+  locationId: string;
+  quantity: number;
+  onHand: number;
+}
+
+export interface ReserveInput {
+  tenantId: string;
+  stage: CommerceStage;
+  orderId: string;
+  cartDigest: string;
+  expiresAt: string;
+  now: string;
+  currency: string;
+  amountMinor: number;
+  issuer: string;
+  jti: string;
+  holds: readonly ReserveHold[];
+}
+
+export type ReserveResult =
+  | { ok: true; authorizationId: string; repeated: boolean; expiresAt: string }
+  | { ok: false; finding: "caller-replay" | "stock-unavailable" | "malformed-request" };
+
+export interface PolicyResult {
+  released: number;
+  restock: false;
+  finding: string;
+  /** Units moved from reserved to confirmed. Present only for payment confirmation. */
+  decremented?: number;
+}
+
+type PolicyKind = "refund" | "cancel" | "payment-failure" | "confirm" | "expiry" | "timeout" | "restart";
+
+export interface PolicyInput {
+  kind: PolicyKind;
+  tenantId: string;
+  stage: CommerceStage;
+  orderId?: string;
+  now?: string;
+  evidence?: CommerceEvidence;
+  providerOutcome?: "intent" | "accepted" | "unknown" | "voided" | "refunded" | null;
+}
+
+const FRESH_EVIDENCE: CommerceEvidence = {
+  verification: "fresh",
+  tax: "fresh",
+  risk: "fresh",
+  stock: "fresh",
+};
+
+let testOnHand: ((sku: string, locationId: string) => number | null) | null = null;
+
+/**
+ * Non-production mirror balance. Production has no on-hand ledger in this schema,
+ * so the read stays empty and authorization fails closed.
+ */
+export function __setMirrorOnHandForTests(reader: ((sku: string, locationId: string) => number | null) | null): void {
+  testOnHand = reader;
+}
+
+export function mirrorOnHand(sku: string, locationId: string): number | null {
+  if (process.env.NODE_ENV === "production") return null;
+  if (!testOnHand) return null;
+  const onHand = testOnHand(sku, locationId);
+  if (typeof onHand !== "number" || !Number.isSafeInteger(onHand) || onHand < 0) return null;
+  return onHand;
+}
+
+export function reservationAuthorityHeader(): typeof RESERVATION_AUTHORITY_NONE {
+  if (CATALOG_IS_RESERVATION_AUTHORITY) {
+    throw new Error("catalog availability is not reservation authority");
+  }
+  return RESERVATION_AUTHORITY_NONE;
+}
+
+export function readMirrorAuthority(value: unknown): MirrorStockAuthority | null {
+  if (!value || typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  if (record.provider !== "mirror" || record.readable !== true) return null;
+  if (typeof record.locationId !== "string" || !LOCATION_RE.test(record.locationId)) return null;
+  if (typeof record.sku !== "string" || !SKU_RE.test(record.sku)) return null;
+  if (typeof record.onHand !== "number" || !Number.isSafeInteger(record.onHand) || record.onHand < 0) return null;
+  if (typeof record.asOf !== "string" || record.asOf.trim() === "" || record.asOf.length > 40) return null;
+  return {
+    provider: "mirror",
+    readable: true,
+    locationId: record.locationId,
+    sku: record.sku,
+    onHand: record.onHand,
+    asOf: record.asOf,
+  };
+}
+
+const chains = new WeakMap<object, Promise<unknown>>();
+
+function enqueue<T>(key: object, job: () => Promise<T> | T): Promise<T> {
+  const previous = chains.get(key) ?? Promise.resolve();
+  const run = previous.then(job, job);
+  chains.set(
+    key,
+    run.then(
+      () => undefined,
+      () => undefined,
+    ),
+  );
+  return run;
+}
+
+function asRows(value: unknown): Record<string, unknown>[] {
+  if (Array.isArray(value)) return value as Record<string, unknown>[];
+  if (value && typeof value === "object" && Array.isArray((value as { results?: unknown }).results)) {
+    return (value as { results: Record<string, unknown>[] }).results;
+  }
+  return [];
+}
+
+export function sqliteCommerceRunner(db: SqliteDatabase): StatementRunner {
+  return {
+    all(sql, params) {
+      return enqueue(db, () => db.prepare(sql).all(...params) as Record<string, unknown>[]);
+    },
+    batch(statements) {
+      return enqueue(db, () => {
+        db.exec("BEGIN IMMEDIATE");
+        try {
+          const results = statements.map(
+            (statement) => db.prepare(statement.sql).all(...statement.params) as Record<string, unknown>[],
+          );
+          db.exec("COMMIT");
+          return results;
+        } catch (error) {
+          try {
+            db.exec("ROLLBACK");
+          } catch {
+            /* the failed statement already aborted the transaction */
+          }
+          throw error;
+        }
+      });
+    },
+  };
+}
+
+export function d1CommerceRunner(db: D1CommerceDatabase): StatementRunner {
+  return {
+    async all(sql, params) {
+      return asRows(await db.prepare(sql).bind(...params).all());
+    },
+    async batch(statements) {
+      if (!db.batch) {
+        const results: Record<string, unknown>[][] = [];
+        for (const statement of statements) {
+          results.push(asRows(await db.prepare(statement.sql).bind(...statement.params).all()));
+        }
+        return results;
+      }
+      const bound: unknown[] = statements.map((statement) => db.prepare(statement.sql).bind(...statement.params));
+      const results = await db.batch(bound);
+      return results.map((result) => asRows(result));
+    },
+  };
+}
+
+function sumQuantity(rows: readonly Record<string, unknown>[]): number {
+  let total = 0;
+  for (const row of rows) {
+    const quantity = row.quantity;
+    if (typeof quantity === "number" && Number.isSafeInteger(quantity) && quantity > 0) total += quantity;
+  }
+  return total;
+}
+
+function text(row: Record<string, unknown>, key: string): string {
+  const value = row[key];
+  return typeof value === "string" ? value : "";
+}
+
+function reserveShape(input: ReserveInput): ReserveResult | null {
+  if (!ID_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" };
+  if (!Number.isSafeInteger(input.amountMinor) || input.amountMinor < 0) return { ok: false, finding: "malformed-request" };
+  if (input.holds.length < 1) return { ok: false, finding: "malformed-request" };
+  for (const hold of input.holds) {
+    if (!SKU_RE.test(hold.sku) || !LOCATION_RE.test(hold.locationId)) return { ok: false, finding: "malformed-request" };
+    if (!Number.isSafeInteger(hold.quantity) || hold.quantity < 1) return { ok: false, finding: "malformed-request" };
+    if (!Number.isSafeInteger(hold.onHand) || hold.onHand < 0) return { ok: false, finding: "malformed-request" };
+  }
+  return null;
+}
+
+function allocationInsert(input: ReserveInput, hold: ReserveHold, seenAt: string): SqlStatement {
+  return {
+    sql: `INSERT INTO scrappy_allocations (tenant_id, stage, order_id, sku, location_id, quantity, state)
+      SELECT ?, ?, ?, ?, ?, ?, 'reserved'
+      WHERE (
+        SELECT COALESCE(SUM(quantity), 0) FROM scrappy_allocations
+        WHERE tenant_id = ? AND stage = ? AND sku = ? AND location_id = ? AND state IN ('reserved', 'confirmed')
+      ) + ? <= ?
+      AND NOT EXISTS (
+        SELECT 1 FROM scrappy_allocations
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND sku = ? AND location_id = ?
+          AND state IN ('reserved', 'confirmed')
+      )
+      AND NOT EXISTS (
+        SELECT 1 FROM scrappy_final_cart_authorizations
+        WHERE tenant_id = ? AND stage = ? AND cart_digest = ? AND state IN ('active', 'consumed')
+      )
+      AND EXISTS (
+        SELECT 1 FROM scrappy_caller_replay
+        WHERE tenant_id = ? AND stage = ? AND issuer = ? AND jti = ? AND seen_at = ?
+      )
+      AND EXISTS (
+        SELECT 1 FROM scrappy_commerce_orders
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?
+      )
+      ON CONFLICT DO NOTHING
+      RETURNING order_id`,
+    params: [
+      input.tenantId,
+      input.stage,
+      input.orderId,
+      hold.sku,
+      hold.locationId,
+      hold.quantity,
+      input.tenantId,
+      input.stage,
+      hold.sku,
+      hold.locationId,
+      hold.quantity,
+      hold.onHand,
+      input.tenantId,
+      input.stage,
+      input.orderId,
+      hold.sku,
+      hold.locationId,
+      input.tenantId,
+      input.stage,
+      input.cartDigest,
+      input.tenantId,
+      input.stage,
+      input.issuer,
+      input.jti,
+      seenAt,
+      input.tenantId,
+      input.stage,
+      input.orderId,
+    ],
+  };
+}
+
+/** Admit one hold per sku. A second active digest returns the existing authorization. */
+export async function reserveAllocation(runner: StatementRunner, input: ReserveInput): Promise<ReserveResult> {
+  const malformed = reserveShape(input);
+  if (malformed) return malformed;
+  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],
+  );
+  if (seen.length > 0) return { ok: false, finding: "caller-replay" };
+
+  const seenAt = `${input.now}|${crypto.randomUUID()}`;
+  const holds = [...input.holds].sort((left, right) => left.sku.localeCompare(right.sku) || left.locationId.localeCompare(right.locationId));
+  const statements: SqlStatement[] = [
+    {
+      sql: `INSERT INTO scrappy_caller_replay (tenant_id, stage, issuer, jti, seen_at)
+        VALUES (?, ?, ?, ?, ?)
+        ON CONFLICT DO NOTHING
+        RETURNING jti`,
+      params: [input.tenantId, input.stage, input.issuer, input.jti, seenAt],
+    },
+    {
+      sql: `INSERT INTO scrappy_commerce_orders (
+          tenant_id, stage, order_id, source, source_order_id, currency, placed_at,
+          payment_state, compliance_state, stock_state, fulfillment_state, label_state,
+          amount_minor, event_version
+        ) VALUES (?, ?, ?, 'scrappy', ?, ?, ?, 'pending', 'UNKNOWN', 'unallocated', 'held', 'none', ?, 1)
+        ON CONFLICT DO NOTHING
+        RETURNING order_id`,
+      params: [input.tenantId, input.stage, input.orderId, input.orderId, input.currency, input.now, input.amountMinor],
+    },
+    ...holds.map((hold) => allocationInsert(input, hold, seenAt)),
+    {
+      sql: `INSERT INTO scrappy_final_cart_authorizations (
+          tenant_id, stage, authorization_id, cart_digest, expires_at, state
+        )
+        SELECT ?, ?, ?, ?, ?, 'active'
+        WHERE (
+          SELECT COUNT(*) FROM scrappy_allocations
+          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 cart_digest = ? AND state IN ('active', 'consumed')
+        )
+        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,
+        input.orderId,
+        input.cartDigest,
+        input.expiresAt,
+        input.tenantId,
+        input.stage,
+        input.orderId,
+        holds.length,
+        input.tenantId,
+        input.stage,
+        input.cartDigest,
+        input.tenantId,
+        input.stage,
+        input.issuer,
+        input.jti,
+        seenAt,
+      ],
+    },
+    {
+      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'
+          )
+        RETURNING quantity`,
+      params: [input.tenantId, input.stage, input.orderId, input.tenantId, input.stage, input.orderId],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET stock_state = 'reserved'
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?
+          AND EXISTS (
+            SELECT 1 FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state = 'active'
+          )
+        RETURNING order_id`,
+      params: [input.tenantId, input.stage, input.orderId, input.tenantId, input.stage, input.orderId],
+    },
+    {
+      sql: `SELECT authorization_id, expires_at FROM scrappy_final_cart_authorizations
+        WHERE tenant_id = ? AND stage = ? AND cart_digest = ? AND state IN ('active', 'consumed')
+        ORDER BY CASE state WHEN 'active' THEN 0 ELSE 1 END
+        LIMIT 1`,
+      params: [input.tenantId, input.stage, input.cartDigest],
+    },
+  ];
+
+  const results = await runner.batch(statements);
+  const replayRows = results[0] ?? [];
+  const authRows = results[2 + holds.length] ?? [];
+  const selected = results[results.length - 1] ?? [];
+  if (authRows.length > 0) {
+    return { ok: true, authorizationId: input.orderId, repeated: false, expiresAt: input.expiresAt };
+  }
+  if (replayRows.length === 0) return { ok: false, finding: "caller-replay" };
+  const existing = selected[0];
+  if (existing) {
+    return {
+      ok: true,
+      authorizationId: text(existing, "authorization_id"),
+      repeated: true,
+      expiresAt: text(existing, "expires_at"),
+    };
+  }
+  return { ok: false, finding: "stock-unavailable" };
+}
+
+export async function releaseHoldOnce(
+  runner: StatementRunner,
+  input: {
+    tenantId: string;
+    stage: CommerceStage;
+    orderId: string;
+    allocationState: "released" | "expired";
+    authState: "denied" | "expired";
+    orderStock: StockState;
+  },
+): Promise<number> {
+  const scope = [input.tenantId, input.stage, input.orderId];
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_final_cart_authorizations
+        SET state = ?
+        WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state IN ('active', 'consumed')
+        RETURNING authorization_id`,
+      params: [input.authState, ...scope],
+    },
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = ?
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state IN ('reserved', 'confirmed')
+        RETURNING quantity`,
+      params: [input.allocationState, ...scope],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET stock_state = ?
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND stock_state IN ('reserved', 'confirmed')
+        RETURNING order_id`,
+      params: [input.orderStock, ...scope],
+    },
+  ]);
+  return sumQuantity(results[1] ?? []);
+}
+
+export async function settleExpired(
+  runner: StatementRunner,
+  input: { tenantId: string; stage: CommerceStage; now: string; orderId?: string; force: boolean },
+): Promise<number> {
+  const orderId = input.orderId ?? "";
+  const force = input.force ? 1 : 0;
+  const due = [input.tenantId, input.stage, orderId, orderId, input.now, force];
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_final_cart_authorizations
+        SET state = 'expired'
+        WHERE tenant_id = ? AND stage = ? AND state = 'active'
+          AND (? = '' OR authorization_id = ?)
+          AND (expires_at <= ? OR ? = 1)
+        RETURNING authorization_id`,
+      params: due,
+    },
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = 'expired'
+        WHERE tenant_id = ? AND stage = ? AND state = 'reserved'
+          AND order_id IN (
+            SELECT authorization_id FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND state = 'expired'
+              AND (? = '' OR authorization_id = ?)
+              AND (expires_at <= ? OR ? = 1)
+          )
+        RETURNING quantity`,
+      params: [input.tenantId, input.stage, ...due],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET stock_state = 'expired'
+        WHERE tenant_id = ? AND stage = ? AND stock_state IN ('reserved', 'confirmed')
+          AND order_id IN (
+            SELECT authorization_id FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND state = 'expired'
+              AND (? = '' OR authorization_id = ?)
+              AND (expires_at <= ? OR ? = 1)
+          )
+        RETURNING order_id`,
+      params: [input.tenantId, input.stage, ...due],
+    },
+  ]);
+  return sumQuantity(results[1] ?? []);
+}
+
+export async function releaseOrphanAllocations(
+  runner: StatementRunner,
+  input: { tenantId: string; stage: CommerceStage },
+): Promise<number> {
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = 'released'
+        WHERE tenant_id = ? AND stage = ?
+          AND state IN ('reserved', 'confirmed')
+          AND NOT EXISTS (
+            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.state IN ('active', 'consumed')
+          )
+        RETURNING quantity`,
+      params: [input.tenantId, input.stage],
+    },
+  ]);
+  return sumQuantity(results[0] ?? []);
+}
+
+interface OrderRow {
+  payment: PaymentState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+}
+
+async function loadOrder(
+  runner: StatementRunner,
+  tenantId: string,
+  stage: CommerceStage,
+  orderId: string,
+): Promise<OrderRow | null> {
+  const rows = await runner.all(
+    `SELECT payment_state, stock_state, fulfillment_state, label_state
+     FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    [tenantId, stage, orderId],
+  );
+  const row = rows[0];
+  if (!row) return null;
+  const allocs = await runner.all(
+    `SELECT state FROM scrappy_allocations WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+    [tenantId, stage, orderId],
+  );
+  const states = allocs.map((alloc) => text(alloc, "state"));
+  const stock = states.includes("reserved")
+    ? "reserved"
+    : states.includes("confirmed")
+      ? "confirmed"
+      : (text(row, "stock_state") as StockState);
+  return {
+    payment: text(row, "payment_state") as PaymentState,
+    stock,
+    fulfillment: text(row, "fulfillment_state") as FulfillmentState,
+    label: text(row, "label_state") as LabelState,
+  };
+}
+
+function commandFinding(reason: string): string {
+  switch (reason) {
+    case "stock":
+      return "stock-unknown";
+    case "fulfillment":
+      return "fulfillment-refused";
+    case "reconcile":
+      return "payment-reconcile";
+    case "payment":
+      return "payment-refused";
+    case "evidence":
+      return "evidence-refused";
+    default:
+      return "fulfillment-refused";
+  }
+}
+
+/** Move reserved units to confirmed once. A second call decrements nothing. */
+export async function confirmHoldOnce(
+  runner: StatementRunner,
+  input: { tenantId: string; stage: CommerceStage; orderId: string },
+): Promise<{ decremented: number; states: string[] }> {
+  const scope = [input.tenantId, input.stage, input.orderId];
+  const results = await runner.batch([
+    {
+      sql: `UPDATE scrappy_allocations
+        SET state = 'confirmed'
+        WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'reserved'
+          AND EXISTS (
+            SELECT 1 FROM scrappy_commerce_orders
+            WHERE tenant_id = ? AND stage = ? AND order_id = ?
+              AND fulfillment_state IN ('held', 'ready')
+              AND payment_state IN ('pending', 'authorized', 'captured')
+          )
+          AND EXISTS (
+            SELECT 1 FROM scrappy_final_cart_authorizations
+            WHERE tenant_id = ? AND stage = ? AND authorization_id = ? AND state = 'active'
+          )
+        RETURNING quantity`,
+      params: [...scope, ...scope, ...scope],
+    },
+    {
+      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 scrappy_allocations
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'confirmed'
+          )
+        RETURNING authorization_id`,
+      params: [...scope, ...scope],
+    },
+    {
+      sql: `UPDATE scrappy_commerce_orders
+        SET payment_state = CASE
+              WHEN payment_state IN ('pending', 'authorized') THEN 'captured'
+              ELSE payment_state
+            END,
+            stock_state = 'confirmed'
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?
+          AND fulfillment_state IN ('held', 'ready')
+          AND payment_state IN ('pending', 'authorized', 'captured')
+          AND EXISTS (
+            SELECT 1 FROM scrappy_allocations
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state = 'confirmed'
+          )
+        RETURNING order_id`,
+      params: [...scope, ...scope],
+    },
+    {
+      sql: `SELECT state FROM scrappy_allocations
+        WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      params: scope,
+    },
+  ]);
+  return {
+    decremented: sumQuantity(results[0] ?? []),
+    states: (results[3] ?? []).map((row) => text(row, "state")),
+  };
+}
+
+/** Apply the recorded release policy. `restock` stays false on every result. */
+export async function applyAllocationPolicy(runner: StatementRunner, input: PolicyInput): Promise<PolicyResult> {
+  const scope = { tenantId: input.tenantId, stage: input.stage };
+  if (input.kind === "confirm") {
+    if (!input.orderId) return { released: 0, restock: false, decremented: 0, finding: "order-absent" };
+    const order = await loadOrder(runner, input.tenantId, input.stage, input.orderId);
+    if (!order) return { released: 0, restock: false, decremented: 0, finding: "order-absent" };
+    if (order.fulfillment === "handed_off") return { released: 0, restock: false, decremented: 0, finding: "shipped-out-of-scope" };
+    if (order.fulfillment === "cancelled" || order.fulfillment === "UNKNOWN") {
+      return { released: 0, restock: false, decremented: 0, finding: "fulfillment-refused" };
+    }
+    const confirmed = await confirmHoldOnce(runner, { tenantId: input.tenantId, stage: input.stage, orderId: input.orderId });
+    if (confirmed.decremented > 0) return { released: 0, restock: false, decremented: confirmed.decremented, finding: "confirmed" };
+    if (confirmed.states.includes("confirmed")) return { released: 0, restock: false, decremented: 0, finding: "already-confirmed" };
+    return { released: 0, restock: false, decremented: 0, finding: "already-released" };
+  }
+  if (input.kind === "restart") {
+    const released = await releaseOrphanAllocations(runner, scope);
+    return { released, restock: false, finding: "restart-reconciled" };
+  }
+  if (input.kind === "expiry" || input.kind === "timeout") {
+    const released = await settleExpired(runner, {
+      ...scope,
+      now: input.now ?? "",
+      orderId: input.orderId,
+      force: input.kind === "timeout",
+    });
+    return { released, restock: false, finding: released > 0 ? "expired" : "already-released" };
+  }
+  if (!input.orderId) return { released: 0, restock: false, finding: "order-absent" };
+  const order = await loadOrder(runner, input.tenantId, input.stage, input.orderId);
+  if (!order) return { released: 0, restock: false, finding: "order-absent" };
+
+  if (input.kind === "payment-failure") {
+    if (order.fulfillment === "handed_off") return { released: 0, restock: false, finding: "shipped-out-of-scope" };
+    if (order.stock === "confirmed" || order.payment === "captured") {
+      return { released: 0, restock: false, finding: "already-confirmed" };
+    }
+    const released = await releaseHoldOnce(runner, {
+      tenantId: input.tenantId,
+      stage: input.stage,
+      orderId: input.orderId,
+      allocationState: "released",
+      authState: "denied",
+      orderStock: "released",
+    });
+    return { released, restock: false, finding: released > 0 ? "released" : "already-released" };
+  }
+
+  const decision = decideCommerceCommand({
+    command: input.kind,
+    payment: order.payment,
+    stock: order.stock,
+    fulfillment: order.fulfillment,
+    label: order.label,
+    evidence: input.evidence ?? FRESH_EVIDENCE,
+    providerOutcome: input.providerOutcome ?? null,
+  });
+  if (input.kind === "refund") {
+    return {
+      released: 0,
+      restock: false,
+      finding: decision.admit ? "refund-no-restock" : commandFinding(decision.reason),
+    };
+  }
+  if (!decision.admit || !decision.releaseReservation) {
+    return { released: 0, restock: false, finding: decision.admit ? "cancel-no-release" : commandFinding(decision.reason) };
+  }
+  const released = await releaseHoldOnce(runner, {
+    tenantId: input.tenantId,
+    stage: input.stage,
+    orderId: input.orderId,
+    allocationState: "released",
+    authState: "denied",
+    orderStock: "released",
+  });
+  return { released, restock: false, finding: released > 0 ? "released" : "already-released" };
+}