@pramen/server 0.0.13 → 0.0.15

package/src/runtime/migrate.ts

@@ -5,10 +5,30 @@
 // Reconciles the live store with the declared schema in two passes:
 //   1. additive (no data loss): missing table -> CREATE TABLE; missing column ->
 //      ALTER TABLE ADD COLUMN (nullable).
-//   2. destructive: a live column the schema no longer declares is DROPPED, a type
-//      change is applied, and a `renamedFrom` column is renamed — all via the
-//      standard SQLite table-rebuild (create new, copy, drop old, rename). This is
-//      auto-applied: a bad deploy CAN lose data, by design (WIP, no backward-compat).
+//   2. reconcile existing columns + drop obsolete ones. A live column the schema no
+//      longer declares is DROPPED, a type change is applied, a `renamedFrom` column is
+//      renamed, and a MODIFIER change on an existing column (NOT NULL / DEFAULT /
+//      PRIMARY KEY) is enacted — all via the standard SQLite table-rebuild (create new,
+//      copy, drop old, rename); UNIQUE is reconciled with a CREATE/DROP INDEX. Each
+//      change is classified SAFE (loses no data — applied always: a DEFAULT add/change,
+//      dropping a constraint, adding NOT NULL when a backfill/default covers it, adding
+//      UNIQUE with no duplicates) or DESTRUCTIVE (GATED behind PRAMEN_ALLOW_DESTRUCTIVE,
+//      off by default: a drop, a type change, a rename, a PRIMARY KEY change, adding
+//      NOT NULL over NULL rows with no default). Adding UNIQUE over duplicate values is
+//      always SKIPPED (the index can't build). `hidden()`/`generated()` are ORM-only —
+//      no physical column change, so they don't appear here.
+//
+// The guiding invariant: the schema hash is recorded ONLY when the store fully matches
+// the schema. Any detected change that is SKIPPED (destructive-gated, a UNIQUE-over-
+// duplicates, or a partition MOVE — see below) leaves the hash UNWRITTEN, so `schema
+// status` keeps reporting drift and a later opt-in / data-fixed deploy retries. This is
+// what stops a modifier change (e.g. an unenforced NOT NULL) from silently diverging the
+// store from the schema while the hash claims "in sync". Local dev sets the flag on; a
+// bad deploy CAN then lose data (WIP, no backward-compat).
+//
+// A partition MOVE (an entity reassigned to a different Durable Object) is never auto-
+// applied — the data can't cross DOs — so it's detected and reported as a skipped manual
+// migration (hash withheld), leaving the source DO's data intact.
 //
 // A schema hash in the internal `_pramen_meta` table lets an unchanged schema skip
 // introspection entirely on warm boots. The live table (PRAGMA) is the ground
@@ -18,10 +38,10 @@
 // A rename can't be inferred from a diff (a removed + added column is ambiguous),
 // so it must be declared with `renamedFrom`; otherwise it is applied as drop+add.
 
-import { addColumnSql, createTableSql, indexStatements, sqlType } from "./ddl";
+import { addColumnSql, createTableSql, defaultSqlValue, indexName, indexStatements, sqlType } from "./ddl";
 import { digest } from "./digest";
-import type { Driver } from "./driver";
-import { entitiesInPartition, validateSchema } from "../sdk/schema";
+import { quoteIdent, type Driver } from "./driver";
+import { entitiesInPartition, partitionOf, validateSchema } from "../sdk/schema";
 import type { EntityFields, FieldDef, SchemaDef } from "../sdk/schema";
 
 export interface MigrationReport {
@@ -66,11 +86,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,10 +95,99 @@ 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()]));
 }
 
