@pramen/server 0.0.10 → 0.0.11

package/dist/durable-object.js

@@ -153,7 +153,7 @@ export class PramenDOBase extends DurableObject {
      * Task handlers get full db access + env (e.g. ctx.env.EMAIL) + their own ctx.tasks. */
     taskCtx() {
         const identity = { roles: ["admin"] };
-        const db = new Db(this.driver, { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition }, this.app.schema);
+        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
@@ -353,23 +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_%'`, []));
-        const tables = {};
-        for (const { name } of tableRows) {
-            // Skip pramen's internal bookkeeping tables (_pramen_meta, _pramen_outbox, …).
-            if (name.toLowerCase().startsWith("_pramen") || name.toLowerCase().startsWith("__pramen"))
-                continue;
-            tables[name] = (await this.driver.exec(`PRAGMA table_info(${name})`, [])).map((r) => r.name);
-        }
-        return Response.json({ ok: true, result: { hash: hashRow[0]?.value ?? null, tables } });
+        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,4 +1,5 @@
-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";

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,6 +1,6 @@
 import { type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
-import type { SchemaDef } from "./sdk/schema";
+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

package/dist/pramen.js

@@ -13,10 +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";
+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) {
+    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.js

@@ -52,5 +52,6 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     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], enqueued };
+    // 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/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.js

@@ -109,7 +109,7 @@ export function makeWorker(app) {
     const d1TaskCtx = (driver, env) => {
         const identity = { roles: ["admin"] };
         const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
-        const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema }, app.schema);
+        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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.10",
+  "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

@@ -202,7 +202,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     const identity: Identity = { roles: ["admin"] };
     const db = new Db(
       this.driver,
-      { acl: this.acl, identity, system: true, schema: this.app.schema, partition: this.partition },
+      { 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) };
@@ -417,27 +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_%'`,
-      [],
-    )) as { name: string }[];
-    const tables: Record<string, string[]> = {};
-    for (const { name } of tableRows) {
-      // Skip pramen's internal bookkeeping tables (_pramen_meta, _pramen_outbox, …).
-      if (name.toLowerCase().startsWith("_pramen") || name.toLowerCase().startsWith("__pramen")) continue;
-      tables[name] = ((await this.driver.exec(`PRAGMA table_info(${name})`, [])) as { name: string }[]).map((r) => r.name);
-    }
-    return Response.json({ ok: true, result: { hash: hashRow[0]?.value ?? null, tables } });
+    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,

package/src/pramen.ts

@@ -14,7 +14,7 @@
 
 import { makeWorker, type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
-import type { SchemaDef } from "./sdk/schema";
+import { validateTriggerTasks, type SchemaDef } from "./sdk/schema";
 import type { AppTaskMap, HandlerMap } from "./sdk/handlers";
 import type { Role } from "./sdk/acl";
 
@@ -60,6 +60,7 @@ export function createPramen(app: PramenApp): {
   scheduled: (event: unknown, env: Env) => Promise<void>;
   PramenDO: ReturnType<typeof pramenDO>;
 } {
+  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

@@ -83,5 +83,6 @@ export async function dispatch(
       ? await handler.run(ctx, parsed)
       : await driver.transaction(async () => handler.run(ctx, parsed));
 
-  return { result, kind: handler.kind, touched: [...db.touched], enqueued };
+  // 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/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}'.`);
+        }
+      }
+    }
   }
 }

package/src/worker.ts

@@ -148,7 +148,7 @@ export function makeWorker(app: PramenApp) {
   const d1TaskCtx = (driver: Driver, env: Env): HandlerContext => {
     const identity: Identity = { roles: ["admin"] };
     const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
-    const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema }, app.schema);
+    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 as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver) };
   };