@pramen/server 0.0.14 → 0.0.15

package/dist/runtime/migrate.js

@@ -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
@@ -17,10 +37,10 @@
 // ADD COLUMN is always nullable (SQLite can't add NOT NULL to a populated table).
 // 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 { quoteIdent } from "./driver";
-import { entitiesInPartition, validateSchema } from "../sdk/schema";
+import { entitiesInPartition, partitionOf, 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
  * dropping them). Matched case-insensitively. */
@@ -44,6 +64,75 @@ async function tableColumns(driver, table) {
     const rows = (await driver.exec(`PRAGMA table_info(${quoteIdent(table)})`, []));
     return new Map(rows.map((r) => [r.name, (r.type || "").toUpperCase()]));
 }
+/** Full live column info (type + modifiers) via PRAGMA table_info. Empty if absent. */
+async function liveColumnInfo(driver, table) {
+    const rows = (await driver.exec(`PRAGMA table_info(${quoteIdent(table)})`, []));
+    const out = new Map();
+    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, table) {
+    const idx = (await driver.exec(`PRAGMA index_list(${quoteIdent(table)})`, []));
+    const out = new Set();
+    for (const i of idx) {
+        if (i.unique !== 1)
+            continue;
+        const cols = (await driver.exec(`PRAGMA index_info(${quoteIdent(i.name)})`, []));
+        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, table, col) {
+    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, table, col) {
+    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) {
+    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) {
+    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, key) {
     const rows = (await driver.exec(`SELECT value FROM _pramen_meta WHERE key = ?`, [key]));
     return rows[0]?.value;
@@ -66,8 +155,16 @@ async function rebuildTable(driver, table, def, live) {
         if (!src)
             continue; // brand-new column with no source -> leave NULL
         const target = sqlType(f);
+        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(live.get(src) === target ? quoteIdent(src) : `CAST(${quoteIdent(src)} AS ${target})`);
+        srcExprs.push(expr);
     }
     if (destCols.length > 0) {
         await driver.exec(`INSERT INTO ${quoteIdent(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${quoteIdent(table)}`, []);
@@ -109,6 +206,9 @@ export async function migrate(driver, schema, opts = {}) {
     const rebuilt = [];
     const droppedTables = [];
     const skipped = [];
+    // 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();
     for (const [table, def] of entries) {
         const existing = await tableColumns(driver, table);
         if (existing.size === 0) {
@@ -132,9 +232,13 @@ export async function migrate(driver, schema, opts = {}) {
             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
-        // 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])); // name -> type
         const desired = new Set(Object.keys(def.fields));
         const renamedSources = new Set();
         for (const f of Object.values(def.fields)) {
@@ -144,24 +248,112 @@ export async function migrate(driver, schema, opts = {}) {
         }
         const needsDrop = [...live.keys()].some((c) => !desired.has(c) && !renamedSources.has(c));
         const needsTypeChange = Object.entries(def.fields).some(([n, f]) => live.has(n) && live.get(n) !== sqlType(f));
-        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 = [];
+        const dropUniqueCols = []; // `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;
+            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)`);
+            // 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) {
-            // An additive-only rebuild (just an expr-default column) needs no permission —
-            // it loses no data.
+        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);
+            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))
+        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).
@@ -195,7 +387,8 @@ export async function migrate(driver, schema, opts = {}) {
         await writeMeta(driver, tablesKey, tablesValue());
     }
     else {
-        console.warn(`pramen: ${skipped.length} destructive migration(s) skipped (set PRAMEN_ALLOW_DESTRUCTIVE=true to apply): ${skipped.join("; ")}`);
+        console.warn(`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/dist/runtime/outbox.js

@@ -87,6 +87,14 @@ export async function drainOutbox(driver, tasks, now, limit = 50) {
         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)}`);
@@ -101,19 +109,33 @@ export async function drainOutbox(driver, tasks, now, limit = 50) {
             failed++;
         }
     }
-    // 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"]));
-    const nextRaw = stats[0]?.nextRunAt;
+        `(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 pendingRaw = stats[0]?.nextPending;
+    const staleRaw = stats[0]?.nextStale;
+    const candidates = [];
+    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,
     };
 }
 /** List outbox rows for admin visibility (e.g. inspect dead-lettered tasks). Newest

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

@@ -55,8 +55,15 @@ export type QueueHandler<Body = unknown> = (ctx: QueueContext, message: QueueMes
 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. */
+ * 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 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).

package/dist/runtime/queue-consumer.js

@@ -10,17 +10,34 @@
 // `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. */
+ * 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, 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)
+    let best = 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

package/dist/runtime/read-engine.js

@@ -85,8 +85,13 @@ export function compileExpr(expr, dialect, params = []) {
         case "false":
             return { sql: "0", params };
         case "cmp":
+            // A comparison against NULL is never TRUE in SQL (=, !=, <, > all yield NULL).
+            // Only the dedicated `null` node produces `IS NULL`; a `cmp` with a null operand
+            // matches nothing. (`eq()` already routes an equality-to-null to the `null` node,
+            // and the keyset comparator handles null order-keys explicitly — so no legitimate
+            // caller reaches here with a null value.)
             if (expr.value === null)
-                return { sql: `${dialect.id(expr.col)} IS NULL`, params };
+                return { sql: "0", params };
             params.push(dialect.encode(expr.value));
             return { sql: `${dialect.id(expr.col)} ${expr.op} ${dialect.placeholder(params.length)}`, params };
         case "null":
@@ -144,7 +149,7 @@ export function evalExpr(expr, row) {
         case "cmp": {
             const left = bind(row[expr.col]);
             if (expr.value === null)
-                return left === null || left === undefined;
+                return false; // comparison against NULL is never true (use the `null` node for IS NULL)
             if (left === null || left === undefined)
                 return false; // NULL compared to a value -> false
             const right = bind(expr.value);

package/dist/runtime/schema-diff.d.ts

@@ -1,14 +1,37 @@
 import type { SchemaDef } from "../sdk/schema";
-/** table -> column -> field type. The comparable surface of a schema. */
-export type SchemaShape = Record<string, Record<string, string>>;
+/** The comparable fingerprint of a single column: type + migration-relevant modifiers. */
+export interface ColumnShape {
+    type: string;
+    notNull?: boolean;
+    unique?: boolean;
+    primaryKey?: boolean;
+    generated?: boolean;
+    hidden?: boolean;
+    /** The literal or raw-SQL default, normalized to a string for comparison. */
+    default?: string;
+}
+/** The comparable fingerprint of a table: its partition + each column's shape. */
+export interface TableShape {
+    partition: string;
+    columns: Record<string, ColumnShape>;
+}
+/** table -> table shape. The comparable surface of a schema. */
+export type SchemaShape = Record<string, TableShape>;
 export declare function schemaShape(schema: SchemaDef): SchemaShape;
 export interface SchemaChange {
-    kind: "add-table" | "drop-table" | "add-column" | "drop-column" | "change-type";
+    kind: "add-table" | "drop-table" | "add-column" | "drop-column" | "change-type" | "change-column" | "move-partition";
     table: string;
     column?: string;
     detail?: string;
-    /** true = rebuilds the table and may lose data (drop / type change); false =
-     * additive, no data loss. All changes are auto-applied on the next DO boot. */
+    /** true = rebuilds the table and may lose data (drop / type change). false = additive
+     * OR a metadata-only change (modifier / partition move) — see `appliesOnBoot`. */
     destructive: boolean;
+    /** Whether migrate() enacts this change on the next DO boot. Additive changes are
+     * always applied; destructive changes (type/drop, or a constraint-tightening modifier
+     * change) apply only when the deploy sets PRAMEN_ALLOW_DESTRUCTIVE=true (and are
+     * skipped when the live data conflicts, leaving the hash unwritten). `false` here means
+     * the boot migrator will NEVER enact it — today only a partition MOVE (needs a manual
+     * cross-DO data migration). Reported for honesty. */
+    appliesOnBoot: boolean;
 }
 export declare function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[];

package/dist/runtime/schema-diff.js

@@ -1,41 +1,133 @@
-// Schema shape + diff — powers the CLI's `schema diff`. migrate() applies every
-// change on the next DO boot, additive AND destructive. A diff classifies each as
-// `destructive` (drop / type change — rebuilds the table and CAN lose data) or not
-// (add table/column — no data loss). A rename can't be detected from a shape diff;
-// it shows as drop+add unless declared with `renamedFrom` in the schema.
+// Schema shape + diff — powers the CLI's `schema diff`. The diff is a REPORTING tool; it
+// does not itself migrate. On the next DO boot migrate() applies ADDITIVE changes only
+// (new table -> CREATE TABLE; new column -> ALTER TABLE ADD COLUMN). DESTRUCTIVE changes
+// (drop column/table, type change, table rebuild) are SKIPPED unless the deploy sets
+// PRAMEN_ALLOW_DESTRUCTIVE=true — and when skipped the schema hash is left unwritten so a
+// later opt-in deploy retries. A rename can't be detected from a shape diff; it shows as
+// drop+add unless declared with `renamedFrom` in the schema.
+//
+// The shape records column type + the migration-relevant modifiers (notNull, unique,
+// primaryKey, generated, default, hidden) and the entity's partition, so the diff REPORTS
+// modifier and partition changes too. migrate() now RECONCILES modifier changes on an
+// existing column (a NOT NULL / DEFAULT / PRIMARY KEY change via a rebuild, a UNIQUE
+// change via a create/drop index), so a `change-column` is `appliesOnBoot: true`. It is
+// flagged `destructive` when it tightens a constraint (adds NOT NULL / UNIQUE / PRIMARY
+// KEY) — those apply only under PRAMEN_ALLOW_DESTRUCTIVE, or are skipped when the live
+// data conflicts (NULL rows / duplicates), leaving the hash unwritten. A partition MOVE
+// still CANNOT be enacted on boot (a partition is a separate Durable Object — it needs a
+// manual cross-DO data migration), so it stays `appliesOnBoot: false`.
+import { partitionOf } from "../sdk/schema";
+function columnShape(f) {
+    const c = { type: f.type };
+    if (f.notNull)
+        c.notNull = true;
+    if (f.unique)
+        c.unique = true;
+    if (f.primaryKey)
+        c.primaryKey = true;
+    if (f.generated)
+        c.generated = true;
+    if (f.hidden)
+        c.hidden = true;
+    if (f.defaultExpr !== undefined)
+        c.default = `(${f.defaultExpr})`;
+    else if (f.default !== undefined)
+        c.default = JSON.stringify(f.default);
+    return c;
+}
 export function schemaShape(schema) {
     const out = {};
     for (const [table, def] of Object.entries(schema)) {
-        const cols = {};
+        const columns = {};
         for (const [col, f] of Object.entries(def.fields))
-            cols[col] = f.type;
-        out[table] = cols;
+            columns[col] = columnShape(f);
+        out[table] = { partition: partitionOf(schema, table), columns };
     }
     return out;
 }
+/** The modifier fields compared for a `change-column` (everything but `type`). */
+const MODIFIER_KEYS = ["notNull", "unique", "primaryKey", "generated", "hidden", "default"];
+/** Does `next` tighten a constraint `prev` lacked (add NOT NULL / UNIQUE / PRIMARY KEY)?
+ * Such a change may require the destructive gate or be skipped when the live data
+ * conflicts (NULL rows / duplicates) — so the diff flags it `destructive`. */
+function tightensConstraint(prev, next) {
+    return (!!next.notNull && !prev.notNull) || (!!next.unique && !prev.unique) || (!!next.primaryKey && !prev.primaryKey);
+}
+function modifierDiff(prev, next) {
+    const parts = [];
+    for (const k of MODIFIER_KEYS) {
+        if (prev[k] !== next[k])
+            parts.push(`${k}: ${fmt(prev[k])} → ${fmt(next[k])}`);
+    }
+    return parts.length ? parts.join(", ") : null;
+}
+function fmt(v) {
+    return v === undefined ? "—" : String(v);
+}
 export function diffSchemaShape(prev, next) {
     const changes = [];
     for (const table of Object.keys(next)) {
-        if (!(table in prev)) {
-            changes.push({ kind: "add-table", table, destructive: false });
+        const pt = prev[table];
+        if (!pt) {
+            changes.push({ kind: "add-table", table, destructive: false, appliesOnBoot: true });
             continue;
         }
-        for (const col of Object.keys(next[table])) {
-            if (!(col in prev[table])) {
-                changes.push({ kind: "add-column", table, column: col, destructive: false });
+        const nt = next[table];
+        if (pt.partition !== nt.partition) {
+            changes.push({
+                kind: "move-partition",
+                table,
+                detail: `${pt.partition} → ${nt.partition}`,
+                destructive: false,
+                // A partition is a separate Durable Object; boot migration can't move a table's
+                // data across DOs. Needs a manual data migration.
+                appliesOnBoot: false,
+            });
+        }
+        for (const col of Object.keys(nt.columns)) {
+            const pc = pt.columns[col];
+            const ncol = nt.columns[col];
+            if (!pc) {
+                changes.push({ kind: "add-column", table, column: col, destructive: false, appliesOnBoot: true });
+            }
+            else if (pc.type !== ncol.type) {
+                changes.push({
+                    kind: "change-type",
+                    table,
+                    column: col,
+                    detail: `${pc.type} → ${ncol.type}`,
+                    destructive: true,
+                    // Applied only under PRAMEN_ALLOW_DESTRUCTIVE (a table rebuild). Report it as
+                    // boot-applicable — the destructive-gating note explains the opt-in.
+                    appliesOnBoot: true,
+                });
             }
-            else if (prev[table][col] !== next[table][col]) {
-                changes.push({ kind: "change-type", table, column: col, detail: `${prev[table][col]} → ${next[table][col]}`, destructive: true });
+            else {
+                const md = modifierDiff(pc, ncol);
+                if (md) {
+                    changes.push({
+                        kind: "change-column",
+                        table,
+                        column: col,
+                        detail: md,
+                        // Tightening a constraint (add NOT NULL / UNIQUE / PRIMARY KEY) rebuilds/
+                        // indexes and applies only under PRAMEN_ALLOW_DESTRUCTIVE (or is skipped when
+                        // live data conflicts). Loosening or a DEFAULT change is additive.
+                        destructive: tightensConstraint(pc, ncol),
+                        // migrate() now reconciles modifier changes on an existing column on boot.
+                        appliesOnBoot: true,
+                    });
+                }
             }
         }
-        for (const col of Object.keys(prev[table])) {
-            if (!(col in next[table]))
-                changes.push({ kind: "drop-column", table, column: col, destructive: true });
+        for (const col of Object.keys(pt.columns)) {
+            if (!(col in nt.columns))
+                changes.push({ kind: "drop-column", table, column: col, destructive: true, appliesOnBoot: true });
         }
     }
     for (const table of Object.keys(prev)) {
         if (!(table in next))
-            changes.push({ kind: "drop-table", table, destructive: true });
+            changes.push({ kind: "drop-table", table, destructive: true, appliesOnBoot: true });
     }
     return changes;
 }