@pramen/server 0.0.9 → 0.0.11

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, 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. */
+    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));
@@ -272,20 +353,21 @@ export class PramenDOBase extends DurableObject {
             return Response.json({ ok: false, error: "point-in-time recovery is unavailable in this environment", code: "unavailable" }, { status: 501 });
         }
     }
-    // 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.
     async handleSchema() {
-        // 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]));
-        const tableRows = (await this.driver.exec(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> '_pramen_meta'`, []));
-        const tables = {};
-        for (const { name } of tableRows) {
-            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 } });
+        const tablesKey = `schema_tables:${this.partition}`;
+        const rows = (await this.driver.exec(`SELECT key, value FROM _pramen_meta WHERE key IN (?, ?)`, [
+            hashKey,
+            tablesKey,
+        ]));
+        const byKey = new Map(rows.map((r) => [r.key, r.value]));
+        const tables = byKey.has(tablesKey) ? JSON.parse(byKey.get(tablesKey)) : {};
+        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
     // Db, so ACL is bypassed — admin can browse/edit any row of any table — while the

package/dist/index.d.ts

@@ -1,9 +1,10 @@
-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, 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/index.js

@@ -7,7 +7,7 @@
 // which only exists in the Workers runtime; keeping it separate lets the CLI, tests,
 // 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 { isValidUuid } from "./sdk/uuid";
 // --- app + handlers ---
 export { createApp } from "./sdk/app";

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 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
  * 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,12 @@
 // 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. */
+import { validateTriggerTasks } from "./sdk/schema";
+/** 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) };
+    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/dist/runtime/acl.d.ts

@@ -30,6 +30,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.
  * Resolvers read through a SYSTEM-mode db (ACL bypassed) to avoid recursion. */

package/dist/runtime/db.d.ts

@@ -62,6 +62,10 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
     private readonly schema;
     /** Tables read or written during this Db's lifetime. */
     readonly touched: 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;
+    get taskEnqueues(): number;
     private readonly dialect;
     private readonly acl;
     constructor(driver: Driver, acl: AclContext, schema: SchemaDef);
@@ -124,6 +128,20 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
     private hiddenColsOf;
     /** Drop hidden columns from a row (copying only if any are present). */
     private stripHidden;
+    /** 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 fireTriggers;
     /** 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). */

package/dist/runtime/db.js

@@ -13,9 +13,21 @@
 import { AclDenied, ALLOW_ALL, compileScopedWhere, effectiveFields, projectRow, resolveRelationScope, resolveScope, resolveWriteRules, } from "./acl";
 import { and, cmp, compileAggregate, compileCount, compileExpr, compileSelect, eq, inList, or, TRUE, } from "./read-engine";
 import { BadRequest } from "./errors";
-import { partitionOf } from "../sdk/schema";
+import { enqueueTask } from "./outbox";
+import { partitionOf, triggersOf, triggerFires } from "../sdk/schema";
 import { isValidUuid } from "../sdk/uuid";
 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, b) {
+    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) {
     if (!orderBy)
         return undefined;
@@ -55,6 +67,12 @@ export class Db {
     schema;
     /** Tables read or written during this Db's lifetime. */
     touched = new Set();
+    /** 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. */
+    taskEnqueueCount = 0;
+    get taskEnqueues() {
+        return this.taskEnqueueCount;
+    }
     dialect;
     acl;
     constructor(driver, acl, schema) {
@@ -283,6 +301,41 @@ export class Db {
             delete out[c];
         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). */
+    async fireTriggers(entity, op, row, writtenCols, before) {
+        if (this.acl.suppressTriggers)
+            return;
+        const triggers = triggersOf(this.schema, entity);
+        if (triggers.length === 0)
+            return;
+        const id = row[this.pkOf(entity)];
+        let safeRow;
+        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). */
@@ -443,7 +496,9 @@ export class Db {
         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);
+        const persisted = this.decodeRow(table, rows[0]);
+        await this.fireTriggers(table, "create", persisted, cols);
+        return this.projectWrite(table, persisted, cols);
     }
     /** Project a mutation's RETURNING row so the echo never reveals more than a read
      * would: the caller's readable fields for this row, PLUS the columns they just
@@ -481,14 +536,20 @@ export class Db {
         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 = p;
-        if (scope.fields !== null && (scope.conditional.length > 0 || scope.fieldsFns.length > 0)) {
+        let before;
+        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);
@@ -506,6 +567,8 @@ export class Db {
         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);
     }
     /** Delete a row by id within scope. Returns whether a row was deleted. */
@@ -519,7 +582,10 @@ export class Db {
         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. */
     async exec(sql, ...params) {

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,11 @@ 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] };
+    // 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/dist/runtime/migrate.js

@@ -98,9 +98,16 @@ export async function migrate(driver, schema, opts = {}) {
     // `schema_hash` key for backward compatibility (existing stores + the D1 path).
     const subset = 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 = [];
     const added = [];
     const rebuilt = [];
@@ -186,6 +193,10 @@ export async function migrate(driver, schema, opts = {}) {
     // 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/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[]>;