@pramen/server 0.0.10 → 0.0.12

package/dist/durable-object.js

@@ -17,6 +17,7 @@
 import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
+import { createMail } from "./runtime/mail";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
@@ -153,8 +154,16 @@ 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);
-        return { db, kv: this.kv, files: this.filesFor(this.tenant), env: this.envBag, identity, tasks: tasksFacade(this.driver) };
+        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),
+            mail: createMail(this.envBag, this.kv),
+        };
     }
     /** 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. */
@@ -353,23 +362,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";
@@ -10,6 +11,8 @@ export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, Pro
 export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
 export type { Driver, Dialect, Row } from "./runtime/driver";

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";
@@ -15,6 +15,8 @@ export { query, mutation } from "./sdk/handlers";
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
+// --- mail (ctx.mail) ---
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 // --- substrate seam (advanced: bring your own SQL backend) ---

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

@@ -11,6 +11,7 @@ import { Db } from "./db";
 import { warmup } from "./acl";
 import { BadRequest } from "./errors";
 import { enqueueTask } from "./outbox";
+import { createMail } from "./mail";
 /** The `ctx.tasks` facade over the outbox. `onEnqueue` lets the caller count enqueues
  * so it can wake the drainer. */
 export function tasksFacade(driver, onEnqueue) {
@@ -48,9 +49,18 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     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);
     let enqueued = 0;
-    const ctx = { db, kv, files, env, identity: acl.identity, tasks: tasksFacade(driver, () => enqueued++) };
+    const ctx = {
+        db,
+        kv,
+        files,
+        env,
+        identity: acl.identity,
+        tasks: tasksFacade(driver, () => enqueued++),
+        mail: createMail(env, kv),
+    };
     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/mail.d.ts

