@pramen/server 0.0.8 → 0.0.10

package/dist/durable-object.d.ts

@@ -30,9 +30,29 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
      * constructor — see `ensureMigrated`. Guards against re-running. */
     private migrated;
     private 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;
+    private identityLoaded;
     constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp);
     private ensureMigrated;
     fetch(request: Request): Promise<Response>;
+    /** 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 armDrain;
+    /** 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;
+    /** 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 loadIdentity;
+    /** 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 drainTasks;
+    alarm(): Promise<void>;
+    private handleDrain;
+    private handleTasksList;
     webSocketMessage(ws: WebSocket, raw: string | ArrayBuffer): Promise<void>;
     webSocketClose(ws: WebSocket): Promise<void>;
     webSocketError(ws: WebSocket, error: unknown): Promise<void>;

package/dist/durable-object.js

@@ -16,7 +16,8 @@
 // (identity + subscriptions) is stored via serializeAttachment().
 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 } from "./runtime/acl";
@@ -45,6 +46,11 @@ export class PramenDOBase extends DurableObject {
      * constructor — see `ensureMigrated`. Guards against re-running. */
     migrated = false;
     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. */
+    identityPersisted = false;
+    identityLoaded = false;
     constructor(ctx, env, app) {
         super(ctx, env);
         this.app = app;
@@ -78,6 +84,7 @@ export class PramenDOBase extends DurableObject {
             if (this.migrated)
                 return; // a concurrent first request already migrated
             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;
         });
     }
@@ -92,6 +99,15 @@ export class PramenDOBase extends DurableObject {
             this.partition = partitionHeader;
         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);
@@ -99,6 +115,10 @@ export class PramenDOBase extends DurableObject {
             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);
         if (request.headers.get("Upgrade") === "websocket") {
             const { 0: client, 1: server } = new WebSocketPair();
@@ -112,9 +132,11 @@ export class PramenDOBase extends DurableObject {
             input = await request.json().catch(() => undefined);
         }
         try {
-            const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(this.tenant), this.envBag, this.ctxFor(identity), name, input);
+            const { result, kind, touched, enqueued } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(this.tenant), this.envBag, this.ctxFor(identity), name, 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) {
@@ -122,6 +144,63 @@ export class PramenDOBase extends DurableObject {
             return Response.json(body, { status });
         }
     }
