@pramen/server 0.0.10 → 0.0.12

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

@@ -6,6 +6,7 @@
 import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
+import { createMail } from "./runtime/mail";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -109,8 +110,9 @@ 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);
-        return { db, kv: new Kv(env.KV), files, env: env, identity, tasks: tasksFacade(driver) };
+        const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
+        const kv = new Kv(env.KV);
+        return { db, kv, files, env: env, identity, tasks: tasksFacade(driver), mail: createMail(env, kv) };
     };
     /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
      * /admin/tasks/drain route with `x-pramen-store: d1`, and by `scheduled()` (Cron). */

package/package.json

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

@@ -18,6 +18,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";
@@ -202,10 +203,18 @@ 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) };
+    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
@@ -417,27 +426,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,
@@ -71,6 +72,10 @@ export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } fro
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 
+// --- mail (ctx.mail) ---
+export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
+
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 

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

@@ -12,6 +12,7 @@ import { Db } from "./db";
 import { warmup, type AclContext } from "./acl";
 import { BadRequest } from "./errors";
 import { enqueueTask, type TaskMap } from "./outbox";
+import { createMail } from "./mail";
 import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
@@ -76,12 +77,21 @@ export async function dispatch(
 
   const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema, partition: acl.partition }, schema);
   let enqueued = 0;
-  const ctx: HandlerContext = { db, kv, files, env, identity: acl.identity, tasks: tasksFacade(driver, () => enqueued++) };
+  const ctx: HandlerContext = {
+    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/src/runtime/mail.ts

@@ -0,0 +1,136 @@
+// 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.
+
+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 class Mail {
+  constructor(
+    private readonly adapter: MailAdapter,
+    private readonly defaultFrom?: MailAddress,
+  ) {}
+
+  async send(message: MailMessage): Promise<void> {
+    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 });
+  }
+}
+
+/** 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 class CloudflareEmailAdapter implements MailAdapter {
+  constructor(private readonly binding: SendEmailBinding) {}
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    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 implements MailAdapter {
+  constructor(private readonly kv: Kv) {}
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    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 implements MailAdapter {
+  readonly sent: Array<MailMessage & { from: MailAddress }> = [];
+  async send(message: MailMessage & { from: MailAddress }): Promise<void> {
+    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 implements MailAdapter {
+  async send(): Promise<void> {
+    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: Readonly<Record<string, unknown>>, kv?: Kv): Mail {
+  const binding = env.EMAIL as SendEmailBinding | undefined;
+  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: MailAddress = { 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/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/handlers.ts

@@ -4,6 +4,7 @@
 
 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";
@@ -17,6 +18,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