@tokenoftrust/storefront-runner 6.5.0 → 6.5.2

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

@@ -51,6 +51,25 @@ import {
   type FulfillmentDatabase,
   type SqlStatement,
 } from "./store.js";
+import {
+  assignmentAtGate,
+  insertAssignmentStatement,
+  moveAssignmentStatement,
+  processorGuard,
+  readOpenAssignment,
+  readProcessor,
+  type AssignmentState,
+  type OpenAssignment,
+  type ProcessorConfig,
+} from "./assignmentStore.js";
+import {
+  CommercePayloadRefused,
+  commerceEventStatements,
+  commerceTargetsQuery,
+} from "../integrations/webhooks/deliveryStore.js";
+import { dispatchCommerceDeliveries } from "./commerceRuntime.js";
+import type { CommerceTopic } from "../integrations/webhooks/commercePayloads.js";
+import { claimedByEventGate, handoffClaimStatement } from "../integrations/webhooks/orderFulfilledClaim.js";
 
 export const OPAQUE_ID = /^[A-Za-z0-9._:-]{1,128}$/;
 
@@ -124,6 +143,10 @@ export interface FulfillmentView {
   evidence: CommerceEvidence;
   placedAt: string;
   currency: string;
+  /** The (tenant, stage) processor install, when one is configured. */
+  processor: { installId: string; notifiable: boolean } | null;
+  /** The order's open assignment and the install that owns it. */
+  assignment: { assignmentId: string; installId: string; state: "active" | "held" } | null;
 }
 
 export interface FulfillmentBatch {
@@ -183,13 +206,38 @@ interface LoadedOrder {
   prohibitedCarriers: string[];
   adultSignatureRequired: boolean;
   auditCount: number;
+  processor: ProcessorConfig | null;
+  assignment: OpenAssignment | null;
   view: FulfillmentView;
 }
 
+interface PlannedDelivery {
+  index: number;
+  deliveryId: string;
+}
+
 type CommitPlan =
   | { type: "done"; view: FulfillmentView }
   | { type: "refuse"; code: string; holds?: readonly ReleaseHold[] }
-  | { type: "write"; statements: SqlStatement[]; minimumChanges: number; sourceAdvance?:boolean };
+  | {
+      type: "write";
+      statements: SqlStatement[];
+      minimumChanges: number;
+      sourceAdvance?: boolean;
+      /** Delivery rows the batch writes; the committed ones are handed to `notify`. */
+      deliveries?: readonly PlannedDelivery[];
+      /** An assignment plan: a CAS miss re-runs build (bound to its install) even with expectedVersion. */
+      assignment?: boolean;
+    };
+
+/** Statement and delivery accumulator for a plan that may carry commerce events. */
+interface PlanStatements {
+  statements: SqlStatement[];
+  deliveries: PlannedDelivery[];
+}
+
+/** Statuses an open assignment reports in its lifecycle event. */
+type ReportedAssignmentState = Exclude<AssignmentState, "released">;
 
 const FAIL_CLOSED_EVIDENCE: CommerceEvidence = {
   verification: "unreadable",
@@ -468,7 +516,11 @@ export async function openFulfillment(
     compliance: tenant?.compliance,
     carrierAccountId: tenant?.carrierAccountId,
   });
-  return { ok: true, actor: decision.actor, service: new FulfillmentService(fulfillmentDbFromD1(d1), { policy }) };
+  return {
+    ok: true,
+    actor: decision.actor,
+    service: new FulfillmentService(fulfillmentDbFromD1(d1), { policy, notify: dispatchCommerceDeliveries }),
+  };
 }
 
 export function parseFulfillmentBody(body: unknown): FulfillmentResult<{
@@ -533,7 +585,12 @@ export class FulfillmentService {
 
   constructor(
     private readonly db: FulfillmentDatabase,
-    private readonly options: { policy: CarrierPolicy; now?: () => string },
+    private readonly options: {
+      policy: CarrierPolicy;
+      now?: () => string;
+      /** Called after a commit with the delivery ids it wrote, to enqueue them and arm the commerce alarm. */
+      notify?: (tenantId: string, deliveryIds: string[]) => void | Promise<void>;
+    },
   ) {
     this.now = options.now ?? (() => new Date().toISOString());
   }
@@ -673,20 +730,16 @@ export class FulfillmentService {
       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)),
-        ],
-      };
+      return this.withAssignmentHeld(state, version, [
+        {
+          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)),
+      ]);
     });
   }
 
