@cosmicdrift/kumiko-bundled-features 0.100.0 → 0.102.1

package/src/delivery/channel-context.ts

@@ -0,0 +1,17 @@
+import type { SseBroker } from "@cosmicdrift/kumiko-framework/api";
+import { createTenantDb, type DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import type { ChannelContext } from "./types";
+
+// Build the per-tenant context a channel's resolve/render/send receives.
+// Shared by the synchronous delivery-service path and the async job handlers
+// (which pass sseBroker=undefined — only the inline inApp channel uses SSE,
+// and it never runs through a job).
+export function buildChannelContext(
+  db: DbConnection,
+  registry: Registry,
+  sseBroker: SseBroker | undefined,
+  tenantId: TenantId,
+): ChannelContext {
+  return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId };
+}

package/src/delivery/constants.ts

@@ -1,6 +1,18 @@
+import type { NotifyPriority } from "@cosmicdrift/kumiko-framework/engine";
+import { QnTypes, qn } from "@cosmicdrift/kumiko-framework/engine";
+
 // Feature name
 export const DELIVERY_FEATURE = "delivery" as const;
 
+// notify() priority → BullMQ job priority. Lower number = processed first; all
+// > 0 so prioritised delivery jobs never mix with BullMQ's "0 = unprioritised
+// FIFO" bucket. critical jobs jump ahead of normal/low in the worker queue.
+export const deliveryPriorityRank: Record<NotifyPriority, number> = {
+  critical: 1,
+  normal: 2,
+  low: 3,
+};
+
 // Qualified write handler names (QN format: scope:type:name)
 export const DeliveryHandlers = {
   setPreference: "delivery:write:set-preference",
@@ -18,8 +30,12 @@ export const DeliveryErrors = {
   channelFailed: "delivery_channel_failed",
 } as const;
 
-// Delivery status values
+// Delivery status values. `queued` is the initial state of an async attempt
+// (email/push) between dispatch and the worker running — it transitions to
+// sent/failed once the delivery.send job finishes. Synchronous attempts
+// (inApp, skips) never observe `queued`.
 export const DeliveryStatus = {
+  queued: "queued",
   sent: "sent",
   failed: "failed",
   skipped: "skipped",
@@ -31,3 +47,21 @@ export type DeliveryStatusValue = (typeof DeliveryStatus)[keyof typeof DeliveryS
 // attempt (sent / failed / skipped). A multi-stream-projection materialises
 // each event into a row in deliveryAttemptsTable for the log-query handler.
 export const DELIVERY_ATTEMPT_EVENT = "delivery:event:attempt" as const;
+
+// Background jobs that carry async (queued-mode) channels. render decouples the
+// expensive template step from the send so each retries independently; render
+// dispatches send on success. Channels without a render() (push) skip straight
+// to send.
+//
+// Short names are what r.job() registers; the registry qualifies them to
+// `scope:job:name`. Dispatch (notify + render→send chaining) must use the
+// QUALIFIED name, so DeliveryJobs holds the qualified form via qn().
+export const DeliveryJobNames = {
+  render: "render",
+  send: "send",
+} as const;
+
+export const DeliveryJobs = {
+  render: qn(DELIVERY_FEATURE, QnTypes.job, DeliveryJobNames.render),
+  send: qn(DELIVERY_FEATURE, QnTypes.job, DeliveryJobNames.send),
+} as const;

package/src/delivery/delivery-service.ts

@@ -3,14 +3,14 @@ import type { DbConnection, DbRow } from "@cosmicdrift/kumiko-framework/db";
 import { createTenantDb } from "@cosmicdrift/kumiko-framework/db";
 import type { NotifyPriority, Registry, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { createSystemUser } from "@cosmicdrift/kumiko-framework/engine";
-import { append } from "@cosmicdrift/kumiko-framework/event-store";
-import { runProjectionsForEvent } from "@cosmicdrift/kumiko-framework/pipeline";
+import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import { bridgeStub } from "@cosmicdrift/kumiko-framework/testing/handler-context";
 import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import type { Redis } from "ioredis";
-import { DELIVERY_ATTEMPT_EVENT } from "./constants";
+import { appendAttemptEvent, logAttempt } from "./attempt-log";
+import { buildChannelContext } from "./channel-context";
+import { DeliveryJobs, deliveryPriorityRank } from "./constants";
 import { selectNotificationPreferences } from "./db/queries/preferences";
-import { deliveryAttemptSchema } from "./events";
 import type {
   ChannelContext,
   ChannelMessage,
@@ -39,6 +39,10 @@ export type DeliveryServiceOptions = {
   // Must be present whenever callers rely on idempotencyKey, otherwise notify()
   // throws at the callsite (silent no-op would be a correctness bug).
   readonly idempotencyRedis?: Redis;
+  // Job runner for async (queued-mode) channels: email/push render+send run in
+  // the delivery.render → delivery.send jobs. When absent, queued channels fall
+  // back to synchronous inline delivery (job-less setups, unit tests).
+  readonly jobRunner?: JobRunner;
 };
 
 // Build channel list from registry extension usages
@@ -47,10 +51,18 @@ export function collectChannels(registry: Registry): DeliveryChannel[] {
   return usages.map((usage) => {
     // @cast-boundary engine-payload — extension-usage carries unknown options
     const opts = usage.options as {
+      mode: DeliveryChannel["mode"];
       resolve: DeliveryChannel["resolve"];
+      render?: DeliveryChannel["render"];
       send: DeliveryChannel["send"];
     };
-    return { name: usage.entityName, resolve: opts.resolve, send: opts.send };
+    return {
+      name: usage.entityName,
+      mode: opts.mode,
+      resolve: opts.resolve,
+      render: opts.render,
+      send: opts.send,
+    };
   });
 }
 
@@ -69,6 +81,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     rateLimit,
     isChannelKilled,
     idempotencyRedis,
+    jobRunner,
   } = options;
   const idemRedis = idempotencyRedis ?? rateLimit?.redis;
 
@@ -152,34 +165,83 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     )) as readonly string[];
   }
 
-  function buildChannelContext(tenantId: TenantId): ChannelContext {
-    return { db: createTenantDb(db, tenantId), registry, sseBroker, tenantId };
+  // Single-shot terminal log (inline channels, skips, idempotency dups). Async
+  // attempts instead append a queued event up front and a terminal event from
+  // the send job — see deliverViaChannel + jobs.ts.
+  async function logDelivery(entry: DeliveryLogEntry): Promise<void> {
+    await logAttempt(db, registry, entry);
   }
 
-  async function logDelivery(entry: DeliveryLogEntry): Promise<void> {
-    // Post-ES: each delivery attempt is a standalone event on its own
-    // aggregate stream (fresh UUID per attempt). The `delivery-log` inline
-    // projection materialises the same row shape into deliveryAttemptsTable.
-    // Low-level append() does NOT auto-fire inline projections (only the
-    // dispatcher / executor / ctx.appendEvent paths do), so we invoke
-    // runProjectionsForEvent manually to keep the write synchronous with
-    // the projection update — same TX, read-your-own-write semantics.
-    const attemptId = generateId();
-    const { tenantId, ...rest } = entry;
-    // Schema-parse to match ctx.appendEvent's guarantee: a payload drift
-    // between service + feature-registration fails loudly here instead of
-    // landing on the events-table and crashing a consumer later.
-    const payload = deliveryAttemptSchema.parse(rest);
-    const stored = await append(db, {
-      aggregateId: attemptId,
-      aggregateType: "deliveryAttempt",
+  // Deliver one resolved (channel, address) pair. Inline channels (inApp) and
+  // the no-job-runner fallback render + send synchronously and log the terminal
+  // status. Queued channels (email/push) record a `queued` attempt up front and
+  // hand off to the delivery.render (or delivery.send) job, which appends the
+  // terminal event on the same attempt stream.
+  async function deliverViaChannel(args: {
+    channel: DeliveryChannel;
+    address: string;
+    message: ChannelMessage;
+    channelCtx: ChannelContext;
+    tenantId: TenantId;
+    recipientId: string | null;
+    notificationType: string;
+    priority: NotifyPriority;
+  }): Promise<void> {
+    const {
+      channel,
+      address,
+      message,
+      channelCtx,
       tenantId,
-      expectedVersion: 0,
-      type: DELIVERY_ATTEMPT_EVENT,
-      payload,
-      metadata: { userId: "system" },
-    });
-    await runProjectionsForEvent(stored, registry, db);
+      recipientId,
+      notificationType,
+      priority,
+    } = args;
+
+    if (channel.mode === "queued" && jobRunner) {
+      // Async hand-off: record the attempt as queued, then dispatch the
+      // render/send job — the terminal sent/failed event is appended by the
+      // job, not here.
+      const deliveryAttemptId = generateId();
+      await appendAttemptEvent(db, registry, deliveryAttemptId, {
+        tenantId,
+        notificationType,
+        channel: channel.name,
+        recipientId,
+        recipientAddress: address,
+        status: "queued",
+        error: null,
+        priority,
+      });
+      await jobRunner.dispatch(
+        channel.render ? DeliveryJobs.render : DeliveryJobs.send,
+        {
+          channelName: channel.name,
+          address,
+          tenantId,
+          recipientId,
+          notificationType,
+          deliveryAttemptId,
+          priority,
+          message,
+        },
+        { priority: deliveryPriorityRank[priority] },
+      );
+    } else {
+      // Inline (inApp) or no-job-runner fallback: render + send synchronously.
+      const rendered = channel.render ? await channel.render(message, channelCtx) : undefined;
+      const result = await channel.send(address, message, channelCtx, rendered);
+      await logDelivery({
+        tenantId,
+        notificationType,
+        channel: channel.name,
+        recipientId,
+        recipientAddress: result.address ?? address,
+        status: result.status,
+        error: result.error ?? null,
+        priority,
+      });
+    }
   }
 
   function buildMessage(
@@ -254,7 +316,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     tenantId: TenantId,
     priority: NotifyPriority,
   ): Promise<void> {
-    const channelCtx = buildChannelContext(tenantId);
+    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
 
     for (const channel of channels) {
       const message = buildMessage(notificationType, data, channel.name);
@@ -271,6 +333,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             recipientAddress: null,
             status: "skipped",
             error: "channel_disabled",
+            priority,
           });
           continue;
         }
@@ -288,6 +351,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             recipientAddress: null,
             status: "skipped",
             error: "preference_disabled",
+            priority,
           });
           continue;
         }
