@pramen/server 0.0.8 → 0.0.10

package/dist/worker.js

@@ -4,9 +4,11 @@
 // endpoints (/tenants, /admin/recover, /admin/schema). createPramen() pairs the
 // returned fetch with the matching DO class; a consumer just re-exports both.
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity } from "./auth";
-import { dispatch } from "./runtime/dispatch";
+import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
+import { Db } from "./runtime/db";
 import { D1Driver } from "./runtime/driver";
 import { toResponse } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
@@ -92,6 +94,7 @@ export function makeWorker(app) {
     const ensureD1Migrated = (driver, allowDestructive) => {
         if (!d1Ready) {
             d1Ready = migrate(driver, app.schema, { allowDestructive })
+                .then(() => ensureOutbox(driver)) // the deferred-tasks table also lives in D1
                 .then(() => undefined)
                 .catch((e) => {
                 d1Ready = undefined;
@@ -100,6 +103,31 @@ export function makeWorker(app) {
         }
         return d1Ready;
     };
+    // A privileged, system-scoped context for running task handlers on the D1 (Worker)
+    // path — mirrors the DO's taskCtx. No live socket, so no DO; drained by a Cron / the
+    // /admin/tasks/drain route, never a DO alarm.
+    const d1TaskCtx = (driver, env) => {
+        const identity = { roles: ["admin"] };
+        const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
+        const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema }, app.schema);
+        return { db, kv: new Kv(env.KV), files, env: env, identity, tasks: tasksFacade(driver) };
+    };
+    /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
+     * /admin/tasks/drain route with `x-pramen-store: d1`, and by `scheduled()` (Cron). */
+    const drainD1 = async (env) => {
+        if (!env.DB)
+            throw new Error("D1 store is not configured");
+        const driver = new D1Driver(env.DB);
+        await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
+        return drainOutbox(driver, bindTasks(app.tasks, d1TaskCtx(driver, env)), Date.now());
+    };
+    const listD1Tasks = async (env, status, limit) => {
+        if (!env.DB)
+            throw new Error("D1 store is not configured");
+        const driver = new D1Driver(env.DB);
+        await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
+        return listTasks(driver, { status, limit });
+    };
     return {
         async fetch(request, env) {
             const url = new URL(request.url);
@@ -196,6 +224,60 @@ export function makeWorker(app) {
                 }));
                 return withCors(res, cors);
             }
+            // --- admin: drain the deferred-task outbox now (the DO also self-drains via an
+            // alarm; this is the manual / Cron entry, and the ONLY drain for the D1 path).
+            // `x-pramen-store: d1` drains the D1 outbox in the Worker; else the tenant's DO. ---
+            if (url.pathname === "/admin/tasks/drain" && request.method === "POST") {
+                if (!isAdmin(identity))
+                    return forbidden("tasks");
+                if (request.headers.get("x-pramen-store") === "d1") {
+                    try {
+                        return withCors(json({ ok: true, result: await drainD1(env) }), cors);
+                    }
+                    catch (err) {
+                        const { status, body } = toResponse(err);
+                        return withCors(json(body, status), cors);
+                    }
+                }
+                const body = (await request.json().catch(() => ({})));
+                const tenant = typeof body.tenant === "string" && body.tenant ? body.tenant : "main";
+                const partition = typeof body.partition === "string" && body.partition ? body.partition : DEFAULT_PARTITION;
+                const stub = partitionStubFor(env, tenant, partition);
+                const res = await stub.fetch(new Request("https://do/__admin/tasks/drain", {
+                    method: "POST",
+                    headers: { "content-type": "application/json", "x-pramen-tenant": tenant, "x-pramen-partition": partition },
+                }));
+                return withCors(res, cors);
+            }
+            // --- admin: list outbox tasks (inspect dead-letters etc.). ?status=&limit=,
+            // ?tenant=&partition= (DO store) or x-pramen-store: d1 (Worker outbox). ---
+            if (url.pathname === "/admin/tasks/list") {
+                if (!isAdmin(identity))
+                    return withCors(forbidden("tasks"), cors);
+                const status = url.searchParams.get("status") ?? undefined;
+                const limit = Number(url.searchParams.get("limit")) || undefined;
+                if (request.headers.get("x-pramen-store") === "d1") {
+                    try {
+                        return withCors(json({ ok: true, result: await listD1Tasks(env, status, limit) }), cors);
+                    }
+                    catch (err) {
+                        const { status: s, body } = toResponse(err);
+                        return withCors(json(body, s), cors);
+                    }
+                }
+                const tenant = url.searchParams.get("tenant") ?? "main";
+                const partition = url.searchParams.get("partition") || DEFAULT_PARTITION;
+                const q = new URLSearchParams();
+                if (status)
+                    q.set("status", status);
+                if (limit)
+                    q.set("limit", String(limit));
+                const stub = partitionStubFor(env, tenant, partition);
+                const res = await stub.fetch(new Request(`https://do/__admin/tasks/list?${q}`, {
+                    headers: { "x-pramen-tenant": tenant, "x-pramen-partition": partition },
+                }));
+                return withCors(res, cors);
+            }
             const isRpc = url.pathname.startsWith("/rpc/");
             const isLive = url.pathname === "/live";
             if (!isRpc && !(isLive && isWs)) {
@@ -259,5 +341,11 @@ export function makeWorker(app) {
             const res = await stub.fetch(new Request(req, { headers }));
             return isWs ? res : withCors(res, cors);
         },
+        // Cron Trigger entry: drains the D1 outbox (the DO path self-drains via an alarm,
+        // so it needs no cron). Wire a `[triggers] crons` in wrangler/oblaka to call this.
+        async scheduled(_event, env) {
+            if (env.DB)
+                await drainD1(env);
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/durable-object.ts

@@ -17,7 +17,8 @@
 
 import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
-import { dispatch } from "./runtime/dispatch";
+import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
 import { compileAcl, type AclContext, type CompiledAcl } from "./runtime/acl";
@@ -28,6 +29,7 @@ import { registryKey } from "./runtime/registry";
 import { DEFAULT_PARTITION } from "./sdk/schema";
 import { createFiles, R2Adapter, type Files } from "./runtime/storage";
 import type { Identity } from "./sdk/acl";
+import type { HandlerContext } from "./sdk/handlers";
 import type { PramenApp } from "./pramen";
 import type { ClientMsg, ServerMsg, Subscription } from "./runtime/protocol";
 
@@ -75,6 +77,11 @@ export class PramenDOBase extends DurableObject<DoEnv> {
    * constructor — see `ensureMigrated`. Guards against re-running. */
   private migrated = false;
   private files?: Files;
+  /** Have we persisted (tenant, partition) to DO storage this instance? They're
+   * persisted so a COLD alarm wake (no request header) can build a correctly-scoped
+   * task context — a DO can't introspect its own idFromName. */
+  private identityPersisted = false;
+  private identityLoaded = false;
 
   constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp) {
     super(ctx, env);
@@ -112,6 +119,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       await this.driver.transaction(() =>
         migrate(this.driver, this.app.schema, { allowDestructive, partition }).then(() => {}),
       );
+      await ensureOutbox(this.driver); // the deferred-tasks table (internal, all partitions)
       this.migrated = true;
     });
   }
@@ -126,11 +134,25 @@ export class PramenDOBase extends DurableObject<DoEnv> {
 
     await this.ensureMigrated();
     await this.ensureRegistered(request);
+    // Persist (tenant, partition) once per instance so a cold alarm can rebuild the
+    // right task context (it has no request header to learn them from). Stored in the
+    // SQL store (_pramen_meta), NOT ctx.storage.put — mixing the KV-style storage API
+    // with raw `PRAGMA` trips workerd's DO SQLite authorizer (SQLITE_AUTH).
+    if (!this.identityPersisted) {
+      await this.driver.exec(
+        `INSERT OR REPLACE INTO _pramen_meta (key, value) VALUES (?, ?), (?, ?)`,
+        ["_pramen_tenant", this.tenant, "_pramen_partition", this.partition].map((v) => this.driver.dialect.encode(v)),
+      );
+      this.identityPersisted = true;
+      this.identityLoaded = true;
+    }
 
     const path = new URL(request.url).pathname;
     if (path === "/__recover") return this.handleRecover(request);
     if (path === "/__schema") return this.handleSchema();
     if (path === "/__admin/data") return this.handleAdminData(request);
+    if (path === "/__admin/tasks/drain") return this.handleDrain();
+    if (path === "/__admin/tasks/list") return this.handleTasksList(request);
 
     const identity = this.identityOf(request);
 
@@ -148,7 +170,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     }
 
     try {
-      const { result, kind, touched } = await dispatch(
+      const { result, kind, touched, enqueued } = await dispatch(
         this.app.handlers,
         this.app.schema,
         this.driver,
@@ -160,6 +182,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
         input,
       );
       if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
+      if (enqueued > 0) await this.armDrain();
       return Response.json({ ok: true, result });
     } catch (err) {
       const { status, body } = toResponse(err);
@@ -167,6 +190,72 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     }
   }
 
+  /** Arm the drain alarm soon after a mutation enqueued task(s). setAlarm replaces any
+   * pending alarm; a near-future time batches a burst of enqueues into one drain. */
+  private async armDrain(): Promise<void> {
+    await this.ctx.storage.setAlarm(Date.now() + 50);
+  }
+
+  /** A privileged, system-scoped context for running task handlers (outside a request).
+   * Task handlers get full db access + env (e.g. ctx.env.EMAIL) + their own ctx.tasks. */
+  private taskCtx(): HandlerContext {
+    const identity: Identity = { roles: ["admin"] };
+    const db = new Db(
+      this.driver,
+      { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition },
+      this.app.schema,
+    );
+    return { db, kv: this.kv, files: this.filesFor(this.tenant), env: this.envBag, identity, tasks: tasksFacade(this.driver) };
+  }
+
+  /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the
+   * task context is scoped correctly. No-op once loaded/persisted this instance. */
+  private async loadIdentity(): Promise<void> {
+    if (this.identityLoaded) return;
+    // _pramen_meta exists: an alarm only fires after a fetch armed it, and that fetch
+    // ran the boot migration which creates the table.
+    const rows = (await this.driver.exec(
+      `SELECT key, value FROM _pramen_meta WHERE key IN ('_pramen_tenant', '_pramen_partition')`,
+      [],
+    )) as { key: string; value: string }[];
+    for (const r of rows) {
+      if (r.key === "_pramen_tenant" && r.value) this.tenant = r.value;
+      if (r.key === "_pramen_partition" && r.value) this.partition = r.value;
+    }
+    this.identityLoaded = true;
+  }
+
+  /** Drain due tasks. Called by the alarm (DO path) and the /__admin/tasks/drain route
+   * (manual / cron). Returns the drain stats incl. `nextRunAt` for rescheduling. */
+  private async drainTasks(): Promise<Awaited<ReturnType<typeof drainOutbox>>> {
+    await ensureOutbox(this.driver); // idempotent — the table may predate this instance (cold alarm)
+    return drainOutbox(this.driver, bindTasks(this.app.tasks, this.taskCtx()), Date.now());
+  }
+
+  override async alarm(): Promise<void> {
+    await this.loadIdentity(); // cold wake: restore tenant/partition before building taskCtx
+    const { nextRunAt } = await this.drainTasks();
+    // Reschedule to the NEXT task's due time (a backed-off retry, or the next batch if
+    // the drain hit its limit) so a failed task can't stall waiting for a new enqueue.
+    if (nextRunAt != null) await this.ctx.storage.setAlarm(Math.max(nextRunAt, Date.now() + 250));
+  }
+
+  private async handleDrain(): Promise<Response> {
+    await this.loadIdentity();
+    const result = await this.drainTasks();
+    // Keep the alarm honest even when drained manually: ensure a backed-off retry wakes.
+    if (result.nextRunAt != null) await this.ctx.storage.setAlarm(Math.max(result.nextRunAt, Date.now() + 250));
+    return Response.json({ ok: true, result });
+  }
+
+  private async handleTasksList(request: Request): Promise<Response> {
+    await ensureOutbox(this.driver);
+    const url = new URL(request.url);
+    const status = url.searchParams.get("status") ?? undefined;
+    const limit = Number(url.searchParams.get("limit")) || undefined;
+    return Response.json({ ok: true, result: await listTasks(this.driver, { status, limit }) });
+  }
+
   // --- Hibernatable WebSocket handlers ---
 
   override async webSocketMessage(ws: WebSocket, raw: string | ArrayBuffer): Promise<void> {
@@ -240,9 +329,10 @@ export class PramenDOBase extends DurableObject<DoEnv> {
   private async onCall(ws: WebSocket, id: string, name: string, input: unknown): Promise<void> {
     const state = this.getState(ws);
     try {
-      const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), name, input);
+      const { result, kind, touched, enqueued } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity, state.partition), name, input);
       this.send(ws, { type: "result", id, result });
       if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
+      if (enqueued > 0) await this.armDrain();
     } catch (err) {
       this.send(ws, toWsError(id, err));
     }
