@pramen/server 0.0.9 → 0.0.11

package/src/pramen.ts

@@ -14,8 +14,8 @@
 
 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 { validateTriggerTasks, type SchemaDef } from "./sdk/schema";
+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,22 @@ 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) };
+  validateTriggerTasks(app.schema, Object.keys(app.tasks ?? {})); // fail fast on a typo'd trigger task
+  const worker = makeWorker(app);
+  return { fetch: worker.fetch, scheduled: worker.scheduled, PramenDO: pramenDO(app) };
 }

package/src/runtime/acl.ts

@@ -64,6 +64,11 @@ export interface AclContext {
    * lives in a different partition (a partition-DO only owns its own tables). Unset
    * (e.g. the D1/Worker shared-store path) disables the guard — a no-op. */
   readonly partition?: string;
+  /** Suppress declarative write-triggers for this Db. Set on the privileged context
+   * that DRAINS tasks, so a task handler's writes don't re-fire triggers (which would
+   * cascade — a trigger → task → write → trigger loop). Triggers fire on request-path
+   * writes, not on task-handler writes. */
+  readonly suppressTriggers?: boolean;
 }
 
 /** Evaluate every resolver reachable by the identity's roles, once per request.

package/src/runtime/db.ts

@@ -40,8 +40,9 @@ import {
   type SqlExpr,
 } from "./read-engine";
 import { BadRequest } from "./errors";
+import { enqueueTask } from "./outbox";
 import type { Dialect, Driver } from "./driver";
-import { partitionOf, type EntityFields, type FieldDef, type RelationDef, type SchemaDef } from "../sdk/schema";
+import { partitionOf, triggersOf, triggerFires, type EntityFields, type FieldDef, type RelationDef, type SchemaDef, type TriggerOp } from "../sdk/schema";
 import { isValidUuid } from "../sdk/uuid";
 import type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, RelationsOf, RelationsResult, WhereClause } from "../sdk/infer";
 
@@ -52,6 +53,15 @@ type Selected = Partial<Record<string, true>> | undefined;
 
 const DEFAULT_PAGE_SIZE = 50;
 
+/** Compare two decoded cell values for trigger change-detection. Primitives by ===;
+ * json/object cells (already parsed) by structural JSON equality. */
+function cellEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a === "object" || typeof b === "object") return JSON.stringify(a) === JSON.stringify(b);
+  return false;
+}
+
 function normalizeOrder(orderBy: unknown): OrderBy[] | undefined {
   if (!orderBy) return undefined;
   return (Array.isArray(orderBy) ? orderBy : [orderBy]) as OrderBy[];
@@ -154,6 +164,12 @@ function keysetAfter(order: OrderBy[], values: unknown[]): SqlExpr {
 export class Db<S extends SchemaDef = SchemaDef> {
   /** Tables read or written during this Db's lifetime. */
   readonly touched = new Set<string>();
+  /** Tasks enqueued by declarative triggers during this Db's lifetime — the DO adds
+   * this to ctx.tasks enqueues to decide whether to arm its drain alarm. */
+  private taskEnqueueCount = 0;
+  get taskEnqueues(): number {
+    return this.taskEnqueueCount;
+  }
   private readonly dialect: Dialect;
   private readonly acl: AclContext;
 
@@ -403,6 +419,43 @@ export class Db<S extends SchemaDef = SchemaDef> {
     return out;
   }
 
+  /** Fire declarative write-triggers for `op` on `entity`: enqueue a task per matching
+   * trigger into the outbox, in THIS mutation's transaction (atomic with the write).
+   * `row` is the affected row (decoded — new values for create/update, the removed row
+   * for delete); `writtenCols` are the columns the write touched; `before` is the prior
+   * row (update only) for value-change detection on a field-filtered trigger.
+   *
+   * - Hidden columns are STRIPPED from the payload row — `hidden()` ("never readable via
+   *   the ORM, even under SYSTEM") must hold here too, or a secret like passwordHash
+   *   would leak to a task handler / webhook.
+   * - A field-filtered update trigger fires only when a watched column's value actually
+   *   CHANGED (not merely was written to the same value).
+   * - Suppressed in the task-drain context, so a task's own writes don't re-fire
+   *   triggers (preventing a trigger→task→write→trigger cascade). */
+  private async fireTriggers(
+    entity: string,
+    op: TriggerOp,
+    row: Row,
+    writtenCols: string[],
+    before?: Row,
+  ): Promise<void> {
+    if (this.acl.suppressTriggers) return;
+    const triggers = triggersOf(this.schema, entity);
+    if (triggers.length === 0) return;
+    const id = row[this.pkOf(entity)];
+    let safeRow: Row | undefined;
+    for (const t of triggers) {
+      if (!triggerFires(t, op, writtenCols)) continue;
+      if (op === "update" && Array.isArray(t.on.update) && before) {
+        const changed = t.on.update.some((c) => writtenCols.includes(c) && !cellEqual(before[c], row[c]));
+        if (!changed) continue; // watched column(s) written, but value unchanged
+      }
+      if (!safeRow) safeRow = this.stripHidden(entity, row); // never leak hidden columns
+      await enqueueTask(this.driver, Date.now(), { kind: t.task, payload: { entity, op, id, row: safeRow } });
+      this.taskEnqueueCount++;
+    }
+  }
+
   /** Mint a UUID for every `generated()` uuid column the caller omitted, mutating
    * `vals`. Returns the columns it filled — server-minted, so the insert path treats
    * them like forced `set` values (bypassing the writable-field ACL check). */
@@ -558,7 +611,9 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const params = cols.map((c) => this.encodeCell(jsonCols, c, vals[c]));
     const sql = `INSERT INTO ${this.dialect.id(table)} (${colList}) VALUES (${phs})${this.returningClause("*")}`;
     const rows = await this.driver.exec(sql, params);
-    return this.projectWrite(table, this.decodeRow(table, rows[0])!, cols) as InferRow<FieldsOf<S[T]>>;
+    const persisted = this.decodeRow(table, rows[0])!;
+    await this.fireTriggers(table, "create", persisted, cols);
+    return this.projectWrite(table, persisted, cols) as InferRow<FieldsOf<S[T]>>;
   }
 
   /** Project a mutation's RETURNING row so the echo never reveals more than a read
@@ -597,13 +652,18 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const cols = Object.keys(p);
     if (cols.length === 0) return undefined;
 
-    // Per-row field permission is evaluated against the FINAL (post-merge) row, so
-    // fetch the existing row within update scope when any cell-level rule applies.
+    // Fetch the existing row when we need it: for per-row field permission (evaluated
+    // against the FINAL post-merge row) OR for a field-filtered update trigger's
+    // value-change detection (so it fires only on an actual change, not a same-value write).
+    const needCellEval = scope.fields !== null && (scope.conditional.length > 0 || scope.fieldsFns.length > 0);
+    const needBefore = !this.acl.suppressTriggers && triggersOf(this.schema, table).some((t) => Array.isArray(t.on.update));
     let evalRow: Row = p;
-    if (scope.fields !== null && (scope.conditional.length > 0 || scope.fieldsFns.length > 0)) {
+    let before: Row | undefined;
+    if (needCellEval || needBefore) {
       const existing = await this.fetchOne(table, id, scope.where);
       if (!existing) return undefined; // out of update scope -> no-op
-      evalRow = { ...existing, ...p };
+      before = existing;
+      if (needCellEval) evalRow = { ...existing, ...p };
     }
     this.checkWriteFields(table, "update", scope, cols, evalRow, new Set(Object.keys(set)));
     this.runValidators(validators, p);
@@ -622,6 +682,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     sql += this.scopeClause(scope.where, params);
     sql += this.returningClause("*");
     const updated = this.decodeRow(table, (await this.driver.exec(sql, params))[0]);
+    if (updated) await this.fireTriggers(table, "update", updated, cols, before);
     return (updated ? this.projectWrite(table, updated, cols) : undefined) as InferRow<FieldsOf<S[T]>> | undefined;
   }
 
@@ -635,7 +696,9 @@ export class Db<S extends SchemaDef = SchemaDef> {
     let sql = `DELETE FROM ${this.dialect.id(table)} WHERE ${this.dialect.id(this.pkOf(table))} = ${this.dialect.placeholder(1)}`;
     sql += this.scopeClause(scope.where, params);
     sql += this.returningClause("*");
-    return (await this.driver.exec(sql, params)).length > 0;
+    const deleted = this.decodeRow(table, (await this.driver.exec(sql, params))[0]);
+    if (deleted) await this.fireTriggers(table, "delete", deleted, []);
+    return deleted != null;
   }
 
   /** Escape hatch — raw SQL, NOT ACL-checked. For system/internal use only. */

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,14 @@ 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] };
+  // Both explicit ctx.tasks.enqueue and declarative trigger enqueues (in db) count.
+  return { result, kind: handler.kind, touched: [...db.touched], enqueued: enqueued + db.taskEnqueues };
 }