@@ -305,6 +369,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             recipientAddress: null,
             status: "skipped",
             error: "rate_limited",
+            priority,
           });
           continue;
         }
@@ -321,19 +386,20 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             recipientAddress: null,
             status: "skipped",
             error: "no_address",
+            priority,
           });
           continue;
         }
 
-        const result = await channel.send(address, message, channelCtx);
-        await logDelivery({
+        await deliverViaChannel({
+          channel,
+          address,
+          message,
+          channelCtx,
           tenantId,
-          notificationType,
-          channel: channel.name,
           recipientId: userId,
-          recipientAddress: result.address ?? address,
-          status: result.status,
-          error: result.error ?? null,
+          notificationType,
+          priority,
         });
       } catch (err) {
         await logDelivery({
@@ -344,6 +410,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           recipientAddress: null,
           status: "failed",
           error: err instanceof Error ? err.message : String(err),
+          priority,
         });
       }
     }
@@ -354,8 +421,9 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
     notificationType: string,
     data: Readonly<Record<string, unknown>> | undefined,
     tenantId: TenantId,
+    priority: NotifyPriority,
   ): Promise<void> {
-    const channelCtx = buildChannelContext(tenantId);
+    const channelCtx = buildChannelContext(db, registry, sseBroker, tenantId);
 
     // Direct routing skips preferences (no user account) but NOT rate limit
     // — direct sends can still be abused (webhook replays, test harnesses).
@@ -375,21 +443,22 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             recipientAddress: address,
             status: "skipped",
             error: "rate_limited",
+            priority,
           });
           continue;
         }
       }
 
       try {
-        const result = await channel.send(address, message, channelCtx);
-        await logDelivery({
+        await deliverViaChannel({
+          channel,
+          address,
+          message,
+          channelCtx,
           tenantId,
-          notificationType,
-          channel: channel.name,
           recipientId: null,
-          recipientAddress: result.address ?? address,
-          status: result.status,
-          error: result.error ?? null,
+          notificationType,
+          priority,
         });
       } catch (err) {
         await logDelivery({
@@ -400,6 +469,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
           recipientAddress: address,
           status: "failed",
           error: err instanceof Error ? err.message : String(err),
+          priority,
         });
       }
     }
@@ -421,6 +491,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
             recipientAddress: null,
             status: "skipped",
             error: "duplicate_idempotency_key",
+            priority,
           });
           // skip: duplicate send deduped via idempotency key, logged above
           return;
