@tokenoftrust/storefront-runner 6.5.0 → 6.5.1

package/apps/storefront/src/lib/integrations/apps/registryService.ts

@@ -41,9 +41,10 @@
  * `app_version_snapshots` table over the SAME `Queryable` seam this service
  * uses). The authority for "which version is active" is the version store's
  * `MAX(seq)` current snapshot; `app_installs.app_version` is a DERIVED MIRROR
- * that this service re-points from the store's post-write current version in
- * the same operation ({@link AppRegistryService.syncActiveVersionMirror}). The
- * two can never diverge because the mirror is only ever written from the
+ * that this service writes from the store's current version in the same
+ * operation: `update` writes it from the activation it commits in the same
+ * batch, and `rollback` re-syncs it ({@link AppRegistryService.syncActiveVersionMirror}).
+ * The two can never diverge because the mirror is only ever written from the
  * store's current snapshot — you change the active version by retaining/rolling
  * one, never by writing the mirror directly. `rollback` restores a prior
  * version's whole facet set atomically (store-side) and re-syncs the mirror, so
@@ -56,6 +57,7 @@ import {
   AppVersionError,
   type AppVersionFacets,
   type AppVersionSnapshot,
+  type PlannedVersionWrite,
 } from "./appVersionStore.js";
 import {
   DEFAULT_EXECUTION_TIER,
@@ -71,6 +73,7 @@ import {
   type PlanIntegrationConsent,
 } from "@tot/public-runtime";
 import type { Queryable } from "../../catalog/d1/catalog.js";
+import { PROCESSOR_SCOPE, detachInstallStatements } from "../../fulfillment/assignmentStore.js";
 
 export type AppInstallStatus = "active" | "suspended" | "uninstalled";
 
@@ -558,20 +561,19 @@ export class AppRegistryService {
     const widgetPlacementsJson =
       widgetPlacements !== undefined ? JSON.stringify(widgetPlacements) : row.widget_placements;
 
-    // Retain this update as a new activation BEFORE the metadata write — after
-    // every fail-closed validation above, so a bad patch retains nothing. This
-    // captures the whole facet set at this version and, being the last write
-    // gate that can refuse (a secret-bearing facet set), keeps `update` all-or-
-    // nothing. `app_version` is NOT written here: it is the mirror, re-pointed
-    // below from the store's post-retain current version.
+    // Plan this update's new activation after every fail-closed validation above, so a
+    // bad patch retains nothing; planning is the last gate that can refuse (a
+    // secret-bearing facet set). The activation, the metadata write and the
+    // `app_version` mirror (the planned activation's version) commit in one batch.
     const facets = resolveVersionFacets({
       appVersion,
       scopes: effectiveScopes,
       manifest: patch.manifest !== undefined ? patch.manifest : (JSON.parse(row.manifest) as unknown),
       override: patch.versionFacets,
     });
+    let retained: PlannedVersionWrite;
     try {
-      await this.versionStore.retainVersion({
+      retained = await this.versionStore.planRetainVersion({
         installId,
         tenantId: row.tenant_id,
         facets,
@@ -581,27 +583,27 @@ export class AppRegistryService {
       throw this.asRegistryError(cause);
     }
 
-    await this.db.run(
-      `UPDATE app_installs
-          SET scopes = ?, manifest = ?, webhook_endpoint = ?,
-              widget_placements = ?, updated_at = ?
-        WHERE install_id = ?`,
-      scopesJson,
-      manifestJson,
-      webhookEndpoint,
-      widgetPlacementsJson,
-      now,
-      installId,
-    );
-    await this.syncActiveVersionMirror(installId);
-
-    await this.appendAudit({
-      installId,
-      tenantId: row.tenant_id,
-      event: "updated",
-      actor,
-      detail: { fields: Object.keys(patch) },
-    });
+    // An install that can no longer be notified of fulfillment work loses its assignments and
+    // processor config in the same batch as the change that descoped it.
+    const processorCapable = effectiveScopes.includes(PROCESSOR_SCOPE) && !!webhookEndpoint;
+    await this.lifecycleBatch([
+      { sql: retained.statement.sql, params: [...(retained.statement.params ?? [])] },
+      {
+        sql: `UPDATE app_installs
+            SET scopes = ?, manifest = ?, webhook_endpoint = ?,
+                widget_placements = ?, app_version = ?, updated_at = ?
+          WHERE install_id = ?`,
+        params: [scopesJson, manifestJson, webhookEndpoint, widgetPlacementsJson, retained.snapshot.appVersion, now, installId],
+      },
+      ...(processorCapable ? [] : this.detach(row.tenant_id, installId, actor)),
+      this.auditStatement({
+        installId,
+        tenantId: row.tenant_id,
+        event: "updated",
+        actor,
+        detail: { fields: Object.keys(patch) },
+      }),
+    ]);
 
     return this.getOrThrow(installId);
   }
@@ -646,8 +648,11 @@ export class AppRegistryService {
         "invalid_state",
       );
     }
-    await this.setStatus(installId, "suspended");
-    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "suspended", actor });
+    await this.lifecycleBatch([
+      this.statusStatement(installId, "suspended"),
+      ...this.detach(row.tenant_id, installId, actor),
+      this.auditStatement({ installId, tenantId: row.tenant_id, event: "suspended", actor }),
+    ]);
     return this.getOrThrow(installId);
   }
 
@@ -660,8 +665,11 @@ export class AppRegistryService {
         "invalid_state",
       );
     }
-    await this.setStatus(installId, "active");
-    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "resumed", actor });
+    // Resume restores access only; released assignments stay released until a new operator release.
+    await this.lifecycleBatch([
+      this.statusStatement(installId, "active"),
+      this.auditStatement({ installId, tenantId: row.tenant_id, event: "resumed", actor }),
+    ]);
     return this.getOrThrow(installId);
   }
 
