@pramen/server 0.0.13 → 0.0.15

package/dist/runtime/ddl.d.ts

@@ -1,5 +1,15 @@
-import type { EntityFields, FieldDef } from "../sdk/schema";
+import type { DefaultValue, EntityFields, FieldDef } from "../sdk/schema";
 export declare const sqlType: (f: FieldDef) => string;
+/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1.
+ * Exported for the migrator, which reconstructs a column's expected DEFAULT text to
+ * compare against the live `PRAGMA table_info.dflt_value`. */
+export declare function defaultLiteral(v: DefaultValue): string;
+/** The SQL text of a column's DEFAULT value (the part after `DEFAULT `), or null when
+ * the column declares no default. A raw-SQL `defaultExpr` is returned unquoted (e.g.
+ * `datetime('now')`); a literal `default` is rendered via {@link defaultLiteral}. Used
+ * by the migrator both to detect a default add/change on an existing column and to
+ * COALESCE-backfill a NOT NULL column during a rebuild. */
+export declare function defaultSqlValue(f: FieldDef): string | null;
 export declare function createTableSql(table: string, def: {
     fields: EntityFields;
 }): string;
@@ -10,7 +20,10 @@ export declare function addColumnSql(name: string, f: FieldDef): string;
 /** Index name for a column's unique/index constraint. */
 export declare function indexName(table: string, col: string): string;
 /** CREATE [UNIQUE] INDEX statements for a table's unique/index columns (idempotent
- * via IF NOT EXISTS). Unique wins if a column declares both. */
+ * via IF NOT EXISTS). Unique wins if a column declares both. `skipCols` omits specific
+ * columns — the migrator uses it to avoid emitting a UNIQUE index that would throw
+ * (duplicate values present on a column that just gained `unique()`); that delta is
+ * reported as skipped instead. */
 export declare function indexStatements(table: string, def: {
     fields: EntityFields;
-}): string[];
+}, skipCols?: ReadonlySet<string>): string[];

package/dist/runtime/ddl.js

@@ -1,6 +1,7 @@
 // DDL generation — CREATE TABLE for a new entity and the additive ALTER fragment
 // for a new column. Runs in TS inside the isolate; see runtime/migrate.ts for how
 // these are applied.
+import { quoteIdent } from "./driver";
 // SQLite has no boolean type; store as INTEGER 0/1. json + fileRef + uuid are
 // stored as TEXT. Exported for the migrator, which compares declared column types
 // (and CASTs on a type change).
@@ -9,8 +10,10 @@ export const sqlType = (f) => f.type === "boolean"
     : f.type === "json" || f.type === "fileRef" || f.type === "uuid"
         ? "TEXT"
         : f.type.toUpperCase();
