@tokenoftrust/storefront-runner 6.5.0 → 6.5.1

package/apps/storefront/migrations-apps/0026_fulfillment_assignment.sql

@@ -0,0 +1,44 @@
+-- Processor config: one row per (tenant, stage) naming the install that processes released orders.
+-- A cleared config keeps the row with state `cleared`; rows are never deleted.
+CREATE TABLE `fulfillment_processor_config` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (`stage` IN ('preview', 'publication')),
+  `install_id` text NOT NULL,
+  `state` text NOT NULL CHECK (`state` IN ('active', 'cleared')),
+  `updated_by` text NOT NULL,
+  `updated_at` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`)
+);
+--> statement-breakpoint
+-- Assignments move by state and keep history; none is deleted.
+CREATE TABLE `fulfillment_assignments` (
+  `assignment_id` text PRIMARY KEY NOT NULL,
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (`stage` IN ('preview', 'publication')),
+  `order_id` text NOT NULL,
+  `install_id` text NOT NULL,
+  `state` text NOT NULL CHECK (`state` IN ('active', 'held', 'cancelled', 'released')),
+  `event_version` integer NOT NULL CHECK (`event_version` >= 0),
+  `assigned_at` text NOT NULL,
+  `updated_at` text NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `fulfillment_assignments_open_order`
+ON `fulfillment_assignments` (`tenant_id`, `stage`, `order_id`)
+WHERE `state` IN ('active', 'held');
+--> statement-breakpoint
+CREATE INDEX `fulfillment_assignments_install_state`
+ON `fulfillment_assignments` (`tenant_id`, `stage`, `install_id`, `state`, `assigned_at`);
+--> statement-breakpoint
+-- One claim per business event across every emitter that can report it.
+CREATE TABLE `commerce_event_claims` (
+  `tenant_id` text NOT NULL,
+  `stage` text NOT NULL CHECK (`stage` IN ('preview', 'publication')),
+  `source` text NOT NULL,
+  `source_order_id` text NOT NULL,
+  `topic` text NOT NULL CHECK (`topic` IN ('order.fulfilled')),
+  `event_id` text NOT NULL,
+  `claimed_by` text NOT NULL CHECK (`claimed_by` IN ('handoff', 'forward')),
+  `claimed_at` text NOT NULL,
+  PRIMARY KEY (`tenant_id`, `stage`, `source`, `source_order_id`, `topic`)
+);

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

@@ -5,6 +5,7 @@ export function mountCommerceDesk(root: HTMLElement): void {
   const status = root.querySelector<HTMLElement>("[data-desk-status]")!;
   const rows = root.querySelector<HTMLElement>("[data-desk-orders]")!;
   const next = root.querySelector<HTMLButtonElement>("[data-desk-next]")!;
+  const processor = root.querySelector<HTMLElement>("[data-desk-processor]");
   const api = parseCommerceDeskApiRoot(root.dataset.commerceApi, root.dataset.targetTenant);
   if (!api) {
     rows.replaceChildren();
@@ -38,6 +39,10 @@ export function mountCommerceDesk(root: HTMLElement): void {
     text("p", `${order.payment} · ${order.fulfillment} · ${order.batch?.phase ?? "unclaimed"}`, card);
     text("p", order.lines.map((line) => `${line.sku} × ${line.quantity}`).join(", ") || "No verified line items", card);
     text("p", order.holds.length ? `Held: ${order.holds.join(", ")}` : "Ready", card);
+    if (order.assignment) {
+      const owner = text("p", `Assigned to processor ${order.assignment.installId} · ${order.assignment.state}`, card);
+      owner.dataset.assignmentState = order.assignment.state;
+    }
     const actions = order.batch
       ? [
           ["pick", "Confirm pick"],
@@ -91,6 +96,17 @@ export function mountCommerceDesk(root: HTMLElement): void {
       };
     }
   }
+  async function loadProcessor(): Promise<void> {
+    if (!processor) return;
+    try {
+      const value = (await request("/processor")) as { processor: { installId: string; notifiable: boolean } | null };
+      processor.textContent = value.processor
+        ? `Processor: ${value.processor.installId}${value.processor.notifiable ? "" : " (not receiving assignments)"}`
+        : "Processor: none. Released orders use the label path.";
+    } catch {
+      processor.textContent = "Processor configuration is visible to the store owner only.";
+    }
+  }
   async function load(after: string | null): Promise<void> {
     status.textContent = "Loading orders…";
     try {
@@ -115,7 +131,11 @@ export function mountCommerceDesk(root: HTMLElement): void {
       status.textContent = "Orders are unavailable. Refresh and try again.";
     }
   }
-  root.querySelector<HTMLButtonElement>("[data-desk-refresh]")!.onclick = () => void load(null);
+  root.querySelector<HTMLButtonElement>("[data-desk-refresh]")!.onclick = () => {
+    void loadProcessor();
+    void load(null);
+  };
   next.onclick = () => void load(cursor);
+  void loadProcessor();
   void load(null);
 }

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

@@ -0,0 +1,284 @@
+/**
+ * Processor configuration and fulfillment assignments.
+ *
+ * A (tenant, stage) names at most one processor install. Operator release writes the order's
+ * assignment to that install; hold, cancel and refund move it by state; switching or clearing the
+ * processor, and suspending, uninstalling or descoping its install, release it. Rows are never
+ * deleted: assignments keep their history and a config clears by state.
+ */
+import type { CommerceStage } from "@tot/public-runtime";
+import type { FulfillmentDatabase, SqlStatement } from "./store.js";
+
+export const PROCESSOR_SCOPE = "fulfillment:process";
+
+export type AssignmentState = "active" | "held" | "cancelled" | "released";
+
+export interface ProcessorConfig {
+  installId: string;
+  /** The install is active on this tenant, has an endpoint and holds `fulfillment:process`. */
+  notifiable: boolean;
+}
+
+export interface OpenAssignment {
+  assignmentId: string;
+  installId: string;
+  state: "active" | "held";
+  eventVersion: number;
+  assignedAt: string;
+}
+
+/** SQL condition: install `?` is active on tenant `?`, has an endpoint and holds the processor scope. */
+const NOTIFIABLE_INSTALL = `EXISTS (
+    SELECT 1 FROM app_installs AS pi
+    WHERE pi.install_id = ? AND pi.tenant_id = ? AND pi.status = 'active' AND pi.managed_kind IS NULL
+      AND COALESCE(pi.webhook_endpoint, '') != ''
+      AND EXISTS (SELECT 1 FROM json_each(pi.scopes) WHERE json_each.value = '${PROCESSOR_SCOPE}')
+  )`;
+
+export async function readProcessor(
+  db: Pick<FulfillmentDatabase, "get">,
+  tenantId: string,
+  stage: CommerceStage,
+): Promise<ProcessorConfig | null> {
+  const config = await db.get<{ install_id: string }>(
+    `SELECT install_id FROM fulfillment_processor_config WHERE tenant_id = ? AND stage = ? AND state = 'active'`,
+    [tenantId, stage],
+  );
+  if (!config) return null;
+  const notifiable = await db.get<{ ok: number }>(`SELECT 1 AS ok WHERE ${NOTIFIABLE_INSTALL}`, [config.install_id, tenantId]);
+  return { installId: config.install_id, notifiable: notifiable?.ok === 1 };
+}
+
+/** True when `installId` could be the processor for `tenantId`: active there, with an endpoint and the scope. */
+export async function installMayProcess(
+  db: Pick<FulfillmentDatabase, "get">,
+  tenantId: string,
+  installId: string,
+): Promise<boolean> {
+  const row = await db.get<{ ok: number }>(`SELECT 1 AS ok WHERE ${NOTIFIABLE_INSTALL}`, [installId, tenantId]);
+  return row?.ok === 1;
+}
+
+/**
+ * Sets or clears the (tenant, stage) processor. Switching or clearing releases the previous
+ * install's active and held assignments on that stage in the same batch; the config write is the
+ * batch's compare-and-set, so a concurrent change aborts it.
+ */
+export async function setProcessor(
+  db: FulfillmentDatabase,
+  input: { tenantId: string; stage: CommerceStage; installId: string | null; actorId: string; now: string },
+): Promise<{ ok: true; installId: string | null } | { ok: false; code: "install-not-found" | "conflict" }> {
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const current = await readProcessor(db, input.tenantId, input.stage);
+    if ((current?.installId ?? null) === input.installId) return { ok: true, installId: input.installId };
+    if (input.installId !== null && !(await installMayProcess(db, input.tenantId, input.installId))) {
+      return { ok: false, code: "install-not-found" };
+    }
+    let first: SqlStatement;
+    if (input.installId === null) {
+      first = {
+        sql: `UPDATE fulfillment_processor_config SET state = 'cleared', updated_by = ?, updated_at = ?
+          WHERE tenant_id = ? AND stage = ? AND state = 'active' AND install_id = ?`,
+        params: [input.actorId, input.now, input.tenantId, input.stage, current!.installId],
+      };
+    } else if (current) {
+      first = {
+        sql: `UPDATE fulfillment_processor_config SET install_id = ?, updated_by = ?, updated_at = ?
+          WHERE tenant_id = ? AND stage = ? AND state = 'active' AND install_id = ? AND ${NOTIFIABLE_INSTALL}`,
+        params: [input.installId, input.actorId, input.now, input.tenantId, input.stage, current.installId, input.installId, input.tenantId],
+      };
+    } else {
+      first = {
+        sql: `INSERT INTO fulfillment_processor_config (tenant_id, stage, install_id, state, updated_by, updated_at)
+          SELECT ?, ?, ?, 'active', ?, ? WHERE ${NOTIFIABLE_INSTALL}
+          ON CONFLICT (tenant_id, stage) DO UPDATE SET
+            install_id = excluded.install_id, state = 'active', updated_by = excluded.updated_by, updated_at = excluded.updated_at
+          WHERE fulfillment_processor_config.state = 'cleared'`,
+        params: [input.tenantId, input.stage, input.installId, input.actorId, input.now, input.installId, input.tenantId],
+      };
+    }
+    const statements: SqlStatement[] = [
+      first,
+      { sql: `SELECT json(CASE WHEN changes() >= 1 THEN 'true' ELSE 'cas-not-applied' END)`, params: [] },
+    ];
+    if (current) {
+      statements.push(
+        releaseInstallAssignmentsStatement({ tenantId: input.tenantId, installId: current.installId, now: input.now, stage: input.stage }),
+      );
+    }
+    try {
+      const changes = await db.batch(statements);
+      if ((changes[0] ?? 0) > 0) return { ok: true, installId: input.installId };
+    } catch (error) {
+      if (!isCasMiss(error)) throw error;
+    }
+  }
+  return { ok: false, code: "conflict" };
+}
+
+function isCasMiss(error: unknown): boolean {
+  let cause: unknown = error;
+  for (let depth = 0; depth < 4 && cause instanceof Error; depth++, cause = cause.cause) {
+    if (cause.message.includes("malformed JSON")) return true;
+  }
+  return false;
+}
+
+export async function readOpenAssignment(
+  db: Pick<FulfillmentDatabase, "get">,
+  tenantId: string,
+  stage: CommerceStage,
+  orderId: string,
+): Promise<OpenAssignment | null> {
+  const row = await db.get<{
+    assignment_id: string;
+    install_id: string;
+    state: string;
+    event_version: number;
+    assigned_at: string;
+  }>(
+    `SELECT assignment_id, install_id, state, event_version, assigned_at
+       FROM fulfillment_assignments
+      WHERE tenant_id = ? AND stage = ? AND order_id = ? AND state IN ('active', 'held')`,
+    [tenantId, stage, orderId],
+  );
+  if (!row || (row.state !== "active" && row.state !== "held")) return null;
+  return {
+    assignmentId: row.assignment_id,
+    installId: row.install_id,
+    state: row.state,
+    eventVersion: Number(row.event_version),
+    assignedAt: row.assigned_at,
+  };
+}
+
+/** SQL condition (no leading AND): the (tenant, stage) config names `installId` and that install is notifiable. */
+export function processorGuard(tenantId: string, stage: CommerceStage, installId: string): SqlStatement {
+  return {
+    sql: `EXISTS (
+        SELECT 1 FROM fulfillment_processor_config AS pc
+        WHERE pc.tenant_id = ? AND pc.stage = ? AND pc.install_id = ? AND pc.state = 'active'
+      ) AND ${NOTIFIABLE_INSTALL}`,
+    params: [tenantId, stage, installId, installId, tenantId],
+  };
+}
+
+function orderAtVersion(tenantId: string, stage: CommerceStage, orderId: string, version: number): SqlStatement {
+  return {
+    sql: `EXISTS (
+        SELECT 1 FROM scrappy_commerce_orders AS ov
+        WHERE ov.tenant_id = ? AND ov.stage = ? AND ov.order_id = ? AND ov.event_version = ?
+      )`,
+    params: [tenantId, stage, orderId, version],
+  };
+}
+
+/** Writes the active assignment only when the order committed at `version` in this batch. */
+export function insertAssignmentStatement(input: {
+  assignmentId: string;
+  tenantId: string;
+  stage: CommerceStage;
+  orderId: string;
+  installId: string;
+  version: number;
+  now: string;
+}): SqlStatement {
+  const gate = orderAtVersion(input.tenantId, input.stage, input.orderId, input.version);
+  return {
+    sql: `INSERT INTO fulfillment_assignments
+        (assignment_id, tenant_id, stage, order_id, install_id, state, event_version, assigned_at, updated_at)
+      SELECT ?, ?, ?, ?, ?, 'active', ?, ?, ? WHERE ${gate.sql}`,
+    params: [
+      input.assignmentId,
+      input.tenantId,
+      input.stage,
+      input.orderId,
+      input.installId,
+      input.version,
+      input.now,
+      input.now,
+      ...gate.params,
+    ],
+  };
+}
+
+/** Moves one assignment from any of `from` to `to` when the order committed at `version`, and `guard` holds. */
+export function moveAssignmentStatement(input: {
+  assignmentId: string;
+  tenantId: string;
+  stage: CommerceStage;
+  orderId: string;
+  from: readonly AssignmentState[];
+  to: AssignmentState;
+  version: number;
+  now: string;
+  guard?: SqlStatement;
+  unlessGuard?: boolean;
+}): SqlStatement {
+  const gate = orderAtVersion(input.tenantId, input.stage, input.orderId, input.version);
+  const marks = input.from.map(() => "?").join(", ");
+  const guard = input.guard ? ` AND ${input.unlessGuard ? "NOT " : ""}(${input.guard.sql})` : "";
+  return {
+    sql: `UPDATE fulfillment_assignments SET state = ?, event_version = ?, updated_at = ?
+      WHERE assignment_id = ? AND tenant_id = ? AND stage = ? AND order_id = ? AND state IN (${marks})
+        AND ${gate.sql}${guard}`,
+    params: [
+      input.to,
+      input.version,
+      input.now,
+      input.assignmentId,
+      input.tenantId,
+      input.stage,
+      input.orderId,
+      ...input.from,
+      ...gate.params,
+      ...(input.guard?.params ?? []),
+    ],
+  };
+}
+
+/** Event gate: the assignment stands at `state` as of `version` — i.e. the transition it reports committed. */
+export function assignmentAtGate(assignmentId: string, state: AssignmentState, version: number): SqlStatement {
+  return {
+    sql: `EXISTS (SELECT 1 FROM fulfillment_assignments WHERE assignment_id = ? AND state = ? AND event_version = ?)`,
+    params: [assignmentId, state, version],
+  };
+}
+
+/** Releases every open assignment `installId` holds on `tenantId` (optionally one stage). No event. */
+export function releaseInstallAssignmentsStatement(input: {
+  tenantId: string;
+  installId: string;
+  now: string;
+  stage?: CommerceStage;
+}): SqlStatement {
+  return {
+    sql: `UPDATE fulfillment_assignments SET state = 'released', updated_at = ?
+      WHERE tenant_id = ? AND install_id = ? AND state IN ('active', 'held')${input.stage ? " AND stage = ?" : ""}`,
+    params: [input.now, input.tenantId, input.installId, ...(input.stage ? [input.stage] : [])],
+  };
+}
+
+/** Clears every active processor config naming `installId` on `tenantId`. */
+export function clearInstallProcessorStatement(input: {
+  tenantId: string;
+  installId: string;
+  actor: string;
+  now: string;
+}): SqlStatement {
+  return {
+    sql: `UPDATE fulfillment_processor_config SET state = 'cleared', updated_by = ?, updated_at = ?
+      WHERE tenant_id = ? AND install_id = ? AND state = 'active'`,
+    params: [input.actor, input.now, input.tenantId, input.installId],
+  };
+}
+
+/** The statements that detach `installId` from fulfillment on `tenantId`: release its assignments, clear its config. */
+export function detachInstallStatements(input: {
+  tenantId: string;
+  installId: string;
+  actor: string;
+  now: string;
+}): SqlStatement[] {
+  return [releaseInstallAssignmentsStatement(input), clearInstallProcessorStatement(input)];
+}

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

@@ -5,6 +5,7 @@ import { foldCommerceEvents, type StoredCommercePayload } from "../orders/data/o
 import { admissionBindsOrder, currentCartEvent, readCommerceAdmission } from "../checkout/commerce/commerceAdmission.js";
 import { FulfillmentService } from "./fulfillmentService.js";
 import { fulfillmentDbFromQueryable } from "./store.js";
+import { dispatchCommerceDeliveries } from "./commerceRuntime.js";
 const UNKNOWN: CommerceEvidence = { verification: "UNKNOWN", tax: "UNKNOWN", risk: "UNKNOWN", stock: "UNKNOWN" };
 
 export async function projectCommerceOrder(
@@ -87,6 +88,7 @@ export async function projectCommerceOrder(
   const service = new FulfillmentService(fulfillmentDbFromQueryable(db), {
     policy: { adultSignatureRequired: false, prohibitedCarriers: [], carrierAccountId: null },
     now: () => input.now,
+    notify: dispatchCommerceDeliveries,
   });
   const applied = await service.applySourceSnapshot(
     { role: "owner", actorId: "commerce-source", tenantId: input.tenantId, stage: input.stage },

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

@@ -3,6 +3,10 @@ import { ScrappyOrderLedger } from "../orders/data/ordersStore.js";
 import { COMMERCE_SCHEDULER, type CommerceStage } from "@tot/public-runtime";
 import type { Queryable } from "../catalog/d1/catalog.js";
 import { sweepDurableCommerce } from "../integrations/webhooks/deliveryEngine.js";
+import { COMMERCE_DELIVERY_GRACE_MS, dueCommerceDeliveries } from "../integrations/webhooks/deliveryStore.js";
+import { deliveryAttemptFor } from "../integrations/webhooks/getDispatcher.js";
+import type { AttemptDeliveryFn } from "../integrations/webhooks/dispatcher.js";
+
 import { projectCommerceOrder } from "./commerceProjection.js";
 
 export async function recoverTenantCommerce(
@@ -10,6 +14,7 @@ export async function recoverTenantCommerce(
   tenantId: string,
   now: string,
   deployedSha: string,
+  attempt: AttemptDeliveryFn = deliveryAttemptFor(db),
 ): Promise<number | null> {
   let incomplete=false;
   for (const stage of ["preview", "publication"] as const) {
@@ -48,12 +53,24 @@ export async function recoverTenantCommerce(
       runId,
     );
   }
+  const webhooks = await dueCommerceDeliveries(db, tenantId, now, COMMERCE_DELIVERY_GRACE_MS);
+  for (const deliveryId of webhooks.due) {
+    try {
+      await attempt(deliveryId);
+    } catch {
+      incomplete = true;
+    }
+  }
   if(incomplete)throw new Error("commerce-recovery-incomplete");
   const due = await db.first<{ available_at: string }>(
     `SELECT MIN(available_at) available_at FROM scrappy_commerce_outbox WHERE tenant_id=? AND state='pending'`,
     tenantId,
   );
-  return due?.available_at ? Math.max(Date.parse(now) + 1000, Date.parse(due.available_at)) : null;
+  const after = await dueCommerceDeliveries(db, tenantId, now, COMMERCE_DELIVERY_GRACE_MS);
+  const candidates = [due?.available_at, after.nextAt, after.due.length > 0 ? now : null]
+    .filter((value): value is string => typeof value === "string")
+    .map((value) => Date.parse(value));
+  return candidates.length > 0 ? Math.max(Date.parse(now) + 1000, Math.min(...candidates)) : null;
 }
 
 export async function replayCommerceOrder(

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

@@ -1,9 +1,12 @@
 /** Commerce reaches the existing tenant scheduler through its own narrow RPC interface. */
 import { getWorkerEnv } from "../publication/shared/runtimeEnv.js";
 import type { CommerceCallerConfig, SignedCommerceResult } from "../orders/data/orderForwardReceiver.js";
+import { COMMERCE_DELIVERY_GRACE_MS } from "../integrations/webhooks/deliveryStore.js";
+import { getDispatcher } from "../integrations/webhooks/getDispatcher.js";
 export interface CommercePipeline {
   commerceReceive(body: unknown, token: string, config: CommerceCallerConfig): Promise<SignedCommerceResult>;
   commerceReplay(tenantId: string, stage: "preview" | "publication", outboxId: string): Promise<boolean>;
+  scheduleCommerce(tenantId: string, at: number): Promise<void>;
 }
 export async function commercePipelineFor(tenantId: string): Promise<CommercePipeline | null> {
   const namespace = (await getWorkerEnv())?.TENANT_PIPELINE as
@@ -11,3 +14,28 @@ export async function commercePipelineFor(tenantId: string): Promise<CommercePip
     | undefined;
   return namespace && typeof namespace.idFromName === "function" ? namespace.get(namespace.idFromName(tenantId)) : null;
 }
+
+/**
+ * After a commerce commit: arm the tenant's commerce alarm past the enqueue grace, then enqueue
+ * each committed delivery. Both are best effort; a delivery neither path reaches stays pending
+ * and the alarm redelivers it under the same id.
+ */
+export async function dispatchCommerceDeliveries(
+  tenantId: string,
+  deliveryIds: readonly string[],
+  now: number = Date.now(),
+): Promise<void> {
+  if (deliveryIds.length === 0) return;
+  try {
+    await (await commercePipelineFor(tenantId))?.scheduleCommerce(tenantId, now + COMMERCE_DELIVERY_GRACE_MS + 1000);
+  } catch {
+    // The delivery rows are committed; the next alarm or commerce receipt for this tenant sweeps them.
+  }
+  try {
+    const dispatcher = await getDispatcher();
+    if (dispatcher instanceof Response) return;
+    for (const deliveryId of deliveryIds) await dispatcher.enqueue({ deliveryId });
+  } catch {
+    // Same: the pending rows remain the durable record.
+  }
+}