package/src/runtime/migrate.ts

@@ -139,9 +139,15 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
   // `schema_hash` key for backward compatibility (existing stores + the D1 path).
   const subset: SchemaDef = Object.fromEntries(entries);
   const hashKey = opts.partition === undefined ? "schema_hash" : `schema_hash:${opts.partition}`;
+  const tablesKey = opts.partition === undefined ? "schema_tables" : `schema_tables:${opts.partition}`;
+  const tablesValue = () => JSON.stringify(Object.fromEntries(entries.map(([table, def]) => [table, Object.keys(def.fields)])));
   const current = schemaHash(subset);
-  if ((await readMeta(driver, hashKey)) === current)
+  if ((await readMeta(driver, hashKey)) === current) {
+    // Backfill the table map for stores migrated before this key existed (the schema
+    // is unchanged, so it's exactly what's applied).
+    if ((await readMeta(driver, tablesKey)) == null) await writeMeta(driver, tablesKey, tablesValue());
     return { changed: false, created: [], added: [], rebuilt: [], droppedTables: [], skipped: [] };
+  }
 
   const created: string[] = [];
   const added: string[] = [];
@@ -230,6 +236,10 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
   // additive work is idempotent, so re-running is safe.
   if (skipped.length === 0) {
     await writeMeta(driver, hashKey, current);
+    // Persist the applied table→columns so /admin/schema reports it without a raw
+    // PRAGMA at request time — workerd's SQLite authorizer rejects PRAGMA once the
+    // DO-storage alarm API has run in the object. Migrate runs on boot, before any.
+    await writeMeta(driver, tablesKey, tablesValue());
   } else {
     console.warn(
       `pramen: ${skipped.length} destructive migration(s) skipped (set PRAMEN_ALLOW_DESTRUCTIVE=true to apply): ${skipped.join("; ")}`,

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> {

package/src/sdk/schema.ts

@@ -95,26 +95,82 @@ export type RelationBuilders = typeof relationBuilders;
 /** The default partition name for entities that don't declare one. */
 export const DEFAULT_PARTITION = "default";
 
+// --- triggers — declarative "on write → enqueue a task" (layered on the outbox) ---
+
+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 function trigger(def: TriggerDef): TriggerDef {
+  return def;
+}
+
+/** Does this trigger fire for `op` given the columns the write touched? */
+export function triggerFires(t: TriggerDef, op: TriggerOp, writtenCols: readonly string[]): boolean {
+  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 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 function Entity<F extends EntityFields, R extends RelationDefs = Record<string, never>>(
   build: (t: FieldBuilders) => F,
   relations?: (r: RelationBuilders) => R,
-  opts?: { partition?: string },
+  opts?: { partition?: string; triggers?: readonly TriggerDef[] },
 ): EntityDef<F, R> {
   return {
     fields: build(builders),
     relations: (relations ? relations(relationBuilders) : {}) as R,
     partition: opts?.partition ?? DEFAULT_PARTITION,
+    triggers: opts?.triggers ?? [],
   };
 }
 
+/** The triggers declared on an entity (empty if none / unknown entity). */
+export function triggersOf(schema: SchemaDef, entity: string): readonly TriggerDef[] {
+  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: SchemaDef, taskNames: Iterable<string>): void {
+  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<F extends FieldDef>(field: F, from: string): F & { readonly renamedFrom: string } {
@@ -254,5 +310,17 @@ export function validateSchema(schema: SchemaDef): void {
         );
       }
     }
+    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}'.`);
+        }
+      }
+    }
   }
 }