-/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1. */
-function defaultLiteral(v) {
+/** Render a DEFAULT literal. Strings are single-quote-escaped; booleans → 0/1.
+ * Exported for the migrator, which reconstructs a column's expected DEFAULT text to
+ * compare against the live `PRAGMA table_info.dflt_value`. */
+export function defaultLiteral(v) {
     if (v === null)
         return "NULL";
     if (typeof v === "boolean")
@@ -19,6 +22,18 @@ function defaultLiteral(v) {
         return String(v);
     return `'${v.replace(/'/g, "''")}'`;
 }
+/** The SQL text of a column's DEFAULT value (the part after `DEFAULT `), or null when
+ * the column declares no default. A raw-SQL `defaultExpr` is returned unquoted (e.g.
+ * `datetime('now')`); a literal `default` is rendered via {@link defaultLiteral}. Used
+ * by the migrator both to detect a default add/change on an existing column and to
+ * COALESCE-backfill a NOT NULL column during a rebuild. */
+export function defaultSqlValue(f) {
+    if (f.defaultExpr !== undefined)
+        return f.defaultExpr;
+    if (f.default !== undefined)
+        return defaultLiteral(f.default);
+    return null;
+}
 /** The ` DEFAULT x` fragment for a column, or "" when it has no default. A raw-SQL
  * `defaultExpr` (e.g. `datetime('now')`) is emitted UNQUOTED; a literal `default` is
  * quote-escaped. UNIQUE/index are NOT inline — they're emitted as separate index
@@ -32,7 +47,7 @@ function defaultSql(f) {
     return f.default !== undefined ? ` DEFAULT ${defaultLiteral(f.default)}` : "";
 }
 function columnSql(name, f) {
-    let s = `${name} ${sqlType(f)}`;
+    let s = `${quoteIdent(name)} ${sqlType(f)}`;
     if (f.primaryKey)
         s += " PRIMARY KEY";
     if (f.autoIncrement)
@@ -44,13 +59,13 @@ function columnSql(name, f) {
 }
 export function createTableSql(table, def) {
     const cols = Object.entries(def.fields).map(([n, f]) => columnSql(n, f));
-    return `CREATE TABLE IF NOT EXISTS ${table} (${cols.join(", ")})`;
+    return `CREATE TABLE IF NOT EXISTS ${quoteIdent(table)} (${cols.join(", ")})`;
 }
 /** Column definition for ALTER TABLE ADD COLUMN. No PRIMARY KEY / AUTOINCREMENT.
  * NOT NULL is only emitted alongside a DEFAULT (SQLite can't add a bare NOT NULL to
  * a populated table); a DEFAULT alone backfills existing rows. */
 export function addColumnSql(name, f) {
-    let s = `${name} ${sqlType(f)}`;
+    let s = `${quoteIdent(name)} ${sqlType(f)}`;
     if (f.notNull && f.default !== undefined)
         s += " NOT NULL";
     s += defaultSql(f);
@@ -61,14 +76,19 @@ export function indexName(table, col) {
     return `pramen_idx_${table}_${col}`;
 }
 /** CREATE [UNIQUE] INDEX statements for a table's unique/index columns (idempotent
- * via IF NOT EXISTS). Unique wins if a column declares both. */
-export function indexStatements(table, def) {
+ * via IF NOT EXISTS). Unique wins if a column declares both. `skipCols` omits specific
+ * columns — the migrator uses it to avoid emitting a UNIQUE index that would throw
+ * (duplicate values present on a column that just gained `unique()`); that delta is
+ * reported as skipped instead. */
+export function indexStatements(table, def, skipCols) {
     const out = [];
     for (const [col, f] of Object.entries(def.fields)) {
         if (!f.unique && !f.index)
             continue;
+        if (skipCols?.has(col))
+            continue;
         const kind = f.unique ? "UNIQUE INDEX" : "INDEX";
-        out.push(`CREATE ${kind} IF NOT EXISTS ${indexName(table, col)} ON ${table} (${col})`);
+        out.push(`CREATE ${kind} IF NOT EXISTS ${quoteIdent(indexName(table, col))} ON ${quoteIdent(table)} (${quoteIdent(col)})`);
     }
     return out;
 }

package/dist/runtime/dispatch.js

@@ -12,6 +12,7 @@ import { warmup } from "./acl";
 import { BadRequest, Forbidden } from "./errors";
 import { enqueueTask } from "./outbox";
 import { createMail } from "./mail";
+import { createQueue } from "./queue";
 import { authorizeHandler } from "../sdk/handlers";
 /** The `ctx.tasks` facade over the outbox. `onEnqueue` lets the caller count enqueues
  * so it can wake the drainer. */
@@ -63,6 +64,7 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
         identity: acl.identity,
         tasks: tasksFacade(driver, () => enqueued++),
         mail: createMail(env, kv),
+        queue: createQueue(env),
     };
     const result = handler.kind === "query"
         ? await handler.run(ctx, parsed)

package/dist/runtime/driver.d.ts

@@ -9,8 +9,15 @@ export interface Dialect {
     /** Coerce a JS value for binding (e.g. boolean → 0/1 on SQLite). */
     encode(v: unknown): unknown;
 }
-/** SQLite (DO SQLite and D1 both speak this). Bare identifiers, `?` placeholders,
- * booleans stored as INTEGER 0/1, RETURNING supported. */
+/** Render an identifier as a standard double-quoted name (`"order"`), guarding its
+ * shape first. SQLite (DO SQLite + D1) and Postgres all accept double-quoted
+ * identifiers, so a column/table named after a reserved word (`order`, `group`, …)
+ * is safe and case is preserved. The single source of truth for both dialects and
+ * the DDL generator — keep every emitted identifier going through this. */
+export declare function quoteIdent(name: string): string;
+/** SQLite (DO SQLite and D1 both speak this). Double-quoted identifiers (so reserved
+ * words like `order` work), `?` placeholders, booleans stored as INTEGER 0/1,
+ * RETURNING supported. */
 export declare const sqliteDialect: Dialect;
 /** Postgres (e.g. over Hyperdrive). Double-quoted identifiers preserve case (so
  * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
@@ -33,13 +40,40 @@ export declare class DoSqliteDriver implements Driver {
     exec(sql: string, params: unknown[]): Promise<Row[]>;
     transaction<T>(fn: () => Promise<T>): Promise<T>;
 }
-/** D1 — SQLite over RPC. Async by nature. D1 has no interactive transactions, so
- * `transaction()` runs `fn` without one (a documented limitation: mutations don't
- * roll back on throw the way they do on a DO). Use a DO when you need that. */
+/** How a D1Driver's session is anchored (passed to `db.withSession`):
+ *   - `"first-primary"`       — first query hits the primary (current data), the rest
+ *                               read replicas consistent with the session bookmark. Use
+ *                               for a MUTATION (reads must see current data; writes go
+ *                               to primary anyway).
+ *   - `"first-unconstrained"` — first query may hit the nearest replica. Use for a QUERY.
+ *   - a bookmark string       — anchor at a prior write's bookmark for read-your-writes
+ *                               (the client carries it forward via a header).
+ * A bookmark always wins over a constraint when one is supplied. */
+export type D1SessionStart = "first-primary" | "first-unconstrained" | (string & {});
+/** D1 — SQLite over RPC. Async by nature.
+ *
+ * Read replicas (Sessions API): every D1Driver opens ONE `db.withSession(start)` and
+ * runs all `exec` through it. Writes in a session always land on the primary; the
+ * `start` only chooses where the FIRST read may begin. The session maintains a
+ * bookmark (`getBookmark()`) so later reads are sequentially consistent with earlier
+ * writes — read-your-writes when the bookmark is threaded across requests.
+ *
+ * ATOMICITY LIMIT (intentional): D1 has NO interactive transactions — a session can't
+ * read mid-`batch()`, and pramen mutations interleave reads + writes + RETURNING +
+ * trigger-into-outbox inside one `transaction()`. So `transaction(fn) = fn()`: each
+ * statement auto-commits on its own, and a multi-statement mutation does NOT roll back
+ * on throw the way it does on a DO. Single-statement mutations are atomic; anything
+ * multi-statement is not. Use the DO store when you need atomic mutations. */
 export declare class D1Driver implements Driver {
-    private readonly db;
     readonly dialect: Dialect;
-    constructor(db: D1Database);
+    private readonly session;
+    constructor(db: D1Database, opts?: {
+        start?: D1SessionStart;
+    });
     exec(sql: string, params: unknown[]): Promise<Row[]>;
+    /** The session's latest bookmark (null before any query). Threaded back to the client
+     * via the `x-pramen-d1-bookmark` response header so a subsequent request can anchor a
+     * fresh session at it and read its own writes. */
+    getBookmark(): string | null;
     transaction<T>(fn: () => Promise<T>): Promise<T>;
 }

package/dist/runtime/driver.js

@@ -18,10 +18,19 @@ function checkIdent(name) {
         throw new Error(`invalid identifier: ${name}`);
     return name;
 }
-/** SQLite (DO SQLite and D1 both speak this). Bare identifiers, `?` placeholders,
- * booleans stored as INTEGER 0/1, RETURNING supported. */
+/** Render an identifier as a standard double-quoted name (`"order"`), guarding its
+ * shape first. SQLite (DO SQLite + D1) and Postgres all accept double-quoted
+ * identifiers, so a column/table named after a reserved word (`order`, `group`, …)
+ * is safe and case is preserved. The single source of truth for both dialects and
+ * the DDL generator — keep every emitted identifier going through this. */
+export function quoteIdent(name) {
+    return `"${checkIdent(name)}"`;
+}
+/** SQLite (DO SQLite and D1 both speak this). Double-quoted identifiers (so reserved
+ * words like `order` work), `?` placeholders, booleans stored as INTEGER 0/1,
+ * RETURNING supported. */
 export const sqliteDialect = {
-    id: checkIdent,
+    id: quoteIdent,
     placeholder: () => "?",
     returning: true,
     encode: (v) => (typeof v === "boolean" ? (v ? 1 : 0) : v),
@@ -30,7 +39,7 @@ export const sqliteDialect = {
  * `ownerId` doesn't fold to `ownerid`), `$n` placeholders, native booleans,
  * RETURNING supported. */
 export const postgresDialect = {
-    id: (name) => `"${checkIdent(name)}"`,
+    id: quoteIdent,
     placeholder: (n) => `$${n}`,
     returning: true,
     encode: (v) => v, // the pg driver handles type encoding
@@ -50,20 +59,38 @@ export class DoSqliteDriver {
         return this.storage.transaction(fn);
     }
 }
-/** D1 — SQLite over RPC. Async by nature. D1 has no interactive transactions, so
- * `transaction()` runs `fn` without one (a documented limitation: mutations don't
- * roll back on throw the way they do on a DO). Use a DO when you need that. */
+/** D1 — SQLite over RPC. Async by nature.
+ *
+ * Read replicas (Sessions API): every D1Driver opens ONE `db.withSession(start)` and
+ * runs all `exec` through it. Writes in a session always land on the primary; the
+ * `start` only chooses where the FIRST read may begin. The session maintains a
+ * bookmark (`getBookmark()`) so later reads are sequentially consistent with earlier
+ * writes — read-your-writes when the bookmark is threaded across requests.
+ *
+ * ATOMICITY LIMIT (intentional): D1 has NO interactive transactions — a session can't
+ * read mid-`batch()`, and pramen mutations interleave reads + writes + RETURNING +
+ * trigger-into-outbox inside one `transaction()`. So `transaction(fn) = fn()`: each
+ * statement auto-commits on its own, and a multi-statement mutation does NOT roll back
+ * on throw the way it does on a DO. Single-statement mutations are atomic; anything
+ * multi-statement is not. Use the DO store when you need atomic mutations. */
 export class D1Driver {
-    db;
     dialect = sqliteDialect;
-    constructor(db) {
-        this.db = db;
+    session;
+    constructor(db, opts) {
+        this.session = db.withSession(opts?.start ?? "first-unconstrained");
     }
     async exec(sql, params) {
-        const stmt = params.length ? this.db.prepare(sql).bind(...params) : this.db.prepare(sql);
+        const stmt = params.length ? this.session.prepare(sql).bind(...params) : this.session.prepare(sql);
         const { results } = await stmt.all();
         return results ?? [];
     }
+    /** The session's latest bookmark (null before any query). Threaded back to the client
+     * via the `x-pramen-d1-bookmark` response header so a subsequent request can anchor a
+     * fresh session at it and read its own writes. */
+    getBookmark() {
+        return this.session.getBookmark();
+    }
+    // D1 has no interactive/atomic transactions — see the class doc. Run `fn` as-is.
     transaction(fn) {
         return fn();
     }

package/dist/runtime/migrate.d.ts

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

package/dist/runtime/migrate.js

@@ -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,9 +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 { entitiesInPartition, validateSchema } from "../sdk/schema";
+import { quoteIdent } from "./driver";
+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. */
@@ -31,11 +52,6 @@ function isInternalTable(name) {
         n.startsWith("_cf_") ||
         n.startsWith("d1_"));
 }
-function ident(name) {
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
-        throw new Error(`invalid identifier: ${name}`);
-    return name;
-}
 export function schemaHash(schema) {
     const canon = {};
     for (const [table, def] of Object.entries(schema))
@@ -45,9 +61,78 @@ export function schemaHash(schema) {
 /** Live columns of a table -> their declared SQL type (uppercased). Empty if the
  * table doesn't exist. */
 async function tableColumns(driver, table) {
-    const rows = (await driver.exec(`PRAGMA table_info(${ident(table)})`, []));
+    const rows = (await driver.exec(`PRAGMA table_info(${quoteIdent(table)})`, []));
     return new Map(rows.map((r) => [r.name, (r.type || "").toUpperCase()]));
 }
+/** 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;
@@ -60,7 +145,7 @@ async function writeMeta(driver, key, value) {
  * type change; brand-new columns left NULL), drop the old table, rename the temp. */
 async function rebuildTable(driver, table, def, live) {
     const tmp = `__pramen_rebuild_${table}`;
-    await driver.exec(`DROP TABLE IF EXISTS ${ident(tmp)}`, []);
+    await driver.exec(`DROP TABLE IF EXISTS ${quoteIdent(tmp)}`, []);
     await driver.exec(createTableSql(tmp, def), []);
     const destCols = [];
     const srcExprs = [];
@@ -70,14 +155,22 @@ async function rebuildTable(driver, table, def, live) {
         if (!src)
             continue; // brand-new column with no source -> leave NULL
         const target = sqlType(f);
-        destCols.push(ident(name));
-        srcExprs.push(live.get(src) === target ? ident(src) : `CAST(${ident(src)} AS ${target})`);
+        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, schema, opts = {}) {
     // Static schema invariants (relation targets exist, no cross-partition relations) —
@@ -113,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) {
@@ -133,12 +229,16 @@ export async function migrate(driver, schema, opts = {}) {
                 needsAdditiveRebuild = true;
                 continue;
             }
-            await driver.exec(`ALTER TABLE ${ident(table)} ADD COLUMN ${addColumnSql(name, field)}`, []);
+            await driver.exec(`ALTER TABLE ${quoteIdent(table)} ADD COLUMN ${addColumnSql(name, field)}`, []);
             added.push(`${table}.${name}`);
         }
-        // Pass 2 — destructive: rebuild if any live column must be dropped, a declared
-        // 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)) {
@@ -148,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).
@@ -181,7 +369,7 @@ export async function migrate(driver, schema, opts = {}) {
         if (isInternalTable(name) || inScope.has(name) || otherPartitionTables.has(name))
             continue;
         if (allowDestructive) {
-            await driver.exec(`DROP TABLE ${ident(name)}`, []);
+            await driver.exec(`DROP TABLE ${quoteIdent(name)}`, []);
             droppedTables.push(name);
         }
         else {
@@ -199,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 };
 }