+    /** 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. */
+    async armDrain() {
+        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. */
+    taskCtx() {
+        const 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. */
+    async loadIdentity() {
+        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')`, []));
+        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. */
+    async drainTasks() {
+        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());
+    }
+    async alarm() {
+        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));
+    }
+    async handleDrain() {
+        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 });
+    }
+    async handleTasksList(request) {
+        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 ---
     async webSocketMessage(ws, raw) {
         let msg;
@@ -190,10 +269,12 @@ export class PramenDOBase extends DurableObject {
     async onCall(ws, id, name, input) {
         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));
@@ -280,9 +361,12 @@ export class PramenDOBase extends DurableObject {
         // does). Read this DO's partition's key.
         const hashKey = `schema_hash:${this.partition}`;
         const hashRow = (await this.driver.exec(`SELECT value FROM _pramen_meta WHERE key = ?`, [hashKey]));
-        const tableRows = (await this.driver.exec(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> '_pramen_meta'`, []));
+        const tableRows = (await this.driver.exec(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'`, []));
         const tables = {};
         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})`, [])).map((r) => r.name);
         }
         return Response.json({ ok: true, result: { hash: hashRow[0]?.value ?? null, tables } });

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export { isValidUuid } from "./sdk/uuid";
 export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, } from "./sdk/schema";
 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";
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export type { Action, Identity, IdentityMarker, InputMarker, Policy, PolicyRule, PolicyRules, Role, Validator, WhereRule, ConditionalFields, FieldsFn, RelationAclRule, SetValue, ResolverFn, ResolverContext, ResolverDb, } from "./sdk/acl";
 export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, ProjectedRow, RelationsOf, RelationsResult, WhereClause, WhereInput, WhereOps, } from "./sdk/infer";

package/dist/pramen.d.ts

@@ -1,7 +1,7 @@
 import { 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
  * tenant's DO without the handler importing any deploy-side code (so app.ts stays
@@ -33,10 +33,16 @@ 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 declare function createPramen(app: PramenApp): {
     fetch: (request: Request, env: Env) => Promise<Response>;
+    scheduled: (event: unknown, env: Env) => Promise<void>;
     PramenDO: ReturnType<typeof pramenDO>;
 };

package/dist/pramen.js

@@ -13,7 +13,10 @@
 // type-only by worker.ts / durable-object.ts, so there is no runtime import cycle.
 import { makeWorker } from "./worker";
 import { pramenDO } from "./durable-object";
-/** 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) {
-    return { fetch: makeWorker(app).fetch, PramenDO: pramenDO(app) };
+    const worker = makeWorker(app);
+    return { fetch: worker.fetch, scheduled: worker.scheduled, PramenDO: pramenDO(app) };
 }

package/dist/runtime/dispatch.d.ts

@@ -1,12 +1,20 @@
 import { type AclContext } from "./acl";
+import { type TaskMap } from "./outbox";
 import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
 import type { SchemaDef } from "../sdk/schema";
-import type { 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 declare function tasksFacade(driver: Driver, onEnqueue?: () => void): Tasks;
+/** Bind `app.tasks` (which take a ctx) into the ctx-free `TaskMap` the drainer calls. */
+export declare function bindTasks(appTasks: AppTaskMap | undefined, ctx: HandlerContext): TaskMap;
 export declare function dispatch(handlers: HandlerMap, schema: SchemaDef, driver: Driver, kv: Kv, files: Files, env: Readonly<Record<string, unknown>>, acl: AclContext, name: string, input: unknown): Promise<DispatchResult>;

package/dist/runtime/dispatch.js

@@ -10,6 +10,24 @@
 import { Db } from "./db";
 import { warmup } from "./acl";
 import { BadRequest } from "./errors";
+import { enqueueTask } from "./outbox";
+/** The `ctx.tasks` facade over the outbox. `onEnqueue` lets the caller count enqueues
+ * so it can wake the drainer. */
+export function tasksFacade(driver, onEnqueue) {
+    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, ctx) {
+    const out = {};
+    for (const [kind, handler] of Object.entries(appTasks ?? {}))
+        out[kind] = (payload, meta) => handler(ctx, payload, meta);
+    return out;
+}
 export async function dispatch(handlers, schema, driver, kv, files, env, acl, name, input) {
     const handler = handlers[name];
     if (!handler)
@@ -29,9 +47,10 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     const systemDb = new Db(driver, { acl: acl.acl, identity: acl.identity, system: true, schema, partition: acl.partition }, schema);
     const resolved = await warmup(acl.acl, acl.identity, systemDb);
     const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
-    const ctx = { db, kv, files, env, identity: acl.identity };
+    let enqueued = 0;
+    const ctx = { 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/dist/runtime/outbox.d.ts

@@ -0,0 +1,57 @@
+import type { Driver } from "./driver";
+export declare const OUTBOX_TABLE = "_pramen_outbox";
+/** 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 declare function ensureOutbox(driver: Driver): Promise<void>;
+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 declare function enqueueTask(driver: Driver, now: number, opts: EnqueueOpts): Promise<void>;
+/** 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 declare function drainOutbox(driver: Driver, tasks: TaskMap, now: number, limit?: number): Promise<DrainResult>;
+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 declare function listTasks(driver: Driver, opts?: {
+    status?: string;
+    limit?: number;
+}): Promise<TaskRow[]>;

package/dist/runtime/outbox.js

@@ -0,0 +1,128 @@
+// 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.
+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) {
+    return Math.min(2 ** attempts * 1000, 5 * 60_000); // 2s, 4s, 8s, … capped at 5min
+}
+const enc = (driver, params) => 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) {
+    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)`, []);
+}
+/** 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, now, opts) {
+    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) => 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,
+    ]));
+}
+/** 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, tasks, now, limit = 50) {
+    const d = driver.dialect;
+    const ph = (i) => 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),
+    };
+}
+/** 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, opts = {}) {
+    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;
+}

package/dist/sdk/handlers.d.ts

@@ -20,7 +20,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> {
     readonly kind: HandlerKind;

package/dist/worker.d.ts

@@ -39,4 +39,5 @@ export declare function callPrivileged(env: Env, opts: {
  * compiled-ACL + one-time migration) is per-app, held in this closure. */
 export declare function makeWorker(app: PramenApp): {
     fetch(request: Request, env: Env): Promise<Response>;
+    scheduled(_event: unknown, env: Env): Promise<void>;
 };