@@ -695,13 +703,15 @@ export class AppRegistryService {
     if (row.status === "uninstalled") {
       throw new RegistryError(`Install is already uninstalled.`, "invalid_state");
     }
-    await this.db.run(
-      `UPDATE app_installs SET status = 'uninstalled', widget_placements = '[]', updated_at = ? WHERE install_id = ?`,
-      this.now(),
-      installId,
-    );
+    await this.lifecycleBatch([
+      {
+        sql: `UPDATE app_installs SET status = 'uninstalled', widget_placements = '[]', updated_at = ? WHERE install_id = ?`,
+        params: [this.now(), installId],
+      },
+      ...this.detach(row.tenant_id, installId, actor),
+      this.auditStatement({ installId, tenantId: row.tenant_id, event: "uninstalled", actor }),
+    ]);
     await this.credentials.clear(installId);
-    await this.appendAudit({ installId, tenantId: row.tenant_id, event: "uninstalled", actor });
     return this.getOrThrow(installId);
   }
 
@@ -738,10 +748,9 @@ export class AppRegistryService {
   /**
    * Re-point `app_installs.app_version` (the derived mirror) to the version
    * store's current (`MAX(seq)`) snapshot — the single reconciliation step that
-   * keeps the mirror and the source-of-truth authority from diverging. Called
-   * after every store write that can change the active version (`update`,
-   * `rollback`); `install` sets the mirror from the same resolved facet set at
-   * INSERT time, so it is already consistent there.
+   * keeps the mirror and the source-of-truth authority from diverging after a
+   * `rollback`. `install` and `update` write the mirror from the activation they
+   * commit in the same write, so they are already consistent.
    */
   private async syncActiveVersionMirror(installId: string): Promise<void> {
     const current = await this.versionStore.currentVersion(installId);
@@ -769,13 +778,24 @@ export class AppRegistryService {
     return cause;
   }
 
-  private async setStatus(installId: string, status: AppInstallStatus): Promise<void> {
-    await this.db.run(
-      `UPDATE app_installs SET status = ?, updated_at = ? WHERE install_id = ?`,
-      status,
-      this.now(),
-      installId,
-    );
+  private statusStatement(installId: string, status: AppInstallStatus): { sql: string; params: unknown[] } {
+    return {
+      sql: `UPDATE app_installs SET status = ?, updated_at = ? WHERE install_id = ?`,
+      params: [status, this.now(), installId],
+    };
+  }
+
+  private detach(tenantId: string, installId: string, actor: string): { sql: string; params: unknown[] }[] {
+    return detachInstallStatements({ tenantId, installId, actor, now: this.now() }).map((statement) => ({
+      sql: statement.sql,
+      params: [...statement.params],
+    }));
+  }
+
+  /** Lifecycle writes commit together or not at all; a handle without batch is refused before any write. */
+  private async lifecycleBatch(statements: { sql: string; params: unknown[] }[]): Promise<void> {
+    if (!this.db.batch) throw new Error("Atomic D1 batch support is required.");
+    await this.db.batch(statements);
   }
 
   private async findRowByAppTenantEnv(
@@ -809,25 +829,32 @@ export class AppRegistryService {
     return toDomain(await this.mustFindRow(installId));
   }
 
-  private async appendAudit(params: {
+  private auditStatement(params: {
     installId: string;
     tenantId: string;
     event: AppAuditEvent;
     actor: string;
     detail?: Record<string, unknown>;
     traceId?: string;
-  }): Promise<void> {
-    await this.db.run(
-      `INSERT INTO app_audit_log (id, install_id, tenant_id, event, actor, trace_id, detail, at)
+  }): { sql: string; params: unknown[] } {
+    return {
+      sql: `INSERT INTO app_audit_log (id, install_id, tenant_id, event, actor, trace_id, detail, at)
        VALUES (?,?,?,?,?,?,?,?)`,
-      crypto.randomUUID(),
-      params.installId,
-      params.tenantId,
-      params.event,
-      params.actor,
-      params.traceId ?? null,
-      JSON.stringify(params.detail ?? {}),
-      this.now(),
-    );
+      params: [
+        crypto.randomUUID(),
+        params.installId,
+        params.tenantId,
+        params.event,
+        params.actor,
+        params.traceId ?? null,
+        JSON.stringify(params.detail ?? {}),
+        this.now(),
+      ],
+    };
+  }
+
+  private async appendAudit(params: Parameters<AppRegistryService["auditStatement"]>[0]): Promise<void> {
+    const statement = this.auditStatement(params);
+    await this.db.run(statement.sql, ...statement.params);
   }
 }

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

@@ -0,0 +1,101 @@
+/**
+ * Payload admission for the commerce topics the single commerce emitter writes:
+ * `fulfillment.assignment.created`, `fulfillment.assignment.updated` and `order.fulfilled`.
+ *
+ * Each topic has a closed key set (`asyncapi.yaml` `FulfillmentAssignmentData` and `OrderData`)
+ * and every payload also passes the private-identity check. Both run when the event row is
+ * written and again before the delivery engine signs and POSTs it.
+ */
+import type { WebhookTopic } from "./deliveryStore.js";
+
+export type CommerceTopic = "fulfillment.assignment.created" | "fulfillment.assignment.updated" | "order.fulfilled";
+
+export const COMMERCE_TOPICS: readonly CommerceTopic[] = [
+  "fulfillment.assignment.created",
+  "fulfillment.assignment.updated",
+  "order.fulfilled",
+];
+
+/** Keys that identify a person or an address. None may appear at any depth of a commerce payload. */
+export const COMMERCE_PRIVATE_KEYS = new Set([
+  "customer",
+  "customerEmail",
+  "customerName",
+  "email",
+  "phone",
+  "line1",
+  "line2",
+  "city",
+  "company",
+  "postalCode",
+  "shippingAddress",
+  "billingAddress",
+  "shipTo",
+  "billTo",
+  "address",
+  "firstName",
+  "lastName",
+  "name",
+]);
+
+const ASSIGNMENT_KEYS = ["assignmentId", "orderId", "stage", "state", "eventVersion", "occurredAt"] as const;
+const ASSIGNMENT_STATES = new Set(["active", "held", "cancelled"]);
+const ORDER_DATA_KEYS = new Set(["id", "status", "currency", "customerHash", "subtotal", "total", "lineItems"]);
+const LINE_ITEM_KEYS = new Set(["sku", "handle", "quantity", "lineTotal"]);
+
+export function isCommerceTopic(topic: WebhookTopic): topic is CommerceTopic {
+  return (COMMERCE_TOPICS as readonly string[]).includes(topic);
+}
+
+export function commercePayloadHasPrivateIdentity(value: unknown): boolean {
+  if (value === null || typeof value !== "object") return false;
+  if (Array.isArray(value)) return value.some((item) => commercePayloadHasPrivateIdentity(item));
+  return Object.entries(value as Record<string, unknown>).some(
+    ([key, child]) => COMMERCE_PRIVATE_KEYS.has(key) || commercePayloadHasPrivateIdentity(child),
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= 256;
+}
+
+function assignmentAdmissible(topic: CommerceTopic, payload: Record<string, unknown>): boolean {
+  const keys = Object.keys(payload);
+  if (keys.length !== ASSIGNMENT_KEYS.length || !ASSIGNMENT_KEYS.every((key) => keys.includes(key))) return false;
+  if (!nonEmptyString(payload.assignmentId) || !nonEmptyString(payload.orderId)) return false;
+  if (payload.stage !== "preview" && payload.stage !== "publication") return false;
+  if (typeof payload.state !== "string" || !ASSIGNMENT_STATES.has(payload.state)) return false;
+  if (topic === "fulfillment.assignment.created" && payload.state !== "active") return false;
+  if (!Number.isSafeInteger(payload.eventVersion) || Number(payload.eventVersion) < 0) return false;
+  return typeof payload.occurredAt === "string" && Number.isFinite(Date.parse(payload.occurredAt));
+}
+
+function orderFulfilledAdmissible(payload: Record<string, unknown>): boolean {
+  if (Object.keys(payload).some((key) => !ORDER_DATA_KEYS.has(key))) return false;
+  if (!nonEmptyString(payload.id) || payload.status !== "fulfilled" || !nonEmptyString(payload.currency)) return false;
+  if (payload.customerHash !== undefined && typeof payload.customerHash !== "string") return false;
+  for (const key of ["subtotal", "total"] as const) {
+    if (payload[key] !== undefined && (typeof payload[key] !== "number" || !Number.isFinite(payload[key]))) return false;
+  }
+  if (payload.lineItems === undefined) return true;
+  if (!Array.isArray(payload.lineItems)) return false;
+  return payload.lineItems.every(
+    (item) =>
+      isRecord(item) &&
+      Object.keys(item).every((key) => LINE_ITEM_KEYS.has(key)) &&
+      nonEmptyString(item.sku) &&
+      Number.isSafeInteger(item.quantity) &&
+      (item.handle === undefined || typeof item.handle === "string") &&
+      (item.lineTotal === undefined || (typeof item.lineTotal === "number" && Number.isFinite(item.lineTotal))),
+  );
+}
+
+/** True when `payload` is exactly the closed shape `topic` allows and carries no private identity. */
+export function commercePayloadAdmissible(topic: CommerceTopic, payload: unknown): boolean {
+  if (!isRecord(payload) || commercePayloadHasPrivateIdentity(payload)) return false;
+  return topic === "order.fulfilled" ? orderFulfilledAdmissible(payload) : assignmentAdmissible(topic, payload);
+}

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

@@ -24,7 +24,8 @@
  */
 import { WebhookDeliveryStore, ScrappyCommerceOutbox, type CommerceOutboxDue, type WebhookDelivery, type WebhookEvent, type WebhookTopic } from "./deliveryStore.js";
 import type { AppInstall } from "../apps/registryService.js";
-import { buildCloudEventEnvelope } from "./events.js";
+import { buildCloudEventEnvelope, TOPIC_REQUIRED_SCOPE } from "./events.js";
+import { commercePayloadAdmissible, commercePayloadHasPrivateIdentity, isCommerceTopic } from "./commercePayloads.js";
 import { computeBackoffDelaySeconds, MAX_DELIVERY_ATTEMPTS, type AttemptOutcome } from "./dispatcher.js";
 import { validateWebhookEndpoint } from "./endpointGuard.js";
 import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
@@ -91,11 +92,17 @@ export class DeliveryEngineError extends Error {
  * still creates a delivery row for it), so refusing it here on status alone
  * would silently swallow every uninstall notification. It still refuses a
  * missing install or one with no endpoint, and every OTHER topic still
- * refuses a non-active (suspended/uninstalled) install exactly as before.
+ * refuses a non-active (suspended/uninstalled) install. Every topic also
+ * requires, at delivery time, that the install belongs to the delivery's
+ * tenant and still holds `TOPIC_REQUIRED_SCOPE[topic]`, so a descoped install
+ * receives nothing already queued.
  */
-function isDeadInstall(install: AppInstall | null, topic: WebhookTopic): boolean {
+function isDeadInstall(install: AppInstall | null, delivery: WebhookDelivery): boolean {
   if (!install || !install.webhookEndpoint) return true;
-  if (topic === "app.uninstalled") return false;
+  if (install.tenantId !== delivery.tenantId) return true;
+  const requiredScope = TOPIC_REQUIRED_SCOPE[delivery.topic];
+  if (requiredScope != null && !install.scopes.includes(requiredScope)) return true;
+  if (delivery.topic === "app.uninstalled") return false;
   return install.status !== "active";
 }
 
@@ -138,7 +145,7 @@ export async function attemptDelivery(deliveryId: string, deps: AttemptDeliveryD
     throw new DeliveryEngineError(`Cannot resolve install "${delivery.installId}" for delivery "${deliveryId}".`, cause);
   }
 
-  if (isDeadInstall(install, delivery.topic)) {
+  if (isDeadInstall(install, delivery)) {
     // Don't deliver to a dead/suspended install, or one with no endpoint
     // configured — no POST attempt, no recordAttempt row; go straight to the
     // one terminal-failure state the store has. This is how suspension kills
@@ -193,6 +200,11 @@ async function deliverSigned(
     return { kind: "dead-lettered", reason: "endpoint_blocked" };
   }
 
+  if (isCommerceTopic(delivery.topic) && !commercePayloadAdmissible(delivery.topic, event.payload)) {
+    await ctx.store.transitionState({ deliveryId, toState: "dead-lettered" });
+    return { kind: "dead-lettered", reason: "payload_refused" };
+  }
+
   const envelope = buildCloudEventEnvelope({
     deliveryId,
     tenantId: delivery.tenantId,
@@ -283,35 +295,6 @@ async function postWithTimeout(
 // Transport rejects private fields even when an outbox row was written outside
 // the Orders service. scrappyDurability.test.ts checks every Orders private key
 // recursively at actual retry time so the two boundary policies cannot diverge.
-const COMMERCE_PRIVATE_KEYS = new Set([
-  "customer",
-  "customerEmail",
-  "customerName",
-  "email",
-  "phone",
-  "line1",
-  "line2",
-  "city",
-  "company",
-  "postalCode",
-  "shippingAddress",
-  "billingAddress",
-  "shipTo",
-  "billTo",
-  "address",
-  "firstName",
-  "lastName",
-  "name",
-]);
-
-function commercePayloadHasPrivateIdentity(value: unknown): boolean {
-  if (value === null || typeof value !== "object") return false;
-  if (Array.isArray(value)) return value.some((item) => commercePayloadHasPrivateIdentity(item));
-  return Object.entries(value as Record<string, unknown>).some(
-    ([key, child]) => COMMERCE_PRIVATE_KEYS.has(key) || commercePayloadHasPrivateIdentity(child),
-  );
-}
-
 function publicCommercePayload(payload: string): Record<string, unknown> | null {
   let parsed: unknown;
   try {

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

@@ -40,6 +40,8 @@
  * read-after-write discipline `AppRegistryService` uses.
  */
 import type { Queryable } from "../../catalog/d1/catalog.js";
+import { TOPIC_REQUIRED_SCOPE } from "./events.js";
+import { COMMERCE_TOPICS, commercePayloadAdmissible, type CommerceTopic } from "./commercePayloads.js";
 
 /** Mirrors the `Delivery.topic` / CloudEvents channel enum in the D1/D2 contract. */
 export type WebhookTopic =
@@ -668,6 +670,134 @@ export class WebhookDeliveryStore {
   }
 }
 
+/** A commerce delivery enqueued after its commit becomes the tenant commerce alarm's only after this long. */
+export const COMMERCE_DELIVERY_GRACE_MS = 60_000;
+
+/** `asyncapi.yaml`'s `dataschemaversion` for V1. */
+export const COMMERCE_DATASCHEMA_VERSION = "1";
+
+/** Thrown before any statement is built when a commerce payload fails its topic's closed schema. */
+export class CommercePayloadRefused extends Error {
+  constructor(readonly topic: CommerceTopic) {
+    super("commerce-payload-refused");
+    this.name = "CommercePayloadRefused";
+  }
+}
+
+export interface CommerceEventStatement {
+  sql: string;
+  params: unknown[];
+}
+
+/** SQL condition an eligible install row `i` satisfies; binds the tenant id, then the topic's required scope. */
+const ELIGIBLE_INSTALL_CONDITION = `i.tenant_id = ? AND i.status = 'active' AND i.managed_kind IS NULL
+    AND COALESCE(i.webhook_endpoint, '') != ''
+    AND EXISTS (SELECT 1 FROM json_each(i.scopes) WHERE json_each.value = ?)`;
+
+/** Installs on `tenantId` that would receive `topic` now, oldest first. Statements re-check this at write. */
+export function commerceTargetsQuery(tenantId: string, topic: CommerceTopic): CommerceEventStatement {
+  return {
+    sql: `SELECT i.install_id AS install_id FROM app_installs AS i
+      WHERE ${ELIGIBLE_INSTALL_CONDITION}
+      ORDER BY i.created_at ASC, i.install_id ASC`,
+    params: [tenantId, TOPIC_REQUIRED_SCOPE[topic]],
+  };
+}
+
+/**
+ * The single commerce emitter: one `webhook_events` row written only when `gate` holds, and one
+ * pending `webhook_deliveries` row per target written only when that event row exists and the
+ * target install is still eligible. Ids are minted by the caller so the statements run inside the
+ * batch of the change they report; the delivery id is the CloudEvents `id`.
+ */
+export function commerceEventStatements(input: {
+  eventId: string;
+  tenantId: string;
+  topic: CommerceTopic;
+  payload: unknown;
+  gate: CommerceEventStatement;
+  targets: readonly { installId: string; deliveryId: string }[];
+  now: string;
+}): CommerceEventStatement[] {
+  if (!commercePayloadAdmissible(input.topic, input.payload)) throw new CommercePayloadRefused(input.topic);
+  const statements: CommerceEventStatement[] = [
+    {
+      sql: `INSERT INTO webhook_events (id, tenant_id, topic, dataschema_version, payload, created_at)
+        SELECT ?, ?, ?, ?, ?, ? WHERE (${input.gate.sql})`,
+      params: [
+        input.eventId,
+        input.tenantId,
+        input.topic,
+        COMMERCE_DATASCHEMA_VERSION,
+        JSON.stringify(input.payload),
+        input.now,
+        ...input.gate.params,
+      ],
+    },
+  ];
+  for (const target of input.targets) {
+    statements.push({
+      sql: `INSERT INTO webhook_deliveries
+          (delivery_id, event_id, install_id, tenant_id, topic, state, attempts, created_at, updated_at)
+        SELECT ?, ?, i.install_id, i.tenant_id, ?, 'pending', 0, ?, ?
+        FROM app_installs AS i
+        WHERE i.install_id = ? AND ${ELIGIBLE_INSTALL_CONDITION}
+          AND EXISTS (SELECT 1 FROM webhook_events WHERE id = ? AND tenant_id = ? AND topic = ?)`,
+      params: [
+        target.deliveryId,
+        input.eventId,
+        input.topic,
+        input.now,
+        input.now,
+        target.installId,
+        input.tenantId,
+        TOPIC_REQUIRED_SCOPE[input.topic],
+        input.eventId,
+        input.tenantId,
+        input.topic,
+      ],
+    });
+  }
+  return statements;
+}
+
+/**
+ * Commerce-topic deliveries for one tenant that the alarm owns: `pending` rows older than the
+ * enqueue grace, and `retrying` rows whose next attempt is due.
+ */
+export async function dueCommerceDeliveries(
+  db: Queryable,
+  tenantId: string,
+  now: string,
+  graceMs: number,
+): Promise<{ due: string[]; nextAt: string | null }> {
+  const cutoff = new Date(Date.parse(now) - graceMs).toISOString();
+  const topics = [...COMMERCE_TOPICS];
+  const marks = topics.map(() => "?").join(",");
+  const rows = await db.all<{ delivery_id: string }>(
+    `SELECT delivery_id FROM webhook_deliveries
+      WHERE tenant_id = ? AND topic IN (${marks})
+        AND ((state = 'pending' AND created_at <= ?) OR (state = 'retrying' AND next_attempt_at <= ?))
+      ORDER BY created_at ASC, delivery_id ASC LIMIT 100`,
+    tenantId,
+    ...topics,
+    cutoff,
+    now,
+  );
+  const next = await db.first<{ next_at: string | null }>(
+    `SELECT MIN(CASE WHEN state = 'pending' THEN strftime('%Y-%m-%dT%H:%M:%fZ', created_at, ?) ELSE next_attempt_at END) AS next_at
+       FROM webhook_deliveries
+      WHERE tenant_id = ? AND topic IN (${marks})
+        AND ((state = 'pending' AND created_at > ?) OR (state = 'retrying' AND next_attempt_at > ?))`,
+    `+${graceMs / 1000} seconds`,
+    tenantId,
+    ...topics,
+    cutoff,
+    now,
+  );
+  return { due: rows.map((row) => row.delivery_id), nextAt: next?.next_at ?? null };
+}
+
 export interface CommerceOutboxDue {
   order_id: string;
   outbox_id: string;

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

@@ -57,7 +57,7 @@ export interface WebhookDispatcher {
 export type AttemptOutcome =
   | { kind: "delivered" }
   | { kind: "retrying"; nextAttemptAt: string }
-  | { kind: "dead-lettered"; reason: "install_unavailable" | "max_attempts" | "endpoint_blocked" };
+  | { kind: "dead-lettered"; reason: "install_unavailable" | "max_attempts" | "endpoint_blocked" | "payload_refused" };
 
 /** One attempt of one delivery. Implemented by `deliveryEngine.ts`'s `attemptDelivery`, partially applied over its deps. */
 export type AttemptDeliveryFn = (deliveryId: string) => Promise<AttemptOutcome>;

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

@@ -29,6 +29,13 @@ import { COMMERCE_SCHEDULER } from "@tot/public-runtime";
 /** Binding name `getDispatcher()` checks to pick the Cloudflare Queues adapter. Not yet declared in `wrangler.toml`. */
 export const WEBHOOK_QUEUE_BINDING = "WEBHOOK_DELIVERY_QUEUE";
 
+/** The `attemptDelivery` composition every dispatcher and the commerce alarm run per delivery id. */
+export function deliveryAttemptFor(db: Queryable, activeKid: string = DEFAULT_APP_GATEWAY_KID): AttemptDeliveryFn {
+  const store = new WebhookDeliveryStore(db);
+  const registry = new AppRegistryService(db, new D1CredentialStore(db, activeKid));
+  return (deliveryId) => attemptDelivery(deliveryId, { store, registry });
+}
+
 /**
  * Build a `WebhookDispatcher` over the real `STOREFRONT_APPS_DB` binding, or
  * return a 503 `Response` when that binding isn't configured in this
@@ -39,10 +46,8 @@ export async function getDispatcher(): Promise<WebhookDispatcher | Response> {
   if (!d1) return json({ error: "webhook dispatcher not configured" }, 503);
   const db = fromD1(d1);
 
-  const store = new WebhookDeliveryStore(db);
   const activeKid = (await readEnv(APP_GATEWAY_KID_ENV)) ?? DEFAULT_APP_GATEWAY_KID;
-  const registry = new AppRegistryService(db, new D1CredentialStore(db, activeKid));
-  const attempt: AttemptDeliveryFn = (deliveryId) => attemptDelivery(deliveryId, { store, registry });
+  const attempt = deliveryAttemptFor(db, activeKid);
 
   const queueSender = (await readQueue(WEBHOOK_QUEUE_BINDING)) as CloudflareQueueSender | undefined;
   if (queueSender) return new CloudflareQueueDispatcher(queueSender);