@pramen/server 0.0.12 → 0.0.14

package/dist/durable-object.js

@@ -18,6 +18,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";
@@ -163,6 +164,7 @@ export class PramenDOBase extends DurableObject {
             identity,
             tasks: tasksFacade(this.driver),
             mail: createMail(this.envBag, this.kv),
+            queue: createQueue(this.envBag),
         };
     }
     /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export type { TriggerDef, TriggerOp } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, } from "./sdk/schema";
 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";
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export type { Action, Identity, IdentityMarker, InputMarker, Policy, PolicyRule, PolicyRules, Role, Validator, WhereRule, ConditionalFields, FieldsFn, RelationAclRule, SetValue, ResolverFn, ResolverContext, ResolverDb, } from "./sdk/acl";
 export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, ProjectedRow, RelationsOf, RelationsResult, WhereClause, WhereInput, WhereOps, } from "./sdk/infer";
@@ -13,6 +13,10 @@ export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runt
 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";
+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";
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
 export type { Driver, Dialect, Row } from "./runtime/driver";

package/dist/index.js

@@ -11,12 +11,15 @@ export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, de
 export { isValidUuid } from "./sdk/uuid";
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
-export { query, mutation } from "./sdk/handlers";
+export { query, mutation, authorizeHandler } from "./sdk/handlers";
 // --- ACL ---
 export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
 // --- mail (ctx.mail) ---
 export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
+// --- queue (ctx.queue — Cloudflare Queues) ---
+export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
+export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";
 // --- errors ---
 export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
 // --- substrate seam (advanced: bring your own SQL backend) ---

package/dist/pramen.d.ts

@@ -2,6 +2,7 @@ import { type Env } from "./worker";
 import { pramenDO, type DoEnv } from "./durable-object";
 import { 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
  * tenant's DO without the handler importing any deploy-side code (so app.ts stays
@@ -36,6 +37,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 };
 /** Build the deployable pair for an app. `scheduled` is a Cron Trigger entry that
@@ -44,5 +49,6 @@ export type { Env, DoEnv };
 export declare 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>;
 };

package/dist/pramen.js

@@ -20,5 +20,5 @@ import { validateTriggerTasks } from "./sdk/schema";
 export function createPramen(app) {
     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/dist/runtime/ddl.js

@@ -1,6 +1,7 @@
 // DDL generation — CREATE TABLE for a new entity and the additive ALTER fragment
 // for a new column. Runs in TS inside the isolate; see runtime/migrate.ts for how
 // these are applied.
+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
 // (and CASTs on a type change).
@@ -32,7 +33,7 @@ function defaultSql(f) {
     return f.default !== undefined ? ` DEFAULT ${defaultLiteral(f.default)}` : "";
 }
 function columnSql(name, f) {
-    let s = `${name} ${sqlType(f)}`;
+    let s = `${quoteIdent(name)} ${sqlType(f)}`;
     if (f.primaryKey)
         s += " PRIMARY KEY";
     if (f.autoIncrement)
@@ -44,13 +45,13 @@ function columnSql(name, f) {
 }
 export function createTableSql(table, def) {
     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, f) {
-    let s = `${name} ${sqlType(f)}`;
+    let s = `${quoteIdent(name)} ${sqlType(f)}`;
     if (f.notNull && f.default !== undefined)
         s += " NOT NULL";
     s += defaultSql(f);
@@ -68,7 +69,7 @@ export function indexStatements(table, def) {
         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/dist/runtime/dispatch.d.ts

@@ -4,7 +4,7 @@ import type { Driver } from "./driver";
 import type { Kv } from "./kv";
 import type { Files } from "../sdk/files";
 import type { SchemaDef } from "../sdk/schema";
-import type { AppTaskMap, HandlerContext, HandlerKind, HandlerMap, Tasks } from "../sdk/handlers";
+import { type AppTaskMap, type HandlerContext, type HandlerKind, type HandlerMap, type Tasks } from "../sdk/handlers";
 export interface DispatchResult {
     readonly result: unknown;
     readonly kind: HandlerKind;

package/dist/runtime/dispatch.js

@@ -9,9 +9,11 @@
 // layer can match a mutation's writes against each subscription's reads.
 import { Db } from "./db";
 import { warmup } from "./acl";
-import { BadRequest } from "./errors";
+import { BadRequest, Forbidden } from "./errors";
 import { enqueueTask } from "./outbox";
 import { createMail } from "./mail";
+import { createQueue } from "./queue";
+import { authorizeHandler } from "../sdk/handlers";
 /** The `ctx.tasks` facade over the outbox. `onEnqueue` lets the caller count enqueues
  * so it can wake the drainer. */
 export function tasksFacade(driver, onEnqueue) {
@@ -33,6 +35,11 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     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) {
@@ -57,6 +64,7 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
         identity: acl.identity,
         tasks: tasksFacade(driver, () => enqueued++),
         mail: createMail(env, kv),
+        queue: createQueue(env),
     };
     const result = handler.kind === "query"
         ? await handler.run(ctx, parsed)