@@ -0,0 +1,80 @@
+import type { Kv } from "./kv";
+export interface MailAddress {
+    email: string;
+    name?: string;
+}
+export interface MailMessage {
+    to: string | string[];
+    /** Sender. Optional — defaults to MAIL_FROM (a verified address). */
+    from?: MailAddress;
+    subject: string;
+    text?: string;
+    html?: string;
+    replyTo?: string | MailAddress;
+}
+/** The transport seam. One per backend (Cloudflare Email Sending, a dev stash, …). */
+export interface MailAdapter {
+    /** Deliver a fully-resolved message (`from` already filled by the facade). */
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export declare class Mail {
+    private readonly adapter;
+    private readonly defaultFrom?;
+    constructor(adapter: MailAdapter, defaultFrom?: MailAddress | undefined);
+    send(message: MailMessage): Promise<void>;
+}
+/** The Cloudflare `send_email` binding shape (workers binding form: `from` uses `email`). */
+export interface SendEmailBinding {
+    send(message: {
+        to: string | string[];
+        from: MailAddress;
+        subject: string;
+        text?: string;
+        html?: string;
+        replyTo?: string | MailAddress;
+    }): Promise<void>;
+}
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export declare class CloudflareEmailAdapter implements MailAdapter {
+    private readonly binding;
+    constructor(binding: SendEmailBinding);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export declare class KvMailAdapter implements MailAdapter {
+    private readonly kv;
+    constructor(kv: Kv);
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export declare class MemoryMailAdapter implements MailAdapter {
+    readonly sent: Array<MailMessage & {
+        from: MailAddress;
+    }>;
+    send(message: MailMessage & {
+        from: MailAddress;
+    }): Promise<void>;
+}
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export declare class UnconfiguredMailAdapter implements MailAdapter {
+    send(): Promise<void>;
+}
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export declare function createMail(env: Readonly<Record<string, unknown>>, kv?: Kv): Mail;

package/dist/runtime/mail.js

@@ -0,0 +1,102 @@
+// ctx.mail — transactional-ish email facade, the same shape as ctx.files: an adapter
+// seam (CloudflareEmailAdapter / KvMailAdapter / MemoryMailAdapter) behind a thin
+// `Mail` facade, chosen from the environment. Handlers send mail without touching the
+// `send_email` binding directly:
+//
+//   await ctx.mail.send({ to: "u@x.com", subject: "Welcome", text: "…" });
+//
+// On Cloudflare the transport is Cloudflare Email Sending (the `send_email`/`EMAIL`
+// binding, no API keys). With no verified sender configured (local/dev), mail is
+// captured instead of sent — to KV (so an e2e/dashboard can read the "inbox") or
+// in-memory — so handlers work unchanged off-platform.
+/** The `ctx.mail` facade: resolves the sender, validates, and delegates to the adapter. */
+export class Mail {
+    adapter;
+    defaultFrom;
+    constructor(adapter, defaultFrom) {
+        this.adapter = adapter;
+        this.defaultFrom = defaultFrom;
+    }
+    async send(message) {
+        const to = Array.isArray(message.to) ? message.to : [message.to];
+        if (to.length === 0 || to.some((a) => typeof a !== "string" || a.length === 0)) {
+            throw new Error("ctx.mail.send: `to` is required");
+        }
+        if (typeof message.subject !== "string" || message.subject.length === 0) {
+            throw new Error("ctx.mail.send: `subject` is required");
+        }
+        const from = message.from ?? this.defaultFrom;
+        if (!from)
+            throw new Error("ctx.mail.send: no sender — set the MAIL_FROM var or pass `from`");
+        await this.adapter.send({ ...message, from });
+    }
+}
+/** Cloudflare Email Sending — sends via the `send_email` binding (no API keys). The
+ * `from` domain must be onboarded (`wrangler email sending enable yourdomain.com`). */
+export class CloudflareEmailAdapter {
+    binding;
+    constructor(binding) {
+        this.binding = binding;
+    }
+    async send(message) {
+        await this.binding.send({
+            to: message.to,
+            from: message.from,
+            subject: message.subject,
+            text: message.text,
+            html: message.html,
+            replyTo: message.replyTo,
+        });
+    }
+}
+/** Dev/test transport: stash the message in KV under `mail:<recipient>` so an e2e suite
+ * (or a dashboard) can read the "inbox" instead of really sending. */
+export class KvMailAdapter {
+    kv;
+    constructor(kv) {
+        this.kv = kv;
+    }
+    async send(message) {
+        const to = Array.isArray(message.to) ? message.to : [message.to];
+        const value = JSON.stringify({ from: message.from, subject: message.subject, text: message.text, html: message.html });
+        for (const addr of to)
+            await this.kv.put(`mail:${addr}`, value, { expirationTtl: 900 });
+    }
+}
+/** In-memory transport: captures sent messages (pure; for unit tests). */
+export class MemoryMailAdapter {
+    sent = [];
+    async send(message) {
+        this.sent.push(message);
+    }
+}
+/** Fail-closed transport: no real sender and no explicit dev-capture opt-in, so a
+ * `send` THROWS rather than silently capturing. Prevents a misconfigured production
+ * (no MAIL_FROM) from writing security emails — magic-link tokens, resets — into KV
+ * instead of delivering them. Mirrors how files fail closed without FILES_SECRET. */
+export class UnconfiguredMailAdapter {
+    async send() {
+        throw new Error("ctx.mail: no transport configured — set MAIL_FROM (with the EMAIL binding) to send, " +
+            "or MAIL_CAPTURE=true to capture in dev.");
+    }
+}
+/** Build `ctx.mail` from the environment:
+ *  - `EMAIL` binding + `MAIL_FROM` → Cloudflare Email Sending (real send).
+ *  - else `MAIL_CAPTURE=true` → capture (KV inbox if a Kv is given, else in-memory) with
+ *    a synthetic dev sender — an EXPLICIT dev opt-in, never the production default.
+ *  - else → fail closed: a `send` throws (so a missing-MAIL_FROM prod doesn't silently
+ *    stash security emails in KV). */
+export function createMail(env, kv) {
+    const binding = env.EMAIL;
+    const fromAddr = typeof env.MAIL_FROM === "string" && env.MAIL_FROM ? env.MAIL_FROM : undefined;
+    if (binding && fromAddr) {
+        const name = typeof env.MAIL_FROM_NAME === "string" ? env.MAIL_FROM_NAME : undefined;
+        return new Mail(new CloudflareEmailAdapter(binding), { email: fromAddr, name });
+    }
+    if (env.MAIL_CAPTURE === "true") {
+        const devFrom = { email: "dev@pramen.local", name: "pramen (dev)" };
+        return new Mail(kv ? new KvMailAdapter(kv) : new MemoryMailAdapter(), devFrom);
+    }
+    // Sentinel `from` so the facade delegates to the adapter, which throws the clear error.
+    return new Mail(new UnconfiguredMailAdapter(), { email: "unconfigured@invalid" });
+}

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

@@ -1,5 +1,6 @@
 import type { Db } from "../runtime/db";
 import type { Kv } from "../runtime/kv";
+import type { Mail } from "../runtime/mail";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
@@ -12,6 +13,11 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
     /** Per-tenant file storage: mint signed upload/download urls, head/delete blobs.
      * Bytes flow through the Worker /files/* route, never through the DO. */
     readonly files: Files;
+    /** Send email: `ctx.mail.send({ to, subject, text/html })`. On Cloudflare this is
+     * Cloudflare Email Sending (the `send_email` binding); off-platform / unconfigured it
+     * captures instead of sending. Prefer enqueuing the send as a task (see `ctx.tasks`)
+     * so it runs off the single-writer write path. */
+    readonly mail: Mail;
     /** The Worker/DO environment — bindings (KV, R2, DB, …) plus vars and secrets
      * (AUTH_SECRET, plus anything in wrangler.jsonc / .dev.vars / `wrangler secret`).
      * Use it to call external services from handlers — Cloudflare bindings (e.g. the

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