@@ -338,11 +428,13 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       value: string;
     }[];
     const tableRows = (await this.driver.exec(
-      `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> '_pramen_meta'`,
+      `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'`,
       [],
     )) as { name: string }[];
     const tables: Record<string, string[]> = {};
     for (const { name } of tableRows) {
+      // Skip pramen's internal bookkeeping tables (_pramen_meta, _pramen_outbox, …).
+      if (name.toLowerCase().startsWith("_pramen") || name.toLowerCase().startsWith("__pramen")) continue;
       tables[name] = ((await this.driver.exec(`PRAGMA table_info(${name})`, [])) as { name: string }[]).map((r) => r.name);
     }
     return Response.json({ ok: true, result: { hash: hashRow[0]?.value ?? null, tables } });

package/src/index.ts

@@ -26,7 +26,7 @@ export type {
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
 export { query, mutation } from "./sdk/handlers";
-export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts } from "./sdk/handlers";
+export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
 
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";

package/src/pramen.ts

@@ -15,7 +15,7 @@
 import { makeWorker, type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
 import type { SchemaDef } from "./sdk/schema";
-import type { HandlerMap } from "./sdk/handlers";
+import type { AppTaskMap, HandlerMap } from "./sdk/handlers";
 import type { Role } from "./sdk/acl";
 
 /** Injected into a public route's handler — forward a privileged mutation into the
@@ -45,14 +45,21 @@ export interface PramenApp {
   handlers: HandlerMap;
   acl?: Role[];
   routes?: PublicRoute[];
+  /** Deferred side-effect handlers keyed by `kind` — drained from the outbox after a
+   * mutation enqueues via `ctx.tasks.enqueue`. For notification email, webhooks, etc. */
+  tasks?: AppTaskMap;
 }
 
 export type { Env, DoEnv };
 