@@ -428,7 +499,7 @@ export function createDeliveryService(options: DeliveryServiceOptions): Delivery
       }
 
       if (route) {
-        await deliverDirect(route, notificationType, data, tenantId);
+        await deliverDirect(route, notificationType, data, tenantId, priority);
         // skip: direct route delivered, no recipient resolution needed
         return;
       }

package/src/delivery/events.ts

@@ -11,8 +11,14 @@ export const deliveryAttemptSchema = z.object({
   channel: z.string(),
   recipientId: z.string().nullable(),
   recipientAddress: z.string().nullable(),
-  status: z.enum([DeliveryStatus.sent, DeliveryStatus.failed, DeliveryStatus.skipped]),
+  status: z.enum([
+    DeliveryStatus.queued,
+    DeliveryStatus.sent,
+    DeliveryStatus.failed,
+    DeliveryStatus.skipped,
+  ]),
   error: z.string().nullable(),
+  priority: z.enum(["critical", "normal", "low"]),
 });
 
 export type DeliveryAttemptPayload = z.infer<typeof deliveryAttemptSchema>;

package/src/delivery/feature.ts

@@ -1,11 +1,12 @@
-import { insertOne } from "@cosmicdrift/kumiko-framework/bun-db";
+import { upsertByPk } from "@cosmicdrift/kumiko-framework/bun-db";
 import { defineFeature, type FeatureDefinition } from "@cosmicdrift/kumiko-framework/engine";
 import type { z } from "zod";
