@pramen/server 0.0.9 → 0.0.11

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/sdk/schema.d.ts

@@ -103,16 +103,48 @@ declare const relationBuilders: {
 export type RelationBuilders = typeof relationBuilders;
 /** The default partition name for entities that don't declare one. */
 export declare const DEFAULT_PARTITION = "default";
+export type TriggerOp = "create" | "update" | "delete";
+/** A declarative trigger on an entity: when a matching write commits, the `Db` write
+ * path enqueues a task of `task` (handled by `app.tasks[task]`) IN THE SAME transaction
+ * as the write, with payload `{ entity, op, id, row }`. So a side effect (webhook,
+ * notification email) fires reliably after the write, off the single-writer path —
+ * reusing the whole outbox machinery (retry, idempotency, drain). Only ORM writes
+ * (`ctx.db` insert/update/delete) fire triggers; the raw `ctx.db.exec` escape hatch
+ * does not. */
+export interface TriggerDef {
+    /** The `app.tasks` handler kind that runs the side effect. */
+    readonly task: string;
+    /** Which ops fire it. For `update`, an array names the columns to watch — fire only
+     * when the update writes one of them; `true` fires on any update. */
+    readonly on: {
+        create?: boolean;
+        update?: boolean | readonly string[];
+        delete?: boolean;
+    };
+}
+/** Declare an entity trigger (sugar; returns the def). */
+export declare function trigger(def: TriggerDef): TriggerDef;
+/** Does this trigger fire for `op` given the columns the write touched? */
+export declare function triggerFires(t: TriggerDef, op: TriggerOp, writtenCols: readonly string[]): boolean;
 export interface EntityDef<F extends EntityFields = EntityFields, R extends RelationDefs = Record<string, never>> {
     readonly fields: F;
     readonly relations: R;
     /** The partition (Durable Object class) this entity lives in. Always populated;
      * defaults to `"default"` so downstream code never branches on `undefined`. */
     readonly partition: string;
+    /** Declarative write-triggers (see TriggerDef). Always an array (possibly empty). */
+    readonly triggers: readonly TriggerDef[];
 }
 export declare function Entity<F extends EntityFields, R extends RelationDefs = Record<string, never>>(build: (t: FieldBuilders) => F, relations?: (r: RelationBuilders) => R, opts?: {
     partition?: string;
+    triggers?: readonly TriggerDef[];
 }): EntityDef<F, R>;
+/** The triggers declared on an entity (empty if none / unknown entity). */
+export declare function triggersOf(schema: SchemaDef, entity: string): readonly TriggerDef[];
+/** Throw if any declarative trigger names a `task` not in `taskNames` — caught at
+ * deploy/load by createPramen, so a typo can't silently enqueue a task that never runs
+ * (it would retry then dead-letter). */
+export declare function validateTriggerTasks(schema: SchemaDef, taskNames: Iterable<string>): void;
 /** Annotate a field as renamed from a previous column name (migration hint). Wraps
  * a builder result, preserving its literal field type: `title: renamedFrom(t.text(), "name")`. */
 export declare function renamedFrom<F extends FieldDef>(field: F, from: string): F & {

package/dist/sdk/schema.js

@@ -30,13 +30,48 @@ const relationBuilders = {
 };
 /** The default partition name for entities that don't declare one. */
 export const DEFAULT_PARTITION = "default";
+/** Declare an entity trigger (sugar; returns the def). */
+export function trigger(def) {
+    return def;
+}
+/** Does this trigger fire for `op` given the columns the write touched? */
+export function triggerFires(t, op, writtenCols) {
+    if (op === "create")
+        return t.on.create === true;
+    if (op === "delete")
+        return t.on.delete === true;
+    const u = t.on.update;
+    if (u === true)
+        return true;
+    if (Array.isArray(u))
+        return u.some((f) => writtenCols.includes(f));
+    return false;
+}
 export function Entity(build, relations, opts) {
     return {
         fields: build(builders),
         relations: (relations ? relations(relationBuilders) : {}),
         partition: opts?.partition ?? DEFAULT_PARTITION,
+        triggers: opts?.triggers ?? [],
     };
 }
+/** The triggers declared on an entity (empty if none / unknown entity). */
+export function triggersOf(schema, entity) {
+    return schema[entity]?.triggers ?? [];
+}
+/** Throw if any declarative trigger names a `task` not in `taskNames` — caught at
+ * deploy/load by createPramen, so a typo can't silently enqueue a task that never runs
+ * (it would retry then dead-letter). */
+export function validateTriggerTasks(schema, taskNames) {
+    const known = new Set(taskNames);
+    for (const [entity, def] of Object.entries(schema)) {
+        for (const t of def.triggers) {
+            if (!known.has(t.task)) {
+                throw new Error(`trigger on '${entity}' references task '${t.task}', but app.tasks has no such handler.`);
+            }
+        }
+    }
+}
 /** Annotate a field as renamed from a previous column name (migration hint). Wraps
  * a builder result, preserving its literal field type: `title: renamedFrom(t.text(), "name")`. */
 export function renamedFrom(field, from) {
@@ -151,5 +186,18 @@ export function validateSchema(schema) {
                     `put both entities in the same partition or drop the relation.`);
             }
         }
+        for (const t of def.triggers) {
+            if (!t.task)
+                throw new Error(`trigger on '${entity}' is missing a 'task'.`);
+            if (!t.on.create && !t.on.update && !t.on.delete) {
+                throw new Error(`trigger '${t.task}' on '${entity}' fires on nothing — set on.create/update/delete.`);
+            }
+            const watched = Array.isArray(t.on.update) ? t.on.update : [];
+            for (const f of watched) {
+                if (!(f in def.fields)) {
+                    throw new Error(`trigger '${t.task}' on '${entity}' watches unknown column '${f}'.`);
+                }
+            }
+        }
     }
 }

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>;
 };

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, suppressTriggers: true }, 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.9",
+  "version": "0.0.11",
   "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, suppressTriggers: true },
