npm - @pramen/server - Versions diffs - 0.0.13 → 0.0.14 - Mend

@pramen/server 0.0.13 → 0.0.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (30) hide show

package/dist/durable-object.js +2 -0
package/dist/index.d.ts +4 -0
package/dist/index.js +3 -0
package/dist/pramen.d.ts +6 -0
package/dist/pramen.js +1 -1
package/dist/runtime/ddl.js +5 -4
package/dist/runtime/dispatch.js +2 -0
package/dist/runtime/driver.d.ts +41 -7
package/dist/runtime/driver.js +38 -11
package/dist/runtime/migrate.d.ts +1 -1
package/dist/runtime/migrate.js +10 -14
package/dist/runtime/queue-consumer.d.ts +64 -0
package/dist/runtime/queue-consumer.js +46 -0
package/dist/runtime/queue.d.ts +72 -0
package/dist/runtime/queue.js +110 -0
package/dist/sdk/handlers.d.ts +7 -0
package/dist/worker.d.ts +21 -0
package/dist/worker.js +90 -13
package/package.json +1 -1
package/src/durable-object.ts +2 -0
package/src/index.ts +6 -0
package/src/pramen.ts +7 -1
package/src/runtime/ddl.ts +5 -4
package/src/runtime/dispatch.ts +2 -0
package/src/runtime/driver.ts +52 -9
package/src/runtime/migrate.ts +10 -15
package/src/runtime/queue-consumer.ts +97 -0
package/src/runtime/queue.ts +155 -0
package/src/sdk/handlers.ts +7 -0
package/src/worker.ts +105 -13

package/src/runtime/queue-consumer.ts ADDED Viewed

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

@@ -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/handlers.ts CHANGED Viewed

@@ -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`. */

package/src/worker.ts CHANGED Viewed

@@ -8,10 +8,12 @@ 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, type QueueProducerBinding } from "./runtime/queue";
+import { dispatchQueueBatch, type QueueBatch, type QueueContext } from "./runtime/queue-consumer";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
-import { D1Driver, type Driver } from "./runtime/driver";
+import { D1Driver, type D1SessionStart, type Driver } from "./runtime/driver";
 import { toResponse } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
 import { listDOs, partitionDoName } from "./runtime/registry";
@@ -45,12 +47,37 @@ 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;
 }
 /** 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): string => 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: { storeHeader: string | null; isLive: boolean; defaultStore: string | undefined }): boolean {
+  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: unknown, status = 200) => Response.json(body, { status });
 const forbidden = (what: string) => json({ ok: false, error: `access denied: ${what}`, code: "forbidden" }, 403);
 const badRequest = (msg: string) => json({ ok: false, error: msg, code: "bad_request" }, 400);
@@ -65,7 +92,10 @@ function corsHeaders(origin: string | null, env: Env): Record<string, string> {
   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",
   };
 }
@@ -83,6 +113,15 @@ function withCors(res: Response, cors: Record<string, string>): Response {
  * `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: Env, tenant: string, partition: string = DEFAULT_PARTITION): DurableObjectStub {
+  // 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)));
 }
@@ -151,21 +190,24 @@ export function makeWorker(app: PramenApp) {
     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 as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv) };
+    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv), queue: createQueue(env as unknown as Record<string, unknown>) };
   };
   /** 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: Env): Promise<unknown> => {
     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: Env, status?: string, limit?: number): Promise<unknown> => {
     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 });
   };
@@ -344,23 +386,42 @@ export function makeWorker(app: PramenApp) {
     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: unknown;
       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: D1SessionStart;
+      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 as unknown as Record<string, unknown>;
       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);
         return withCors(json(body, status), cors);
@@ -384,6 +445,21 @@ export function makeWorker(app: PramenApp) {
     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 }));
@@ -395,5 +471,21 @@ export function makeWorker(app: PramenApp) {
     async scheduled(_event: unknown, env: Env): Promise<void> {
       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: QueueBatch, env: Env): Promise<void> {
+      const envBag = env as unknown as Record<string, unknown>;
+      const kv = new Kv(env.KV);
+      const ctx: QueueContext = {
+        env: envBag,
+        kv,
+        mail: createMail(envBag, kv),
+        queue: createQueue(envBag),
+        callPrivileged: (opts) => callPrivileged(env, opts),
+      };
+      await dispatchQueueBatch(app.queues ?? {}, ctx, batch);
+    },
   };
 }