@cosmicdrift/kumiko-bundled-features 0.100.0 → 0.102.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.100.0",
+  "version": "0.102.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -73,6 +73,7 @@
     "./renderer-simple": "./src/renderer-simple/index.ts",
     "./files-provider-s3": "./src/files-provider-s3/index.ts",
     "./rate-limiting": "./src/rate-limiting/index.ts",
+    "./presets": "./src/presets/index.ts",
     "./secrets": "./src/secrets/index.ts",
     "./sessions": "./src/sessions/index.ts",
     "./sessions/testing": "./src/sessions/testing.ts",
@@ -91,11 +92,11 @@
     "./step-dispatcher": "./src/step-dispatcher/index.ts"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.100.0",
-    "@cosmicdrift/kumiko-framework": "0.100.0",
-    "@cosmicdrift/kumiko-headless": "0.100.0",
-    "@cosmicdrift/kumiko-renderer": "0.100.0",
-    "@cosmicdrift/kumiko-renderer-web": "0.100.0",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.102.0",
+    "@cosmicdrift/kumiko-framework": "0.102.0",
+    "@cosmicdrift/kumiko-headless": "0.102.0",
+    "@cosmicdrift/kumiko-renderer": "0.102.0",
+    "@cosmicdrift/kumiko-renderer-web": "0.102.0",
     "@mollie/api-client": "^4.5.0",
     "@node-rs/argon2": "^2.0.2",
     "@types/nodemailer": "^8.0.0",

package/src/auth-email-password/auth-mailer.ts

@@ -56,20 +56,35 @@ export type AuthMailerConfig = {
   };
 };
 