-import { DELIVERY_ATTEMPT_EVENT } from "./constants";
+import { DELIVERY_ATTEMPT_EVENT, DeliveryJobNames } from "./constants";
 import { deliveryAttemptSchema } from "./events";
 import { logQuery } from "./handlers/log.query";
 import { preferencesQuery } from "./handlers/preferences.query";
 import { setPreferenceWrite } from "./handlers/set-preference.write";
+import { deliveryRenderJob, deliverySendJob } from "./jobs";
 import {
   deliveryAttemptsTable,
   deliveryAttemptsTableMeta,
@@ -54,18 +55,26 @@ export function createDeliveryFeature(): FeatureDefinition {
       apply: {
         [DELIVERY_ATTEMPT_EVENT]: async (event, tx) => {
           const p = event.payload as z.infer<typeof deliveryAttemptSchema>; // @cast-boundary engine-payload
-          // PK = aggregateId — replaying the same event twice conflicts on
-          // the PK rather than silently duplicating the log row.
-          await insertOne(tx, deliveryAttemptsTable, {
-            id: event.aggregateId,
-            tenantId: event.tenantId,
-            notificationType: p.notificationType,
-            channel: p.channel,
-            recipientId: p.recipientId,
-            recipientAddress: p.recipientAddress,
-            status: p.status,
-            error: p.error,
-          });
+          // PK = aggregateId. An async attempt accrues multiple events on one
+          // stream (queued → sent/failed): the first INSERTs, later events
+          // UPDATE the same row. Events arrive in version order, so the last
+          // status wins; replays stay idempotent (same row, same values).
+          await upsertByPk(
+            tx,
+            deliveryAttemptsTable,
+            {
+              id: event.aggregateId,
+              tenantId: event.tenantId,
+              notificationType: p.notificationType,
+              channel: p.channel,
+              recipientId: p.recipientId,
+              recipientAddress: p.recipientAddress,
+              status: p.status,
+              error: p.error,
+              priority: p.priority,
+            },
+            { status: p.status, error: p.error, recipientAddress: p.recipientAddress },
+          );
         },
       },
     });
@@ -80,6 +89,21 @@ export function createDeliveryFeature(): FeatureDefinition {
       onRegister: () => {},
     });
 