package/dist/runtime/driver.d.ts

@@ -9,8 +9,15 @@ export interface Dialect {
     /** Coerce a JS value for binding (e.g. boolean → 0/1 on SQLite). */
     encode(v: unknown): unknown;
 }
-/** 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 declare function quoteIdent(name: string): string;
+/** 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 declare const sqliteDialect: Dialect;
 /** Postgres (e.g. over Hyperdrive). Double-quoted identifiers preserve case (so
  * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
@@ -33,13 +40,40 @@ export declare class DoSqliteDriver implements Driver {
     exec(sql: string, params: unknown[]): Promise<Row[]>;
     transaction<T>(fn: () => Promise<T>): Promise<T>;
 }
-/** 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 declare class D1Driver implements Driver {
-    private readonly db;
     readonly dialect: Dialect;
-    constructor(db: D1Database);
+    private readonly session;
+    constructor(db: D1Database, opts?: {
+        start?: D1SessionStart;
+    });
     exec(sql: string, params: unknown[]): Promise<Row[]>;
+    /** 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;
     transaction<T>(fn: () => Promise<T>): Promise<T>;
 }

package/dist/runtime/driver.js

@@ -18,10 +18,19 @@ function checkIdent(name) {
         throw new Error(`invalid identifier: ${name}`);
     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) {
+    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 = {
-    id: checkIdent,
+    id: quoteIdent,
     placeholder: () => "?",
     returning: true,
     encode: (v) => (typeof v === "boolean" ? (v ? 1 : 0) : v),
@@ -30,7 +39,7 @@ export const sqliteDialect = {
  * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
  * RETURNING supported. */
 export const postgresDialect = {
-    id: (name) => `"${checkIdent(name)}"`,
+    id: quoteIdent,
     placeholder: (n) => `$${n}`,
     returning: true,
     encode: (v) => v, // the pg driver handles type encoding
@@ -50,20 +59,38 @@ export class DoSqliteDriver {
         return this.storage.transaction(fn);
     }
 }