+/** Pfad-Konstanten der 4 Auth-Seiten (relativ zur App-baseUrl). */
+export type AuthPaths = {
+  readonly resetPassword: string;
+  readonly verifyEmail: string;
+  readonly signupComplete: string;
+  readonly inviteAccept: string;
+};
+
+/** Konventions-Pfade — alle Kumiko-Apps nutzen dieselben. Apps überschreiben
+ *  nur die Ausnahme via `makeAuthPaths({ ... })`. */
+export const DEFAULT_AUTH_PATHS: AuthPaths = {
+  resetPassword: "/reset-password",
+  verifyEmail: "/verify-email",
+  signupComplete: "/signup/complete",
+  inviteAccept: "/invite/accept",
+};
+
+export function makeAuthPaths(overrides: Partial<AuthPaths> = {}): AuthPaths {
+  return { ...DEFAULT_AUTH_PATHS, ...overrides };
+}
+
 export type CreateAuthMailerConfigArgs = {
   readonly mailSender: EmailTransport;
   readonly hmacSecret: string;
   /** Basis-URL der App inkl. Schema (z.B. "https://admin.example.com").
    *  Die factory hängt paths.resetPassword etc. an. */
   readonly baseUrl: string;
-  /** Pfad-Konstanten für die Auth-Seiten — jede App hat ihre eigenen
-   *  in `./auth-paths.ts`. */
-  readonly paths: {
-    readonly resetPassword: string;
-    readonly verifyEmail: string;
-    readonly signupComplete: string;
-    readonly inviteAccept: string;
-  };
+  /** Pfad-Konstanten für die Auth-Seiten. Default: DEFAULT_AUTH_PATHS. */
+  readonly paths?: AuthPaths;
   /** App-Name für Mail-Subject + Body. Default "Account". */
   readonly appName?: string;
   /** Locale für die Mail-Templates. Default "de". */
@@ -91,10 +106,11 @@ export type CreateAuthMailerConfigArgs = {
 export function createAuthMailerConfig(args: CreateAuthMailerConfigArgs): AuthMailerConfig {
   const appName = args.appName ?? "Account";
   const locale = args.locale ?? "de";
+  const paths = args.paths ?? DEFAULT_AUTH_PATHS;
   return {
     passwordReset: {
       hmacSecret: args.hmacSecret,
-      appResetUrl: `${args.baseUrl}${args.paths.resetPassword}`,
+      appResetUrl: `${args.baseUrl}${paths.resetPassword}`,
       sendResetEmail: async ({ email, resetUrl, expiresAt }) => {
         await args.mailSender.send({
           to: email,
@@ -107,7 +123,7 @@ export function createAuthMailerConfig(args: CreateAuthMailerConfigArgs): AuthMa
       ...(args.emailVerificationMode !== undefined && {
         mode: args.emailVerificationMode,
       }),
-      appVerifyUrl: `${args.baseUrl}${args.paths.verifyEmail}`,
+      appVerifyUrl: `${args.baseUrl}${paths.verifyEmail}`,
       sendVerificationEmail: async ({ email, verificationUrl, expiresAt }) => {
         await args.mailSender.send({
           to: email,
@@ -116,7 +132,7 @@ export function createAuthMailerConfig(args: CreateAuthMailerConfigArgs): AuthMa
       },
     },
     signup: {
-      appActivationUrl: `${args.baseUrl}${args.paths.signupComplete}`,
+      appActivationUrl: `${args.baseUrl}${paths.signupComplete}`,
       sendActivationEmail: async ({ email, activationUrl, expiresAt }) => {
         await args.mailSender.send({
           to: email,
@@ -125,7 +141,7 @@ export function createAuthMailerConfig(args: CreateAuthMailerConfigArgs): AuthMa
       },
     },
     invite: {
-      appAcceptUrl: `${args.baseUrl}${args.paths.inviteAccept}`,
+      appAcceptUrl: `${args.baseUrl}${paths.inviteAccept}`,
       sendInviteEmail: async ({ email, inviteUrl, expiresAt, role }) => {
         await args.mailSender.send({
           to: email,

package/src/auth-email-password/index.ts

@@ -4,8 +4,11 @@
 // und solon (jede App hatte identische send*Email-Wrapper kopiert).
 export {
   type AuthMailerConfig,
+  type AuthPaths,
   type CreateAuthMailerConfigArgs,
   createAuthMailerConfig,
+  DEFAULT_AUTH_PATHS,
+  makeAuthPaths,
 } from "./auth-mailer";
 export { AUTH_EMAIL_PASSWORD_FEATURE, AuthErrors, AuthHandlers } from "./constants";
 // Default-HTML-Renderer für die Reset-Password + Verify-Email Mails.

package/src/channel-email/__tests__/smtp-transport-from-env.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+import { createSmtpTransportFromEnv } from "../smtp-transport";
+
+describe("createSmtpTransportFromEnv", () => {
+  test("no SMTP_HOST → null (no-mail, not crash)", () => {
+    expect(createSmtpTransportFromEnv({}, { fallbackFrom: "x@y.z" })).toBeNull();
+    expect(
+      createSmtpTransportFromEnv(
+        { SMTP_USER: "u", SMTP_PASS: "p", SMTP_FROM: "a@b.c" },
+        { fallbackFrom: "x@y.z" },
+      ),
+    ).toBeNull();
+  });
+
+  test("host present → transport with send()", () => {
+    const t = createSmtpTransportFromEnv({ SMTP_HOST: "localhost" }, { fallbackFrom: "x@y.z" });
+    expect(t).not.toBeNull();
+    expect(typeof t?.send).toBe("function");
+  });
+
+  test("full env (port coercion + auth) builds without throwing", () => {
+    const t = createSmtpTransportFromEnv(
+      {
+        SMTP_HOST: "smtp.example.com",
+        SMTP_PORT: "465",
+        SMTP_SECURE: "true",
+        SMTP_USER: "user",
+        SMTP_PASS: "pass",
+        SMTP_FROM: "App <noreply@example.com>",
+      },
+      { fallbackFrom: "x@y.z" },
+    );
+    expect(typeof t?.send).toBe("function");
+  });
+});

package/src/channel-email/email-channel.ts

@@ -1,6 +1,11 @@
 import type { DbRow } from "@cosmicdrift/kumiko-framework/db";
 import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
-import type { DeliveryChannel, NotificationRenderer } from "../delivery";
+import type {
+  ChannelMessage,
+  DeliveryChannel,
+  NotificationRenderer,
+  RenderedMessage,
+} from "../delivery";
 import type { EmailTransport } from "./types";
 
 export type EmailChannelOptions = {
@@ -15,33 +20,40 @@ export type EmailChannelOptions = {
 export function createEmailChannel(options: EmailChannelOptions): DeliveryChannel {
   const { transport, renderer, resolveEmail } = options;
 
+  // Render is the expensive step (template engine, possibly a remote service)
+  // and runs in the delivery.render job, decoupled from the SMTP send so each
+  // can retry independently. Extracted so the inline fallback (no job runner)
+  // can reuse it without going through the channel's own render() indirection.
+  async function renderMessage(message: ChannelMessage): Promise<RenderedMessage> {
+    // Build renderer input: per-channel template data (if any) or fall back
+    // to title/body from the message. Renderer handles both cases.
+    const variables = (message.data as DbRow) ?? {
+      title: message.title,
+      body: message.body,
+    };
+    const html = await renderer.render({
+      template: message.notificationType,
+      variables,
+    });
+    const subject = (variables["subject"] as string) ?? message.title; // @cast-boundary dynamic-key
+    return { html, subject };
+  }
+
   return {
     name: "email",
+    mode: "queued",
 
     async resolve(userId, ctx) {
       return resolveEmail(userId, ctx);
     },
 
-    async send(address, message, _ctx) {
-      // Build renderer input: per-channel template data (if any) or fall back
-      // to title/body from the message. Renderer handles both cases.
-      const variables = (message.data as DbRow) ?? {
-        title: message.title,
-        body: message.body,
-      };
-
-      const html = await renderer.render({
-        template: message.notificationType,
-        variables,
-      });
-      const subject = (variables["subject"] as string) ?? message.title; // @cast-boundary dynamic-key
-
-      await transport.send({
-        to: address,
-        subject,
-        html,
-      });
+    render(message, _ctx) {
+      return renderMessage(message);
+    },
 
+    async send(address, message, _ctx, rendered) {
+      const { html, subject } = rendered ?? (await renderMessage(message));
+      await transport.send({ to: address, subject, html });
       return { status: "sent", address };
     },
   };

package/src/channel-email/feature.ts

@@ -16,7 +16,9 @@ export function createChannelEmailFeature(options: EmailChannelOptions): Feature
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "email", {
+      mode: channel.mode,
       resolve: channel.resolve,
+      render: channel.render,
       send: channel.send,
     });
   });

package/src/channel-email/index.ts

@@ -1,4 +1,9 @@
 export { createEmailChannel, type EmailChannelOptions } from "./email-channel";
 export { createChannelEmailFeature } from "./feature";
-export { createSmtpTransport, type SmtpTransportOptions } from "./smtp-transport";
+export {
+  createSmtpTransport,
+  createSmtpTransportFromEnv,
+  type SmtpEnv,
+  type SmtpTransportOptions,
+} from "./smtp-transport";
 export { createInMemoryTransport, type EmailMessage, type EmailTransport } from "./types";

package/src/channel-email/smtp-transport.ts

@@ -63,3 +63,40 @@ export function createSmtpTransport(options: SmtpTransportOptions): EmailTranspo
     },
   };
 }
+
+/** Env-Felder die `createSmtpTransportFromEnv` liest. Apps die SMTP
+ *  nutzen extenden ihr env-Schema um genau diese Keys. */
+export type SmtpEnv = {
+  readonly SMTP_HOST?: string;
+  readonly SMTP_PORT?: string;
+  readonly SMTP_SECURE?: string;
+  readonly SMTP_USER?: string;
+  readonly SMTP_PASS?: string;
+  readonly SMTP_FROM?: string;
+};
+
+/**
+ * Boot-Time-Transport aus env. Ohne `SMTP_HOST` → `null` (Caller behandelt
+ * das als "kein Mail-Versand", statt zu crashen). Port wird zu Number
+ * gecoerced (default 587), `secure` ist `SMTP_SECURE === "true"`, auth nur
+ * wenn user UND pass gesetzt sind.
+ *
+ * Ersetzt den identischen `env.SMTP_HOST ? createSmtpTransport({...}) : null`
+ * Block den jede App in bin/main.ts + bin/server.ts hand-rollte — nur die
+ * From-Default (`fallbackFrom`) variiert pro App.
+ */
+export function createSmtpTransportFromEnv(
+  env: SmtpEnv,
+  opts: { readonly fallbackFrom: string },
+): EmailTransport | null {
+  if (!env.SMTP_HOST) return null;
+  return createSmtpTransport({
+    host: env.SMTP_HOST,
+    port: env.SMTP_PORT ? Number(env.SMTP_PORT) : 587,
+    secure: env.SMTP_SECURE === "true",
+    ...(env.SMTP_USER && env.SMTP_PASS
+      ? { auth: { user: env.SMTP_USER, pass: env.SMTP_PASS } }
+      : {}),
+    from: env.SMTP_FROM ?? opts.fallbackFrom,
+  });
+}

package/src/channel-in-app/feature.ts

@@ -19,6 +19,7 @@ export function createChannelInAppFeature(): FeatureDefinition {
 
     // Register as delivery channel via extension system
     r.useExtension("deliveryChannel", "inApp", {
+      mode: inAppChannel.mode,
       resolve: inAppChannel.resolve,
       send: inAppChannel.send,
     });

package/src/channel-in-app/in-app-channel.ts

@@ -4,6 +4,7 @@ import { inAppMessagesTable } from "./tables";
 
 export const inAppChannel: DeliveryChannel = {
   name: "inApp",
+  mode: "inline",
 
   async resolve(userId) {
     // InApp always resolves — the userId IS the address

package/src/channel-push/feature.ts

@@ -16,6 +16,7 @@ export function createChannelPushFeature(options: PushChannelOptions): FeatureDe
     r.requires("delivery");
 
     r.useExtension("deliveryChannel", "push", {
+      mode: channel.mode,
       resolve: channel.resolve,
       send: channel.send,
     });

package/src/channel-push/push-channel.ts

@@ -15,6 +15,7 @@ export function createPushChannel(options: PushChannelOptions): DeliveryChannel
 
   return {
     name: "push",
+    mode: "queued",
 
     async resolve(userId, ctx) {
       return resolveToken(userId, ctx);

package/src/delivery/__tests__/delivery.integration.test.ts

@@ -10,6 +10,7 @@ import {
   type NotifyFn,
   qn,
 } from "@cosmicdrift/kumiko-framework/engine";
+import { createJobRunner, type JobRunner } from "@cosmicdrift/kumiko-framework/jobs";
 import {
   createTestUser,
   setupTestStack,
@@ -35,9 +36,10 @@ import { TenantQueries } from "../../tenant/constants";
 import { createTenantFeature } from "../../tenant/feature";
 import { tenantMembershipsTable } from "../../tenant/membership-table";
 import { tenantEntity } from "../../tenant/schema/tenant";
-import { DeliveryHandlers, DeliveryQueries } from "../constants";
+import { DeliveryHandlers, DeliveryJobs, DeliveryQueries } from "../constants";
 import { collectChannels, createDeliveryService } from "../delivery-service";
 import { createDeliveryFeature } from "../feature";
+import { deliveryRenderJob } from "../jobs";
 import { deliveryAttemptsTable, notificationPreferencesTable } from "../tables";
 import { createDeliveryTestContext } from "../testing";
 import type { DeliveryService } from "../types";
@@ -1319,3 +1321,247 @@ describe("flow 16: repeated unsubscribe clicks are idempotent", () => {
     expect(rows[0]?.["enabled"]).toBe(false);
   });
 });
+
+// --- Flow 17: async delivery via delivery.render → delivery.send jobs ---
+
+// Dedicated recipient id, untouched by earlier tests, so no stale preference
+// or unsubscribe row disables a channel under us. String id — notify() treats a
+// non-string `to` as a broadcast target ("tenant" in to).
+const asyncRecipient = "7";
+
+async function waitFor(check: () => Promise<void>, timeoutMs = 10000): Promise<void> {
+  const start = Date.now();
+  let lastErr: unknown;
+  for (;;) {
+    try {
+      await check();
+      return;
+    } catch (err) {
+      lastErr = err;
+      if (Date.now() - start > timeoutMs) throw lastErr;
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+  }
+}
+
+function makeStubRunner(): {
+  runner: JobRunner;
+  dispatched: Array<{
+    name: string;
+    payload: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+  }>;
+} {
+  const dispatched: Array<{
+    name: string;
+    payload: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+  }> = [];
+  const runner = {
+    async start() {},
+    async stop() {},
+    async dispatch(
+      name: string,
+      payload?: Record<string, unknown>,
+      meta?: Record<string, unknown>,
+    ) {
+      dispatched.push({ name, payload: payload ?? {}, ...(meta !== undefined && { meta }) });
+      return "stub-job-id";
+    },
+    async handleEvent() {},
+  } as unknown as JobRunner;
+  return { runner, dispatched };
+}
+
+describe("flow 17: async render→send pipeline", () => {
+  test("with a real job runner, email + push deliver via delivery.render → delivery.send", async () => {
+    const redisUrl = process.env["REDIS_URL"];
+    if (!redisUrl) throw new Error("REDIS_URL required for the async delivery e2e test");
+    const queueNamePrefix = `kumiko-delivery-test-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const jobRunner = createJobRunner({
+      registry: stack.registry,
+      context: { db },
+      redisUrl,
+      consumerLane: "worker",
+      queueNamePrefix,
+    });
+    await jobRunner.start();
+    try {
+      const asyncService = createDeliveryService({
+        db,
+        registry: stack.registry,
+        channels: collectChannels(stack.registry),
+        tenantUserIdsQuery: TenantQueries.resolveUserIds,
+        jobRunner,
+      });
+
+      await asyncService.notify(
+        "app:notify:async-e2e",
+        {
+          to: asyncRecipient,
+          data: { title: "Async", body: "delivered via jobs", subject: "Async Subject" },
+        },
+        admin,
+        admin.tenantId,
+      );
+
+      // Email: queued → render job → send job → sent. Proves the framework
+      // jobRunner-into-job-ctx injection (render dispatches send) end-to-end.
+      await waitFor(async () => {
+        const rows = await selectMany(db, deliveryAttemptsTable, {
+          notificationType: "app:notify:async-e2e",
+          channel: "email",
+        });
+        expect(rows.some((r) => r["status"] === "sent")).toBe(true);
+      });
+      const email = emailTransport.sent.find((m) => m.to === testEmail(asyncRecipient));
+      expect(email).toBeDefined();
+      expect(email?.subject).toBe("Async Subject");
+      expect(email?.html).toContain("delivered via jobs");
+      expect(email?.html).toContain("<!DOCTYPE html>");
+
+      // Push: no render step → dispatched straight to delivery.send.
+      await waitFor(async () => {
+        const rows = await selectMany(db, deliveryAttemptsTable, {
+          notificationType: "app:notify:async-e2e",
+          channel: "push",
+        });
+        expect(rows.some((r) => r["status"] === "sent")).toBe(true);
+      });
+      expect(
+        pushTransport.sent.find((m) => m.token === testPushToken(asyncRecipient)),
+      ).toBeDefined();
+    } finally {
+      await jobRunner.stop();
+    }
+  }, 20000);
+
+  test("queued channels dispatch jobs instead of sending inline; inApp stays inline", async () => {
+    const { runner, dispatched } = makeStubRunner();
+    const asyncService = createDeliveryService({
+      db,
+      registry: stack.registry,
+      channels: collectChannels(stack.registry),
+      tenantUserIdsQuery: TenantQueries.resolveUserIds,
+      jobRunner: runner,
+    });
+
+    await asyncService.notify(
+      "app:notify:queued-dispatch",
+      { to: asyncRecipient, data: { title: "Q", body: "Q", subject: "Q" } },
+      admin,
+      admin.tenantId,
+    );
+
+    // email has a render step → delivery.render; push has none → delivery.send.
+    const renderDispatch = dispatched.find((d) => d.name === DeliveryJobs.render);
+    expect(renderDispatch?.payload["channelName"]).toBe("email");
+    expect(renderDispatch?.payload["deliveryAttemptId"]).toBeDefined();
+    expect(
+      dispatched.some((d) => d.name === DeliveryJobs.send && d.payload["channelName"] === "push"),
+    ).toBe(true);
+
+    // email is NOT sent inline — it waits for the job.
+    expect(emailTransport.sent.find((m) => m.to === testEmail(asyncRecipient))).toBeUndefined();
+
+    // email attempt row exists as "queued"; inApp was delivered inline ("sent").
+    const emailRows = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:queued-dispatch",
+      channel: "email",
+    });
+    expect(emailRows.some((r) => r["status"] === "queued")).toBe(true);
+    const inAppRows = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:queued-dispatch",
+      channel: "inApp",
+    });
+    expect(inAppRows.some((r) => r["status"] === "sent")).toBe(true);
+  });
+
+  test("without a job runner, queued channels fall back to synchronous inline send", async () => {
+    const inlineService = createDeliveryService({
+      db,
+      registry: stack.registry,
+      channels: collectChannels(stack.registry),
+      tenantUserIdsQuery: TenantQueries.resolveUserIds,
+    });
+
+    await inlineService.notify(
+      "app:notify:inline-fallback",
+      { to: asyncRecipient, data: { title: "Inline", body: "sent inline", subject: "Inline" } },
+      admin,
+      admin.tenantId,
+    );
+
+    // Sent synchronously during notify() — no job runner, no waiting.
+    expect(emailTransport.sent.find((m) => m.to === testEmail(asyncRecipient))).toBeDefined();
+    const emailRows = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:inline-fallback",
+      channel: "email",
+    });
+    expect(emailRows.some((r) => r["status"] === "sent")).toBe(true);
+  });
+
+  test("delivery.render on a channel without a render step records failed and does not dispatch send", async () => {
+    const { runner, dispatched } = makeStubRunner();
+    const attemptId = "00000000-0000-4000-8000-0000000000aa";
+    await expect(
+      deliveryRenderJob(
+        {
+          channelName: "push", // push has no render() — render job must not be used for it
+          address: testPushToken(asyncRecipient),
+          tenantId: admin.tenantId,
+          recipientId: String(asyncRecipient),
+          notificationType: "app:notify:render-isolation",
+          deliveryAttemptId: attemptId,
+          priority: "normal",
+          message: { notificationType: "app:notify:render-isolation", title: "X" },
+        },
+        { db, registry: stack.registry, jobRunner: runner },
+      ),
+    ).rejects.toThrow(/no render step/);
+
+    // No send dispatched, and the attempt is recorded as failed (not stuck queued).
+    expect(dispatched).toHaveLength(0);
+    const rows = await selectMany(db, deliveryAttemptsTable, {
+      notificationType: "app:notify:render-isolation",
+    });
+    expect(rows.some((r) => r["status"] === "failed")).toBe(true);
+  });
+});
+
+// --- Flow 18: priority maps onto the BullMQ job priority ---
+
+describe("flow 18: priority → job priority mapping", () => {
+  test("critical/normal/low map to ascending BullMQ priorities on dispatch", async () => {
+    const send = async (notificationType: string, priority: "critical" | "normal" | "low") => {
+      const { runner, dispatched } = makeStubRunner();
+      const asyncService = createDeliveryService({
+        db,
+        registry: stack.registry,
+        channels: collectChannels(stack.registry),
+        tenantUserIdsQuery: TenantQueries.resolveUserIds,
+        jobRunner: runner,
+      });
+      await asyncService.notify(
+        notificationType,
+        { to: asyncRecipient, data: { title: "P", body: "P" }, priority },
+        admin,
+        admin.tenantId,
+      );
+      // email → delivery.render carries the priority meta.
+      const render = dispatched.find((d) => d.name === DeliveryJobs.render);
+      return render?.meta?.["priority"];
+    };
+
+    const critical = await send("app:notify:prio-critical", "critical");
+    const normal = await send("app:notify:prio-normal", "normal");
+    const low = await send("app:notify:prio-low", "low");
+
+    expect(critical).toBe(1);
+    expect(normal).toBe(2);
+    expect(low).toBe(3);
+    // Lower number = higher priority: critical jumps ahead of normal ahead of low.
+    expect(critical as number).toBeLessThan(normal as number);
+    expect(normal as number).toBeLessThan(low as number);
+  });
+});

package/src/delivery/attempt-log.ts

@@ -0,0 +1,54 @@
+// Shared delivery-attempt event writer. Used both synchronously by the
+// delivery-service (inline channels, skips) and asynchronously by the
+// delivery.render / delivery.send job handlers — keeping the append +
+// inline-projection logic in one place so both paths produce identical rows.
+
+import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { append, getStreamVersion } from "@cosmicdrift/kumiko-framework/event-store";
+import { runProjectionsForEvent } from "@cosmicdrift/kumiko-framework/pipeline";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { DELIVERY_ATTEMPT_EVENT } from "./constants";
+import { deliveryAttemptSchema } from "./events";
+import type { DeliveryLogEntry } from "./types";
+
+// Append one delivery-attempt event to `attemptId`'s stream and run the inline
+// `delivery-log` projection in the same write (low-level append() does not
+// auto-fire projections — only the dispatcher/executor paths do). getStreamVersion
+// returns 0 for a fresh stream, so the same call serves both the first event
+// (queued, or a single-shot terminal) and follow-ups (queued → sent/failed).
+export async function appendAttemptEvent(
+  db: DbConnection,
+  registry: Registry,
+  attemptId: string,
+  entry: DeliveryLogEntry,
+): Promise<void> {
+  const { tenantId, ...rest } = entry;
+  // Schema-parse to match ctx.appendEvent's guarantee: a payload drift between
+  // service/job + feature-registration fails loudly here instead of landing on
+  // the events-table and crashing a consumer later.
+  const payload = deliveryAttemptSchema.parse(rest);
+  const expectedVersion = await getStreamVersion(db, attemptId, tenantId);
+  const stored = await append(db, {
+    aggregateId: attemptId,
+    aggregateType: "deliveryAttempt",
+    tenantId,
+    expectedVersion,
+    type: DELIVERY_ATTEMPT_EVENT,
+    payload,
+    metadata: { userId: "system" },
+  });
+  await runProjectionsForEvent(stored, registry, db);
+}
+
+// Single-shot terminal log (inline channels, skips, idempotency dups): fresh
+// aggregate id, one event.
+export async function logAttempt(
+  db: DbConnection,
+  registry: Registry,
+  entry: DeliveryLogEntry,
+): Promise<string> {
+  const attemptId = generateId();
+  await appendAttemptEvent(db, registry, attemptId, entry);
+  return attemptId;
+}