+    // Async delivery pipeline for queued-mode channels. render decouples the
+    // expensive template step (own worker, own retry) and dispatches send;
+    // channels without a render() go straight to send. Dispatched explicitly
+    // from the delivery-service, hence manual trigger.
+    r.job(
+      DeliveryJobNames.render,
+      { trigger: { manual: true }, retries: 3, backoff: "exponential" },
+      deliveryRenderJob,
+    );
+    r.job(
+      DeliveryJobNames.send,
+      { trigger: { manual: true }, retries: 3, backoff: "exponential" },
+      deliverySendJob,
+    );
+
     const handlers = {
       setPreference: r.writeHandler(setPreferenceWrite),
     };

package/src/delivery/index.ts

@@ -3,6 +3,7 @@ export {
   DELIVERY_FEATURE,
   DeliveryErrors,
   DeliveryHandlers,
+  DeliveryJobs,
   DeliveryQueries,
   DeliveryStatus,
 } from "./constants";
@@ -21,9 +22,11 @@ export type {
   ChannelMessage,
   ChannelResult,
   DeliveryChannel,
+  DeliveryChannelMode,
   DeliveryLogEntry,
   DeliveryService,
   NotificationRenderer,
+  RenderedMessage,
   RendererInput,
 } from "./types";
 export {

package/src/delivery/jobs.ts

@@ -0,0 +1,153 @@
+// delivery.render → delivery.send job handlers. Async (queued-mode) channels
+// are delivered here instead of inline in notify(): render runs the expensive
+// template step in its own worker and dispatches send on success, so a render
+// crash never blocks the SMTP send and each step retries independently. The
+// `queued` attempt event is written by the delivery-service at dispatch time;
+// these handlers append the terminal sent/failed event on the same stream.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type {
+  AppContext,
+  JobHandlerFn,
+  Registry,
+  TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import type { JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
+import { z } from "zod";
+import { appendAttemptEvent } from "./attempt-log";
+import { buildChannelContext } from "./channel-context";
+import { DeliveryJobs, deliveryPriorityRank } from "./constants";
+import { collectChannels } from "./delivery-service";
+import type { ChannelMessage, DeliveryChannel, DeliveryLogEntry, RenderedMessage } from "./types";
+
+const channelMessageSchema = z.object({
+  notificationType: z.string(),
+  title: z.string(),
+  body: z.string().optional(),
+  data: z.record(z.string(), z.unknown()).optional(),
+});
+
+const renderJobPayloadSchema = z.object({
+  channelName: z.string(),
+  address: z.string(),
+  tenantId: z.string(),
+  recipientId: z.string().nullable(),
+  notificationType: z.string(),
+  deliveryAttemptId: z.string(),
+  priority: z.enum(["critical", "normal", "low"]),
+  message: channelMessageSchema,
+});
+
+const sendJobPayloadSchema = renderJobPayloadSchema.extend({
+  rendered: z.object({ html: z.string(), subject: z.string() }).optional(),
+});
+
+type RenderJobPayload = z.infer<typeof renderJobPayloadSchema>;
+
+function requireDeps(ctx: AppContext): { db: DbConnection; registry: Registry } {
+  const registry = ctx.registry;
+  if (!registry) throw new Error("delivery job: missing registry in job context");
+  // Job context provides the raw system connection (not tenant-scoped); the
+  // append + projection layer scopes per event payload.
+  const db = ctx.db as DbConnection; // @cast-boundary engine-bridge — job ctx db is the system connection
+  if (!db) throw new Error("delivery job: missing db in job context");
+  return { db, registry };
+}
+
+function resolveChannel(registry: Registry, name: string): DeliveryChannel {
+  const channel = collectChannels(registry).find((c) => c.name === name);
+  if (!channel) throw new Error(`delivery job: unknown channel "${name}"`);
+  return channel;
+}
+
+function toMessage(p: RenderJobPayload): ChannelMessage {
+  return {
+    notificationType: p.message.notificationType,
+    title: p.message.title,
+    body: p.message.body,
+    data: p.message.data,
+  };
+}
+
+function entryFor(
+  p: RenderJobPayload,
+  status: DeliveryLogEntry["status"],
+  error: string | null,
+  address: string | null,
+): DeliveryLogEntry {
+  return {
+    tenantId: p.tenantId as TenantId, // @cast-boundary engine-payload — job payload string is the stream tenant
+    notificationType: p.notificationType,
+    channel: p.channelName,
+    recipientId: p.recipientId,
+    recipientAddress: address,
+    status,
+    error,
+    priority: p.priority,
+  };
+}
+
+function messageOf(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// Render the message and hand off to delivery.send. On failure: record the
+// terminal failed event and rethrow so BullMQ retries this step (re-render);
+// the send step is never reached, so a stuck render can't half-send.
+export const deliveryRenderJob: JobHandlerFn = async (payload, ctx) => {
+  const p = renderJobPayloadSchema.parse(payload);
+  const { db, registry } = requireDeps(ctx);
+  const channel = resolveChannel(registry, p.channelName);
+  const tenantId = p.tenantId as TenantId; // @cast-boundary engine-payload — stream tenant
+  const channelCtx = buildChannelContext(db, registry, undefined, tenantId);
+
+  try {
+    if (!channel.render) {
+      throw new Error(`delivery.render: channel "${p.channelName}" has no render step`);
+    }
+    const rendered: RenderedMessage = await channel.render(toMessage(p), channelCtx);
+    const jobRunner = ctx["jobRunner"] as JobRunner; // @cast-boundary dynamic-key — dispatch lives on the concrete runner
+    await jobRunner.dispatch(
+      DeliveryJobs.send,
+      { ...p, rendered },
+      { priority: deliveryPriorityRank[p.priority] },
+    );
+  } catch (err) {
+    await appendAttemptEvent(
+      db,
+      registry,
+      p.deliveryAttemptId,
+      entryFor(p, "failed", `render: ${messageOf(err)}`, p.address),
+    );
+    throw err;
+  }
+};
+
+// Deliver via the channel using the rendered payload (if any). On failure:
+// record the terminal failed event and rethrow so BullMQ retries the send with
+// the same already-rendered HTML — no re-render needed.
+export const deliverySendJob: JobHandlerFn = async (payload, ctx) => {
+  const p = sendJobPayloadSchema.parse(payload);
+  const { db, registry } = requireDeps(ctx);
+  const channel = resolveChannel(registry, p.channelName);
+  const tenantId = p.tenantId as TenantId; // @cast-boundary engine-payload — stream tenant
+  const channelCtx = buildChannelContext(db, registry, undefined, tenantId);
+
+  try {
+    const result = await channel.send(p.address, toMessage(p), channelCtx, p.rendered);
+    await appendAttemptEvent(
+      db,
+      registry,
+      p.deliveryAttemptId,
+      entryFor(p, result.status, result.error ?? null, result.address ?? p.address),
+    );
+  } catch (err) {
+    await appendAttemptEvent(
+      db,
+      registry,
+      p.deliveryAttemptId,
+      entryFor(p, "failed", `send: ${messageOf(err)}`, p.address),
+    );
+    throw err;
+  }
+};

package/src/delivery/tables.ts

@@ -36,8 +36,11 @@ export const deliveryAttemptsTable = pgTable("read_delivery_attempts", {
   // User-IDs as UUID-strings post-ES migration.
   recipientId: text("recipient_id"),
   recipientAddress: text("recipient_address"),
-  status: text("status").notNull().$type<"sent" | "failed" | "skipped">(),
+  status: text("status").notNull().$type<"queued" | "sent" | "failed" | "skipped">(),
   error: text("error"),
+  // Default covers rows that predate the column; new rows always carry the
+  // notify() priority from the event payload.
+  priority: text("priority").notNull().default("normal").$type<"critical" | "normal" | "low">(),
   createdAt: instant("created_at").default(sql`now()`).notNull(),
 });
 
@@ -60,6 +63,7 @@ export const deliveryAttemptsTableMeta: EntityTableMeta = defineUnmanagedTable({
     { name: "recipient_address", pgType: "text", notNull: false },
     { name: "status", pgType: "text", notNull: true },
     { name: "error", pgType: "text", notNull: false },
+    { name: "priority", pgType: "text", notNull: true, defaultSql: "'normal'" },
     { name: "created_at", pgType: "timestamptz", notNull: true, defaultSql: "now()" },
   ],
 });