@pramen/server 0.0.12 → 0.0.14

package/dist/runtime/queue.js

@@ -0,0 +1,110 @@
+// 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.
+/** The `ctx.queue` facade: validates, then delegates to the adapter for a named queue. */
+export class Queue {
+    adapter;
+    constructor(adapter) {
+        this.adapter = adapter;
+    }
+    /** Enqueue a single message onto `queue`. `body` is serialized by the platform. */
+    async send(queue, body, options) {
+        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, messages, options) {
+        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) {
+    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 {
+    bindings;
+    constructor(bindings) {
+        this.bindings = bindings;
+    }
+    bindingFor(queue) {
+        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, body, options) {
+        await this.bindingFor(queue).send(body, options);
+    }
+    async sendBatch(queue, messages, options) {
+        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 {
+    sent = [];
+    async send(queue, body, options) {
+        this.sent.push({ queue, body, options });
+    }
+    async sendBatch(queue, messages, options) {
+        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) {
+    const out = {};
+    for (const [name, value] of Object.entries(env)) {
+        if (value &&
+            typeof value === "object" &&
+            typeof value.send === "function" &&
+            typeof value.sendBatch === "function") {
+            out[name] = value;
+        }
+    }
+    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) {
+    return new Queue(new CloudflareQueueAdapter(discoverQueueBindings(env)));
+}

package/dist/sdk/app.js

@@ -5,7 +5,7 @@
 //   const { query, mutation } = createApp(schema);
 //   const listNotes = query((ctx) => ctx.db.find({ from: "notes" })); // typed!
 export function createApp(schema) {
-    const query = (run, opts) => ({ kind: "query", run: run, input: opts?.input, partition: opts?.partition });
-    const mutation = (run, opts) => ({ kind: "mutation", run: run, input: opts?.input, partition: opts?.partition });
+    const query = (run, opts) => ({ kind: "query", run: run, input: opts?.input, partition: opts?.partition, auth: opts?.auth });
+    const mutation = (run, opts) => ({ kind: "mutation", run: run, input: opts?.input, partition: opts?.partition, auth: opts?.auth });
     return { schema, query, mutation };
 }

package/dist/sdk/handlers.d.ts

@@ -1,6 +1,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";
@@ -31,6 +32,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`. */
 export interface Tasks {
@@ -56,6 +63,17 @@ export type TaskHandler = (ctx: HandlerContext, payload: unknown, meta: TaskMeta
 /** Map of `kind` → handler. Set as `app.tasks`; drained by the DO alarm / a Cron. */
 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 declare function authorizeHandler(auth: HandlerAuth, identity: Identity | null): boolean;
 export interface Handler<I = unknown, O = unknown> {
     readonly kind: HandlerKind;
     readonly run: (ctx: HandlerContext<any>, input: I) => O | Promise<O>;
@@ -66,11 +84,15 @@ 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;
 }
 export declare function query<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;
 export declare function mutation<I = unknown, O = unknown>(run: (ctx: HandlerContext, input: I) => O | Promise<O>, opts?: HandlerOpts<I>): Handler<I, O>;

package/dist/sdk/handlers.js

@@ -1,11 +1,23 @@
 // Handler factories — `query()` and `mutation()`. A query reads; a mutation is
 // wrapped in BEGIN/COMMIT by the dispatcher and
 // rolls back on throw (see runtime/dispatch.ts).
+/** Evaluate a handler's `auth` requirement against the caller's identity. */
+export function authorizeHandler(auth, identity) {
+    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));
+}
 // Standalone (schema-agnostic) handler factories. Prefer createApp(schema) for a
 // typed ctx.db; these remain for untyped/ad-hoc use.
 export function query(run, opts) {
-    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(run, opts) {
-    return { kind: "mutation", run, input: opts?.input, partition: opts?.partition };
+    return { kind: "mutation", run, input: opts?.input, partition: opts?.partition, auth: opts?.auth };
 }

package/dist/worker.d.ts

@@ -1,3 +1,5 @@
+import { type QueueProducerBinding } from "./runtime/queue";
+import { type QueueBatch } from "./runtime/queue-consumer";
 import type { PramenApp } from "./pramen";
 export interface Env {
     PRAMEN: DurableObjectNamespace;
@@ -23,7 +25,25 @@ export interface Env {
     CORS_ORIGINS?: string;
     /** "true" to apply destructive schema migrations on the D1 path. Off by default. */
     PRAMEN_ALLOW_DESTRUCTIVE?: string;
+    /** Default store for /rpc when no `x-pramen-store` header is sent: `"d1"` runs the
+     * Worker+D1 path by default (requires DB bound); `"do"` (the default) routes to the
+     * per-tenant Durable Object. The header still overrides per-request. /live always
+     * needs the DO regardless of this setting. */
+    PRAMEN_STORE?: string;
+    /** Cloudflare Queues producer binding for ctx.queue (declared in oblaka.ts). Optional —
+     * ctx.queue discovers any producer binding by name; this just types the common one. */
+    JOBS?: QueueProducerBinding;
 }
+/** Decide whether an /rpc request runs on the D1 store. **Live queries ALWAYS use the
+ * DO** (they need a single writer + a socket host), regardless of header or default —
+ * so enabling `PRAMEN_STORE=d1` never silently breaks `/live`. Otherwise an explicit
+ * `x-pramen-store` header wins (`d1`/`do`), then the `PRAMEN_STORE` default. Pure +
+ * exported for unit testing. */
+export declare function useD1Store(opts: {
+    storeHeader: string | null;
+    isLive: boolean;
+    defaultStore: string | undefined;
+}): boolean;
 /** Forward a privileged mutation into a tenant's DO from a public route. The
  * synthetic identity (default `["admin"]`) is trusted because the call originates
  * in the Worker — the same internal mechanism the admin endpoints use. Returns the
@@ -40,4 +60,5 @@ export declare function callPrivileged(env: Env, opts: {
 export declare function makeWorker(app: PramenApp): {
     fetch(request: Request, env: Env): Promise<Response>;
     scheduled(_event: unknown, env: Env): Promise<void>;
+    queue(batch: QueueBatch, env: Env): Promise<void>;
 };

package/dist/worker.js

@@ -7,6 +7,8 @@ import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity }
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { createMail } from "./runtime/mail";
+import { createQueue } from "./runtime/queue";
+import { dispatchQueueBatch } from "./runtime/queue-consumer";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -19,6 +21,24 @@ import { DEFAULT_PARTITION } from "./sdk/schema";
 /** The secret used to sign/verify file tokens — a dedicated FILES_SECRET if set,
  * else AUTH_SECRET (so HS256 setups work out of the box). */
 const filesSecret = (env) => env.FILES_SECRET || env.AUTH_SECRET;
+/** Request/response header carrying the D1 session bookmark for read-your-writes: a
+ * client echoes the last response's value on its next request, anchoring a fresh
+ * session at that write so it reads its own writes (even off a lagging replica). */
+const D1_BOOKMARK_HEADER = "x-pramen-d1-bookmark";
+/** Decide whether an /rpc request runs on the D1 store. **Live queries ALWAYS use the
+ * DO** (they need a single writer + a socket host), regardless of header or default —
+ * so enabling `PRAMEN_STORE=d1` never silently breaks `/live`. Otherwise an explicit
+ * `x-pramen-store` header wins (`d1`/`do`), then the `PRAMEN_STORE` default. Pure +
+ * exported for unit testing. */
+export function useD1Store(opts) {
+    if (opts.isLive)
+        return false; // live is DO-only — never the D1 path
+    if (opts.storeHeader === "d1")
+        return true;
+    if (opts.storeHeader === "do")
+        return false;
+    return opts.defaultStore === "d1";
+}
 const json = (body, status = 200) => Response.json(body, { status });
 const forbidden = (what) => json({ ok: false, error: `access denied: ${what}`, code: "forbidden" }, 403);
 const badRequest = (msg) => json({ ok: false, error: msg, code: "bad_request" }, 400);
@@ -34,7 +54,10 @@ function corsHeaders(origin, env) {
     return {
         "access-control-allow-origin": allow.includes("*") ? "*" : origin,
         "access-control-allow-methods": "GET, POST, OPTIONS",
-        "access-control-allow-headers": "content-type, authorization, x-pramen-tenant, x-pramen-store",
+        "access-control-allow-headers": "content-type, authorization, x-pramen-tenant, x-pramen-store, x-pramen-d1-bookmark",
+        // Expose the D1 read-your-writes bookmark so a browser client can read it off the
+        // response and carry it forward on the next request.
+        "access-control-expose-headers": "x-pramen-d1-bookmark",
         vary: "origin",
     };
 }
@@ -52,6 +75,13 @@ function withCors(res, cors) {
  * `tenant` for the default partition (so `idFromName(tenant)` is byte-for-byte unchanged
  * — backward-compat) and `${tenant}:${partition}` for any other partition. */
 function partitionStubFor(env, tenant, partition = DEFAULT_PARTITION) {
+    // Fail with a clear message rather than a cryptic `Cannot read 'get' of undefined`
+    // when the Durable Object isn't bound (e.g. a D1-only deployment that fell through to
+    // the DO path). The Worker RPC surface depends on this binding existing.
+    if (!env.PRAMEN) {
+        throw new Error("pramen: no Durable Object bound (PRAMEN). Pin the D1 store per request with the " +
+            "'x-pramen-store: d1' header (or set PRAMEN_STORE=d1), or bind the PramenDO.");
+    }
     return env.PRAMEN.get(env.PRAMEN.idFromName(partitionDoName(tenant, partition)));
 }
 /** Forward a privileged mutation into a tenant's DO from a public route. The
@@ -112,21 +142,24 @@ export function makeWorker(app) {
         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, suppressTriggers: true }, app.schema);
         const kv = new Kv(env.KV);
-        return { db, kv, files, env: env, identity, tasks: tasksFacade(driver), mail: createMail(env, kv) };
+        return { db, kv, files, env: env, identity, tasks: tasksFacade(driver), mail: createMail(env, kv), queue: createQueue(env) };
     };
     /** 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). */
     const drainD1 = async (env) => {
         if (!env.DB)
             throw new Error("D1 store is not configured");
-        const driver = new D1Driver(env.DB);
+        // The drain reads due tasks then writes their status — pin the primary so it sees
+        // and updates current outbox state (not a lagging replica).
+        const driver = new D1Driver(env.DB, { start: "first-primary" });
         await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
         return drainOutbox(driver, bindTasks(app.tasks, d1TaskCtx(driver, env)), Date.now());
     };
     const listD1Tasks = async (env, status, limit) => {
         if (!env.DB)
             throw new Error("D1 store is not configured");
-        const driver = new D1Driver(env.DB);
+        // Inspection listing — pin the primary so it reflects current outbox state.
+        const driver = new D1Driver(env.DB, { start: "first-primary" });
         await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
         return listTasks(driver, { status, limit });
     };
@@ -294,26 +327,46 @@ export function makeWorker(app) {
             const tenant = req.headers.get("x-pramen-tenant") ?? "main";
             if (!authorizeTenant(identity, tenant))
                 return withCors(forbidden(`tenant '${tenant}'`), cors);
-            // --- Worker + D1 (no DO): the same schema/ACL/read engine over a D1 binding,
-            // selected per-request via `x-pramen-store: d1`. RPC only — live queries need the
-            // DO (single writer + a socket host). This proof uses ONE shared D1 database
-            // across tenants; a real product would add a tenant column or a per-tenant DB.
-            if (req.headers.get("x-pramen-store") === "d1") {
+            // --- Worker + D1 (no DO): the same schema/ACL/read engine over a D1 binding.
+            // Selected per-request via `x-pramen-store: d1`, OR as the app-wide default when
+            // PRAMEN_STORE=d1 (the header still overrides: `x-pramen-store: do` forces the DO).
+            // RPC only — live queries need the DO (single writer + a socket host). This proof
+            // uses ONE shared D1 database across tenants; a real product would add a tenant
+            // column or a per-tenant DB.
+            const storeHeader = req.headers.get("x-pramen-store");
+            const useD1 = useD1Store({ storeHeader, isLive, defaultStore: env.PRAMEN_STORE });
+            if (useD1) {
                 if (!env.DB)
                     return badRequest("D1 store is not configured");
-                if (isLive)
-                    return badRequest("live queries require the default (DO) store");
+                // (isLive is excluded by useD1Store — live always routes to the DO below.)
                 const name = url.pathname.replace(/^\/rpc\//, "");
                 let input;
                 if (request.method === "POST")
                     input = await request.json().catch(() => undefined);
-                const driver = new D1Driver(env.DB);
+                // Pick where the D1 session may start its first read. A client-supplied bookmark
+                // wins (read-your-writes); otherwise default by handler kind: a mutation pins the
+                // primary so its reads see current data, a query may begin at the nearest replica.
+                const inboundBookmark = req.headers.get(D1_BOOKMARK_HEADER);
+                const kind = app.handlers[name]?.kind;
+                let start;
+                if (inboundBookmark)
+                    start = inboundBookmark;
+                else if (kind === "mutation")
+                    start = "first-primary";
+                else
+                    start = "first-unconstrained";
+                const driver = new D1Driver(env.DB, { start });
                 const files = createFiles({ tenant, secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
                 const envBag = env;
                 try {
                     await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
                     const { result } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, envBag, { acl: d1Acl, identity }, name, input);
-                    return withCors(json({ ok: true, result }), cors);
+                    const res = json({ ok: true, result });
+                    // Thread the session's latest bookmark back so the client can read its own writes.
+                    const bookmark = driver.getBookmark();
+                    if (bookmark)
+                        res.headers.set(D1_BOOKMARK_HEADER, bookmark);
+                    return withCors(res, cors);
                 }
                 catch (err) {
                     const { status, body } = toResponse(err);
@@ -338,6 +391,15 @@ export function makeWorker(app) {
             else
                 headers.delete("x-pramen-identity");
             headers.set("x-pramen-partition", partition);
+            // Routed to the DO but no DO is bound — return a clear, actionable error instead of
+            // crashing the whole RPC surface. (A D1-only deployment should pin the D1 store with
+            // the `x-pramen-store: d1` header; the `PRAMEN_STORE` env default can be dropped by
+            // some adapters' env proxies, so the header is the reliable way to pin it.)
+            if (!env.PRAMEN) {
+                return withCors(badRequest(isLive
+                    ? "live queries require a Durable Object, but no PRAMEN binding is configured"
+                    : "no Durable Object (PRAMEN) is bound — pin the D1 store with the 'x-pramen-store: d1' header (or bind the DO)"), cors);
+            }
             const stub = partitionStubFor(env, tenant, partition);
             // WebSocket upgrades (101) must be returned untouched; only add CORS to HTTP.
             const res = await stub.fetch(new Request(req, { headers }));
@@ -349,5 +411,20 @@ export function makeWorker(app) {
             if (env.DB)
                 await drainD1(env);
         },
+        // Cloudflare Queues consumer entry: routes a batch to the matching `app.queues`
+        // handler (ACK on success / RETRY on throw, per message). A consumer is Worker-level
+        // (no tenant DO): its ctx carries env/kv/mail/queue + callPrivileged to reach a DO.
+        async queue(batch, env) {
+            const envBag = env;
+            const kv = new Kv(env.KV);
+            const ctx = {
+                env: envBag,
+                kv,
+                mail: createMail(envBag, kv),
+                queue: createQueue(envBag),
+                callPrivileged: (opts) => callPrivileged(env, opts),
+            };
+            await dispatchQueueBatch(app.queues ?? {}, ctx, batch);
+        },
     };
 }

package/package.json

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

@@ -19,6 +19,7 @@ import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { createMail } from "./runtime/mail";
+import { createQueue } from "./runtime/queue";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
@@ -214,6 +215,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       identity,
       tasks: tasksFacade(this.driver),
       mail: createMail(this.envBag, this.kv),
+      queue: createQueue(this.envBag),
     };
   }
 

package/src/index.ts

@@ -26,8 +26,8 @@ export type {
 
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
-export { query, mutation } from "./sdk/handlers";
-export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
+export { query, mutation, authorizeHandler } from "./sdk/handlers";
+export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap } from "./sdk/handlers";
 
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
@@ -76,6 +76,12 @@ 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";
 
+// --- queue (ctx.queue — Cloudflare Queues) ---
+export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
+export type { QueueAdapter, QueueProducerBinding, QueueSendOptions, QueueSendRequest, QueueBatchOptions, QueueContentType } from "./runtime/queue";
+export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";
+export type { QueueContext, QueueHandler, QueueMessage, QueueBatch, AppQueueMap } from "./runtime/queue-consumer";
+
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 

package/src/pramen.ts

@@ -16,6 +16,7 @@ import { makeWorker, type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
 import { validateTriggerTasks, type SchemaDef } from "./sdk/schema";
 import type { AppTaskMap, HandlerMap } from "./sdk/handlers";
+import type { AppQueueMap, QueueBatch } from "./runtime/queue-consumer";
 import type { Role } from "./sdk/acl";
 
 /** Injected into a public route's handler — forward a privileged mutation into the
@@ -48,6 +49,10 @@ export interface PramenApp {
   /** Deferred side-effect handlers keyed by `kind` — drained from the outbox after a
    * mutation enqueues via `ctx.tasks.enqueue`. For notification email, webhooks, etc. */
   tasks?: AppTaskMap;
+  /** Cloudflare Queues consumers keyed by queue name — process messages produced via
+   * `ctx.queue.send(...)`. Dispatched by `createPramen(app).queue` (a consumer is
+   * Worker-level: no `ctx.db`, reach a tenant via `ctx.callPrivileged`). */
+  queues?: AppQueueMap;
 }
 
 export type { Env, DoEnv };
@@ -58,9 +63,10 @@ export type { Env, DoEnv };
 export function createPramen(app: PramenApp): {
   fetch: (request: Request, env: Env) => Promise<Response>;
   scheduled: (event: unknown, env: Env) => Promise<void>;
+  queue: (batch: QueueBatch, 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) };
+  return { fetch: worker.fetch, scheduled: worker.scheduled, queue: worker.queue, PramenDO: pramenDO(app) };
 }

package/src/runtime/ddl.ts

@@ -3,6 +3,7 @@
 // these are applied.
 
 import type { DefaultValue, EntityFields, FieldDef } from "../sdk/schema";
+import { quoteIdent } from "./driver";
 
 // SQLite has no boolean type; store as INTEGER 0/1. json + fileRef + uuid are
 // stored as TEXT. Exported for the migrator, which compares declared column types
@@ -35,7 +36,7 @@ function defaultSql(f: FieldDef): string {
 }
 
 function columnSql(name: string, f: FieldDef): string {
-  let s = `${name} ${sqlType(f)}`;
+  let s = `${quoteIdent(name)} ${sqlType(f)}`;
   if (f.primaryKey) s += " PRIMARY KEY";
   if (f.autoIncrement) s += " AUTOINCREMENT";
   if (f.notNull && !f.primaryKey) s += " NOT NULL";
@@ -45,14 +46,14 @@ function columnSql(name: string, f: FieldDef): string {
 
 export function createTableSql(table: string, def: { fields: EntityFields }): string {
   const cols = Object.entries(def.fields).map(([n, f]) => columnSql(n, f));
-  return `CREATE TABLE IF NOT EXISTS ${table} (${cols.join(", ")})`;
+  return `CREATE TABLE IF NOT EXISTS ${quoteIdent(table)} (${cols.join(", ")})`;
 }
 
 /** Column definition for ALTER TABLE ADD COLUMN. No PRIMARY KEY / AUTOINCREMENT.
  * NOT NULL is only emitted alongside a DEFAULT (SQLite can't add a bare NOT NULL to
  * a populated table); a DEFAULT alone backfills existing rows. */
 export function addColumnSql(name: string, f: FieldDef): string {
-  let s = `${name} ${sqlType(f)}`;
+  let s = `${quoteIdent(name)} ${sqlType(f)}`;
   if (f.notNull && f.default !== undefined) s += " NOT NULL";
   s += defaultSql(f);
   return s;
@@ -70,7 +71,7 @@ export function indexStatements(table: string, def: { fields: EntityFields }): s
   for (const [col, f] of Object.entries(def.fields)) {
     if (!f.unique && !f.index) continue;
     const kind = f.unique ? "UNIQUE INDEX" : "INDEX";
-    out.push(`CREATE ${kind} IF NOT EXISTS ${indexName(table, col)} ON ${table} (${col})`);
+    out.push(`CREATE ${kind} IF NOT EXISTS ${quoteIdent(indexName(table, col))} ON ${quoteIdent(table)} (${quoteIdent(col)})`);
   }
   return out;
 }

package/src/runtime/dispatch.ts

@@ -10,15 +10,16 @@
 
 import { Db } from "./db";
 import { warmup, type AclContext } from "./acl";
-import { BadRequest } from "./errors";
+import { BadRequest, Forbidden } from "./errors";
 import { enqueueTask, type TaskMap } from "./outbox";
 import { createMail } from "./mail";
+import { createQueue } from "./queue";
 import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
 import type { ResolverDb } from "../sdk/acl";
 import type { SchemaDef } from "../sdk/schema";
-import type { AppTaskMap, HandlerContext, HandlerKind, HandlerMap, Tasks } from "../sdk/handlers";
+import { authorizeHandler, type AppTaskMap, type HandlerContext, type HandlerKind, type HandlerMap, type Tasks } from "../sdk/handlers";
 
 export interface DispatchResult {
   readonly result: unknown;
@@ -60,6 +61,12 @@ export async function dispatch(
   const handler = handlers[name];
   if (!handler) throw new BadRequest(`unknown handler: ${name}`);
 
+  // Per-handler authorization, enforced before any work (input parse / handler body) —
+  // gates handlers that bypass the row-ACL by touching ctx.kv/ctx.env/ctx.mail directly.
+  if (handler.auth && !authorizeHandler(handler.auth, acl.identity)) {
+    throw new Forbidden(`not authorized to call '${name}'`);
+  }
+
   // Validate/parse the request input at the boundary, if the handler declares it.
   let parsed = input;
   if (handler.input) {
@@ -85,6 +92,7 @@ export async function dispatch(
     identity: acl.identity,
     tasks: tasksFacade(driver, () => enqueued++),
     mail: createMail(env, kv),
+    queue: createQueue(env),
   };
 
   const result =