@pramen/server 0.0.12 → 0.0.14

package/src/runtime/driver.ts

@@ -33,10 +33,20 @@ function checkIdent(name: string): string {
   return name;
 }
 
-/** SQLite (DO SQLite and D1 both speak this). Bare identifiers, `?` placeholders,
- * booleans stored as INTEGER 0/1, RETURNING supported. */
+/** Render an identifier as a standard double-quoted name (`"order"`), guarding its
+ * shape first. SQLite (DO SQLite + D1) and Postgres all accept double-quoted
+ * identifiers, so a column/table named after a reserved word (`order`, `group`, …)
+ * is safe and case is preserved. The single source of truth for both dialects and
+ * the DDL generator — keep every emitted identifier going through this. */
+export function quoteIdent(name: string): string {
+  return `"${checkIdent(name)}"`;
+}
+
+/** SQLite (DO SQLite and D1 both speak this). Double-quoted identifiers (so reserved
+ * words like `order` work), `?` placeholders, booleans stored as INTEGER 0/1,
+ * RETURNING supported. */
 export const sqliteDialect: Dialect = {
-  id: checkIdent,
+  id: quoteIdent,
   placeholder: () => "?",
   returning: true,
   encode: (v) => (typeof v === "boolean" ? (v ? 1 : 0) : v),
@@ -46,7 +56,7 @@ export const sqliteDialect: Dialect = {
  * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
  * RETURNING supported. */
 export const postgresDialect: Dialect = {
-  id: (name) => `"${checkIdent(name)}"`,
+  id: quoteIdent,
   placeholder: (n) => `$${n}`,
   returning: true,
   encode: (v) => v, // the pg driver handles type encoding
@@ -76,19 +86,52 @@ export class DoSqliteDriver implements Driver {
   }
 }
 
-/** D1 — SQLite over RPC. Async by nature. D1 has no interactive transactions, so
- * `transaction()` runs `fn` without one (a documented limitation: mutations don't
- * roll back on throw the way they do on a DO). Use a DO when you need that. */
+/** How a D1Driver's session is anchored (passed to `db.withSession`):
+ *   - `"first-primary"`       — first query hits the primary (current data), the rest
+ *                               read replicas consistent with the session bookmark. Use
+ *                               for a MUTATION (reads must see current data; writes go
+ *                               to primary anyway).
+ *   - `"first-unconstrained"` — first query may hit the nearest replica. Use for a QUERY.
+ *   - a bookmark string       — anchor at a prior write's bookmark for read-your-writes
+ *                               (the client carries it forward via a header).
+ * A bookmark always wins over a constraint when one is supplied. */
+export type D1SessionStart = "first-primary" | "first-unconstrained" | (string & {});
+
+/** D1 — SQLite over RPC. Async by nature.
+ *
+ * Read replicas (Sessions API): every D1Driver opens ONE `db.withSession(start)` and
+ * runs all `exec` through it. Writes in a session always land on the primary; the
+ * `start` only chooses where the FIRST read may begin. The session maintains a
+ * bookmark (`getBookmark()`) so later reads are sequentially consistent with earlier
+ * writes — read-your-writes when the bookmark is threaded across requests.
+ *
+ * ATOMICITY LIMIT (intentional): D1 has NO interactive transactions — a session can't
+ * read mid-`batch()`, and pramen mutations interleave reads + writes + RETURNING +
+ * trigger-into-outbox inside one `transaction()`. So `transaction(fn) = fn()`: each
+ * statement auto-commits on its own, and a multi-statement mutation does NOT roll back
+ * on throw the way it does on a DO. Single-statement mutations are atomic; anything
+ * multi-statement is not. Use the DO store when you need atomic mutations. */
 export class D1Driver implements Driver {
   readonly dialect = sqliteDialect;
-  constructor(private readonly db: D1Database) {}
+  private readonly session: D1DatabaseSession;
+  constructor(db: D1Database, opts?: { start?: D1SessionStart }) {
+    this.session = db.withSession(opts?.start ?? "first-unconstrained");
+  }
 
   async exec(sql: string, params: unknown[]): Promise<Row[]> {
-    const stmt = params.length ? this.db.prepare(sql).bind(...params) : this.db.prepare(sql);
+    const stmt = params.length ? this.session.prepare(sql).bind(...params) : this.session.prepare(sql);
     const { results } = await stmt.all<Row>();
     return results ?? [];
   }
 
+  /** The session's latest bookmark (null before any query). Threaded back to the client
+   * via the `x-pramen-d1-bookmark` response header so a subsequent request can anchor a
+   * fresh session at it and read its own writes. */
+  getBookmark(): string | null {
+    return this.session.getBookmark();
+  }
+
+  // D1 has no interactive/atomic transactions — see the class doc. Run `fn` as-is.
   transaction<T>(fn: () => Promise<T>): Promise<T> {
     return fn();
   }

package/src/runtime/migrate.ts

@@ -20,7 +20,7 @@
 
 import { addColumnSql, createTableSql, indexStatements, sqlType } from "./ddl";
 import { digest } from "./digest";
-import type { Driver } from "./driver";
+import { quoteIdent, type Driver } from "./driver";
 import { entitiesInPartition, validateSchema } from "../sdk/schema";
 import type { EntityFields, FieldDef, SchemaDef } from "../sdk/schema";
 
@@ -66,11 +66,6 @@ function isInternalTable(name: string): boolean {
   );
 }
 
-function ident(name: string): string {
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`invalid identifier: ${name}`);
-  return name;
-}
-
 export function schemaHash(schema: SchemaDef): string {
   const canon: Record<string, unknown> = {};
   for (const [table, def] of Object.entries(schema)) canon[table] = def.fields;
@@ -80,7 +75,7 @@ export function schemaHash(schema: SchemaDef): string {
 /** Live columns of a table -> their declared SQL type (uppercased). Empty if the
  * table doesn't exist. */
 async function tableColumns(driver: Driver, table: string): Promise<Map<string, string>> {
-  const rows = (await driver.exec(`PRAGMA table_info(${ident(table)})`, [])) as { name: string; type: string }[];
+  const rows = (await driver.exec(`PRAGMA table_info(${quoteIdent(table)})`, [])) as { name: string; type: string }[];
   return new Map(rows.map((r) => [r.name, (r.type || "").toUpperCase()]));
 }
 
@@ -98,7 +93,7 @@ async function writeMeta(driver: Driver, key: string, value: string): Promise<vo
  * type change; brand-new columns left NULL), drop the old table, rename the temp. */
 async function rebuildTable(driver: Driver, table: string, def: { fields: EntityFields }, live: Map<string, string>): Promise<void> {
   const tmp = `__pramen_rebuild_${table}`;
-  await driver.exec(`DROP TABLE IF EXISTS ${ident(tmp)}`, []);
+  await driver.exec(`DROP TABLE IF EXISTS ${quoteIdent(tmp)}`, []);
   await driver.exec(createTableSql(tmp, def), []);
 
   const destCols: string[] = [];
@@ -108,14 +103,14 @@ async function rebuildTable(driver: Driver, table: string, def: { fields: Entity
     const src = f.renamedFrom && live.has(f.renamedFrom) ? f.renamedFrom : live.has(name) ? name : undefined;
     if (!src) continue; // brand-new column with no source -> leave NULL
     const target = sqlType(f);
-    destCols.push(ident(name));
-    srcExprs.push(live.get(src) === target ? ident(src) : `CAST(${ident(src)} AS ${target})`);
+    destCols.push(quoteIdent(name));
+    srcExprs.push(live.get(src) === target ? quoteIdent(src) : `CAST(${quoteIdent(src)} AS ${target})`);
   }
   if (destCols.length > 0) {
-    await driver.exec(`INSERT INTO ${ident(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${ident(table)}`, []);
+    await driver.exec(`INSERT INTO ${quoteIdent(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${quoteIdent(table)}`, []);
   }
-  await driver.exec(`DROP TABLE ${ident(table)}`, []);
-  await driver.exec(`ALTER TABLE ${ident(tmp)} RENAME TO ${ident(table)}`, []);
+  await driver.exec(`DROP TABLE ${quoteIdent(table)}`, []);
+  await driver.exec(`ALTER TABLE ${quoteIdent(tmp)} RENAME TO ${quoteIdent(table)}`, []);
 }
 
 export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOptions = {}): Promise<MigrationReport> {
@@ -174,7 +169,7 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
         needsAdditiveRebuild = true;
         continue;
       }
-      await driver.exec(`ALTER TABLE ${ident(table)} ADD COLUMN ${addColumnSql(name, field as FieldDef)}`, []);
+      await driver.exec(`ALTER TABLE ${quoteIdent(table)} ADD COLUMN ${addColumnSql(name, field as FieldDef)}`, []);
       added.push(`${table}.${name}`);
     }
 
@@ -224,7 +219,7 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
   for (const { name } of liveTables) {
     if (isInternalTable(name) || inScope.has(name) || otherPartitionTables.has(name)) continue;
     if (allowDestructive) {
-      await driver.exec(`DROP TABLE ${ident(name)}`, []);
+      await driver.exec(`DROP TABLE ${quoteIdent(name)}`, []);
       droppedTables.push(name);
     } else {
       skipped.push(`drop table ${name}`);

package/src/runtime/queue-consumer.ts

@@ -0,0 +1,97 @@
+// Queue consumer dispatch — the receiving half of ctx.queue. A pramen Worker is the
+// consumer for its declared queues (oblaka `new Queue({ binding: "both", ... })`), so
+// `createPramen(app).queue` is the Cloudflare `queue(batch, env, ctx)` entry. It routes
+// each batch to the matching `app.queues[name]` handler and ACKs/RETRIES per message.
+//
+// A consumer runs in the WORKER, not a Durable Object — a queue message isn't bound to a
+// tenant, so there's no direct `ctx.db`. To touch tenant data, carry the tenant in the
+// message body and `ctx.callPrivileged({ name, input, tenant })` into its DO (exactly
+// like a public route). The consumer still gets `ctx.mail` / `ctx.queue` / `ctx.kv` /
+// `ctx.env`, so the canonical "consume a job → send a notification" path is one call.
+
+import type { Mail } from "./mail";
+import type { Queue } from "./queue";
+import type { Kv } from "./kv";
+
+/** One received message (the Cloudflare Queues `Message` shape). */
+export interface QueueMessage<Body = unknown> {
+  readonly id: string;
+  readonly timestamp: Date;
+  readonly body: Body;
+  /** 1-based delivery attempt — grows on each retry (use it to give up / dead-letter). */
+  readonly attempts: number;
+  /** Mark this message handled (won't be redelivered). The framework calls this for you
+   * when the handler resolves; call it yourself only for fine-grained control. */
+  ack(): void;
+  /** Schedule this message for redelivery (the framework calls it when the handler throws). */
+  retry(options?: { delaySeconds?: number }): void;
+}
+
+/** A batch delivered to the consumer (the Cloudflare Queues `MessageBatch` shape). */
+export interface QueueBatch<Body = unknown> {
+  /** The queue this batch came from (the oblaka `Queue` name; env-prefixed remotely). */
+  readonly queue: string;
+  readonly messages: readonly QueueMessage<Body>[];
+  ackAll(): void;
+  retryAll(options?: { delaySeconds?: number }): void;
+}
+
+/** The context handed to a queue consumer handler. Worker-level (no `ctx.db`): reach
+ * tenant data via `ctx.callPrivileged`. */
+export interface QueueContext {
+  /** The Worker environment (bindings + vars + secrets). */
+  readonly env: Readonly<Record<string, unknown>>;
+  /** Project KV (cross-tenant). */
+  readonly kv: Kv;
+  /** Send email (the notification path). */
+  readonly mail: Mail;
+  /** Enqueue onto a (possibly different) queue — fan-out / chaining. */
+  readonly queue: Queue;
+  /** Apply a privileged mutation into a tenant's DO (the consumer has no direct db).
+   * The message body should carry the `tenant`. */
+  callPrivileged(opts: { name: string; input?: unknown; tenant?: string; roles?: string[]; partition?: string }): Promise<Response>;
+}
+
+/** A queue consumer handler — runs once per message. Resolving ACKs the message;
+ * throwing RETRIES it (subject to the queue's max_retries → dead-letter queue). */
+export type QueueHandler<Body = unknown> = (ctx: QueueContext, message: QueueMessage<Body>) => void | Promise<void>;
+
+/** Map of queue name → consumer handler. Set as `app.queues`; dispatched by
+ * `createPramen(app).queue`. */
+export type AppQueueMap = Record<string, QueueHandler>;
+
+/** Resolve the handler for a batch's queue. Queue names are env-prefixed in remote
+ * environments (`production-pramen-jobs`) but bare locally (`pramen-jobs`), so match
+ * leniently: exact, then suffix (`…-<key>`), then — if there's exactly one handler —
+ * fall through to it (the common single-queue app). Returns null if nothing matches. */
+export function routeQueue(queues: AppQueueMap, queueName: string): QueueHandler | null {
+  const keys = Object.keys(queues);
+  if (queues[queueName]) return queues[queueName];
+  const suffix = keys.find((k) => queueName.endsWith(`-${k}`) || k.endsWith(`-${queueName}`));
+  if (suffix) return queues[suffix];
+  if (keys.length === 1) return queues[keys[0]];
+  return null;
+}
+
+/** Dispatch one batch: route to the handler, then run it per message, ACKing on success
+ * and RETRYing on throw (per message, so one poison message doesn't re-deliver the rest).
+ * An unrouted batch is retried whole (never silently acked) and logged. */
+export async function dispatchQueueBatch(queues: AppQueueMap, ctx: QueueContext, batch: QueueBatch): Promise<void> {
+  const handler = routeQueue(queues, batch.queue);
+  if (!handler) {
+    console.error(`pramen: no app.queues handler for queue '${batch.queue}' — retrying batch (declare it in app.queues)`);
+    batch.retryAll();
+    return;
+  }
+  await Promise.all(
+    batch.messages.map(async (message) => {
+      try {
+        await handler(ctx, message);
+        message.ack();
+      } catch (err) {
+        console.error(`pramen: queue '${batch.queue}' message ${message.id} failed (attempt ${message.attempts}) — retrying`, err);
+        message.retry();
+      }
+    }),
+  );
+}

package/src/runtime/queue.ts

@@ -0,0 +1,155 @@
+// ctx.queue — Cloudflare Queues producer facade, the same shape as ctx.mail / ctx.files:
+// an adapter seam (CloudflareQueueAdapter / MemoryQueueAdapter) behind a thin `Queue`
+// facade, built from the environment. Handlers enqueue onto a native Cloudflare Queue
+// without touching the producer binding directly:
+//
+//   await ctx.queue.send("jobs", { kind: "resize", id });
+//   await ctx.queue.sendBatch("jobs", [{ body: a }, { body: b, delaySeconds: 30 }]);
+//
+// This is distinct from `ctx.tasks` (the transactional outbox). `ctx.tasks.enqueue`
+// is atomic with the mutation's DB write (commit-or-rollback together) and drained
+// in-process. `ctx.queue` is a native Cloudflare Queue: NOT transactional with the
+// write (the message is sent regardless of whether the mutation later rolls back),
+// but higher-throughput, with platform-native batching/retry/DLQ and a consumer that
+// can run in a *different* Worker. Reach for ctx.tasks when the side-effect must commit
+// with the data; reach for ctx.queue for decoupled, high-volume fan-out.
+//
+// On Cloudflare the transport is the Queues producer binding (declared in oblaka.ts as
+// `new Queue({ binding: "both", ... })`). Off-platform / unconfigured, sending to a queue
+// that isn't bound FAILS CLOSED (throws) rather than silently dropping the message —
+// mirroring how ctx.mail fails closed without a transport.
+
+/** Cloudflare Queues content type for a sent message. Omitted ⇒ the platform default
+ * (v8 structured clone). Use "json" for cross-runtime / external consumers. */
+export type QueueContentType = "text" | "bytes" | "json" | "v8";
+
+/** Per-message send options (mirrors the Cloudflare Queues producer API). */
+export interface QueueSendOptions {
+  /** Defer delivery by N seconds (the consumer won't see the message until then). */
+  delaySeconds?: number;
+  /** How the body is serialized on the wire. Omitted ⇒ platform default (v8). */
+  contentType?: QueueContentType;
+}
+
+/** One message in a `sendBatch` — a body plus its own per-message options. */
+export interface QueueSendRequest {
+  body: unknown;
+  delaySeconds?: number;
+  contentType?: QueueContentType;
+}
+
+/** Batch-level send options. */
+export interface QueueBatchOptions {
+  /** Default delay applied to every message in the batch (per-message overrides win). */
+  delaySeconds?: number;
+}
+
+/** The Cloudflare Queues producer binding shape (what `env.<QUEUE>` exposes). A binding
+ * is recognized as a queue producer iff it has BOTH `send` and `sendBatch` (which
+ * distinguishes it from the email `send`-only binding, KV, R2, D1, …). */
+export interface QueueProducerBinding {
+  send(body: unknown, options?: QueueSendOptions): Promise<void>;
+  sendBatch(messages: Iterable<QueueSendRequest>, options?: QueueBatchOptions): Promise<void>;
+}
+
+/** The transport seam — one per backend (Cloudflare Queues, an in-memory capture, …). */
+export interface QueueAdapter {
+  send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void>;
+  sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void>;
+}
+
+/** The `ctx.queue` facade: validates, then delegates to the adapter for a named queue. */
+export class Queue {
+  constructor(private readonly adapter: QueueAdapter) {}
+
+  /** Enqueue a single message onto `queue`. `body` is serialized by the platform. */
+  async send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void> {
+    assertQueueName(queue);
+    if (body === undefined) throw new Error("ctx.queue.send: `body` is required");
+    await this.adapter.send(queue, body, options);
+  }
+
+  /** Enqueue many messages onto `queue` in one call (cheaper than N sends). */
+  async sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void> {
+    assertQueueName(queue);
+    if (!Array.isArray(messages) || messages.length === 0) {
+      throw new Error("ctx.queue.sendBatch: `messages` must be a non-empty array");
+    }
+    for (const m of messages) {
+      if (!m || m.body === undefined) throw new Error("ctx.queue.sendBatch: every message needs a `body`");
+    }
+    await this.adapter.sendBatch(queue, messages, options);
+  }
+}
+
+function assertQueueName(queue: string): void {
+  if (typeof queue !== "string" || queue.length === 0) {
+    throw new Error("ctx.queue: a queue name is required (the oblaka `Queue` name)");
+  }
+}
+
+/** Cloudflare Queues transport. Constructed with the producer bindings discovered from
+ * the environment, keyed by binding name. Sending to a name with no bound queue throws
+ * a clear error (fail-closed) — a missing binding is a config error, not a silent drop. */
+export class CloudflareQueueAdapter implements QueueAdapter {
+  constructor(private readonly bindings: Readonly<Record<string, QueueProducerBinding>>) {}
+
+  private bindingFor(queue: string): QueueProducerBinding {
+    const b = this.bindings[queue];
+    if (!b) {
+      const known = Object.keys(this.bindings);
+      const avail = known.length ? known.join(", ") : "none";
+      throw new Error(
+        `ctx.queue: no queue binding '${queue}' — declare it in oblaka.ts ` +
+          `(new Queue({ name: '${queue}', binding: 'both' })). Bound queues: ${avail}.`,
+      );
+    }
+    return b;
+  }
+
+  async send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void> {
+    await this.bindingFor(queue).send(body, options);
+  }
+
+  async sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void> {
+    await this.bindingFor(queue).sendBatch(messages, options);
+  }
+}
+
+/** In-memory transport: captures sent messages instead of delivering them. For unit
+ * tests (assert on `.sent`) and pure off-platform use. */
+export class MemoryQueueAdapter implements QueueAdapter {
+  readonly sent: Array<{ queue: string; body: unknown; options?: QueueSendOptions | QueueBatchOptions }> = [];
+  async send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void> {
+    this.sent.push({ queue, body, options });
+  }
+  async sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void> {
+    for (const m of messages) this.sent.push({ queue, body: m.body, options: { ...options, ...m } });
+  }
+}
+
+/** Discover the Cloudflare Queues producer bindings in an environment: any value that
+ * exposes BOTH `send` and `sendBatch` functions (which excludes the email `send`-only
+ * binding, KV, R2, D1, the DO namespace, …). Returns name → binding. */
+export function discoverQueueBindings(env: Readonly<Record<string, unknown>>): Record<string, QueueProducerBinding> {
+  const out: Record<string, QueueProducerBinding> = {};
+  for (const [name, value] of Object.entries(env)) {
+    if (
+      value &&
+      typeof value === "object" &&
+      typeof (value as { send?: unknown }).send === "function" &&
+      typeof (value as { sendBatch?: unknown }).sendBatch === "function"
+    ) {
+      out[name] = value as QueueProducerBinding;
+    }
+  }
+  return out;
+}
+
+/** Build `ctx.queue` from the environment: a Cloudflare adapter over the discovered
+ * producer bindings. Sending to an undeclared queue fails closed (the adapter throws).
+ * There is no silent capture fallback — declare the `Queue` binding and it exists in
+ * dev (lopata) and miniflare too. */
+export function createQueue(env: Readonly<Record<string, unknown>>): Queue {
+  return new Queue(new CloudflareQueueAdapter(discoverQueueBindings(env)));
+}

package/src/sdk/app.ts

@@ -14,12 +14,12 @@ export function createApp<S extends SchemaDef>(schema: S) {
   const query = <I = unknown, O = unknown>(
     run: (ctx: Ctx, input: I) => O | Promise<O>,
     opts?: HandlerOpts<I>,
-  ): Handler<I, O> => ({ kind: "query", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition });
+  ): Handler<I, O> => ({ kind: "query", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition, auth: opts?.auth });
 
   const mutation = <I = unknown, O = unknown>(
     run: (ctx: Ctx, input: I) => O | Promise<O>,
     opts?: HandlerOpts<I>,
-  ): Handler<I, O> => ({ kind: "mutation", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition });
+  ): Handler<I, O> => ({ kind: "mutation", run: run as Handler<I, O>["run"], input: opts?.input, partition: opts?.partition, auth: opts?.auth });
 
   return { schema, query, mutation };
 }

package/src/sdk/handlers.ts

@@ -5,6 +5,7 @@
 import type { Db } from "../runtime/db";
 import type { Kv } from "../runtime/kv";
 import type { Mail } from "../runtime/mail";
+import type { Queue } from "../runtime/queue";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
@@ -36,6 +37,12 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
    * runs the matching `app.tasks` handler after commit, off the write path, with
    * retry. For notification email, webhooks, etc. — see `app.tasks`. */
   readonly tasks: Tasks;
+  /** Enqueue onto a native Cloudflare Queue: `ctx.queue.send("jobs", body)`. Unlike
+   * `ctx.tasks` (a transactional outbox, atomic with the mutation, drained in-process),
+   * a queue send is NOT transactional with the write but is higher-throughput, with
+   * platform-native batching/retry/DLQ and a consumer that may live in another Worker.
+   * Declare queues in oblaka.ts; consume them via `app.queues`. */
+  readonly queue: Queue;
 }
 
 /** The deferred-side-effects facade handed to handlers as `ctx.tasks`. */