+      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));
     }
@@ -327,25 +417,21 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     }
   }
 
-  // Introspection: this tenant's applied schema hash + live table/column shape
-  // (admin-gated at the Worker). Powers the CLI's `schema status`.
+  // Introspection: this tenant's applied schema hash + table/column shape (admin-gated
+  // at the Worker). Powers the CLI's `schema status`. Both are read from _pramen_meta
+  // (written by migrate on boot) — NOT a request-time `PRAGMA`/introspection: once the
+  // DO-storage alarm API has run in this object, workerd's SQLite authorizer rejects
+  // PRAGMA (SQLITE_AUTH), so the outbox's alarm would otherwise break this endpoint.
   private async handleSchema(): Promise<Response> {
-    // The applied-schema hash is stored per-partition (migrate keys it
-    // `schema_hash:<partition>` whenever a partition is scoped, which the DO always
-    // 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])) as {
-      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'`,
-      [],
-    )) as { name: string }[];
-    const tables: Record<string, string[]> = {};
-    for (const { name } of tableRows) {
-      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 } });
+    const tablesKey = `schema_tables:${this.partition}`;
+    const rows = (await this.driver.exec(`SELECT key, value FROM _pramen_meta WHERE key IN (?, ?)`, [
+      hashKey,
+      tablesKey,
+    ])) as { key: string; value: string }[];
+    const byKey = new Map(rows.map((r) => [r.key, r.value]));
+    const tables = byKey.has(tablesKey) ? (JSON.parse(byKey.get(tablesKey)!) as Record<string, string[]>) : {};
+    return Response.json({ ok: true, result: { hash: byKey.get(hashKey) ?? null, tables } });
   }
 
   // Generic admin data ops (admin-gated at the Worker). Runs through a SYSTEM-mode

package/src/index.ts

@@ -8,7 +8,8 @@
 // and codegen load an app.ts for its schema without dragging in the DO runtime.
 
 // --- schema authoring ---
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger } from "./sdk/schema";
+export type { TriggerDef, TriggerOp } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type {
   DefaultValue,
@@ -26,7 +27,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";