+/** The constraint-bearing facts a migrator compares against a schema field's modifiers:
+ * SQL type, NOT NULL, PRIMARY KEY membership, and the raw DEFAULT text (as reported by
+ * PRAGMA — e.g. `'pending'`, `1`, `datetime('now')`, or null). */
+interface LiveColumn {
+  type: string;
+  notNull: boolean;
+  pk: boolean;
+  default: string | null;
+}
+
+/** Full live column info (type + modifiers) via PRAGMA table_info. Empty if absent. */
+async function liveColumnInfo(driver: Driver, table: string): Promise<Map<string, LiveColumn>> {
+  const rows = (await driver.exec(`PRAGMA table_info(${quoteIdent(table)})`, [])) as {
+    name: string;
+    type: string;
+    notnull: number;
+    dflt_value: string | null;
+    pk: number;
+  }[];
+  const out = new Map<string, LiveColumn>();
+  for (const r of rows) {
+    out.set(r.name, {
+      type: (r.type || "").toUpperCase(),
+      notNull: r.notnull === 1,
+      pk: r.pk > 0,
+      default: r.dflt_value ?? null,
+    });
+  }
+  return out;
+}
+
+/** The columns backed by a single-column UNIQUE index (a `unique()` constraint). Reads
+ * PRAGMA index_list + index_info; multi-column indexes are ignored (pramen only emits
+ * single-column ones). */
+async function liveUniqueColumns(driver: Driver, table: string): Promise<Set<string>> {
+  const idx = (await driver.exec(`PRAGMA index_list(${quoteIdent(table)})`, [])) as { name: string; unique: number }[];
+  const out = new Set<string>();
+  for (const i of idx) {
+    if (i.unique !== 1) continue;
+    const cols = (await driver.exec(`PRAGMA index_info(${quoteIdent(i.name)})`, [])) as { name: string | null }[];
+    if (cols.length === 1 && cols[0]?.name) out.add(cols[0].name);
+  }
+  return out;
+}
+
+/** Does the column currently hold any NULL? (Adding NOT NULL to such a column is
+ * unsafe without a backfill default.) */
+async function columnHasNulls(driver: Driver, table: string, col: string): Promise<boolean> {
+  const rows = await driver.exec(`SELECT 1 FROM ${quoteIdent(table)} WHERE ${quoteIdent(col)} IS NULL LIMIT 1`, []);
+  return rows.length > 0;
+}
+
+/** Does the column hold a duplicate non-NULL value? (Adding UNIQUE to such a column
+ * can't build the index.) NULLs are never "equal" in SQLite, so they're excluded. */
+async function columnHasDuplicates(driver: Driver, table: string, col: string): Promise<boolean> {
+  const rows = await driver.exec(
+    `SELECT ${quoteIdent(col)} FROM ${quoteIdent(table)} WHERE ${quoteIdent(col)} IS NOT NULL GROUP BY ${quoteIdent(col)} HAVING COUNT(*) > 1 LIMIT 1`,
+    [],
+  );
+  return rows.length > 0;
+}
+
+/** Normalize a DEFAULT's SQL text for comparison: trim, and strip balanced outer
+ * parens (SQLite reports an expr default with or without the wrapping parens the DDL
+ * emitted — `(datetime('now'))` vs `datetime('now')` — depending on the engine, so the
+ * comparison must not depend on them). */
+function normalizeDefault(s: string | null): string | null {
+  if (s == null) return null;
+  let t = s.trim();
+  while (t.length >= 2 && t[0] === "(" && t[t.length - 1] === ")" && outerParensBalanced(t)) {
+    t = t.slice(1, -1).trim();
+  }
+  return t;
+}
+
+/** Does the leading `(` in `t` match the trailing `)` (i.e. is the whole string wrapped
+ * in one paren group)? Prevents stripping `(a) + (b)`. */
+function outerParensBalanced(t: string): boolean {
+  let depth = 0;
+  for (let i = 0; i < t.length; i++) {
+    if (t[i] === "(") depth++;
+    else if (t[i] === ")") {
+      depth--;
+      if (depth === 0 && i !== t.length - 1) return false;
+    }
+  }
+  return depth === 0;
+}
+
 async function readMeta(driver: Driver, key: string): Promise<string | undefined> {
   const rows = (await driver.exec(`SELECT value FROM _pramen_meta WHERE key = ?`, [key])) as { value: string }[];
   return rows[0]?.value;
@@ -98,7 +202,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 +212,21 @@ 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})`);
+    let expr = live.get(src) === target ? quoteIdent(src) : `CAST(${quoteIdent(src)} AS ${target})`;
+    // Backfill NULLs when the target is NOT NULL and carries a default — makes adding
+    // NOT NULL to a column with NULL rows safe (the copy fills them from the default),
+    // instead of the INSERT failing the new NOT NULL constraint.
+    const notNull = !!f.notNull || !!f.primaryKey;
+    const dflt = defaultSqlValue(f);
+    if (notNull && dflt !== null) expr = `COALESCE(${expr}, ${dflt})`;
+    destCols.push(quoteIdent(name));
+    srcExprs.push(expr);
   }
   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> {
@@ -154,6 +265,9 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
   const rebuilt: string[] = [];
   const droppedTables: string[] = [];
   const skipped: string[] = [];
+  // Per-table: columns whose new `unique()` can't be indexed (duplicate values) — the
+  // index pass must skip them so it doesn't throw. They're already reported in `skipped`.
+  const uniqueIndexSkip = new Map<string, Set<string>>();
 
   for (const [table, def] of entries) {
     const existing = await tableColumns(driver, table);
@@ -174,13 +288,17 @@ 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}`);
     }
 
