@pramen/server 0.0.13 → 0.0.15

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/acl.ts

@@ -225,6 +225,12 @@ function resolveMarkers(rule: Record<string, unknown>, identity: Identity | null
     } else {
       const rv = resolveValue(v, identity, input);
       if (rv === UNRESOLVED) return null;
+      // A bare-value marker must only ever produce an EQUALITY comparison. If it
+      // resolves to a caller-controlled non-primitive (object/array), compileWhere
+      // would read it as an operator predicate (`{"gte":""}` → full-table
+      // enumeration), defeating the intended equality. Treat that as unresolvable so
+      // the branch matches nothing (the safe-deny path). Primitives resolve as today.
+      if (isMarker && rv !== null && typeof rv === "object") return null;
       out[key] = rv;
     }
   }
@@ -244,6 +250,24 @@ function pkOf(schema: SchemaDef | undefined, entity: string): string {
   return "id";
 }
 
+/** Reject a relation `where` that filters the target on a column it can't read —
+ * anywhere in the clause, including inside nested AND/OR groups (else a hidden/
+ * unreadable column is LIKE-oracle'able through the subquery). Nested relation keys
+ * are skipped: they're re-scoped against THEIR own target's read scope downstream.
+ * Mirrors Db.assertReadableWhere's recursion for the top-level user `where`. */
+function assertReadableRelationWhere(where: Record<string, unknown>, target: string, fields: string[], ctx: AclContext): void {
+  const targetRels = (ctx.schema?.[target]?.relations ?? {}) as Record<string, unknown>;
+  for (const [k, v] of Object.entries(where)) {
+    if (k === "AND" || k === "OR") {
+      for (const g of v as Record<string, unknown>[]) assertReadableRelationWhere(g, target, fields, ctx);
+    } else if (targetRels[k]) {
+      continue;
+    } else if (!fields.includes(k)) {
+      throw new AclDenied(target, "read", k);
+    }
+  }
+}
+
 /** Compile a relation predicate `{ rel: { … } }` to a subquery, AND-merging the
  * related entity's read scope (and rejecting filters on fields it can't read) so
  * traversal can never widen access beyond a direct read of the target. */
@@ -268,11 +292,7 @@ function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: stri
       inner = FALSE; // can't filter through a relation you can't read
     } else {
       if (tScope.fields !== null) {
-        const targetRels = (ctx.schema?.[rel.target]?.relations ?? {}) as Record<string, unknown>;
-        for (const k of Object.keys(nested as Record<string, unknown>)) {
-          if (k === "AND" || k === "OR" || targetRels[k]) continue;
-          if (!tScope.fields.includes(k)) throw new AclDenied(rel.target, "read", k);
-        }
+        assertReadableRelationWhere(nested as Record<string, unknown>, rel.target, tScope.fields, ctx);
       }
       if (tScope.where) inner = and(inner, tScope.where);
     }

package/src/runtime/db.ts

@@ -32,7 +32,9 @@ import {
   compileExpr,
   compileSelect,
   eq,
+  FALSE,
   inList,
+  isNull,
   or,
   TRUE,
   type AggFn,
@@ -147,15 +149,28 @@ function decodeCursor(s: string): unknown[] {
   }
 }
 
+// Strictly-after predicate for a single order column, NULL-aware. SQLite sorts
+// NULLs FIRST for ASC and LAST for DESC, so a naive `col > v` (which is NULL, never
+// TRUE, when col or v is NULL) would re-match already-seen NULL rows forever.
+//   ASC:  v null    -> any non-null row is after it        (col IS NOT NULL)
+//         v non-null-> col > v (NULL cols excluded, they sort before)
+//   DESC: v null    -> nothing is strictly after a null    (FALSE; PK tiebreak advances)
+//         v non-null-> col < v OR col IS NULL (nulls sort after all non-nulls)
+function keysetCmp(o: OrderBy, value: unknown): SqlExpr {
+  const desc = o.dir === "desc";
+  if (value === null) return desc ? FALSE : isNull(o.column, true);
+  return desc ? or(cmp("<", o.column, value), isNull(o.column)) : cmp(">", o.column, value);
+}
+
 // Strictly-after predicate for a composite key: lexicographic comparison,
