@tokenoftrust/storefront-runner 1.4.1 → 2.0.0

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

@@ -1,10 +1,9 @@
 /**
- * Webhook event/delivery storage — PrivateApps epic, D4 (Chunk A: Storage
- * only). Owns the `webhook_events` / `webhook_deliveries` /
+ * Webhook event/delivery storage. Owns the `webhook_events` / `webhook_deliveries` /
  * `webhook_delivery_attempts` / `webhook_install_health` rows described in
- * `../d1/schema.ts`. Signing (Chunk B), the retry/backoff dispatcher
- * (Chunk C), event emission/targeting (Chunk D), and the `/webhooks/*`
- * routes (Chunk E) all build on this store; none of that policy lives here.
+ * `../d1/schema.ts`. Signing, the retry/backoff dispatcher, event
+ * emission/targeting, and the `/webhooks/*` routes all build on this store; none
+ * of that policy lives here.
  *
  * Pure over the `Queryable` seam (see `../d1/catalog.ts`) — the same shape
  * `AppRegistryService` uses, so this runs unchanged against real D1 in the
@@ -16,12 +15,12 @@
  *   - `deliveryId` (`webhook_deliveries.delivery_id`) — the CloudEvents
  *     envelope `id` for one (event × target install) delivery. This is what
  *     goes on the wire and is what receivers dedupe on; it stays stable
- *     across that delivery's own retries AND across a manual replay (Chunk
- *     E's `requeueForReplay` resets state/attempts on the SAME row rather
+ *     across that delivery's own retries AND across a manual replay
+ *     (`requeueForReplay` resets state/attempts on the SAME row rather
  *     than minting a new one — a receiver that already acked a delivered
  *     delivery must still dedupe a replayed resend of it).
  *
- * Responsibility split for the two mutating paths a dispatcher (Chunk C)
+ * Responsibility split for the two mutating paths a dispatcher
  * drives per attempt:
  *   - `recordAttempt` is dumb bookkeeping of ONE HTTP attempt's outcome: it
  *     appends to `webhook_delivery_attempts`, bumps the delivery's
@@ -117,7 +116,7 @@ export interface CreateEventResult {
 
 export interface ListDeliveriesOptions {
   state?: DeliveryState;
-  /** Cap the result, newest first. Used internally by {@link WebhookDeliveryStore.getInstallHealth} to bound its p95 sample; unset means unbounded (the historical behavior). */
+  /** Cap the result, newest first. Used internally by {@link WebhookDeliveryStore.getInstallHealth} to bound its p95 sample; unset means unbounded. */
   limit?: number;
 }
 
@@ -165,8 +164,8 @@ const MAX_RECENT_TRACE_IDS = 10;
 const P95_SAMPLE_SIZE = 50;
 
 // A delivery only ever moves forward via `transitionState`; `delivered`/
-// `dead-lettered` are terminal THERE. A manual replay (Chunk E's
-// `requeueForReplay`) is the one deliberate exception: it resets a delivery
+// `dead-lettered` are terminal THERE. A manual replay (`requeueForReplay`)
+// is the one deliberate exception: it resets a delivery
 // out of a terminal state back to `pending` on the SAME row, bypassing this
 // table entirely — see that method's own doc comment for why.
 const ALLOWED_TRANSITIONS: Record<DeliveryState, readonly DeliveryState[]> = {
@@ -287,7 +286,7 @@ export class WebhookDeliveryStore {
   /**
    * Write one immutable event, then fan it out to one `pending` delivery per
    * target install. Targeting (which installs get the event) is the caller's
-   * job (Chunk D) — this just persists whatever target list it's handed.
+   * job — this just persists whatever target list it's handed.
    */
   async createEvent(input: CreateEventInput, targets: readonly DeliveryTarget[]): Promise<CreateEventResult> {
     const eventId = input.eventId ?? crypto.randomUUID();
@@ -345,8 +344,8 @@ export class WebhookDeliveryStore {
   }
 
   /**
-   * Read one event by id, or `null` if it doesn't exist. Added for the
-   * dispatcher/delivery engine (Chunk C): `attemptDelivery` resolves a
+   * Read one event by id, or `null` if it doesn't exist. The dispatcher/delivery
+   * engine uses it: `attemptDelivery` resolves a
    * delivery's `eventId` via `getDelivery`, then needs this to fetch the
    * `payload`/`dataschemaVersion` that only `webhook_events` (not
    * `webhook_deliveries`) carries, in order to build the CloudEvents
@@ -381,7 +380,7 @@ export class WebhookDeliveryStore {
    * All deliveries for a tenant, across every install (the ops/support admin
    * view — an install only ever sees its OWN deliveries via
    * {@link listDeliveriesByInstall}; this is the tenant-wide superset), newest
-   * first. Added for D4 Chunk E's admin route; Chunk A/B/C never call this.
+   * first.
    */
   async listDeliveriesByTenant(
     tenantId: string,
@@ -443,7 +442,7 @@ export class WebhookDeliveryStore {
 
   /**
    * Move a delivery's `state` forward per `ALLOWED_TRANSITIONS`. The
-   * caller (Chunk C's dispatcher) decides WHEN to retry vs. give up; this
+   * caller (the dispatcher) decides WHEN to retry vs. give up; this
    * only records that decision. Dead-lettering bumps the install's
    * `dlqCount` — the one rollup field {@link recordAttempt} doesn't own.
    */
@@ -478,7 +477,7 @@ export class WebhookDeliveryStore {
   }
 
   /**
-   * D4 Chunk E's replay support: force a delivery back to `pending` with a
+   * Replay support: force a delivery back to `pending` with a
    * fresh attempt budget — from ANY current state, INCLUDING the terminal
    * `delivered`/`dead-lettered` states `transitionState`/`ALLOWED_TRANSITIONS`
    * refuse to leave. This is deliberately a separate write path, not a call