@@ -696,9 +749,7 @@ export class FulfillmentService {
       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,
+      const plan: PlanStatements = {
         statements: [
           {
             sql: `UPDATE scrappy_commerce_orders
@@ -709,7 +760,30 @@ export class FulfillmentService {
           },
           auditStatement(state, actor.actorId, "operator-hold", "open", "cleared", version, stamp(this.now(), state.auditCount + 1)),
         ],
+        deliveries: [],
       };
+      const assignment = state.assignment;
+      if (assignment?.state === "held" && !state.cancelPending && state.order.payment !== "refund_requested") {
+        // Resume only while the install is still the configured, notifiable processor; otherwise
+        // release it so the order waits for a new operator release.
+        const guard = processorGuard(state.order.tenantId, state.order.stage, assignment.installId);
+        this.appendAssignmentMove(plan, state, assignment, "active", version, guard);
+        plan.statements.push(
+          moveAssignmentStatement({
+            assignmentId: assignment.assignmentId,
+            tenantId: state.order.tenantId,
+            stage: state.order.stage,
+            orderId: state.order.orderId,
+            from: ["held"],
+            to: "released",
+            version,
+            now: this.now(),
+            guard,
+            unlessGuard: true,
+          }),
+        );
+      }
+      return { type: "write", minimumChanges: 1, statements: plan.statements, deliveries: plan.deliveries };
     });
   }
 
@@ -727,28 +801,24 @@ export class FulfillmentService {
       });
       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),
-          ),
-        ],
-      };
+      return this.withAssignmentHeld(state, version, [
+        {
+          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),
+        ),
+      ]);
     });
   }
 
@@ -771,21 +841,17 @@ export class FulfillmentService {
       });
       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)),
-        ],
-      };
+      return this.withAssignmentHeld(state, version, [
+        {
+          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)),
+      ]);
     });
   }
 
@@ -796,6 +862,7 @@ export class FulfillmentService {
     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.assignment) return { type: "refuse", code: "processor-assigned" };
       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) {
@@ -877,7 +944,8 @@ export class FulfillmentService {
   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) => {
+    return this.commit(actor, orderId, options.expectedVersion, async (state) => {
+      if (state.assignment) return { type: "refuse", code: "processor-assigned" };
       if (state.shipment?.handoffState === "handed_off" || state.order.fulfillment === "handed_off") {
         return { type: "done", view: state.view };
       }
@@ -887,10 +955,8 @@ export class FulfillmentService {
         return { type: "refuse", code: "label" };
       }
       const version = state.order.eventVersion + 1;
-      return {
-        type: "write",
-        minimumChanges: 1,
-        sourceAdvance:true,
+      const plan: PlanStatements = {
+        deliveries: [],
         statements: [
           {
             sql: `UPDATE scrappy_commerce_orders
@@ -936,6 +1002,8 @@ export class FulfillmentService {
           terminalTransitionExpiryStatement(state.order, version, new Date(this.now())),
         ],
       };
+      await this.appendOrderFulfilled(plan, state, version);
+      return { type: "write", minimumChanges: 1, sourceAdvance: true, statements: plan.statements, deliveries: plan.deliveries };
     });
   }
 
