@tokenoftrust/storefront-runner 2.4.54 → 2.4.56

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

@@ -0,0 +1,1654 @@
+/**
+ * Whole-order fulfillment commands.
+ *
+ * `decideCommerceCommand` is the commerce decision core. This service stores the
+ * result. It does not call a carrier, does not select a vendor, and does not
+ * read the admin fulfillment mock. Label purchase stays an intent row for a
+ * separate adapter. UI fields are not source truth.
+ */
+import type { APIContext } from "astro";
+import {
+  COMPLIANCE_STATES,
+  EVIDENCE_STATES,
+  FULFILLMENT_STATES,
+  LABEL_STATES,
+  PAYMENT_STATES,
+  STOCK_STATES,
+  actorMayCommand,
+  decideCommerceCommand,
+  publicCommerceEvent,
+  readOwnerAddress,
+  totalsMatch,
+  type CommerceActor,
+  type CommerceEvidence,
+  type CommerceStage,
+  type ComplianceState,
+  type FulfillmentState,
+  type LabelState,
+  type MinorTotals,
+  type PaymentState,
+  type ProviderOutcome,
+  type StockState,
+} from "@tot/public-runtime";
+import { readD1 } from "@/lib/env";
+import { decideAdminApiAccess } from "@/lib/auth/adminApiGuard";
+import { readViewerSession } from "@/lib/auth/route";
+import type { SessionRecord } from "@/lib/auth/session";
+import {
+  canRelease,
+  carrierPolicyForTenant,
+  carrierSelectionRefusal,
+  handoffRefusal,
+  releaseHolds,
+  type CarrierPolicy,
+  type ReadinessInput,
+  type ReleaseHold,
+} from "./readiness.js";
+import {
+  fulfillmentDbFromD1,
+  type FulfillmentDatabase,
+  type SqlStatement,
+} from "./store.js";
+
+export const OPAQUE_ID = /^[A-Za-z0-9._:-]{1,128}$/;
+
+export function isOpaqueId(value: string): boolean {
+  return OPAQUE_ID.test(value) && !value.includes("@");
+}
+
+export interface FulfillmentActor extends CommerceActor {
+  actorId: string;
+}
+
+export interface SourceOrderSnapshot {
+  tenantId: string;
+  stage: CommerceStage;
+  orderId: string;
+  source: string;
+  sourceOrderId: string;
+  currency: string;
+  placedAt: string;
+  payment: PaymentState;
+  compliance: ComplianceState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  amountMinor: number;
+  totals: MinorTotals;
+  evidence: CommerceEvidence;
+  lines: readonly { sku: string; quantity: number }[];
+  address: Record<string, unknown> | null;
+}
+
+export interface PackingSlip {
+  orderId: string;
+  currency: string;
+  lines: { sku: string; quantity: number }[];
+  adultSignatureRequired: boolean;
+  prohibitedCarriers: string[];
+}
+
+export type BatchPhase = "claimed" | "picked" | "packed";
+
+export interface ShipmentIntentView {
+  scope: "whole-order";
+  purchaseId: string | null;
+  labelPurchaseState: string;
+  handoffState: string;
+  vendorSelected: false;
+  carrierAccountId: string | null;
+  adultSignatureRequired: boolean;
+  prohibitedCarriers: string[];
+}
+
+export interface FulfillmentView {
+  orderId: string;
+  tenantId: string;
+  stage: CommerceStage;
+  eventVersion: number;
+  payment: PaymentState;
+  compliance: ComplianceState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  holds: ReleaseHold[];
+  canRelease: boolean;
+  canHandOff: boolean;
+  batch: { batchId: string; phase: BatchPhase } | null;
+  shipment: ShipmentIntentView | null;
+  packingSlip: PackingSlip | null;
+}
+
+export interface FulfillmentBatch {
+  batchId: string;
+  orders: { orderId: string; phase: BatchPhase }[];
+}
+
+export interface FulfillmentCommandOptions {
+  expectedVersion?: number;
+  scope?: string;
+  carrier?: string;
+  lines?: unknown;
+}
+
+export interface LabelOutcomeInput {
+  outcome: "purchased" | "unknown" | "voided";
+  adultSignature: "accepted" | "refused" | "absent";
+  carrier?: string;
+  expectedVersion?: number;
+}
+
+export type FulfillmentResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; code: string; holds?: readonly ReleaseHold[] };
+
+interface LoadedOrder {
+  order: {
+    tenantId: string;
+    stage: CommerceStage;
+    orderId: string;
+    source: string;
+    sourceOrderId: string;
+    currency: string;
+    placedAt: string;
+    payment: PaymentState;
+    compliance: ComplianceState;
+    stock: StockState;
+    fulfillment: FulfillmentState;
+    label: LabelState;
+    amountMinor: number;
+    eventVersion: number;
+  };
+  evidence: CommerceEvidence;
+  lines: { sku: string; quantity: number }[];
+  totals: MinorTotals | null;
+  batch: { batchId: string; phase: BatchPhase } | null;
+  operatorHold: boolean;
+  cancelPending: boolean;
+  packingSlip: PackingSlip | null;
+  shipment: { labelPurchaseState: string; handoffState: string } | null;
+  provider: { purchaseId: string; outcome: ProviderOutcome } | null;
+  labelOutcome: { adultSignature: "accepted" | "refused" | "absent" } | null;
+  carrierAccountId: string | null;
+  prohibitedCarriers: string[];
+  adultSignatureRequired: boolean;
+  auditCount: number;
+  view: FulfillmentView;
+}
+
+type CommitPlan =
+  | { type: "done"; view: FulfillmentView }
+  | { type: "refuse"; code: string; holds?: readonly ReleaseHold[] }
+  | { type: "write"; statements: SqlStatement[]; minimumChanges: number };
+
+const FAIL_CLOSED_EVIDENCE: CommerceEvidence = {
+  verification: "unreadable",
+  tax: "unreadable",
+  risk: "unreadable",
+  stock: "unreadable",
+};
+
+const LABEL_RANK: Record<LabelState, number> = {
+  UNKNOWN: 0,
+  none: 1,
+  voided: 1,
+  intent: 2,
+  void_requested: 3,
+  purchased: 4,
+  printed: 5,
+};
+
+const FORBIDDEN_BODY_KEYS = new Set([
+  "address",
+  "email",
+  "phone",
+  "line1",
+  "line2",
+  "postalCode",
+  "name",
+  "customer",
+]);
+
+function refuse(code: string, holds?: readonly ReleaseHold[]): FulfillmentResult<never> {
+  return holds && holds.length > 0 ? { ok: false, code, holds } : { ok: false, code };
+}
+
+function ok<T>(value: T): FulfillmentResult<T> {
+  return { ok: true, value };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function oneOf<T extends string>(value: unknown, allowed: readonly T[]): value is T {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value);
+}
+
+function phaseRank(phase: BatchPhase | null): number {
+  if (phase === "packed") return 3;
+  if (phase === "picked") return 2;
+  if (phase === "claimed") return 1;
+  return 0;
+}
+
+function stamp(now: string, n: number): string {
+  return `${now}#${String(n).padStart(6, "0")}`;
+}
+
+function jsonText(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+function containsForbiddenKey(value: unknown): boolean {
+  if (!isRecord(value) && !Array.isArray(value)) return false;
+  for (const [key, child] of Object.entries(value)) {
+    if (FORBIDDEN_BODY_KEYS.has(key) || containsForbiddenKey(child)) return true;
+  }
+  return false;
+}
+
+async function digestHex(content: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(content));
+  return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function purchaseIdFor(tenantId: string, stage: CommerceStage, orderId: string): Promise<string> {
+  const digest = await digestHex(`scrappy-label-intent-v1\n${tenantId}\n${stage}\n${orderId}`);
+  return `label_${digest.slice(0, 32)}`;
+}
+
+function observedEvent(input: {
+  eventVersion: number;
+  orderId: string;
+  placedAt: string;
+  currency: string;
+  payment: PaymentState;
+  compliance: ComplianceState;
+  stock: StockState;
+  fulfillment: FulfillmentState;
+  label: LabelState;
+  totals: MinorTotals;
+  evidence: CommerceEvidence;
+  address: unknown;
+}): string {
+  return jsonText(
+    publicCommerceEvent({
+      eventVersion: input.eventVersion,
+      orderId: input.orderId,
+      placedAt: input.placedAt,
+      currency: input.currency,
+      payment: input.payment,
+      compliance: input.compliance,
+      stock: input.stock,
+      fulfillment: input.fulfillment,
+      label: input.label,
+      totals: input.totals,
+      verificationDetail: input.evidence,
+      address: input.address,
+    }),
+  );
+}
+
+function mergePayment(local: PaymentState | null, source: PaymentState): PaymentState {
+  if (local === "refund_requested" && (source === "captured" || source === "authorized" || source === "pending")) {
+    return "refund_requested";
+  }
+  return source;
+}
+
+function mergeLabel(local: LabelState | null, source: LabelState): LabelState {
+  if (!local) return source;
+  return LABEL_RANK[local] >= LABEL_RANK[source] ? local : source;
+}
+
+function parseEvidence(value: unknown): CommerceEvidence | null {
+  if (!isRecord(value)) return null;
+  const verification = value.verification;
+  const tax = value.tax;
+  const risk = value.risk;
+  const stock = value.stock;
+  if (!oneOf(verification, EVIDENCE_STATES) || !oneOf(tax, EVIDENCE_STATES) || !oneOf(risk, EVIDENCE_STATES) || !oneOf(stock, EVIDENCE_STATES)) {
+    return null;
+  }
+  return { verification, tax, risk, stock };
+}
+
+function parseLines(value: unknown): { sku: string; quantity: number }[] | null {
+  if (!Array.isArray(value)) return null;
+  const lines: { sku: string; quantity: number }[] = [];
+  for (const entry of value) {
+    if (!isRecord(entry) || typeof entry.sku !== "string" || !isOpaqueId(entry.sku)) return null;
+    if (!Number.isSafeInteger(entry.quantity) || Number(entry.quantity) < 1) return null;
+    lines.push({ sku: entry.sku, quantity: Number(entry.quantity) });
+  }
+  return lines;
+}
+
+function parseTotals(value: unknown): MinorTotals | null {
+  if (!isRecord(value)) return null;
+  const totals = {
+    subtotalMinor: Number(value.subtotalMinor),
+    shippingMinor: Number(value.shippingMinor),
+    taxMinor: Number(value.taxMinor),
+    totalMinor: Number(value.totalMinor),
+  };
+  if (
+    !Number.isSafeInteger(totals.subtotalMinor) ||
+    !Number.isSafeInteger(totals.shippingMinor) ||
+    !Number.isSafeInteger(totals.taxMinor) ||
+    !Number.isSafeInteger(totals.totalMinor)
+  ) {
+    return null;
+  }
+  return totals;
+}
+
+function auditStatement(
+  state: { order: LoadedOrder["order"] },
+  actorId: string,
+  kind: string,
+  fromState: string,
+  toState: string,
+  version: number,
+  at: string,
+): SqlStatement {
+  return {
+    sql: `INSERT INTO scrappy_shipment_audit (
+      audit_id, tenant_id, stage, order_id, at, actor_id, kind, from_state, to_state
+    )
+    SELECT ?, tenant_id, stage, order_id, ?, ?, ?, ?, ?
+    FROM scrappy_commerce_orders
+    WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?`,
+    params: [
+      `audit_${crypto.randomUUID()}`,
+      at,
+      actorId,
+      kind,
+      fromState,
+      toState,
+      state.order.tenantId,
+      state.order.stage,
+      state.order.orderId,
+      version,
+    ],
+  };
+}
+
+export function commerceStageForEnv(env: string | undefined): CommerceStage | null {
+  if (env === "live") return "publication";
+  if (env === "test") return "preview";
+  return null;
+}
+
+export function decideFulfillmentAccess(input: {
+  record: SessionRecord | null | undefined;
+  hostResource: string;
+  nowSeconds: number;
+  customizationEnv: string | undefined;
+  subject: string | undefined;
+  bodyTenantId?: string | null;
+}): { ok: true; actor: FulfillmentActor } | { ok: false; status: 401 | 403 | 409; code: string } {
+  const access = decideAdminApiAccess({
+    record: input.record,
+    hostResource: input.hostResource,
+    nowSeconds: input.nowSeconds,
+    requireOwner: true,
+  });
+  if (!access.ok) return { ok: false, status: access.status, code: access.reason };
+  const stage = commerceStageForEnv(input.customizationEnv);
+  if (!stage) return { ok: false, status: 409, code: "stage-unknown" };
+  const host = input.hostResource.trim();
+  if (!isOpaqueId(host) && host.length === 0) return { ok: false, status: 403, code: "denied" };
+  if (!host) return { ok: false, status: 403, code: "denied" };
+  if (input.bodyTenantId && input.bodyTenantId !== host) return { ok: false, status: 403, code: "denied" };
+  if (!input.subject || !isOpaqueId(input.subject)) return { ok: false, status: 403, code: "denied" };
+  const actor: FulfillmentActor = { role: "owner", tenantId: host, stage, actorId: input.subject };
+  if (!actorMayCommand(actor, { tenantId: host, stage })) return { ok: false, status: 403, code: "denied" };
+  return { ok: true, actor };
+}
+
+function jsonResponse(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "content-type": "application/json; charset=utf-8",
+      "cache-control": "no-store",
+      "x-robots-tag": "noindex, nofollow",
+    },
+  });
+}
+
+export function fulfillmentResultResponse<T>(result: FulfillmentResult<T>, body: (value: T) => unknown): Response {
+  if (!result.ok) {
+    const status = result.code === "not-found" ? 404 : result.code === "denied" ? 403 : result.code === "unavailable" ? 503 : result.code === "malformed" ? 400 : 409;
+    return jsonResponse({ error: result.code, ...(result.holds ? { holds: result.holds } : {}) }, status);
+  }
+  return jsonResponse(body(result.value), 200);
+}
+
+export async function openFulfillment(
+  context: APIContext,
+  bodyTenantId?: string | null,
+): Promise<{ ok: false; response: Response } | { ok: true; service: FulfillmentService; actor: FulfillmentActor }> {
+  const url = new URL(context.request.url);
+  if (url.searchParams.has("tenant") || url.searchParams.has("tenantId") || url.searchParams.has("stage")) {
+    return { ok: false, response: jsonResponse({ error: "denied" }, 403) };
+  }
+  const tenant = context.locals.tenant as
+    | {
+        appDomain?: string;
+        tenant_id?: string;
+        compliance?: { ruleProfile?: string };
+        carrierAccountId?: unknown;
+      }
+    | undefined;
+  const host = tenant?.appDomain?.trim() ?? "";
+  const record = await readViewerSession(context);
+  const decision = decideFulfillmentAccess({
+    record,
+    hostResource: host,
+    nowSeconds: Math.floor(Date.now() / 1000),
+    customizationEnv: context.locals.customizationEnv,
+    subject: record?.subject,
+    bodyTenantId,
+  });
+  if (!decision.ok) return { ok: false, response: jsonResponse({ error: decision.code }, decision.status) };
+  const d1 = await readD1("STOREFRONT_APPS_DB");
+  if (!d1) return { ok: false, response: jsonResponse({ error: "unavailable" }, 503) };
+  const policy = carrierPolicyForTenant({
+    tenant_id: tenant?.tenant_id || host,
+    compliance: tenant?.compliance,
+    carrierAccountId: tenant?.carrierAccountId,
+  });
+  return { ok: true, actor: decision.actor, service: new FulfillmentService(fulfillmentDbFromD1(d1), { policy }) };
+}
+
+export function parseFulfillmentBody(body: unknown): FulfillmentResult<{
+  action: string;
+  expectedVersion?: number;
+  scope?: string;
+  carrier?: string;
+  lines?: unknown;
+  outcome?: string;
+  adultSignature?: string;
+  orderIds?: string[];
+  tenantId?: string;
+  expectedVersions?: Record<string, number>;
+}> {
+  if (!isRecord(body) || containsForbiddenKey(body)) return refuse("malformed");
+  const action = typeof body.action === "string" ? body.action : "";
+  if (body.action !== undefined && action === "") return refuse("malformed");
+  if (body.expectedVersion !== undefined && (!Number.isSafeInteger(body.expectedVersion) || Number(body.expectedVersion) < 1)) {
+    return refuse("malformed");
+  }
+  if (body.orderIds !== undefined) {
+    if (!Array.isArray(body.orderIds) || body.orderIds.some((id) => typeof id !== "string" || !isOpaqueId(id))) {
+      return refuse("malformed");
+    }
+  }
+  let expectedVersions: Record<string, number> | undefined;
+  if (body.expectedVersions !== undefined) {
+    if (!isRecord(body.expectedVersions)) return refuse("malformed");
+    expectedVersions = {};
+    for (const [key, value] of Object.entries(body.expectedVersions)) {
+      if (!isOpaqueId(key) || !Number.isSafeInteger(value) || Number(value) < 1) return refuse("malformed");
+      expectedVersions[key] = Number(value);
+    }
+  }
+  const tenantId = typeof body.tenantId === "string" ? body.tenantId : undefined;
+  return ok({
+    action,
+    ...(body.expectedVersion !== undefined ? { expectedVersion: Number(body.expectedVersion) } : {}),
+    ...(typeof body.scope === "string" ? { scope: body.scope } : {}),
+    ...(typeof body.carrier === "string" ? { carrier: body.carrier } : {}),
+    ...(body.lines !== undefined ? { lines: body.lines } : {}),
+    ...(typeof body.outcome === "string" ? { outcome: body.outcome } : {}),
+    ...(typeof body.adultSignature === "string" ? { adultSignature: body.adultSignature } : {}),
+    ...(Array.isArray(body.orderIds) ? { orderIds: body.orderIds as string[] } : {}),
+    ...(tenantId ? { tenantId } : {}),
+    ...(expectedVersions ? { expectedVersions } : {}),
+  });
+}
+
+export async function readJsonBody(request: Request): Promise<FulfillmentResult<unknown>> {
+  const text = await request.text();
+  if (text.trim() === "") return ok({});
+  try {
+    return ok(JSON.parse(text) as unknown);
+  } catch {
+    return refuse("malformed");
+  }
+}
+
+export class FulfillmentService {
+  private readonly now: () => string;
+
+  constructor(
+    private readonly db: FulfillmentDatabase,
+    private readonly options: { policy: CarrierPolicy; now?: () => string },
+  ) {
+    this.now = options.now ?? (() => new Date().toISOString());
+  }
+
+  get policy(): CarrierPolicy {
+    return this.options.policy;
+  }
+
+  async get(actor: FulfillmentActor, orderId: string): Promise<FulfillmentResult<FulfillmentView>> {
+    const scope = this.commandScope(actor);
+    if (!scope) return refuse("denied");
+    if (!isOpaqueId(orderId)) return refuse("not-found");
+    const state = await this.load(scope.tenantId, scope.stage, orderId);
+    return state ? ok(state.view) : refuse("not-found");
+  }
+
+  async batch(actor: FulfillmentActor, batchId: string): Promise<FulfillmentResult<FulfillmentBatch>> {
+    const scope = this.commandScope(actor);
+    if (!scope) return refuse("denied");
+    if (!isOpaqueId(batchId)) return refuse("not-found");
+    const rows = await this.db.all<{ order_id: string; to_state: string }>(
+      `SELECT order_id, to_state FROM scrappy_shipment_audit
+       WHERE tenant_id = ? AND stage = ? AND kind = 'batch'
+       ORDER BY at ASC, audit_id ASC`,
+      [scope.tenantId, scope.stage],
+    );
+    const latest = new Map<string, { batchId: string; phase: BatchPhase }>();
+    for (const row of rows) {
+      const parsed = parseBatchState(row.to_state);
+      if (parsed && isOpaqueId(row.order_id)) latest.set(row.order_id, parsed);
+    }
+    const orders = [...latest.entries()]
+      .filter(([, value]) => value.batchId === batchId)
+      .map(([orderId, value]) => ({ orderId, phase: value.phase }));
+    if (orders.length === 0) return refuse("not-found");
+    return ok({ batchId, orders });
+  }
+
+  async readAddress(
+    actor: FulfillmentActor,
+    orderId: string,
+  ): Promise<FulfillmentResult<Record<string, unknown>>> {
+    const scope = { tenantId: actor.tenantId, stage: actor.stage };
+    let opened = false;
+    const gate = readOwnerAddress(actor, scope, () => {
+      opened = true;
+      return true;
+    });
+    if (!gate.ok || !opened || !isOpaqueId(actor.actorId)) return refuse("denied");
+    if (!isOpaqueId(orderId)) return refuse("not-found");
+    const row = await this.db.get<{ address_json: string }>(
+      `SELECT address_json FROM scrappy_order_addresses WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      [scope.tenantId, scope.stage, orderId],
+    );
+    if (!row) return refuse("not-found");
+    try {
+      const parsed = JSON.parse(row.address_json) as unknown;
+      if (!isRecord(parsed)) return refuse("unreadable");
+      return ok(parsed);
+    } catch {
+      return refuse("unreadable");
+    }
+  }
+
+  async applySourceSnapshot(
+    actor: FulfillmentActor,
+    snapshot: SourceOrderSnapshot,
+  ): Promise<FulfillmentResult<FulfillmentView>> {
+    const scope = this.commandScope(actor);
+    if (!scope) return refuse("denied");
+    if (snapshot.tenantId !== scope.tenantId || snapshot.stage !== scope.stage) return refuse("denied");
+    const invalid = validateSnapshot(snapshot);
+    if (invalid) return refuse(invalid);
+    const existing = await this.load(scope.tenantId, scope.stage, snapshot.orderId);
+    if (!existing) {
+      const inserted = await this.insertSnapshot(actor, snapshot);
+      if (inserted !== "exists") return inserted;
+      const raced = await this.load(scope.tenantId, scope.stage, snapshot.orderId);
+      if (!raced) return refuse("unavailable");
+      return this.updateSnapshot(actor, raced, snapshot);
+    }
+    return this.updateSnapshot(actor, existing, snapshot);
+  }
+
+  async claim(
+    actor: FulfillmentActor,
+    orderIds: readonly string[],
+    expectedVersions?: Readonly<Record<string, number>>,
+  ): Promise<FulfillmentResult<FulfillmentBatch>> {
+    const scope = this.commandScope(actor);
+    if (!scope) return refuse("denied");
+    if (orderIds.length === 0 || new Set(orderIds).size !== orderIds.length) return refuse("malformed");
+    if (orderIds.some((id) => !isOpaqueId(id))) return refuse("malformed");
+    for (let attempt = 0; attempt < 5; attempt++) {
+      const states: LoadedOrder[] = [];
+      for (const orderId of orderIds) {
+        const state = await this.load(scope.tenantId, scope.stage, orderId);
+        if (!state) return refuse("not-found");
+        states.push(state);
+      }
+      if (expectedVersions && states.some((state) => expectedVersions[state.order.orderId] !== state.order.eventVersion)) {
+        return refuse("conflict");
+      }
+      const blocked = states.find((state) => state.order.fulfillment === "handed_off" || state.order.fulfillment === "cancelled");
+      if (blocked) return refuse("fulfillment");
+      const batches = new Set(states.map((state) => state.batch?.batchId).filter((id): id is string => !!id));
+      if (states.every((state) => state.batch) && batches.size === 1) {
+        return this.batch(actor, [...batches][0] ?? "");
+      }
+      if (batches.size > 0) return refuse("conflict");
+      const batchId = `batch_${crypto.randomUUID()}`;
+      const statements: SqlStatement[] = [claimUpdate(states)];
+      states.forEach((state, index) => {
+        statements.push(
+          auditStatement(
+            state,
+            actor.actorId,
+            "batch",
+            "none",
+            `claimed|${batchId}`,
+            state.order.eventVersion + 1,
+            stamp(this.now(), state.auditCount + 1 + index),
+          ),
+        );
+      });
+      const changes = await this.write(statements);
+      if (!changes) return refuse("unavailable");
+      if ((changes[0] ?? 0) === states.length) return this.batch(actor, batchId);
+      if (expectedVersions) return refuse("conflict");
+    }
+    return refuse("conflict");
+  }
+
+  async pick(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.advance(actor, orderId, "picked", options);
+  }
+
+  async pack(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.advance(actor, orderId, "packed", options);
+  }
+
+  async release(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.advance(actor, orderId, null, options);
+  }
+
+  async hold(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.commit(actor, orderId, options.expectedVersion, (state) => {
+      if (state.order.fulfillment === "handed_off" || state.order.fulfillment === "cancelled") return { type: "refuse", code: "fulfillment" };
+      if (state.operatorHold) return { type: "done", view: state.view };
+      const version = state.order.eventVersion + 1;
+      return {
+        type: "write",
+        minimumChanges: 1,
+        statements: [
+          {
+            sql: `UPDATE scrappy_commerce_orders
+              SET fulfillment_state = 'held', event_version = event_version + 1
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                AND fulfillment_state IN ('ready', 'held')`,
+            params: [state.order.tenantId, state.order.stage, state.order.orderId, state.order.eventVersion],
+          },
+          auditStatement(state, actor.actorId, "operator-hold", state.order.fulfillment, "open", version, stamp(this.now(), state.auditCount + 1)),
+        ],
+      };
+    });
+  }
+
+  async clearOperatorHold(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.commit(actor, orderId, options.expectedVersion, (state) => {
+      if (!state.operatorHold) return { type: "done", view: state.view };
+      if (state.order.fulfillment === "handed_off") return { type: "refuse", code: "fulfillment" };
+      const next = projectedFulfillment(state, false, state.cancelPending);
+      const version = state.order.eventVersion + 1;
+      return {
+        type: "write",
+        minimumChanges: 1,
+        statements: [
+          {
+            sql: `UPDATE scrappy_commerce_orders
+              SET fulfillment_state = ?, event_version = event_version + 1
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                AND fulfillment_state = 'held'`,
+            params: [next, state.order.tenantId, state.order.stage, state.order.orderId, state.order.eventVersion],
+          },
+          auditStatement(state, actor.actorId, "operator-hold", "open", "cleared", version, stamp(this.now(), state.auditCount + 1)),
+        ],
+      };
+    });
+  }
+
+  async requestCancel(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.commit(actor, orderId, options.expectedVersion, (state) => {
+      if (state.cancelPending || state.order.fulfillment === "cancelled") return { type: "done", view: state.view };
+      const decision = decideCommerceCommand({
+        command: "cancel",
+        payment: state.order.payment,
+        stock: state.order.stock,
+        fulfillment: state.order.fulfillment,
+        label: state.order.label,
+        evidence: state.evidence,
+        providerOutcome: state.provider?.outcome ?? null,
+      });
+      if (!decision.admit) return { type: "refuse", code: decision.reason };
+      const version = state.order.eventVersion + 1;
+      return {
+        type: "write",
+        minimumChanges: 1,
+        statements: [
+          {
+            sql: `UPDATE scrappy_commerce_orders
+              SET fulfillment_state = 'held', event_version = event_version + 1
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                AND fulfillment_state IN ('ready', 'held')`,
+            params: [state.order.tenantId, state.order.stage, state.order.orderId, state.order.eventVersion],
+          },
+          auditStatement(
+            state,
+            actor.actorId,
+            "pending-cancel",
+            decision.releaseReservation ? "release-reservation" : "keep-reservation",
+            "open",
+            version,
+            stamp(this.now(), state.auditCount + 1),
+          ),
+        ],
+      };
+    });
+  }
+
+  async requestRefund(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.commit(actor, orderId, options.expectedVersion, (state) => {
+      if (state.order.payment === "refund_requested" || state.order.payment === "refunded") {
+        return { type: "done", view: state.view };
+      }
+      if (state.order.fulfillment === "handed_off" || state.order.fulfillment === "cancelled") {
+        return { type: "refuse", code: "fulfillment" };
+      }
+      const decision = decideCommerceCommand({
+        command: "refund",
+        payment: state.order.payment,
+        stock: state.order.stock,
+        fulfillment: state.order.fulfillment,
+        label: state.order.label,
+        evidence: state.evidence,
+        providerOutcome: state.provider?.outcome ?? null,
+      });
+      if (!decision.admit) return { type: "refuse", code: decision.reason };
+      const version = state.order.eventVersion + 1;
+      return {
+        type: "write",
+        minimumChanges: 1,
+        statements: [
+          {
+            sql: `UPDATE scrappy_commerce_orders
+              SET payment_state = 'refund_requested', fulfillment_state = 'held', event_version = event_version + 1
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                AND payment_state = 'captured'
+                AND fulfillment_state NOT IN ('handed_off', 'cancelled')`,
+            params: [state.order.tenantId, state.order.stage, state.order.orderId, state.order.eventVersion],
+          },
+          auditStatement(state, actor.actorId, "pending-refund", state.order.payment, "open", version, stamp(this.now(), state.auditCount + 1)),
+        ],
+      };
+    });
+  }
+
+  async applyLabelOutcome(actor: FulfillmentActor, orderId: string, input: LabelOutcomeInput): Promise<FulfillmentResult<FulfillmentView>> {
+    const selected = carrierSelectionRefusal(this.policy, input.carrier);
+    if (selected) return refuse(selected);
+    if (!oneOf(input.outcome, ["purchased", "unknown", "voided"] as const)) return refuse("malformed");
+    if (!oneOf(input.adultSignature, ["accepted", "refused", "absent"] as const)) return refuse("malformed");
+    const mapped = labelOutcomeColumns(input.outcome);
+    return this.commit(actor, orderId, input.expectedVersion, (state) => {
+      if (!state.shipment || !state.provider) return { type: "refuse", code: "label" };
+      if (state.order.fulfillment === "handed_off") return { type: "refuse", code: "fulfillment" };
+      if (state.shipment.labelPurchaseState === mapped.shipment && state.labelOutcome?.adultSignature === input.adultSignature) {
+        return { type: "done", view: state.view };
+      }
+      const version = state.order.eventVersion + 1;
+      return {
+        type: "write",
+        minimumChanges: 1,
+        statements: [
+          {
+            sql: `UPDATE scrappy_commerce_orders
+              SET label_state = ?, event_version = event_version + 1
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                AND fulfillment_state != 'handed_off'
+                AND label_state IN ('intent', 'purchased', 'UNKNOWN', 'voided', 'void_requested')`,
+            params: [mapped.order, state.order.tenantId, state.order.stage, state.order.orderId, state.order.eventVersion],
+          },
+          {
+            sql: `UPDATE scrappy_shipments
+              SET label_purchase_state = ?
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND handoff_state = 'none'
+                AND EXISTS (
+                  SELECT 1 FROM scrappy_commerce_orders
+                  WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                )`,
+            params: [
+              mapped.shipment,
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+              version,
+            ],
+          },
+          {
+            sql: `UPDATE scrappy_provider_operations
+              SET outcome = ?
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND kind = 'label_purchase'
+                AND provider = 'unselected' AND purchase_id = ?
+                AND EXISTS (
+                  SELECT 1 FROM scrappy_commerce_orders
+                  WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                )`,
+            params: [
+              mapped.provider,
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+              state.provider.purchaseId,
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+              version,
+            ],
+          },
+          auditStatement(
+            state,
+            actor.actorId,
+            "label-outcome",
+            state.order.label,
+            jsonText({ outcome: input.outcome, adultSignature: input.adultSignature }),
+            version,
+            stamp(this.now(), state.auditCount + 1),
+          ),
+        ],
+      };
+    });
+  }
+
+  async handOff(actor: FulfillmentActor, orderId: string, options: FulfillmentCommandOptions = {}): Promise<FulfillmentResult<FulfillmentView>> {
+    const selected = carrierSelectionRefusal(this.policy, options.carrier);
+    if (selected) return refuse(selected);
+    return this.commit(actor, orderId, options.expectedVersion, (state) => {
+      if (state.shipment?.handoffState === "handed_off" || state.order.fulfillment === "handed_off") {
+        return { type: "done", view: state.view };
+      }
+      const code = handoffRefusal(this.readiness(state));
+      if (code) return { type: "refuse", code, holds: releaseHolds(this.readiness(state)) };
+      if (state.shipment?.labelPurchaseState !== "purchased" || state.provider?.outcome !== "accepted") {
+        return { type: "refuse", code: "label" };
+      }
+      const version = state.order.eventVersion + 1;
+      return {
+        type: "write",
+        minimumChanges: 1,
+        statements: [
+          {
+            sql: `UPDATE scrappy_commerce_orders
+              SET fulfillment_state = 'handed_off', event_version = event_version + 1
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                AND payment_state = 'captured' AND stock_state = 'confirmed'
+                AND fulfillment_state = 'ready' AND label_state IN ('purchased', 'printed')
+                AND EXISTS (
+                  SELECT 1 FROM scrappy_shipments
+                  WHERE tenant_id = ? AND stage = ? AND order_id = ?
+                    AND scope = 'whole-order' AND label_purchase_state = 'purchased' AND handoff_state = 'none'
+                )`,
+            params: [
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+              state.order.eventVersion,
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+            ],
+          },
+          {
+            sql: `UPDATE scrappy_shipments
+              SET handoff_state = 'handed_off'
+              WHERE tenant_id = ? AND stage = ? AND order_id = ?
+                AND scope = 'whole-order' AND label_purchase_state = 'purchased' AND handoff_state = 'none'
+                AND EXISTS (
+                  SELECT 1 FROM scrappy_commerce_orders
+                  WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+                )`,
+            params: [
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+              state.order.tenantId,
+              state.order.stage,
+              state.order.orderId,
+              version,
+            ],
+          },
+          auditStatement(state, actor.actorId, "transition", state.order.fulfillment, "handed_off", version, stamp(this.now(), state.auditCount + 1)),
+        ],
+      };
+    });
+  }
+
+  /** Returns are not automated. This records nothing. */
+  createReturn(actor: FulfillmentActor, _orderId: string): FulfillmentResult<never> {
+    if (!this.commandScope(actor)) return refuse("denied");
+    return refuse("returns-not-automated");
+  }
+
+  private commandScope(actor: FulfillmentActor): { tenantId: string; stage: CommerceStage } | null {
+    if (!isOpaqueId(actor.actorId)) return null;
+    const scope = { tenantId: actor.tenantId, stage: actor.stage };
+    return actorMayCommand(actor, scope) ? scope : null;
+  }
+
+  private readiness(state: LoadedOrder): ReadinessInput {
+    return {
+      payment: state.order.payment,
+      stock: state.order.stock,
+      fulfillment: state.order.fulfillment,
+      label: state.order.label,
+      evidence: state.evidence,
+      operatorHold: state.operatorHold,
+      cancelPending: state.cancelPending,
+      providerOutcome: state.provider?.outcome ?? null,
+      adultSignature: state.labelOutcome?.adultSignature ?? "absent",
+      adultSignatureRequired: state.adultSignatureRequired || this.policy.adultSignatureRequired,
+    };
+  }
+
+  private async advance(
+    actor: FulfillmentActor,
+    orderId: string,
+    phase: BatchPhase | null,
+    options: FulfillmentCommandOptions,
+  ): Promise<FulfillmentResult<FulfillmentView>> {
+    const selected = carrierSelectionRefusal(this.policy, options.carrier);
+    if (selected) return refuse(selected);
+    if (options.scope !== undefined && options.scope !== "whole-order") return refuse("partial-shipment");
+    if (options.lines !== undefined) return refuse("partial-shipment");
+    return this.commit(actor, orderId, options.expectedVersion, async (state) => {
+      if (!state.batch) return { type: "refuse", code: "batch" };
+      if (state.order.fulfillment === "handed_off" || state.order.fulfillment === "cancelled") {
+        return { type: "refuse", code: "fulfillment" };
+      }
+      const raising = phase !== null && phaseRank(state.batch.phase) < phaseRank(phase);
+      const wantSlip = phase === "packed" && !state.packingSlip;
+      const readiness = this.readiness(state);
+      const releasable = canRelease(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) {
+        if (!releasable) {
+          const holds = releaseHolds(readiness);
+          return { type: "refuse", code: holds[0] ?? "hold", holds };
+        }
+        const labelCode = state.order.label === "UNKNOWN" || state.order.label === "void_requested" ? "reconcile" : "label";
+        return { type: "refuse", code: labelCode };
+      }
+      if (!raising && !wantSlip && !wantIntent) {
+        if (state.shipment || phase !== null) return { type: "done", view: state.view };
+      }
+      const version = state.order.eventVersion + 1;
+      const statements: SqlStatement[] = [touchOrder(state, wantIntent)];
+      let n = state.auditCount;
+      if (raising && phase) {
+        n += 1;
+        statements.push(auditStatement(state, actor.actorId, "batch", state.batch.phase, `${phase}|${state.batch.batchId}`, version, stamp(this.now(), n)));
+      }
+      if (wantSlip) {
+        n += 1;
+        const slip = packingSlip(state, this.policy);
+        statements.push(auditStatement(state, actor.actorId, "packing-slip", "none", jsonText(slip), version, stamp(this.now(), n)));
+      }
+      if (wantIntent) {
+        const intent = await this.intentStatements(state, actor.actorId, version, () => {
+          n += 1;
+          return stamp(this.now(), n);
+        });
+        statements.push(...intent);
+      }
+      return { type: "write", statements, minimumChanges: 1 };
+    });
+  }
+
+  private async intentStatements(
+    state: LoadedOrder,
+    actorId: string,
+    version: number,
+    nextStamp: () => string,
+  ): Promise<SqlStatement[]> {
+    const purchaseId = state.provider?.purchaseId ?? (await purchaseIdFor(state.order.tenantId, state.order.stage, state.order.orderId));
+    const intent = {
+      purchaseId,
+      adultSignatureRequired: this.policy.adultSignatureRequired,
+      prohibitedCarriers: [...this.policy.prohibitedCarriers],
+      carrierAccountId: this.policy.carrierAccountId,
+      vendorSelected: false as const,
+    };
+    const { order } = state;
+    return [
+      {
+        sql: `INSERT INTO scrappy_shipments (
+          tenant_id, stage, order_id, scope, label_purchase_state, label_print_state, handoff_state
+        )
+        SELECT tenant_id, stage, order_id, 'whole-order', 'intent', 'none', 'none'
+        FROM scrappy_commerce_orders AS o
+        WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id = ? AND o.event_version = ?
+          AND NOT EXISTS (
+            SELECT 1 FROM scrappy_shipments AS s
+            WHERE s.tenant_id = o.tenant_id AND s.stage = o.stage AND s.order_id = o.order_id
+          )`,
+        params: [order.tenantId, order.stage, order.orderId, version],
+      },
+      {
+        sql: `INSERT INTO scrappy_provider_operations (
+          tenant_id, stage, provider, purchase_id, order_id, kind, outcome, amount_minor
+        )
+        SELECT tenant_id, stage, 'unselected', ?, order_id, 'label_purchase', 'intent', amount_minor
+        FROM scrappy_commerce_orders AS o
+        WHERE o.tenant_id = ? AND o.stage = ? AND o.order_id = ? AND o.event_version = ?
+          AND NOT EXISTS (
+            SELECT 1 FROM scrappy_provider_operations AS p
+            WHERE p.tenant_id = o.tenant_id AND p.stage = o.stage AND p.order_id = o.order_id
+              AND p.kind = 'label_purchase' AND p.outcome IN ('intent', 'accepted', 'unknown')
+          )`,
+        params: [purchaseId, order.tenantId, order.stage, order.orderId, version],
+      },
+      auditStatement(state, actorId, "label-intent", state.order.label, jsonText(intent), version, nextStamp()),
+    ];
+  }
+
+  private async commit(
+    actor: FulfillmentActor,
+    orderId: string,
+    expectedVersion: number | undefined,
+    build: (state: LoadedOrder) => CommitPlan | Promise<CommitPlan>,
+  ): Promise<FulfillmentResult<FulfillmentView>> {
+    const scope = this.commandScope(actor);
+    if (!scope) return refuse("denied");
+    if (!isOpaqueId(orderId)) return refuse("not-found");
+    for (let attempt = 0; attempt < 5; attempt++) {
+      const state = await this.load(scope.tenantId, scope.stage, orderId);
+      if (!state) return refuse("not-found");
+      const plan = await build(state);
+      if (plan.type === "done") return ok(plan.view);
+      if (plan.type === "refuse") return refuse(plan.code, plan.holds);
+      if (expectedVersion !== undefined && state.order.eventVersion !== expectedVersion) return refuse("conflict");
+      const changes = await this.write(plan.statements);
+      if (!changes) return refuse("unavailable");
+      if ((changes[0] ?? 0) >= plan.minimumChanges) {
+        const next = await this.load(scope.tenantId, scope.stage, orderId);
+        return next ? ok(next.view) : refuse("not-found");
+      }
+      if (expectedVersion !== undefined) return refuse("conflict");
+    }
+    return refuse("conflict");
+  }
+
+  private async write(statements: readonly SqlStatement[]): Promise<number[] | null> {
+    try {
+      return await this.db.batch(statements);
+    } catch (error) {
+      if (error instanceof Error && error.message === "storage") return null;
+      return null;
+    }
+  }
+
+  private async insertSnapshot(actor: FulfillmentActor, snapshot: SourceOrderSnapshot): Promise<FulfillmentResult<FulfillmentView> | "exists"> {
+    const payment = mergePayment(null, snapshot.payment);
+    const label = mergeLabel(null, snapshot.label);
+    const fulfillment = projectedFromSnapshot(null, snapshot, payment, false, false);
+    const version = 1;
+    const at = stamp(this.now(), 1);
+    const statements: SqlStatement[] = [
+      {
+        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
+        )
+        SELECT ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 1
+        WHERE NOT EXISTS (
+          SELECT 1 FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ?
+        )`,
+        params: [
+          snapshot.tenantId,
+          snapshot.stage,
+          snapshot.orderId,
+          snapshot.source,
+          snapshot.sourceOrderId,
+          snapshot.currency,
+          snapshot.placedAt,
+          payment,
+          snapshot.compliance,
+          snapshot.stock,
+          fulfillment,
+          label,
+          snapshot.amountMinor,
+          snapshot.tenantId,
+          snapshot.stage,
+          snapshot.orderId,
+        ],
+      },
+    ];
+    const gate = `tenant_id = ? AND stage = ? AND order_id = ? AND event_version = 1 AND source = ? AND source_order_id = ?`;
+    const gateParams = [snapshot.tenantId, snapshot.stage, snapshot.orderId, snapshot.source, snapshot.sourceOrderId];
+    if (snapshot.address) {
+      statements.push({
+        sql: `INSERT INTO scrappy_order_addresses (tenant_id, stage, order_id, address_json)
+          SELECT tenant_id, stage, order_id, ?
+          FROM scrappy_commerce_orders
+          WHERE ${gate}
+            AND NOT EXISTS (
+              SELECT 1 FROM scrappy_order_addresses AS a
+              WHERE a.tenant_id = scrappy_commerce_orders.tenant_id
+                AND a.stage = scrappy_commerce_orders.stage
+                AND a.order_id = scrappy_commerce_orders.order_id
+            )`,
+        params: [jsonText(snapshot.address), ...gateParams],
+      });
+    }
+    const stub = {
+      order: {
+        tenantId: snapshot.tenantId,
+        stage: snapshot.stage,
+        orderId: snapshot.orderId,
+        source: snapshot.source,
+        sourceOrderId: snapshot.sourceOrderId,
+        currency: snapshot.currency,
+        placedAt: snapshot.placedAt,
+        payment,
+        compliance: snapshot.compliance,
+        stock: snapshot.stock,
+        fulfillment,
+        label,
+        amountMinor: snapshot.amountMinor,
+        eventVersion: version,
+      },
+    };
+    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),
+      gatedAudit(stub, actor.actorId, "totals", "none", jsonText(snapshot.totals), stamp(this.now(), 3), gate, gateParams),
+      gatedAudit(stub, actor.actorId, "address-present", "none", snapshot.address ? "yes" : "no", stamp(this.now(), 4), gate, gateParams),
+      gatedAudit(
+        stub,
+        actor.actorId,
+        "public-event",
+        "none",
+        observedEvent({
+          eventVersion: version,
+          orderId: snapshot.orderId,
+          placedAt: snapshot.placedAt,
+          currency: snapshot.currency,
+          payment,
+          compliance: snapshot.compliance,
+          stock: snapshot.stock,
+          fulfillment,
+          label,
+          totals: snapshot.totals,
+          evidence: snapshot.evidence,
+          address: snapshot.address,
+        }),
+        stamp(this.now(), 5),
+        gate,
+        gateParams,
+      ),
+    );
+    const changes = await this.write(statements);
+    if (!changes) return refuse("unavailable");
+    if ((changes[0] ?? 0) !== 1) return "exists";
+    const loaded = await this.load(snapshot.tenantId, snapshot.stage, snapshot.orderId);
+    return loaded ? ok(loaded.view) : refuse("unavailable");
+  }
+
+  private updateSnapshot(
+    actor: FulfillmentActor,
+    _existing: LoadedOrder,
+    snapshot: SourceOrderSnapshot,
+  ): Promise<FulfillmentResult<FulfillmentView>> {
+    return this.commit(actor, snapshot.orderId, undefined, (state) => {
+      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";
+      const cancelPending = state.cancelPending && !confirmedCancel;
+      const fulfillment = projectedFromSnapshot(state.order.fulfillment, snapshot, payment, state.operatorHold, cancelPending);
+      const version = state.order.eventVersion + 1;
+      const statements: SqlStatement[] = [
+        {
+          sql: `UPDATE scrappy_commerce_orders
+            SET payment_state = ?, compliance_state = ?, stock_state = ?, fulfillment_state = ?,
+                label_state = ?, amount_minor = ?, event_version = event_version + 1
+            WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+              AND (? = 'handed_off' OR fulfillment_state != 'handed_off' OR ? = 'handed_off')`,
+          params: [
+            payment,
+            snapshot.compliance,
+            snapshot.stock,
+            state.order.fulfillment === "handed_off" ? "handed_off" : fulfillment,
+            label,
+            snapshot.amountMinor,
+            state.order.tenantId,
+            state.order.stage,
+            state.order.orderId,
+            state.order.eventVersion,
+            state.order.fulfillment,
+            fulfillment,
+          ],
+        },
+      ];
+      let n = state.auditCount;
+      const nextVersion = version;
+      n += 1;
+      statements.push(auditStatement(state, actor.actorId, "evidence", "source", jsonText(snapshot.evidence), nextVersion, stamp(this.now(), n)));
+      n += 1;
+      statements.push(auditStatement(state, actor.actorId, "lines", "source", jsonText(snapshot.lines), nextVersion, stamp(this.now(), n)));
+      n += 1;
+      statements.push(auditStatement(state, actor.actorId, "totals", "source", jsonText(snapshot.totals), nextVersion, stamp(this.now(), n)));
+      if (snapshot.address) {
+        statements.push({
+          sql: `INSERT INTO scrappy_order_addresses (tenant_id, stage, order_id, address_json)
+            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 address_json = excluded.address_json
+            WHERE EXISTS (
+              SELECT 1 FROM scrappy_commerce_orders
+              WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+            )`,
+          params: [
+            snapshot.tenantId,
+            snapshot.stage,
+            snapshot.orderId,
+            jsonText(snapshot.address),
+            snapshot.tenantId,
+            snapshot.stage,
+            snapshot.orderId,
+            nextVersion,
+            snapshot.tenantId,
+            snapshot.stage,
+            snapshot.orderId,
+            nextVersion,
+          ],
+        });
+      }
+      const storedFulfillment = state.order.fulfillment === "handed_off" ? "handed_off" : fulfillment;
+      n += 1;
+      statements.push(
+        auditStatement(
+          state,
+          actor.actorId,
+          "public-event",
+          "source",
+          observedEvent({
+            eventVersion: nextVersion,
+            orderId: state.order.orderId,
+            placedAt: state.order.placedAt,
+            currency: state.order.currency,
+            payment,
+            compliance: snapshot.compliance,
+            stock: snapshot.stock,
+            fulfillment: storedFulfillment,
+            label,
+            totals: snapshot.totals,
+            evidence: snapshot.evidence,
+            address: snapshot.address,
+          }),
+          nextVersion,
+          stamp(this.now(), n),
+        ),
+      );
+      if (confirmedCancel && state.order.fulfillment !== "handed_off") {
+        n += 1;
+        statements.push(auditStatement(state, actor.actorId, "pending-cancel", "open", "confirmed", nextVersion, stamp(this.now(), n)));
+      }
+      return { type: "write", statements, minimumChanges: 1 };
+    });
+  }
+
+  private async load(tenantId: string, stage: CommerceStage, orderId: string): Promise<LoadedOrder | null> {
+    const row = await this.db.get<Record<string, unknown>>(
+      `SELECT 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
+       FROM scrappy_commerce_orders
+       WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      [tenantId, stage, orderId],
+    );
+    if (!row) return null;
+    if (
+      !oneOf(row.payment_state, PAYMENT_STATES) ||
+      !oneOf(row.compliance_state, COMPLIANCE_STATES) ||
+      !oneOf(row.stock_state, STOCK_STATES) ||
+      !oneOf(row.fulfillment_state, FULFILLMENT_STATES) ||
+      !oneOf(row.label_state, LABEL_STATES) ||
+      !oneOf(row.stage, ["preview", "publication"] as const) ||
+      typeof row.order_id !== "string" ||
+      typeof row.currency !== "string" ||
+      typeof row.placed_at !== "string" ||
+      typeof row.source !== "string" ||
+      typeof row.source_order_id !== "string"
+    ) {
+      return null;
+    }
+    const audits = await this.db.all<{ kind: string; from_state: string; to_state: string }>(
+      `SELECT kind, from_state, to_state FROM scrappy_shipment_audit
+       WHERE tenant_id = ? AND stage = ? AND order_id = ?
+       ORDER BY at ASC, audit_id ASC`,
+      [tenantId, stage, orderId],
+    );
+    const shipment = await this.db.get<{ label_purchase_state: string; handoff_state: string; scope: string }>(
+      `SELECT scope, label_purchase_state, handoff_state FROM scrappy_shipments
+       WHERE tenant_id = ? AND stage = ? AND order_id = ?`,
+      [tenantId, stage, orderId],
+    );
+    const providers = await this.db.all<{ purchase_id: string; outcome: string }>(
+      `SELECT purchase_id, outcome FROM scrappy_provider_operations
+       WHERE tenant_id = ? AND stage = ? AND order_id = ? AND kind = 'label_purchase'`,
+      [tenantId, stage, orderId],
+    );
+    let evidence = FAIL_CLOSED_EVIDENCE;
+    let lines: { sku: string; quantity: number }[] = [];
+    let totals: MinorTotals | null = null;
+    let batch: { batchId: string; phase: BatchPhase } | null = null;
+    let operatorHold = false;
+    let cancelPending = false;
+    let packingSlip: PackingSlip | null = null;
+    let labelOutcome: LoadedOrder["labelOutcome"] = null;
+    let intentAccount: string | null = null;
+    let intentProhibited: string[] = [...this.policy.prohibitedCarriers];
+    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 === "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);
+      else if (audit.kind === "operator-hold") operatorHold = audit.to_state === "open";
+      else if (audit.kind === "pending-cancel") cancelPending = audit.to_state === "open";
+      else if (audit.kind === "packing-slip") packingSlip = parseSlip(parseJson(audit.to_state));
+      else if (audit.kind === "label-outcome") labelOutcome = parseLabelOutcome(parseJson(audit.to_state));
+      else if (audit.kind === "label-intent") {
+        const intent = parseJson(audit.to_state);
+        if (isRecord(intent)) {
+          intentAccount = typeof intent.carrierAccountId === "string" ? intent.carrierAccountId : null;
+          intentAdult = intent.adultSignatureRequired === true;
+          intentProhibited = Array.isArray(intent.prohibitedCarriers)
+            ? intent.prohibitedCarriers.filter((item): item is string => typeof item === "string")
+            : intentProhibited;
+        }
+      }
+    }
+    const provider = pickProvider(providers);
+    const order = {
+      tenantId,
+      stage: row.stage,
+      orderId: row.order_id,
+      source: row.source,
+      sourceOrderId: row.source_order_id,
+      currency: row.currency,
+      placedAt: row.placed_at,
+      payment: row.payment_state,
+      compliance: row.compliance_state,
+      stock: row.stock_state,
+      fulfillment: row.fulfillment_state,
+      label: row.label_state,
+      amountMinor: Number(row.amount_minor),
+      eventVersion: Number(row.event_version),
+    };
+    const loaded: LoadedOrder = {
+      order,
+      evidence,
+      lines,
+      totals,
+      batch,
+      operatorHold,
+      cancelPending,
+      packingSlip,
+      shipment: shipment && shipment.scope === "whole-order"
+        ? { labelPurchaseState: shipment.label_purchase_state, handoffState: shipment.handoff_state }
+        : null,
+      provider,
+      labelOutcome,
+      carrierAccountId: intentAccount,
+      prohibitedCarriers: intentProhibited,
+      adultSignatureRequired: intentAdult,
+      auditCount: audits.length,
+      view: {
+        orderId: order.orderId,
+        tenantId: order.tenantId,
+        stage: order.stage,
+        eventVersion: order.eventVersion,
+        payment: order.payment,
+        compliance: order.compliance,
+        stock: order.stock,
+        fulfillment: order.fulfillment,
+        label: order.label,
+        holds: [],
+        canRelease: false,
+        canHandOff: false,
+        batch,
+        shipment: null,
+        packingSlip,
+      },
+    };
+    const readiness = this.readiness(loaded);
+    const holds = releaseHolds(readiness);
+    loaded.view.holds = holds;
+    loaded.view.canRelease = canRelease(readiness) && !loaded.shipment;
+    loaded.view.canHandOff = handoffRefusal(readiness) === null && loaded.shipment?.handoffState !== "handed_off";
+    loaded.view.shipment = loaded.shipment
+      ? {
+          scope: "whole-order",
+          purchaseId: provider?.purchaseId ?? null,
+          labelPurchaseState: loaded.shipment.labelPurchaseState,
+          handoffState: loaded.shipment.handoffState,
+          vendorSelected: false,
+          carrierAccountId: loaded.carrierAccountId,
+          adultSignatureRequired: loaded.adultSignatureRequired,
+          prohibitedCarriers: loaded.prohibitedCarriers,
+        }
+      : null;
+    return loaded;
+  }
+}
+
+function touchOrder(state: LoadedOrder, wantIntent: boolean): SqlStatement {
+  return {
+    sql: `UPDATE scrappy_commerce_orders
+      SET event_version = event_version + 1,
+          label_state = CASE WHEN ? = 1 THEN 'intent' ELSE label_state END
+      WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?
+        AND fulfillment_state NOT IN ('handed_off', 'cancelled')
+        AND (? = 0 OR (
+          payment_state = 'captured' AND stock_state = 'confirmed' AND fulfillment_state = 'ready'
+          AND label_state IN ('none', 'voided', 'intent')
+        ))`,
+    params: [
+      wantIntent ? 1 : 0,
+      state.order.tenantId,
+      state.order.stage,
+      state.order.orderId,
+      state.order.eventVersion,
+      wantIntent ? 1 : 0,
+    ],
+  };
+}
+
+function claimUpdate(states: readonly LoadedOrder[]): SqlStatement {
+  const first = states[0];
+  if (!first) return { sql: "SELECT 0", params: [] };
+  const match = states.map(() => "(order_id = ? AND event_version = ?)").join(" OR ");
+  const versionParams = states.flatMap((state) => [state.order.orderId, state.order.eventVersion]);
+  return {
+    sql: `UPDATE scrappy_commerce_orders
+      SET event_version = event_version + 1
+      WHERE tenant_id = ? AND stage = ? AND (${match})
+        AND fulfillment_state NOT IN ('handed_off', 'cancelled')
+        AND (
+          SELECT COUNT(*) FROM scrappy_commerce_orders
+          WHERE tenant_id = ? AND stage = ? AND (${match})
+            AND fulfillment_state NOT IN ('handed_off', 'cancelled')
+        ) = ?`,
+    params: [first.order.tenantId, first.order.stage, ...versionParams, first.order.tenantId, first.order.stage, ...versionParams, states.length],
+  };
+}
+
+function gatedAudit(
+  state: { order: LoadedOrder["order"] },
+  actorId: string,
+  kind: string,
+  fromState: string,
+  toState: string,
+  at: string,
+  gate: string,
+  gateParams: readonly unknown[],
+): SqlStatement {
+  return {
+    sql: `INSERT INTO scrappy_shipment_audit (
+      audit_id, tenant_id, stage, order_id, at, actor_id, kind, from_state, to_state
+    )
+    SELECT ?, tenant_id, stage, order_id, ?, ?, ?, ?, ?
+    FROM scrappy_commerce_orders
+    WHERE ${gate}
+      AND NOT EXISTS (
+        SELECT 1 FROM scrappy_shipment_audit AS existing
+        WHERE existing.tenant_id = scrappy_commerce_orders.tenant_id
+          AND existing.stage = scrappy_commerce_orders.stage
+          AND existing.order_id = scrappy_commerce_orders.order_id
+          AND existing.kind = ?
+      )`,
+    params: [`audit_${crypto.randomUUID()}`, at, actorId, kind, fromState, toState, ...gateParams, kind],
+  };
+}
+
+function packingSlip(state: LoadedOrder, policy: CarrierPolicy): PackingSlip {
+  return {
+    orderId: state.order.orderId,
+    currency: state.order.currency,
+    lines: state.lines.map((line) => ({ sku: line.sku, quantity: line.quantity })),
+    adultSignatureRequired: policy.adultSignatureRequired,
+    prohibitedCarriers: [...policy.prohibitedCarriers],
+  };
+}
+
+function projectedFulfillment(
+  state: LoadedOrder,
+  operatorHold: boolean,
+  cancelPending: boolean,
+): FulfillmentState {
+  return projectedFromSnapshot(
+    state.order.fulfillment,
+    {
+      fulfillment: state.order.fulfillment,
+      stock: state.order.stock,
+      label: state.order.label,
+      evidence: state.evidence,
+    },
+    state.order.payment,
+    operatorHold,
+    cancelPending,
+  );
+}
+
+function projectedFromSnapshot(
+  current: FulfillmentState | null,
+  snapshot: Pick<SourceOrderSnapshot, "fulfillment" | "stock" | "label" | "evidence">,
+  payment: PaymentState,
+  operatorHold: boolean,
+  cancelPending: boolean,
+): FulfillmentState {
+  if (current === "handed_off") return "handed_off";
+  if (snapshot.fulfillment === "cancelled" || payment === "voided" || payment === "refunded") return "cancelled";
+  if (snapshot.fulfillment === "UNKNOWN") return "UNKNOWN";
+  const holds = releaseHolds({
+    payment,
+    stock: snapshot.stock,
+    fulfillment: "ready",
+    label: snapshot.label,
+    evidence: snapshot.evidence,
+    operatorHold,
+    cancelPending,
+    providerOutcome: null,
+    adultSignature: "absent",
+    adultSignatureRequired: false,
+  });
+  if (holds.length > 0 || operatorHold || cancelPending) return "held";
+  return "ready";
+}
+
+function validateSnapshot(snapshot: SourceOrderSnapshot): string | null {
+  if (!isOpaqueId(snapshot.orderId) || !isOpaqueId(snapshot.source) || !isOpaqueId(snapshot.sourceOrderId)) return "malformed";
+  if (!/^[A-Z]{3}$/.test(snapshot.currency)) return "malformed";
+  if (snapshot.placedAt.trim() === "" || snapshot.placedAt.includes("\n")) return "malformed";
+  if (!Number.isSafeInteger(snapshot.amountMinor) || snapshot.amountMinor < 0) return "malformed";
+  if (!oneOf(snapshot.payment, PAYMENT_STATES) || !oneOf(snapshot.compliance, COMPLIANCE_STATES)) return "malformed";
+  if (!oneOf(snapshot.stock, STOCK_STATES) || !oneOf(snapshot.fulfillment, FULFILLMENT_STATES)) return "malformed";
+  if (!oneOf(snapshot.label, LABEL_STATES) || !oneOf(snapshot.stage, ["preview", "publication"] as const)) return "malformed";
+  if (!parseEvidence(snapshot.evidence) || !parseLines(snapshot.lines) || !parseTotals(snapshot.totals)) return "malformed";
+  if (snapshot.amountMinor !== snapshot.totals.totalMinor || !totalsMatch(snapshot.totals)) return "malformed";
+  if (snapshot.address !== null && !isRecord(snapshot.address)) return "malformed";
+  return null;
+}
+
+function labelOutcomeColumns(outcome: "purchased" | "unknown" | "voided"): {
+  order: LabelState;
+  shipment: string;
+  provider: ProviderOutcome;
+} {
+  if (outcome === "purchased") return { order: "purchased", shipment: "purchased", provider: "accepted" };
+  if (outcome === "voided") return { order: "voided", shipment: "voided", provider: "voided" };
+  return { order: "UNKNOWN", shipment: "unknown", provider: "unknown" };
+}
+
+function parseBatchState(value: string): { batchId: string; phase: BatchPhase } | null {
+  const split = value.indexOf("|");
+  if (split <= 0) return null;
+  const phase = value.slice(0, split);
+  const batchId = value.slice(split + 1);
+  if ((phase !== "claimed" && phase !== "picked" && phase !== "packed") || !isOpaqueId(batchId)) return null;
+  return { phase, batchId };
+}
+
+function parseSlip(value: unknown): PackingSlip | null {
+  if (!isRecord(value) || typeof value.orderId !== "string" || typeof value.currency !== "string") return null;
+  const lines = parseLines(value.lines);
+  if (!lines) return null;
+  return {
+    orderId: value.orderId,
+    currency: value.currency,
+    lines,
+    adultSignatureRequired: value.adultSignatureRequired === true,
+    prohibitedCarriers: Array.isArray(value.prohibitedCarriers)
+      ? value.prohibitedCarriers.filter((item): item is string => typeof item === "string")
+      : [],
+  };
+}
+
+function parseLabelOutcome(value: unknown): { adultSignature: "accepted" | "refused" | "absent" } | null {
+  if (!isRecord(value)) return null;
+  if (value.adultSignature !== "accepted" && value.adultSignature !== "refused" && value.adultSignature !== "absent") return null;
+  return { adultSignature: value.adultSignature };
+}
+
+function parseJson(value: string): unknown {
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function pickProvider(rows: readonly { purchase_id: string; outcome: string }[]): LoadedOrder["provider"] {
+  const open = rows.find((row) => row.outcome === "intent" || row.outcome === "accepted" || row.outcome === "unknown");
+  const chosen = open ?? rows[0];
+  if (!chosen || !oneOf(chosen.outcome, ["intent", "accepted", "unknown", "voided", "refunded"] as const)) return null;
+  return { purchaseId: chosen.purchase_id, outcome: chosen.outcome };
+}