@pramen/server 0.0.13 → 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/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 {

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.13",
+  "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

@@ -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

@@ -13,6 +13,7 @@ import { warmup, type AclContext } from "./acl";
 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";
@@ -91,6 +92,7 @@ export async function dispatch(
     identity: acl.identity,
     tasks: tasksFacade(driver, () => enqueued++),
     mail: createMail(env, kv),
+    queue: createQueue(env),
   };
 
   const result =

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}`);