-/** Build the deployable pair for an app. */
+/** Build the deployable pair for an app. `scheduled` is a Cron Trigger entry that
+ * drains the D1 outbox (the DO path self-drains via an alarm) — wire it only if you
+ * use the D1 store with deferred tasks. */
 export function createPramen(app: PramenApp): {
   fetch: (request: Request, env: Env) => Promise<Response>;
+  scheduled: (event: unknown, env: Env) => Promise<void>;
   PramenDO: ReturnType<typeof pramenDO>;
 } {
-  return { fetch: makeWorker(app).fetch, PramenDO: pramenDO(app) };
+  const worker = makeWorker(app);
+  return { fetch: worker.fetch, scheduled: worker.scheduled, PramenDO: pramenDO(app) };
 }

package/src/runtime/dispatch.ts

@@ -11,17 +11,38 @@
 import { Db } from "./db";
 import { warmup, type AclContext } from "./acl";
 import { BadRequest } from "./errors";
+import { enqueueTask, type TaskMap } from "./outbox";
 import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
 import type { ResolverDb } from "../sdk/acl";
 import type { SchemaDef } from "../sdk/schema";
-import type { HandlerContext, HandlerKind, HandlerMap } from "../sdk/handlers";
+import type { AppTaskMap, HandlerContext, HandlerKind, HandlerMap, Tasks } from "../sdk/handlers";
 
 export interface DispatchResult {
   readonly result: unknown;
   readonly kind: HandlerKind;
   readonly touched: string[];
+  /** Number of tasks the handler enqueued — the DO uses this to arm its drain alarm. */
+  readonly enqueued: number;
+}
+
+/** The `ctx.tasks` facade over the outbox. `onEnqueue` lets the caller count enqueues
+ * so it can wake the drainer. */
+export function tasksFacade(driver: Driver, onEnqueue?: () => void): Tasks {
+  return {
+    enqueue: async (opts) => {
+      await enqueueTask(driver, Date.now(), opts);
+      onEnqueue?.();
+    },
+  };
+}
+
+/** Bind `app.tasks` (which take a ctx) into the ctx-free `TaskMap` the drainer calls. */
+export function bindTasks(appTasks: AppTaskMap | undefined, ctx: HandlerContext): TaskMap {
+  const out: TaskMap = {};
+  for (const [kind, handler] of Object.entries(appTasks ?? {})) out[kind] = (payload, meta) => handler(ctx, payload, meta);
+  return out;
 }
 
 export async function dispatch(
@@ -54,12 +75,13 @@ export async function dispatch(
   const resolved = await warmup(acl.acl, acl.identity, systemDb as unknown as ResolverDb);
 
   const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
-  const ctx: HandlerContext = { db, kv, files, env, identity: acl.identity };
+  let enqueued = 0;
+  const ctx: HandlerContext = { db, kv, files, env, identity: acl.identity, tasks: tasksFacade(driver, () => enqueued++) };
 
   const result =
     handler.kind === "query"
       ? await handler.run(ctx, parsed)
       : await driver.transaction(async () => handler.run(ctx, parsed));
 
-  return { result, kind: handler.kind, touched: [...db.touched] };
+  return { result, kind: handler.kind, touched: [...db.touched], enqueued };
 }

package/src/runtime/outbox.ts

@@ -0,0 +1,204 @@
+// Transactional outbox — the substrate-agnostic core of deferred side-effects
+// ("tasks"), e.g. sending a notification email off the write path.
+//
+// A handler calls `ctx.tasks.enqueue({ kind, payload })`, which INSERTs a row into
+// `_pramen_outbox` through the SAME Driver (and, for a mutation, the SAME transaction)
+// as the data write — so the task and the data commit or roll back together (no
+// dual-write window). A drainer later runs the app's task handler for that `kind`,
+// with retry/backoff and a dead-letter terminal state.
+//
+// Everything here is written against the `Driver`/`Dialect` seam, so it runs
+// identically on the DO's in-process SQLite AND on D1 (the Worker path). What differs
+// is only the WAKE-UP: the DO self-drains via an alarm scheduled at the next due time;
+// the D1/Worker path drains via a Cron Trigger or POST /admin/tasks/drain — same
+// drainOutbox(), both paths.
+//
+// Delivery is at-least-once. The drain CLAIMS a batch atomically (status
+// pending→processing) so concurrent drainers (the D1/Cron path) never process the same
+// row twice; a crashed drainer's claim is reclaimed after STALE_MS. Handlers get the
+// task `id` as an idempotency key so they can dedupe across the rare retry.
+
+import type { Driver } from "./driver";
+
+export const OUTBOX_TABLE = "_pramen_outbox";
+
+const MAX_ATTEMPTS = 5;
+/** A claimed ('processing') row whose claim is older than this is presumed abandoned
+ * (the drainer crashed) and is reclaimed. Must exceed the slowest task. */
+const STALE_MS = 60_000;
+/** Keep 'done' rows this long (a dedup window + debugging), then prune. */
+const DONE_RETENTION_MS = 3_600_000;
+
+/** Exponential backoff (ms) before the next attempt of a failed task. */
+function backoffMs(attempts: number): number {
+  return Math.min(2 ** attempts * 1000, 5 * 60_000); // 2s, 4s, 8s, … capped at 5min
+}
+
+const enc = (driver: Driver, params: unknown[]): unknown[] => params.map((p) => driver.dialect.encode(p));
+
+/** Create the outbox table if absent. Idempotent — run on DO boot (and lazily on the
+ * D1 path). Internal table (`_pramen_` prefix), never part of the user schema. */
+export async function ensureOutbox(driver: Driver): Promise<void> {
+  const t = driver.dialect.id(OUTBOX_TABLE);
+  await driver.exec(
+    `CREATE TABLE IF NOT EXISTS ${t} (` +
+      `id TEXT PRIMARY KEY, kind TEXT NOT NULL, payload TEXT NOT NULL, ` +
+      `status TEXT NOT NULL DEFAULT 'pending', attempts INTEGER NOT NULL DEFAULT 0, ` +
+      `runAt INTEGER NOT NULL, createdAt INTEGER NOT NULL, claimedAt INTEGER, lastError TEXT)`,
+    [],
+  );
+  // Drain queries filter on (status, runAt); index keeps claim/scan cheap as it grows.
+  await driver.exec(`CREATE INDEX IF NOT EXISTS _pramen_outbox_due ON ${OUTBOX_TABLE} (status, runAt)`, []);
+}
+
+export interface EnqueueOpts {
+  kind: string;
+  payload?: unknown;
+  /** Delay before the task becomes due (ms from now). Default 0 (drain ASAP). */
+  delayMs?: number;
+}
+
+/** Insert one task row. Uses the driver directly, so inside a mutation it joins that
+ * mutation's transaction (atomic with the data write). `now` is stamped by the caller. */
+export async function enqueueTask(driver: Driver, now: number, opts: EnqueueOpts): Promise<void> {
+  if (!opts || typeof opts.kind !== "string" || opts.kind.length === 0) {
+    throw new Error("ctx.tasks.enqueue: `kind` is required");
+  }
+  const d = driver.dialect;
+  const ph = (i: number) => d.placeholder(i);
+  await driver.exec(
+    `INSERT INTO ${d.id(OUTBOX_TABLE)} (id, kind, payload, status, attempts, runAt, createdAt) ` +
+      `VALUES (${ph(1)}, ${ph(2)}, ${ph(3)}, ${ph(4)}, ${ph(5)}, ${ph(6)}, ${ph(7)})`,
+    enc(driver, [
+      crypto.randomUUID(),
+      opts.kind,
+      JSON.stringify(opts.payload ?? null),
+      "pending",
+      0,
+      now + Math.max(0, Math.trunc(opts.delayMs ?? 0)),
+      now,
+    ]),
+  );
+}
+
+/** Idempotency metadata handed to a task handler. `id` is stable across retries — a
+ * handler can record it and skip a duplicate delivery (at-least-once). */
+export interface TaskMeta {
+  id: string;
+  /** 1-based attempt number for this delivery. */
+  attempts: number;
+}
+
+/** A task handler: runs the side effect for one `kind`. Throwing schedules a retry. */
+export type TaskHandler = (payload: unknown, meta: TaskMeta) => void | Promise<void>;
+export type TaskMap = Record<string, TaskHandler>;
+
+export interface DrainResult {
+  processed: number;
+  succeeded: number;
+  failed: number;
+  /** Tasks still pending+due after this pass (a caller may loop to clear a backlog). */
+  remaining: number;
+  /** Epoch-ms of the earliest not-yet-run task (due or backed-off), or null if none —
+   * the DO schedules its next alarm here so a backed-off retry can't stall. */
+  nextRunAt: number | null;
+}
+
+/** Run every due task once (claimed batch, up to `limit`). On success mark it done; on
+ * throw, bump attempts and back off, or dead-letter ('failed') past MAX_ATTEMPTS.
+ *
+ * Substrate-agnostic and concurrency-safe: the claim UPDATE (pending→processing) is
+ * atomic, so two drainers (the D1/Cron path) get disjoint batches; a crashed drainer's
+ * claim is reclaimed after STALE_MS. The DO path is single-writer so claims never
+ * contend, but the same code runs there too. */
+export async function drainOutbox(driver: Driver, tasks: TaskMap, now: number, limit = 50): Promise<DrainResult> {
+  const d = driver.dialect;
+  const ph = (i: number) => d.placeholder(i);
+
+  // Prune long-since-delivered rows so the table stays bounded.
+  await driver.exec(
+    `DELETE FROM ${d.id(OUTBOX_TABLE)} WHERE status = ${ph(1)} AND createdAt < ${ph(2)}`,
+    enc(driver, ["done", now - DONE_RETENTION_MS]),
+  );
+
+  // Atomically claim a due batch: fresh 'pending', plus 'processing' rows whose claim
+  // is stale (the drainer crashed). RETURNING gives us exactly our claimed rows, so a
+  // concurrent drainer (writes serialize) claims a disjoint set.
+  const staleBefore = now - STALE_MS;
+  const claimed = await driver.exec(
+    `UPDATE ${d.id(OUTBOX_TABLE)} SET status = ${ph(1)}, claimedAt = ${ph(2)} WHERE id IN (` +
+      `SELECT id FROM ${d.id(OUTBOX_TABLE)} ` +
+      `WHERE (status = ${ph(3)} OR (status = ${ph(4)} AND claimedAt <= ${ph(5)})) AND runAt <= ${ph(6)} ` +
+      `ORDER BY createdAt LIMIT ${Math.max(1, Math.trunc(limit))}) ` +
+      `RETURNING id, kind, payload, attempts`,
+    enc(driver, ["processing", now, "pending", "processing", staleBefore, now]),
+  );
+
+  let succeeded = 0;
+  let failed = 0;
+  for (const row of claimed) {
+    const id = String(row.id);
+    const kind = String(row.kind);
+    const attempts = Number(row.attempts) + 1;
+    const handler = tasks[kind];
+    try {
+      if (!handler) throw new Error(`no task handler registered for kind ${JSON.stringify(kind)}`);
+      await handler(JSON.parse(String(row.payload)), { id, attempts });
+      await driver.exec(
+        `UPDATE ${d.id(OUTBOX_TABLE)} SET status = ${ph(1)}, attempts = ${ph(2)}, claimedAt = NULL WHERE id = ${ph(3)}`,
+        enc(driver, ["done", attempts, id]),
+      );
+      succeeded++;
+    } catch (e) {
+      const dead = attempts >= MAX_ATTEMPTS;
+      const msg = e instanceof Error ? e.message : String(e);
+      await driver.exec(
+        `UPDATE ${d.id(OUTBOX_TABLE)} SET status = ${ph(1)}, attempts = ${ph(2)}, runAt = ${ph(3)}, claimedAt = NULL, lastError = ${ph(4)} WHERE id = ${ph(5)}`,
+        enc(driver, [dead ? "failed" : "pending", attempts, now + backoffMs(attempts), msg.slice(0, 500), id]),
+      );
+      failed++;
+    }
+  }
+
+  // remaining = pending AND due now; nextRunAt = the earliest pending runAt (any), so
+  // the DO can schedule its alarm exactly when the next task — including a backed-off
+  // retry — becomes due.
+  const stats = await driver.exec(
+    `SELECT ` +
+      `(SELECT COUNT(*) FROM ${d.id(OUTBOX_TABLE)} WHERE status = ${ph(1)} AND runAt <= ${ph(2)}) AS due, ` +
+      `(SELECT MIN(runAt) FROM ${d.id(OUTBOX_TABLE)} WHERE status = ${ph(3)}) AS nextRunAt`,
+    enc(driver, ["pending", now, "pending"]),
+  );
+  const nextRaw = stats[0]?.nextRunAt;
+  return {
+    processed: claimed.length,
+    succeeded,
+    failed,
+    remaining: Number(stats[0]?.due ?? 0),
+    nextRunAt: nextRaw == null ? null : Number(nextRaw),
+  };
+}
+
+export interface TaskRow {
+  id: string;
+  kind: string;
+  status: string;
+  attempts: number;
+  runAt: number;
+  createdAt: number;
+  lastError: string | null;
+}
+
+/** List outbox rows for admin visibility (e.g. inspect dead-lettered tasks). Newest
+ * first; optionally filter by `status` (e.g. "failed"). Excludes the payload. */
+export async function listTasks(driver: Driver, opts: { status?: string; limit?: number } = {}): Promise<TaskRow[]> {
+  const d = driver.dialect;
+  const limit = Math.min(Math.max(Math.trunc(opts.limit ?? 100) || 100, 1), 500);
+  const where = opts.status ? `WHERE status = ${d.placeholder(1)} ` : "";
+  const rows = await driver.exec(
+    `SELECT id, kind, status, attempts, runAt, createdAt, lastError FROM ${d.id(OUTBOX_TABLE)} ` +
+      `${where}ORDER BY createdAt DESC LIMIT ${limit}`,
+    opts.status ? enc(driver, [opts.status]) : [],
+  );
+  return rows as unknown as TaskRow[];
+}

package/src/sdk/handlers.ts

@@ -25,8 +25,35 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
   readonly env: Readonly<Record<string, unknown>>;
   /** Resolved identity for this request (null = anonymous). */
   readonly identity: Identity | null;
+  /** Deferred side-effects (a transactional outbox). `tasks.enqueue` persists a task
+   * row in the SAME transaction as a mutation (atomic with the data write); a drainer
+   * runs the matching `app.tasks` handler after commit, off the write path, with
+   * retry. For notification email, webhooks, etc. — see `app.tasks`. */
+  readonly tasks: Tasks;
 }
 