-/** 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. */
+/** 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 {
-    db;
     dialect = sqliteDialect;
-    constructor(db) {
-        this.db = db;
+    session;
+    constructor(db, opts) {
+        this.session = db.withSession(opts?.start ?? "first-unconstrained");
     }
     async exec(sql, params) {
-        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();
         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() {
+        return this.session.getBookmark();
+    }
+    // D1 has no interactive/atomic transactions — see the class doc. Run `fn` as-is.
     transaction(fn) {
         return fn();
     }

package/dist/runtime/migrate.d.ts

@@ -1,4 +1,4 @@
-import type { Driver } from "./driver";
+import { type Driver } from "./driver";
 import type { SchemaDef } from "../sdk/schema";
 export interface MigrationReport {
     changed: boolean;

package/dist/runtime/migrate.js

@@ -19,6 +19,7 @@
 // so it must be declared with `renamedFrom`; otherwise it is applied as drop+add.
 import { addColumnSql, createTableSql, indexStatements, sqlType } from "./ddl";
 import { digest } from "./digest";
+import { quoteIdent } from "./driver";
 import { entitiesInPartition, validateSchema } from "../sdk/schema";
 /** Internal bookkeeping tables the migrator must never touch — pramen's own, SQLite's,
  * and the substrate's (D1 keeps `_cf_*` / `d1_*` tables in sqlite_master and forbids
@@ -31,11 +32,6 @@ function isInternalTable(name) {
         n.startsWith("_cf_") ||
         n.startsWith("d1_"));
 }
-function ident(name) {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
-        throw new Error(`invalid identifier: ${name}`);
-    return name;
-}
 export function schemaHash(schema) {
     const canon = {};
     for (const [table, def] of Object.entries(schema))
@@ -45,7 +41,7 @@ export function schemaHash(schema) {
 /** Live columns of a table -> their declared SQL type (uppercased). Empty if the
  * table doesn't exist. */
 async function tableColumns(driver, table) {
-    const rows = (await driver.exec(`PRAGMA table_info(${ident(table)})`, []));
+    const rows = (await driver.exec(`PRAGMA table_info(${quoteIdent(table)})`, []));
     return new Map(rows.map((r) => [r.name, (r.type || "").toUpperCase()]));
 }
 async function readMeta(driver, key) {
@@ -60,7 +56,7 @@ async function writeMeta(driver, key, value) {
  * type change; brand-new columns left NULL), drop the old table, rename the temp. */
 async function rebuildTable(driver, table, def, live) {
     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 = [];
     const srcExprs = [];
@@ -70,14 +66,14 @@ async function rebuildTable(driver, table, def, live) {
         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, schema, opts = {}) {
     // Static schema invariants (relation targets exist, no cross-partition relations) —
@@ -133,7 +129,7 @@ export async function migrate(driver, schema, opts = {}) {
                 needsAdditiveRebuild = true;
                 continue;
             }
-            await driver.exec(`ALTER TABLE ${ident(table)} ADD COLUMN ${addColumnSql(name, field)}`, []);
+            await driver.exec(`ALTER TABLE ${quoteIdent(table)} ADD COLUMN ${addColumnSql(name, field)}`, []);
             added.push(`${table}.${name}`);
         }
         // Pass 2 — destructive: rebuild if any live column must be dropped, a declared
@@ -181,7 +177,7 @@ export async function migrate(driver, schema, opts = {}) {
         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 {

package/dist/runtime/queue-consumer.d.ts

@@ -0,0 +1,64 @@
+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 declare function routeQueue(queues: AppQueueMap, queueName: string): QueueHandler | 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 declare function dispatchQueueBatch(queues: AppQueueMap, ctx: QueueContext, batch: QueueBatch): Promise<void>;

package/dist/runtime/queue-consumer.js

@@ -0,0 +1,46 @@
+// 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.
+/** 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, queueName) {
+    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, ctx, batch) {
+    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/dist/runtime/queue.d.ts

@@ -0,0 +1,72 @@
+/** 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 declare class Queue {
+    private readonly adapter;
+    constructor(adapter: QueueAdapter);
+    /** Enqueue a single message onto `queue`. `body` is serialized by the platform. */
+    send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void>;
+    /** Enqueue many messages onto `queue` in one call (cheaper than N sends). */
+    sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void>;
+}
+/** 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 declare class CloudflareQueueAdapter implements QueueAdapter {
+    private readonly bindings;
+    constructor(bindings: Readonly<Record<string, QueueProducerBinding>>);
+    private bindingFor;
+    send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void>;
+    sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void>;
+}
+/** In-memory transport: captures sent messages instead of delivering them. For unit
+ * tests (assert on `.sent`) and pure off-platform use. */
+export declare class MemoryQueueAdapter implements QueueAdapter {
+    readonly sent: Array<{
+        queue: string;
+        body: unknown;
+        options?: QueueSendOptions | QueueBatchOptions;
+    }>;
+    send(queue: string, body: unknown, options?: QueueSendOptions): Promise<void>;
+    sendBatch(queue: string, messages: readonly QueueSendRequest[], options?: QueueBatchOptions): Promise<void>;
+}
+/** 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 declare function discoverQueueBindings(env: Readonly<Record<string, unknown>>): Record<string, QueueProducerBinding>;
+/** 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 declare function createQueue(env: Readonly<Record<string, unknown>>): Queue;