@pramen/server 0.0.14 → 0.0.16

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 { quoteIdent, type Driver } from "./driver";
-import { entitiesInPartition, validateSchema } from "../sdk/schema";
+import { entitiesInPartition, partitionOf, validateSchema } from "../sdk/schema";
 import type { EntityFields, FieldDef, SchemaDef } from "../sdk/schema";
 
 export interface MigrationReport {
@@ -79,6 +99,95 @@ async function tableColumns(driver: Driver, table: string): Promise<Map<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;
@@ -103,8 +212,15 @@ 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);
+    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)}`, []);
@@ -149,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);
@@ -173,9 +292,13 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
       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)) {
@@ -186,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).
@@ -237,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

@@ -62,14 +62,33 @@ 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 function routeQueue(queues: AppQueueMap, queueName: string): QueueHandler | null {
   const keys = Object.keys(queues);
   if (queues[queueName]) return queues[queueName];
-  const suffix = keys.find((k) => queueName.endsWith(`-${k}`) || k.endsWith(`-${queueName}`));
-  if (suffix) return queues[suffix];
-  if (keys.length === 1) return queues[keys[0]];
+  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;
 }
 

package/src/runtime/read-engine.ts

@@ -91,7 +91,12 @@ export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] =
     case "false":
       return { sql: "0", params };
     case "cmp":
-      if (expr.value === null) return { sql: `${dialect.id(expr.col)} IS NULL`, params };
+      // 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: "0", params };
       params.push(dialect.encode(expr.value));
       return { sql: `${dialect.id(expr.col)} ${expr.op} ${dialect.placeholder(params.length)}`, params };
     case "null":
@@ -145,7 +150,7 @@ export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
       return false;
     case "cmp": {
       const left = bind(row[expr.col]);
-      if (expr.value === null) return left === null || left === undefined;
+      if (expr.value === null) 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);
       switch (expr.op) {

package/src/runtime/schema-diff.ts

@@ -1,56 +1,170 @@
-// 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 type { FieldDef, SchemaDef } from "../sdk/schema";
+import { partitionOf } 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>;
+
+function columnShape(f: FieldDef): ColumnShape {
+  const c: ColumnShape = { 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: SchemaDef): SchemaShape {
   const out: SchemaShape = {};
   for (const [table, def] of Object.entries(schema)) {
-    const cols: Record<string, string> = {};
-    for (const [col, f] of Object.entries(def.fields)) cols[col] = (f as FieldDef).type;
-    out[table] = cols;
+    const columns: Record<string, ColumnShape> = {};
+    for (const [col, f] of Object.entries(def.fields)) columns[col] = columnShape(f as FieldDef);
+    out[table] = { partition: partitionOf(schema, table), columns };
   }
   return out;
 }
 
+/** The modifier fields compared for a `change-column` (everything but `type`). */
+const MODIFIER_KEYS: (keyof ColumnShape)[] = ["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: ColumnShape, next: ColumnShape): boolean {
+  return (!!next.notNull && !prev.notNull) || (!!next.unique && !prev.unique) || (!!next.primaryKey && !prev.primaryKey);
+}
+
+function modifierDiff(prev: ColumnShape, next: ColumnShape): string | null {
+  const parts: string[] = [];
+  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: unknown): string {
+  return v === undefined ? "—" : String(v);
+}
+
 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 function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[] {
   const changes: SchemaChange[] = [];
 
   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 });
-      } 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 });
+    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 {
+        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 });
+    if (!(table in next)) changes.push({ kind: "drop-table", table, destructive: true, appliesOnBoot: true });
   }
 
   return changes;