@@ -62,6 +69,26 @@ export type AppTaskMap = Record<string, TaskHandler>;
 
 export type HandlerKind = "query" | "mutation";
 
+/** Authorization required to CALL a handler, enforced BEFORE its body runs. This is
+ * distinct from the row-level ACL (which gates `ctx.db`): use it to gate handlers that
+ * touch `ctx.kv`/`ctx.env`/`ctx.mail`/`ctx.tasks` directly — those bypass the ACL, so an
+ * un-gated such handler is callable by anyone (incl. anonymous) on an open tenant. Forms:
+ *   - `"authenticated"` — any non-anonymous caller (identity != null)
+ *   - `string[]`        — the caller must hold one of these roles
+ *   - `(identity) => boolean` — a custom predicate
+ * Absent ⇒ open (the prior behavior; a `ctx.db` handler is still ACL-gated). */
+export type HandlerAuth = "authenticated" | readonly string[] | ((identity: Identity | null) => boolean);
+
+/** Evaluate a handler's `auth` requirement against the caller's identity. */
+export function authorizeHandler(auth: HandlerAuth, identity: Identity | null): boolean {
+  if (auth === "authenticated") return identity != null;
+  if (typeof auth === "function") return auth(identity);
+  if (!identity) return false; // a role list can never be satisfied by an anonymous caller
+  const roles = Array.isArray(identity.roles) ? identity.roles : [];
+  const held = identity.role ? [identity.role, ...roles] : roles;
+  return auth.some((r) => held.includes(r));
+}
+
 export interface Handler<I = unknown, O = unknown> {
   readonly kind: HandlerKind;
   // Stored handlers are schema-agnostic; createApp() binds the typed surface.
@@ -74,12 +101,16 @@ export interface Handler<I = unknown, O = unknown> {
    * routes the request to the matching partition-DO before dispatch. Absent ⇒ the
    * default partition (routed to the bare tenant key). */
   readonly partition?: string;
+  /** Optional call-authorization, enforced before the handler runs (see HandlerAuth). */
+  readonly auth?: HandlerAuth;
 }
 
 export interface HandlerOpts<I> {
   input?: (raw: unknown) => I;
   /** DO partition this handler runs in. Absent ⇒ the default partition. */
   partition?: string;
+  /** Authorization to CALL this handler (see HandlerAuth) — gate non-`ctx.db` handlers. */
+  auth?: HandlerAuth;
 }
 
 // Standalone (schema-agnostic) handler factories. Prefer createApp(schema) for a
@@ -88,14 +119,14 @@ export function query<I = unknown, O = unknown>(
   run: (ctx: HandlerContext, input: I) => O | Promise<O>,
   opts?: HandlerOpts<I>,
 ): Handler<I, O> {
-  return { kind: "query", run, input: opts?.input, partition: opts?.partition };
+  return { kind: "query", run, input: opts?.input, partition: opts?.partition, auth: opts?.auth };
 }
 
 export function mutation<I = unknown, O = unknown>(
   run: (ctx: HandlerContext, input: I) => O | Promise<O>,
   opts?: HandlerOpts<I>,
 ): Handler<I, O> {
-  return { kind: "mutation", run, input: opts?.input, partition: opts?.partition };
+  return { kind: "mutation", run, input: opts?.input, partition: opts?.partition, auth: opts?.auth };
 }
 
 // Registry of handlers keyed by RPC name. Uses `any` for the per-handler input/