@@ -978,6 +1046,8 @@ export class FulfillmentService {
     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");
+    // The install a release's first assignment plan targeted; a CAS-miss retry stays bound to it.
+    let boundInstall: string | null = null;
     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") {
@@ -988,8 +1058,31 @@ export class FulfillmentService {
       const readiness = this.readiness(state);
       const releasable = canRelease(readiness);
       if (raising && !releasable) return {type:"refuse",code:releaseHolds(readiness)[0] ?? "held",holds:releaseHolds(readiness)};
+      if (phase === null && (boundInstall !== null || state.processor)) {
+        const target = boundInstall ?? state.processor!.installId;
+        // The install that already holds the order's assignment answers done at any version.
+        if (state.assignment) {
+          return state.assignment.installId === target ? { type: "done", view: state.view } : { type: "refuse", code: "assignment-conflict" };
+        }
+        // A desk release carries the version it saw; any other version lost to a concurrent change.
+        if (options.expectedVersion !== undefined && state.order.eventVersion !== options.expectedVersion) {
+          return { type: "refuse", code: "assignment-conflict" };
+        }
+        if (!state.processor || state.processor.installId !== target || !state.processor.notifiable) {
+          return { type: "refuse", code: "assignment-conflict" };
+        }
+        if (state.shipment || holdsLiveLabelOperation(state)) return { type: "refuse", code: "label-intent" };
+        if (!releasable) {
+          const holds = releaseHolds(readiness);
+          return { type: "refuse", code: holds[0] ?? "hold", holds };
+        }
+        boundInstall = target;
+        return this.assignmentPlan(state, target);
+      }
+      if (phase === null && state.assignment) return { type: "refuse", code: "processor-assigned" };
       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;
+      const wantIntent = (phase === null || phase === "picked" || phase === "packed") && releasable && !state.shipment && labelAcceptsIntent
+        && !state.processor && !state.assignment;
       if (phase === null && !state.shipment && !wantIntent) {
         if (!releasable) {
           const holds = releaseHolds(readiness);
@@ -1050,6 +1143,11 @@ export class FulfillmentService {
           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
+          )
+          AND NOT EXISTS (
+            SELECT 1 FROM fulfillment_assignments AS fa
+            WHERE fa.tenant_id = o.tenant_id AND fa.stage = o.stage AND fa.order_id = o.order_id
+              AND fa.state IN ('active', 'held')
           )`,
         params: [order.tenantId, order.stage, order.orderId, version],
       },
@@ -1080,12 +1178,20 @@ export class FulfillmentService {
     const scope = this.commandScope(actor);
     if (!scope) return refuse("denied");
     if (!isOpaqueId(orderId)) return refuse("not-found");
+    let assignmentPlan = false;
     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);
+      let plan: CommitPlan;
+      try {
+        plan = await build(state);
+      } catch (error) {
+        if (error instanceof CommercePayloadRefused) return refuse("malformed");
+        throw error;
+      }
       if (plan.type === "done") return ok(plan.view);
       if (plan.type === "refuse") return refuse(plan.code, plan.holds);
+      assignmentPlan = plan.assignment === true;
       if (expectedVersion !== undefined && state.order.eventVersion !== expectedVersion) return refuse("conflict");
       const fence=authorityFence(state.sourceAuthority,this.now(),plan.sourceAdvance===true);
       const first=plan.statements[0];
@@ -1094,12 +1200,205 @@ export class FulfillmentService {
       const changes = await this.write(guarded);
       if (!changes) return refuse("unavailable");
       if ((changes[0] ?? 0) >= plan.minimumChanges) {
+        await this.notifyCommitted(scope.tenantId, plan.deliveries ?? [], changes);
         const next = await this.load(scope.tenantId, scope.stage, orderId);
         return next ? ok(next.view) : refuse("not-found");
       }
-      if (expectedVersion !== undefined) return refuse("conflict");
+      if (expectedVersion !== undefined && !assignmentPlan) return refuse("conflict");
     }
-    return refuse("conflict");
+    return refuse(assignmentPlan ? "assignment-conflict" : "conflict");
+  }
+
+  /** A hold-shaped write: the order statements plus, for an active assignment, its move to held. */
+  private withAssignmentHeld(state: LoadedOrder, version: number, statements: SqlStatement[]): CommitPlan {
+    const plan: PlanStatements = { statements, deliveries: [] };
+    if (state.assignment?.state === "active") this.appendAssignmentMove(plan, state, state.assignment, "held", version);
+    return { type: "write", minimumChanges: 1, statements: plan.statements, deliveries: plan.deliveries };
+  }
+
+  /**
+   * Release to the configured processor: the order CAS (also requiring the config to name
+   * `installId` and the install to be notifiable), the active assignment, and its one
+   * `fulfillment.assignment.created` delivery to that install. No label intent is written.
+   */
+  private assignmentPlan(state: LoadedOrder, installId: string): CommitPlan {
+    const { order } = state;
+    const version = order.eventVersion + 1;
+    const assignmentId = `asg_${crypto.randomUUID()}`;
+    const touch = touchOrder(state, false);
+    const guard = processorGuard(order.tenantId, order.stage, installId);
+    const plan: PlanStatements = {
+      statements: [
+        { sql: `${touch.sql} AND ${guard.sql}`, params: [...touch.params, ...guard.params] },
+        insertAssignmentStatement({
+          assignmentId,
+          tenantId: order.tenantId,
+          stage: order.stage,
+          orderId: order.orderId,
+          installId,
+          version,
+          now: this.now(),
+        }),
+      ],
+      deliveries: [],
+    };
+    this.appendCommerceEvent(plan, {
+      tenantId: order.tenantId,
+      topic: "fulfillment.assignment.created",
+      payload: assignmentPayload(state, assignmentId, "active", version, this.now()),
+      gate: assignmentAtGate(assignmentId, "active", version),
+      installIds: [installId],
+    });
+    return {
+      type: "write",
+      minimumChanges: 1,
+      sourceAdvance: true,
+      assignment: true,
+      statements: plan.statements,
+      deliveries: plan.deliveries,
+    };
+  }
+
+  /** The handoff's `order.fulfilled`: claim it for this order, and write the event only under that claim. */
+  private async appendOrderFulfilled(plan: PlanStatements, state: LoadedOrder, version: number): Promise<void> {
+    const { order } = state;
+    const key = { tenantId: order.tenantId, stage: order.stage, source: order.source, sourceOrderId: order.sourceOrderId };
+    const eventId = crypto.randomUUID();
+    plan.statements.push(
+      handoffClaimStatement(key, eventId, this.now(), {
+        sql: `EXISTS (SELECT 1 FROM scrappy_commerce_orders WHERE tenant_id = ? AND stage = ? AND order_id = ? AND event_version = ?)`,
+        params: [order.tenantId, order.stage, order.orderId, version],
+      }),
+    );
+    const targets = commerceTargetsQuery(order.tenantId, "order.fulfilled");
+    const installs = await this.db.all<{ install_id: string }>(targets.sql, targets.params);
+    const payload: Record<string, unknown> = { id: order.sourceOrderId, status: "fulfilled", currency: order.currency };
+    if (state.lines.length > 0) payload.lineItems = state.lines.map((line) => ({ sku: line.sku, quantity: line.quantity }));
+    this.appendCommerceEvent(plan, {
+      tenantId: order.tenantId,
+      topic: "order.fulfilled",
+      payload,
+      gate: claimedByEventGate(key, eventId),
+      installIds: installs.map((row) => row.install_id),
+      eventId,
+    });
+  }
+
+  /**
+   * The processor's reconciliation read: the calling install's active assignments on this tenant
+   * and stage whose order is still releasable at its current event version, oldest first.
+   */
+  async listAssignments(input: {
+    tenantId: string;
+    stage: CommerceStage;
+    installId: string;
+    limit: number;
+    cursor: string | null;
+  }): Promise<FulfillmentResult<{ assignments: AssignmentReadItem[]; nextCursor: string | null }>> {
+    const limit = Math.max(1, Math.min(100, Math.trunc(input.limit)));
+    let after: [string, string] = ["", ""];
+    if (input.cursor !== null) {
+      const decoded = decodeAssignmentCursor(input.cursor);
+      if (!decoded) return ok({ assignments: [], nextCursor: null });
+      after = decoded;
+    }
+    const rows = await this.db.all<{ assignment_id: string; order_id: string; assigned_at: string }>(
+      `SELECT assignment_id, order_id, assigned_at FROM fulfillment_assignments
+        WHERE tenant_id = ? AND stage = ? AND install_id = ? AND state = 'active'
+          AND (assigned_at > ? OR (assigned_at = ? AND assignment_id > ?))
+        ORDER BY assigned_at ASC, assignment_id ASC LIMIT ?`,
+      [input.tenantId, input.stage, input.installId, after[0], after[0], after[1], limit + 1],
+    );
+    const page = rows.slice(0, limit);
+    const assignments: AssignmentReadItem[] = [];
+    for (const row of page) {
+      const state = await this.load(input.tenantId, input.stage, row.order_id);
+      if (!state || state.assignment?.assignmentId !== row.assignment_id || state.assignment.installId !== input.installId) continue;
+      if (state.assignment.state !== "active" || state.lines.length === 0) continue;
+      if (!canRelease(this.readiness(state))) continue;
+      assignments.push({
+        assignmentId: row.assignment_id,
+        orderId: row.order_id,
+        stage: input.stage,
+        eventVersion: state.order.eventVersion,
+        assignedAt: row.assigned_at,
+        purchaseId: await purchaseIdFor(input.tenantId, input.stage, row.order_id),
+        lineItems: state.lines.map((line) => ({ sku: line.sku, quantity: line.quantity })),
+      });
+    }
+    const last = page[page.length - 1];
+    return ok({ assignments, nextCursor: rows.length > limit && last ? encodeAssignmentCursor(last.assigned_at, last.assignment_id) : null });
+  }
+
+  private async notifyCommitted(tenantId: string, deliveries: readonly PlannedDelivery[], changes: readonly number[]): Promise<void> {
+    const committed = deliveries.filter((delivery) => (changes[delivery.index] ?? 0) > 0).map((delivery) => delivery.deliveryId);
+    if (committed.length === 0 || !this.options.notify) return;
+    try {
+      await this.options.notify(tenantId, committed);
+    } catch {
+      // The delivery rows are committed and pending; the tenant commerce alarm redelivers them.
+    }
+  }
+
+  /** Appends one commerce event (gated on `gate`) and a delivery per install to `plan`. */
+  private appendCommerceEvent(
+    plan: PlanStatements,
+    input: {
+      tenantId: string;
+      topic: CommerceTopic;
+      payload: Record<string, unknown>;
+      gate: SqlStatement;
+      installIds: readonly string[];
+      eventId?: string;
+    },
+  ): void {
+    const targets = input.installIds.map((installId) => ({ installId, deliveryId: crypto.randomUUID() }));
+    const built = commerceEventStatements({
+      eventId: input.eventId ?? crypto.randomUUID(),
+      tenantId: input.tenantId,
+      topic: input.topic,
+      payload: input.payload,
+      gate: { sql: input.gate.sql, params: [...input.gate.params] },
+      targets,
+      now: this.now(),
+    });
+    built.forEach((statement, index) => {
+      const target = index > 0 ? targets[index - 1] : undefined;
+      if (target) plan.deliveries.push({ index: plan.statements.length, deliveryId: target.deliveryId });
+      plan.statements.push(statement);
+    });
+  }
+
+  /** Appends the assignment's move to `to` at `version` plus its `fulfillment.assignment.updated` event. */
+  private appendAssignmentMove(
+    plan: PlanStatements,
+    state: LoadedOrder,
+    assignment: OpenAssignment,
+    to: ReportedAssignmentState,
+    version: number,
+    guard?: SqlStatement,
+  ): void {
+    const from: AssignmentState[] = to === "cancelled" ? ["active", "held"] : to === "held" ? ["active"] : ["held"];
+    plan.statements.push(
+      moveAssignmentStatement({
+        assignmentId: assignment.assignmentId,
+        tenantId: state.order.tenantId,
+        stage: state.order.stage,
+        orderId: state.order.orderId,
+        from,
+        to,
+        version,
+        now: this.now(),
+        guard,
+      }),
+    );
+    this.appendCommerceEvent(plan, {
+      tenantId: state.order.tenantId,
+      topic: "fulfillment.assignment.updated",
+      payload: assignmentPayload(state, assignment.assignmentId, to, version, this.now()),
+      gate: assignmentAtGate(assignment.assignmentId, to, version),
+      installIds: [assignment.installId],
+    });
   }
 
   private async write(statements: readonly SqlStatement[],minimumChanges=1): Promise<number[] | null> {
@@ -1292,7 +1591,9 @@ export class FulfillmentService {
         statements.push(terminalTransitionExpiryStatement(state.order, nextVersion, new Date(this.now())));
       }
       if (snapshot.sourceVersion !== undefined) statements.push(projectionCheckpoint(snapshot,nextVersion,this.now()));
-      return { type: "write", statements, minimumChanges: 1 };
+      const plan: PlanStatements = { statements, deliveries: [] };
+      if (confirmedCancel && state.assignment) this.appendAssignmentMove(plan, state, state.assignment, "cancelled", nextVersion);
+      return { type: "write", statements: plan.statements, deliveries: plan.deliveries, minimumChanges: 1 };
     });
   }
 
@@ -1394,6 +1695,8 @@ export class FulfillmentService {
     try { sourceAuthority=await this.db.get<AuthorityRow & Record<string,unknown>>(`SELECT * FROM commerce_source_authority WHERE tenant_id=? AND stage=? AND source=? AND source_order_id=?`,[tenantId,stage,order.source,order.sourceOrderId]) ?? null;
       sourceHolds=sourceAuthority?.order_id!==order.orderId?["source-authority-unavailable"]:authorityHolds(sourceAuthority,this.now());
     }catch{sourceHolds=["source-authority-unreadable"];}
+    const processor = await readProcessor(this.db, tenantId, stage);
+    const assignment = await readOpenAssignment(this.db, tenantId, stage, orderId);
     const contacts = await readOrderContactAvailability({
       all: (sql, ...params) => this.db.all(sql, params),
     }, { tenantId, stage, orderIds: [orderId], now: new Date(this.now()) });
@@ -1417,6 +1720,8 @@ export class FulfillmentService {
       prohibitedCarriers: intentProhibited,
       adultSignatureRequired: intentAdult,
       auditCount: audits.length,
+      processor,
+      assignment,
       view: {
         orderId: order.orderId,
         tenantId: order.tenantId,
@@ -1434,13 +1739,15 @@ export class FulfillmentService {
         shipment: null,
         packingSlip,
         lines, evidence, placedAt:order.placedAt, currency:order.currency,
+        processor,
+        assignment: assignment ? { assignmentId: assignment.assignmentId, installId: assignment.installId, state: assignment.state } : null,
       },
     };
     const readiness = this.readiness(loaded);
     const holds = releaseHolds(readiness);
     loaded.view.holds = holds;
     if(holds.length&&order.fulfillment==="ready")loaded.view.fulfillment="held";
-    loaded.view.canRelease = canRelease(readiness) && !loaded.shipment;
+    loaded.view.canRelease = canRelease(readiness) && !loaded.shipment && !assignment;
     loaded.view.canHandOff = handoffRefusal(readiness) === null && loaded.shipment?.handoffState !== "handed_off";
     loaded.view.shipment = loaded.shipment
       ? {
@@ -1458,6 +1765,56 @@ export class FulfillmentService {
   }
 }
 
+export interface AssignmentReadItem {
+  assignmentId: string;
+  orderId: string;
+  stage: CommerceStage;
+  eventVersion: number;
+  assignedAt: string;
+  purchaseId: string;
+  lineItems: { sku: string; quantity: number }[];
+}
+
+function encodeAssignmentCursor(assignedAt: string, assignmentId: string): string {
+  return btoa(JSON.stringify([assignedAt, assignmentId])).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function decodeAssignmentCursor(cursor: string): [string, string] | null {
+  if (cursor.length === 0 || cursor.length > 512 || !/^[A-Za-z0-9_-]+$/.test(cursor)) return null;
+  try {
+    const parsed: unknown = JSON.parse(atob(cursor.replace(/-/g, "+").replace(/_/g, "/")));
+    if (!Array.isArray(parsed) || parsed.length !== 2) return null;
+    const [assignedAt, assignmentId] = parsed as unknown[];
+    return typeof assignedAt === "string" && typeof assignmentId === "string" ? [assignedAt, assignmentId] : null;
+  } catch {
+    return null;
+  }
+}
+
+/** `FulfillmentAssignmentData` (asyncapi.yaml): exactly these six keys. */
+function assignmentPayload(
+  state: LoadedOrder,
+  assignmentId: string,
+  assignmentState: ReportedAssignmentState,
+  version: number,
+  now: string,
+): Record<string, unknown> {
+  return {
+    assignmentId,
+    orderId: state.order.orderId,
+    stage: state.order.stage,
+    state: assignmentState,
+    eventVersion: version,
+    occurredAt: now,
+  };
+}
+
+/** A whole-order label purchase is in flight or held by the provider. */
+function holdsLiveLabelOperation(state: LoadedOrder): boolean {
+  const outcome = state.provider?.outcome;
+  return outcome === "intent" || outcome === "accepted" || outcome === "unknown";
+}
+
 function touchOrder(state: LoadedOrder, wantIntent: boolean): SqlStatement {
   return {
     sql: `UPDATE scrappy_commerce_orders
@@ -1639,11 +1996,13 @@ function parseLabelOutcome(value: unknown): { adultSignature: "accepted" | "refu
   return { adultSignature: value.adultSignature };
 }
 
+/** A stored audit state that is not JSON parses to null, which every caller fails closed on. */
 function parseJson(value: string): unknown {
   try {
     return JSON.parse(value) as unknown;
-  } catch {
-    return null;
+  } catch (error) {
+    if (error instanceof SyntaxError) return null;
+    throw error;
   }
 }