-    // Pass 2 — destructive: rebuild if any live column must be dropped, a declared
-    // column changed type, or a rename hint points at an existing live column.
-    const live = await tableColumns(driver, table); // re-read (now includes additively-added columns)
+    // Pass 2 — reconcile existing columns against the schema. Rebuild the table when a
+    // live column must be dropped, a declared column changed type, a rename hint points
+    // at an existing live column, or a MODIFIER changed on an existing column (NOT NULL,
+    // DEFAULT, PRIMARY KEY). UNIQUE is reconciled with an index (create/drop), no rebuild.
+    const liveInfo = await liveColumnInfo(driver, table); // re-read (includes additively-added columns)
+    const liveUnique = await liveUniqueColumns(driver, table);
+    const live = new Map([...liveInfo].map(([name, info]) => [name, info.type] as const)); // name -> type
     const desired = new Set(Object.keys(def.fields));
     const renamedSources = new Set<string>();
     for (const f of Object.values(def.fields)) {
@@ -191,24 +309,117 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
     const needsTypeChange = Object.entries(def.fields).some(
       ([n, f]) => live.has(n) && live.get(n) !== sqlType(f as FieldDef),
     );
-    const destructive = needsDrop || needsTypeChange || renamedSources.size > 0;
+
+    // Modifier reconciliation on existing (same-named) columns. A change to NOT NULL /
+    // DEFAULT / PRIMARY KEY is enacted by a table rebuild (which reconstructs the column
+    // to its exact declared shape); UNIQUE is an index op. Classify each as either a
+    // SAFE change (loses no data — applied always) or a DESTRUCTIVE one (gated behind
+    // allowDestructive). `hidden()`/`generated()` are ORM-only (no physical column
+    // change), so they never appear here.
+    let modifierRebuildSafe = false; // default add/change/remove, notNull widen, safe notNull add
+    let modifierRebuildDestructive = false; // notNull add over NULL rows w/o default, PK change
+    const destructiveReasons: string[] = [];
+    const dropUniqueCols: string[] = []; // `unique()` removed -> drop the managed index
+    for (const [name, field] of Object.entries(def.fields)) {
+      const info = liveInfo.get(name);
+      if (!info) continue; // new column (Pass 1) or a rename target — not an existing column
+      const f = field as FieldDef;
+      const fieldPk = !!f.primaryKey;
+      const fieldNotNull = !!f.notNull || fieldPk;
+
+      // DEFAULT add / change / remove — a rebuild backfills existing rows and applies the
+      // new default going forward; no data loss.
+      if (normalizeDefault(defaultSqlValue(f)) !== normalizeDefault(info.default)) modifierRebuildSafe = true;
+
+      // NOT NULL — PRAGMA reports notnull=0 for a PRIMARY KEY column, so only compare on
+      // non-PK columns (PK-ness is compared separately below).
+      if (!fieldPk && !info.pk) {
+        if (fieldNotNull && !info.notNull) {
+          const backfillable = defaultSqlValue(f) !== null;
+          if (!backfillable && (await columnHasNulls(driver, table, name))) {
+            modifierRebuildDestructive = true;
+            destructiveReasons.push(`NOT NULL ${name} (NULL rows, no default)`);
+          } else {
+            modifierRebuildSafe = true; // no NULLs, or backfilled from the default
+          }
+        } else if (!fieldNotNull && info.notNull) {
+          modifierRebuildSafe = true; // dropping NOT NULL only widens — safe
+        }
+      }
+
+      // PRIMARY KEY change — reshapes the table's key; treat as destructive.
+      if (fieldPk !== info.pk) {
+        modifierRebuildDestructive = true;
+        destructiveReasons.push(`PRIMARY KEY ${name}`);
+      }
+
+      // UNIQUE — reconciled with an index (create/drop), not a rebuild.
+      const fieldUnique = !!f.unique;
+      if (fieldUnique && !liveUnique.has(name)) {
+        // Added: safe only if no duplicate values exist; otherwise the index can't build.
+        if (await columnHasDuplicates(driver, table, name)) {
+          (uniqueIndexSkip.get(table) ?? uniqueIndexSkip.set(table, new Set()).get(table)!).add(name);
+          skipped.push(`add UNIQUE ${table}.${name} (duplicate values present)`);
+        }
+        // else: the index pass creates it below (no rebuild needed).
+      } else if (!fieldUnique && liveUnique.has(name)) {
+        dropUniqueCols.push(name); // drop the managed unique index (safe — no data loss)
+      }
+    }
+
+    const destructive = needsDrop || needsTypeChange || renamedSources.size > 0 || modifierRebuildDestructive;
     if (destructive && !allowDestructive) {
-      // The destructive part is gated off — skip the whole rebuild (any pending
-      // expr-default column waits until destructive migrations are allowed).
-      skipped.push(`rebuild ${table} (drop/type-change/rename)`);
-    } else if (destructive || needsAdditiveRebuild) {
-      // An additive-only rebuild (just an expr-default column) needs no permission —
-      // it loses no data.
+      // The destructive part is gated off — skip the whole rebuild (any pending safe
+      // rebuild for this table waits until destructive migrations are allowed).
+      const reasons = [
+        ...(needsDrop ? ["drop"] : []),
+        ...(needsTypeChange ? ["type-change"] : []),
+        ...(renamedSources.size > 0 ? ["rename"] : []),
+        ...destructiveReasons,
+      ];
+      skipped.push(`rebuild ${table} (${reasons.join(", ")})`);
+    } else if (destructive || needsAdditiveRebuild || modifierRebuildSafe) {
+      // A safe rebuild (expr-default column, default/notNull modifier change) needs no
+      // permission — it loses no data.
       await rebuildTable(driver, table, def, live);
       rebuilt.push(table);
     }
+
+    // Drop the managed unique index for a column that no longer declares `unique()`. A
+    // rebuild already dropped every index (and the index pass won't recreate this one),
+    // so this only matters when no rebuild ran — DROP INDEX IF EXISTS is a safe no-op
+    // otherwise. No data loss either way.
+    for (const col of dropUniqueCols) {
+      await driver.exec(`DROP INDEX IF EXISTS ${quoteIdent(indexName(table, col))}`, []);
+    }
+  }
+
+  // A partition MOVE — an entity that was applied in THIS partition before but the
+  // current schema assigns to a DIFFERENT partition — is NOT auto-migratable: the data
+  // lives in this DO's SQLite and boot migration can't move it across DOs. Detect it
+  // (scoped path only; the unscoped/single-store path never strands data), report it as
+  // a skipped manual migration, and leave the table in place so its data is preserved
+  // for a hand-run migration. Leaving it in `skipped` also withholds the hash.
+  if (opts.partition !== undefined) {
+    const prevRaw = await readMeta(driver, tablesKey);
+    if (prevRaw) {
+      const prevApplied = JSON.parse(prevRaw) as Record<string, string[]>;
+      for (const t of Object.keys(prevApplied)) {
+        if (!inScope.has(t) && t in schema && partitionOf(schema, t) !== opts.partition) {
+          skipped.push(
+            `move partition ${t} (${opts.partition} → ${partitionOf(schema, t)}) — data stays in this DO; manual cross-DO migration required`,
+          );
+        }
+      }
+    }
   }
 
   // Ensure unique/index declarations (idempotent, via IF NOT EXISTS). Indexes can be
   // added to an existing table without a rebuild; a stale index from a removed