+/** The deferred-side-effects facade handed to handlers as `ctx.tasks`. */
+export interface Tasks {
+  /** Enqueue a task to run after commit. `kind` selects the `app.tasks` handler;
+   * `payload` is JSON-serialized. `delayMs` defers when it becomes due. */
+  enqueue(opts: { kind: string; payload?: unknown; delayMs?: number }): Promise<void>;
+}
+
+/** Idempotency metadata for a task delivery. `id` is stable across retries — record it
+ * to dedupe the rare duplicate (delivery is at-least-once). `attempts` is 1-based. */
+export interface TaskMeta {
+  id: string;
+  attempts: number;
+}
+
+/** An app task handler — runs a deferred side effect for one `kind` (e.g. send an
+ * email via `ctx.env.EMAIL`). Throwing schedules a retry (capped, then dead-lettered).
+ * Receives a privileged, system-scoped context plus the task's idempotency `meta`.
+ * Register handlers in `app.tasks`. */
+export type TaskHandler = (ctx: HandlerContext, payload: unknown, meta: TaskMeta) => void | Promise<void>;
+/** Map of `kind` → handler. Set as `app.tasks`; drained by the DO alarm / a Cron. */
+export type AppTaskMap = Record<string, TaskHandler>;
+
 export type HandlerKind = "query" | "mutation";
 
 export interface Handler<I = unknown, O = unknown> {