-// e.g. (a,b) after (a0,b0) => a>a0 OR (a=a0 AND b>b0); DESC columns flip to <.
+// e.g. (a,b) after (a0,b0) => a>a0 OR (a=a0 AND b>b0); DESC columns flip to <. Each
+// column's comparison and the eq-tiebreaker are NULL-aware (eq() maps null→IS NULL).
 function keysetAfter(order: OrderBy[], values: unknown[]): SqlExpr {
   const ors: SqlExpr[] = [];
   for (let i = 0; i < order.length; i++) {
     const parts: SqlExpr[] = [];
     for (let j = 0; j < i; j++) parts.push(eq(order[j]!.column, values[j]));
-    const o = order[i]!;
-    parts.push(o.dir === "desc" ? cmp("<", o.column, values[i]) : cmp(">", o.column, values[i]));
+    parts.push(keysetCmp(order[i]!, values[i]));
     ors.push(parts.length === 1 ? parts[0]! : and(...parts));
   }
   return ors.length === 1 ? ors[0]! : or(...ors);
@@ -247,6 +262,10 @@ export class Db<S extends SchemaDef = SchemaDef> {
    * and the keyset cursor would otherwise expose a hidden column's values). Columns
    * granted only conditionally are NOT orderable. */
   private assertReadableCols(from: string, scope: Scope, cols: string[]): void {
+    // Hidden columns are never readable through the ORM — not orderable either,
+    // regardless of scope (else the order/keyset cursor leaks the hidden value).
+    const hidden = new Set(this.hiddenColsOf(from));
+    for (const c of cols) if (hidden.has(c)) throw new AclDenied(from, "read", c);
     if (scope.fields === null) return;
     for (const c of cols) if (!scope.fields.includes(c)) throw new AclDenied(from, "read", c);
   }
@@ -344,6 +363,15 @@ export class Db<S extends SchemaDef = SchemaDef> {
       }
     }
 
+    // Hidden columns are never readable through the ORM — reject group-by / aggregating
+    // them UNCONDITIONALLY (independent of scope.fields, which is null under full/SYSTEM
+    // read), else min/max/groupBy over a hidden column exposes its values.
+    const hiddenCols = new Set(this.hiddenColsOf(from));
+    for (const c of groupBy) if (hiddenCols.has(c)) throw new AclDenied(from, "read", c);
+    for (const agg of Object.values(spec.aggregations)) {
+      if (agg.column && hiddenCols.has(agg.column as string)) throw new AclDenied(from, "read", agg.column as string);
+    }
+
     if (scope.fields) {
       const refs = new Set<string>(groupBy);
       for (const agg of Object.values(spec.aggregations)) if (agg.column) refs.add(agg.column as string);
@@ -362,7 +390,29 @@ export class Db<S extends SchemaDef = SchemaDef> {
     // subqueries), then AND-merges the entity's own ACL row scope.
     if (userWhere) this.assertReadableWhere(from, scope, userWhere);
     const userExpr: SqlExpr = userWhere ? compileScopedWhere(userWhere as Record<string, unknown>, from, this.acl) : TRUE;
-    return scope.where ? and(userExpr, scope.where) : userExpr;
+    const where = scope.where ? and(userExpr, scope.where) : userExpr;
+    // A relation-traversal `where` (or a relation-traversing ACL scope) compiles to a
+    // `sub` node over another table. Record those tables in `touched` so the live-query
+    // layer re-checks the subscription when the traversed table changes — else a write
+    // there never intersects the sub's read-set and the client stays stale.
+    this.addTouchedTables(where);
+    return where;
+  }
+
+  /** Walk a compiled predicate and add every relation-subquery target table to
+   * `touched` (the live-query read-set). Recurses into nested subqueries. */
+  private addTouchedTables(expr: SqlExpr | null | undefined): void {
+    if (!expr) return;
+    switch (expr.t) {
+      case "sub":
+        this.touched.add(expr.from);
+        this.addTouchedTables(expr.where);
+        break;
+      case "and":
+      case "or":
+        for (const p of expr.parts) this.addTouchedTables(p);
+        break;
+    }
   }
 
   /** Reject a user `where` that filters on a column the caller cannot read (closes
@@ -401,6 +451,16 @@ export class Db<S extends SchemaDef = SchemaDef> {
       .map(([n]) => n);
   }
 
+  /** Boolean columns — stored as INTEGER 0/1 (SQLite has no boolean), decoded back to
+   * true/false on read so handlers see the `boolean` the InferRow type promises. */
+  private boolColsOf(table: string): string[] {
+    const fields = this.schema[table]?.fields;
+    if (!fields) return [];
+    return Object.entries(fields)
+      .filter(([, f]) => (f as FieldDef).type === "boolean")
+      .map(([n]) => n);
+  }
+
   /** Columns marked `hidden()` — never projected on an ORM read (even SYSTEM/full). */
   private hiddenColsOf(table: string): string[] {
     const fields = this.schema[table]?.fields;
@@ -487,7 +547,8 @@ export class Db<S extends SchemaDef = SchemaDef> {
 
   private decodeRows(table: string, rows: Row[]): Row[] {
     const cols = this.jsonColsOf(table);
-    if (cols.length === 0) return rows;
+    const boolCols = this.boolColsOf(table);
+    if (cols.length === 0 && boolCols.length === 0) return rows;
     for (const row of rows) {
       for (const c of cols) {
         const v = row[c];
@@ -499,6 +560,12 @@ export class Db<S extends SchemaDef = SchemaDef> {
           }
         }
       }
+      // INTEGER 0/1 -> boolean (leave NULL as null for a nullable bool column).
+      for (const c of boolCols) {
+        const v = row[c];
+        if (typeof v === "number") row[c] = v !== 0;
+        else if (typeof v === "bigint") row[c] = v !== 0n;
+      }
     }
     return rows;
   }
@@ -556,7 +623,9 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const scope = this.acl.system ? ALLOW_ALL : resolveRelationScope(this.acl, parentEntity, relName, rel.target);
     if (!scope.allowed) throw new AclDenied(rel.target, "read");
 
-    const project = (row: Row): Row => projectRow(row, effectiveFields(scope, row, this.acl.identity));
+    // Strip hidden() columns from the relation load, like every other read path —
+    // projectRow alone keeps them under a full/allow()/SYSTEM scope (fields === null).
+    const project = (row: Row): Row => this.stripHidden(rel.target, projectRow(row, effectiveFields(scope, row, this.acl.identity)));
     // One IN query per relation (no N+1). Match column before projecting (which
     // may drop the join column).
     const fetchBy = async (col: string, values: unknown[]): Promise<Array<{ key: unknown; row: Row }>> => {
@@ -574,14 +643,16 @@ export class Db<S extends SchemaDef = SchemaDef> {
       for (const { key, row } of await fetchBy(this.pkOf(rel.target), keys)) byId.set(key, row);
       for (const r of rows) r[relName] = r[rel.column] != null ? (byId.get(r[rel.column]) ?? null) : null;
     } else {
-      // hasMany: target[column] -> parent.id
-      const ids = [...new Set(rows.map((r) => r.id).filter((v) => v != null))];
+      // hasMany: target[column] -> parent.<pk> (NOT hardcoded `id` — a parent keyed by
+      // slug/username would otherwise join on an undefined `r.id` and get []).
+      const pk = this.pkOf(parentEntity);
+      const ids = [...new Set(rows.map((r) => r[pk]).filter((v) => v != null))];
       const grouped = new Map<unknown, Row[]>();
       for (const { key, row } of await fetchBy(rel.column, ids)) {
         const bucket = grouped.get(key) ?? grouped.set(key, []).get(key)!;
         bucket.push(row);
       }
-      for (const r of rows) r[relName] = grouped.get(r.id) ?? [];
+      for (const r of rows) r[relName] = grouped.get(r[pk]) ?? [];
     }
   }
 

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
@@ -14,14 +15,27 @@ export const sqlType = (f: FieldDef): string =>
       ? "TEXT"
       : f.type.toUpperCase();
 
-/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1. */
-function defaultLiteral(v: DefaultValue): string {
+/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1.
+ * Exported for the migrator, which reconstructs a column's expected DEFAULT text to
+ * compare against the live `PRAGMA table_info.dflt_value`. */
+export function defaultLiteral(v: DefaultValue): string {
   if (v === null) return "NULL";
   if (typeof v === "boolean") return v ? "1" : "0";
   if (typeof v === "number") return String(v);
   return `'${v.replace(/'/g, "''")}'`;
 }
 
+/** The SQL text of a column's DEFAULT value (the part after `DEFAULT `), or null when
+ * the column declares no default. A raw-SQL `defaultExpr` is returned unquoted (e.g.
+ * `datetime('now')`); a literal `default` is rendered via {@link defaultLiteral}. Used
+ * by the migrator both to detect a default add/change on an existing column and to
+ * COALESCE-backfill a NOT NULL column during a rebuild. */
+export function defaultSqlValue(f: FieldDef): string | null {
+  if (f.defaultExpr !== undefined) return f.defaultExpr;
+  if (f.default !== undefined) return defaultLiteral(f.default);
+  return null;
+}
+
 /** The ` DEFAULT x` fragment for a column, or "" when it has no default. A raw-SQL
  * `defaultExpr` (e.g. `datetime('now')`) is emitted UNQUOTED; a literal `default` is
  * quote-escaped. UNIQUE/index are NOT inline — they're emitted as separate index
@@ -35,7 +49,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 +59,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;
@@ -64,13 +78,17 @@ export function indexName(table: string, col: string): string {
 }
 
 /** CREATE [UNIQUE] INDEX statements for a table's unique/index columns (idempotent
- * via IF NOT EXISTS). Unique wins if a column declares both. */
-export function indexStatements(table: string, def: { fields: EntityFields }): string[] {
+ * via IF NOT EXISTS). Unique wins if a column declares both. `skipCols` omits specific
+ * columns — the migrator uses it to avoid emitting a UNIQUE index that would throw
+ * (duplicate values present on a column that just gained `unique()`); that delta is
+ * reported as skipped instead. */
+export function indexStatements(table: string, def: { fields: EntityFields }, skipCols?: ReadonlySet<string>): string[] {
   const out: string[] = [];
   for (const [col, f] of Object.entries(def.fields)) {
     if (!f.unique && !f.index) continue;
+    if (skipCols?.has(col)) 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();
   }