-  // declaration is left in place (cleanup is future work).
+  // declaration is dropped above. A column whose new `unique()` has duplicate values is
+  // skipped (reported above) so this doesn't throw.
   for (const [table, def] of entries) {
-    for (const stmt of indexStatements(table, def)) await driver.exec(stmt, []);
+    for (const stmt of indexStatements(table, def, uniqueIndexSkip.get(table))) await driver.exec(stmt, []);
   }
 
   // Drop tables the schema no longer declares (internal bookkeeping tables skipped).
@@ -224,7 +435,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}`);
@@ -242,7 +453,8 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
     await writeMeta(driver, tablesKey, tablesValue());
   } else {
     console.warn(
-      `pramen: ${skipped.length} destructive migration(s) skipped (set PRAMEN_ALLOW_DESTRUCTIVE=true to apply): ${skipped.join("; ")}`,
+      `pramen: ${skipped.length} migration(s) skipped, schema hash left unwritten (a gated change needs ` +
+        `PRAMEN_ALLOW_DESTRUCTIVE=true; a UNIQUE-over-duplicates or partition move needs a manual fix): ${skipped.join("; ")}`,
     );
   }
   return { changed: true, created, added, rebuilt, droppedTables, skipped };

package/src/runtime/outbox.ts

@@ -141,6 +141,17 @@ export async function drainOutbox(driver: Driver, tasks: TaskMap, now: number, l
     const kind = String(row.kind);
     const attempts = Number(row.attempts) + 1;
     const handler = tasks[kind];
+    // Re-stamp claimedAt to WALL-CLOCK time immediately before running this row, so its
+    // stale clock starts when its own processing starts — not when the whole batch was
+    // claimed. Otherwise a batch (up to `limit` rows) processed SEQUENTIALLY whose total
+    // time exceeds STALE_MS would leave the not-yet-run tail reclaimable by a concurrent
+    // drainer under the batch-shared claimedAt, running it twice. We use Date.now() (not
+    // the caller's fixed `now`) because that is the only clock that advances across the
+    // loop; the atomic claim above still gives disjoint batches for concurrent drainers.
+    await driver.exec(
+      `UPDATE ${d.id(OUTBOX_TABLE)} SET claimedAt = ${ph(1)} WHERE id = ${ph(2)}`,
+      enc(driver, [Date.now(), id]),
+    );
     try {
       if (!handler) throw new Error(`no task handler registered for kind ${JSON.stringify(kind)}`);
       await handler(JSON.parse(String(row.payload)), { id, attempts });
@@ -160,22 +171,34 @@ export async function drainOutbox(driver: Driver, tasks: TaskMap, now: number, l
     }
   }
 
-  // remaining = pending AND due now; nextRunAt = the earliest pending runAt (any), so
-  // the DO can schedule its alarm exactly when the next task — including a backed-off
-  // retry — becomes due.
+  // remaining = pending AND due now. nextRunAt = the earliest moment the DO must wake to
+  // make progress, so it can re-arm its alarm exactly there. That is the min of:
+  //   (a) MIN(runAt) over pending rows (a due-now or backed-off retry), and
+  //   (b) MIN(claimedAt) + STALE_MS over 'processing' rows — a claim stranded by a
+  //       crashed drainer becomes reclaimable at claimedAt + STALE_MS. Without folding
+  //       this in, a mid-drain crash would leave a row 'processing' with no pending row
+  //       to re-arm the alarm, and on a quiet tenant the task would stall forever (the
+  //       alarm is the only DO-path drain trigger). Any processing rows here belong to a
+  //       *different* (concurrent or crashed) drainer — our own batch is never left
+  //       processing after this loop.
   const stats = await driver.exec(
     `SELECT ` +
       `(SELECT COUNT(*) FROM ${d.id(OUTBOX_TABLE)} WHERE status = ${ph(1)} AND runAt <= ${ph(2)}) AS due, ` +
-      `(SELECT MIN(runAt) FROM ${d.id(OUTBOX_TABLE)} WHERE status = ${ph(3)}) AS nextRunAt`,
-    enc(driver, ["pending", now, "pending"]),
+      `(SELECT MIN(runAt) FROM ${d.id(OUTBOX_TABLE)} WHERE status = ${ph(3)}) AS nextPending, ` +
+      `(SELECT MIN(claimedAt) FROM ${d.id(OUTBOX_TABLE)} WHERE status = ${ph(4)}) AS nextStale`,
+    enc(driver, ["pending", now, "pending", "processing"]),
   );
-  const nextRaw = stats[0]?.nextRunAt;
+  const pendingRaw = stats[0]?.nextPending;
+  const staleRaw = stats[0]?.nextStale;
+  const candidates: number[] = [];
+  if (pendingRaw != null) candidates.push(Number(pendingRaw));
+  if (staleRaw != null) candidates.push(Number(staleRaw) + STALE_MS);
   return {
     processed: claimed.length,
     succeeded,
     failed,
     remaining: Number(stats[0]?.due ?? 0),
-    nextRunAt: nextRaw == null ? null : Number(nextRaw),
+    nextRunAt: candidates.length ? Math.min(...candidates) : null,
   };
 }
 

package/src/runtime/queue-consumer.ts

@@ -0,0 +1,116 @@
+// 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 the LONGEST `…-<key>` suffix, then — if there's exactly one
+ * handler — fall through to it (the common single-queue app). Returns null if nothing
+ * matches.
+ *
+ * The suffix match must prefer the longest key so `email-jobs` wins over `jobs` for
+ * `prod-email-jobs` (a plain `find` was insertion-order dependent and could misroute).
+ * We only match a handler key that is a `-`-delimited suffix of the incoming queue name
+ * (env prefix stripped) — never the reverse (a handler key ending in `-<queueName>`),
+ * which let a shorter queue name grab a longer, unrelated handler. */
+export function routeQueue(queues: AppQueueMap, queueName: string): QueueHandler | null {
+  const keys = Object.keys(queues);
+  if (queues[queueName]) return queues[queueName];
+  let best: string | null = null;
+  for (const k of keys) {
+    if (queueName.endsWith(`-${k}`) && (best === null || k.length > best.length)) best = k;
+  }
+  if (best !== null) return queues[best];
+  // Single-handler fallback: a lone queue whose env-prefixed name we couldn't suffix-
+  // match. Kept for the common single-queue app, but LOG it — otherwise a dead-letter
+  // queue (a distinct name) would silently route to the one handler and hide the misroute.
+  if (keys.length === 1) {
+    console.warn(
+      `pramen: routing queue '${queueName}' to the sole handler '${keys[0]}' by fallback ` +
+        `(no exact/suffix match — verify this isn't a dead-letter or foreign queue)`,
+    );
+    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();
+      }
+    }),
+  );
+}