@pramen/server 0.0.35 → 0.0.36

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger } from "./sdk/schema";
 export type { TriggerDef, TriggerOp } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
-export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, } from "./sdk/schema";
+export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, ManyToManyDef, OneHasOneDef, OneHasOneInverseDef, OnDelete, } from "./sdk/schema";
 export { createApp } from "./sdk/app";
 export { query, mutation, authorizeHandler } from "./sdk/handlers";
 export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts, HandlerAuth, Tasks, TaskHandler, AppTaskMap, BootstrapContext, BootstrapFn } from "./sdk/handlers";

package/dist/runtime/acl.js

@@ -3,7 +3,7 @@
 // granted, the row-level predicate to merge into the query, and any field
 // restriction. Deny-by-default; grants OR-merge across the identity's roles.
 import { deny, isAllow, isDeny, isIdentityMarker, isInputMarker, isResolver, } from "../sdk/acl";
-import { and, compileWhere, evalExpr, FALSE, or, TRUE } from "./read-engine";
+import { and, compileWhere, evalExpr, FALSE, not, or, TRUE } from "./read-engine";
 import { BadRequest, PramenError } from "./errors";
 export class AclDenied extends PramenError {
     entity;
@@ -183,6 +183,9 @@ function assertReadableRelationWhere(where, target, fields, ctx) {
             for (const g of v)
                 assertReadableRelationWhere(g, target, fields, ctx);
         }
+        else if (k === "NOT") {
+            assertReadableRelationWhere(v, target, fields, ctx);
+        }
         else if (targetRels[k]) {
             continue;
         }
@@ -224,7 +227,15 @@ function relationPredicate(rel, nested, parentEntity, ctx, depth) {
     }
     // belongsTo: parent.<fk> IN (SELECT <target pk> FROM target WHERE inner)
     // hasMany:   parent.<pk> IN (SELECT <target fk> FROM target WHERE inner)
-    return rel.kind === "belongsTo"
+    // manyToMany: parent.<pk> IN (SELECT <sourceCol> FROM through
+    //               WHERE <targetCol> IN (SELECT <target pk> FROM target WHERE inner))
+    if (rel.kind === "manyToMany") {
+        const targetSub = { t: "sub", outerCol: rel.targetColumn, from: rel.target, selectCol: pkOf(ctx.schema, rel.target), where: inner, negate: false };
+        return { t: "sub", outerCol: pkOf(ctx.schema, parentEntity), from: rel.through, selectCol: rel.sourceColumn, where: targetSub, negate: false };
+    }
+    // oneHasOne mirrors belongsTo (this row's FK → target pk); oneHasOneInverse mirrors
+    // hasMany (target's column → this row's pk).
+    return rel.kind === "belongsTo" || rel.kind === "oneHasOne"
         ? { t: "sub", outerCol: rel.column, from: rel.target, selectCol: pkOf(ctx.schema, rel.target), where: inner, negate: false }
         : { t: "sub", outerCol: pkOf(ctx.schema, parentEntity), from: rel.target, selectCol: rel.column, where: inner, negate: false };
 }
@@ -254,6 +265,9 @@ export function compileScopedWhere(rule, entity, ctx, depth = 0, allowRelations
             const groups = v.map((g) => compileScopedWhere(g, entity, ctx, depth, allowRelations));
             parts.push(k === "AND" ? and(...groups) : or(...groups));
         }
+        else if (k === "NOT") {
+            parts.push(not(compileScopedWhere(v, entity, ctx, depth, allowRelations)));
+        }
         else if (relations[k]) {
             if (!allowRelations) {
                 throw new BadRequest(`cell-level \`when\` cannot traverse relations: '${k}' (relations need a SQL round-trip)`);

package/dist/runtime/db.js

@@ -296,6 +296,9 @@ export class Db {
                 for (const p of expr.parts)
                     this.addTouchedTables(p);
                 break;
+            case "not":
+                this.addTouchedTables(expr.expr);
+                break;
         }
     }
     /** Reject a user `where` that filters on a column the caller cannot read (closes
@@ -313,6 +316,9 @@ export class Db {
                 for (const g of v)
                     this.assertReadableWhere(from, scope, g);
             }
+            else if (k === "NOT") {
+                this.assertReadableWhere(from, scope, v);
+            }
             else if (relations[k]) {
                 continue; // relation traversal: enforced against the target's scope downstream
             }
@@ -526,8 +532,8 @@ export class Db {
             const rows = this.decodeRows(rel.target, await this.driver.exec(sql, params));
             return rows.map((row) => ({ key: row[col], row: project(row) }));
         };
-        if (rel.kind === "belongsTo") {
-            // parent[column] -> target.id
+        if (rel.kind === "belongsTo" || rel.kind === "oneHasOne") {
+            // parent[column] -> target.id (single-valued; oneHasOne is belongsTo + a 1:1 unique)
             const keys = [...new Set(rows.map((r) => r[rel.column]).filter((v) => v != null))];
             const byId = new Map();
             for (const { key, row } of await fetchBy(this.pkOf(rel.target), keys))
@@ -535,6 +541,47 @@ export class Db {
             for (const r of rows)
                 r[relName] = r[rel.column] != null ? (byId.get(r[rel.column]) ?? null) : null;
         }
+        else if (rel.kind === "oneHasOneInverse") {
+            // inverse 1:1 — target[column] -> parent.<pk>, single object (or null)
+            const pk = this.pkOf(parentEntity);
+            const ids = [...new Set(rows.map((r) => r[pk]).filter((v) => v != null))];
+            const byParent = new Map();
+            for (const { key, row } of await fetchBy(rel.column, ids))
+                if (!byParent.has(key))
+                    byParent.set(key, row);
+            for (const r of rows)
+                r[relName] = byParent.get(r[pk]) ?? null;
+        }
+        else if (rel.kind === "manyToMany") {
+            // parent.<pk> -> junction(sourceColumn -> targetColumn) -> target.<pk>. The junction
+            // is read for just its two link columns (its own ACL isn't applied — like hasMany's
+            // intermediate); the target rows ARE scope-filtered by fetchBy, so an unreadable
+            // target simply drops out of the list.
+            const pk = this.pkOf(parentEntity);
+            const parentIds = [...new Set(rows.map((r) => r[pk]).filter((v) => v != null))];
+            if (parentIds.length === 0) {
+                for (const r of rows)
+                    r[relName] = [];
+                return;
+            }
+            this.touched.add(rel.through);
+            const linkSel = compileSelect({ from: rel.through, where: inList(rel.sourceColumn, parentIds) }, this.dialect);
+            const links = this.decodeRows(rel.through, await this.driver.exec(linkSel.sql, linkSel.params));
+            const targetIds = [...new Set(links.map((l) => l[rel.targetColumn]).filter((v) => v != null))];
+            const byTarget = new Map();
+            for (const { key, row } of await fetchBy(this.pkOf(rel.target), targetIds))
+                byTarget.set(key, row);
+            const grouped = new Map();
+            for (const l of links) {
+                const t = byTarget.get(l[rel.targetColumn]);
+                if (!t)
+                    continue; // target unreadable or missing -> excluded from the list
+                const src = l[rel.sourceColumn];
+                (grouped.get(src) ?? grouped.set(src, []).get(src)).push(t);
+            }
+            for (const r of rows)
+                r[relName] = grouped.get(r[pk]) ?? [];
+        }
         else {
             // hasMany: target[column] -> parent.<pk> (NOT hardcoded `id` — a parent keyed by
             // slug/username would otherwise join on an undefined `r.id` and get []).

package/dist/runtime/ddl.d.ts

@@ -1,4 +1,4 @@
-import type { DefaultValue, EntityFields, FieldDef } from "../sdk/schema";
+import type { DefaultValue, EntityFields, FieldDef, RelationDefs } 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
@@ -10,20 +10,46 @@ export declare function defaultLiteral(v: DefaultValue): string;
  * 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;
+/** Table-level FOREIGN KEY clauses for an entity's owning relations. A real FK is emitted
+ * ONLY for a `belongsTo`/`oneHasOne` that declares `onDelete` — so FKs are opt-in and
+ * pre-existing logical relations are unaffected (no retroactive constraint on data). `pkOf`
+ * resolves the referenced entity's primary-key column. `skip` omits specific FK columns —
+ * the migrator uses it to drop an FK whose existing data has orphaned references. */
+export declare function foreignKeyClauses(def: {
+    relations?: RelationDefs;
+}, pkOf: (entity: string) => string, skip?: ReadonlySet<string>): string[];
+/** The FK columns an entity declares (belongsTo with onDelete) → their {target, action}.
+ * Used by the migrator to compare declared FKs against the live `foreign_key_list`. */
+export declare function declaredForeignKeys(def: {
+    relations?: RelationDefs;
+}): Map<string, {
+    target: string;
+    onDelete: string;
+}>;
 export declare function createTableSql(table: string, def: {
     fields: EntityFields;
-}): string;
+    relations?: RelationDefs;
+}, pkOf?: (entity: string) => string, skipFks?: ReadonlySet<string>): string;
 /** 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 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;
+/** Index name for a composite (multi-column) UNIQUE constraint. The `pramen_uidx_`
+ * prefix distinguishes managed composite uniques from single-column `pramen_idx_` ones,
+ * so the migrator can enumerate and reconcile just the ones it owns. */
+export declare function compositeUniqueName(table: string, cols: readonly string[]): string;
+/** Canonical key for a composite-unique column tuple (order-significant, matching the
+ * index definition). Used to compare declared vs live composite uniques. */
+export declare function compositeKey(cols: readonly 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. `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. */
+ * reported as skipped instead. Entity-level composite uniques (`def.uniques`) are
+ * emitted too; `skipUniques` omits specific tuples (keyed by {@link compositeKey}). */
 export declare function indexStatements(table: string, def: {
     fields: EntityFields;
-}, skipCols?: ReadonlySet<string>): string[];
+    uniques?: readonly (readonly string[])[];
+}, skipCols?: ReadonlySet<string>, skipUniques?: ReadonlySet<string>): string[];

package/dist/runtime/ddl.js

@@ -57,9 +57,39 @@ function columnSql(name, f) {
     s += defaultSql(f);
     return s;
 }
-export function createTableSql(table, def) {
+/** Table-level FOREIGN KEY clauses for an entity's owning relations. A real FK is emitted
+ * ONLY for a `belongsTo`/`oneHasOne` that declares `onDelete` — so FKs are opt-in and
+ * pre-existing logical relations are unaffected (no retroactive constraint on data). `pkOf`
+ * resolves the referenced entity's primary-key column. `skip` omits specific FK columns —
+ * the migrator uses it to drop an FK whose existing data has orphaned references. */
+export function foreignKeyClauses(def, pkOf, skip) {
+    const out = [];
+    for (const rel of Object.values(def.relations ?? {})) {
+        if ((rel.kind !== "belongsTo" && rel.kind !== "oneHasOne") || rel.onDelete === undefined)
+            continue; // FK only when onDelete is declared
+        if (skip?.has(rel.column))
+            continue;
+        const action = rel.onDelete === "cascade" ? "CASCADE" : rel.onDelete === "setNull" ? "SET NULL" : "RESTRICT";
+        out.push(`FOREIGN KEY (${quoteIdent(rel.column)}) REFERENCES ${quoteIdent(rel.target)}(${quoteIdent(pkOf(rel.target))}) ON DELETE ${action}`);
+    }
+    return out;
+}
+/** The FK columns an entity declares (belongsTo with onDelete) → their {target, action}.
+ * Used by the migrator to compare declared FKs against the live `foreign_key_list`. */
+export function declaredForeignKeys(def) {
+    const out = new Map();
+    for (const rel of Object.values(def.relations ?? {})) {
+        if ((rel.kind !== "belongsTo" && rel.kind !== "oneHasOne") || rel.onDelete === undefined)
+            continue;
+        const action = rel.onDelete === "cascade" ? "CASCADE" : rel.onDelete === "setNull" ? "SET NULL" : "RESTRICT";
+        out.set(rel.column, { target: rel.target, onDelete: action });
+    }
+    return out;
+}
+export function createTableSql(table, def, pkOf, skipFks) {
     const cols = Object.entries(def.fields).map(([n, f]) => columnSql(n, f));
-    return `CREATE TABLE IF NOT EXISTS ${quoteIdent(table)} (${cols.join(", ")})`;
+    const fks = pkOf ? foreignKeyClauses(def, pkOf, skipFks) : [];
+    return `CREATE TABLE IF NOT EXISTS ${quoteIdent(table)} (${[...cols, ...fks].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
@@ -75,12 +105,24 @@ export function addColumnSql(name, f) {
 export function indexName(table, col) {
     return `pramen_idx_${table}_${col}`;
 }
+/** Index name for a composite (multi-column) UNIQUE constraint. The `pramen_uidx_`
+ * prefix distinguishes managed composite uniques from single-column `pramen_idx_` ones,
+ * so the migrator can enumerate and reconcile just the ones it owns. */
+export function compositeUniqueName(table, cols) {
+    return `pramen_uidx_${table}_${cols.join("_")}`;
+}
+/** Canonical key for a composite-unique column tuple (order-significant, matching the
+ * index definition). Used to compare declared vs live composite uniques. */
+export function compositeKey(cols) {
+    return cols.join(",");
+}
 /** CREATE [UNIQUE] INDEX statements for a table's unique/index columns (idempotent
  * 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) {
+ * reported as skipped instead. Entity-level composite uniques (`def.uniques`) are
+ * emitted too; `skipUniques` omits specific tuples (keyed by {@link compositeKey}). */
+export function indexStatements(table, def, skipCols, skipUniques) {
     const out = [];
     for (const [col, f] of Object.entries(def.fields)) {
         if (!f.unique && !f.index)
@@ -90,5 +132,11 @@ export function indexStatements(table, def, skipCols) {
         const kind = f.unique ? "UNIQUE INDEX" : "INDEX";
         out.push(`CREATE ${kind} IF NOT EXISTS ${quoteIdent(indexName(table, col))} ON ${quoteIdent(table)} (${quoteIdent(col)})`);
     }
+    for (const cols of def.uniques ?? []) {
+        if (cols.length === 0 || skipUniques?.has(compositeKey(cols)))
+            continue;
+        const colList = cols.map((c) => quoteIdent(c)).join(", ");
+        out.push(`CREATE UNIQUE INDEX IF NOT EXISTS ${quoteIdent(compositeUniqueName(table, cols))} ON ${quoteIdent(table)} (${colList})`);
+    }
     return out;
 }

package/dist/runtime/driver.d.ts

@@ -30,6 +30,15 @@ export interface Driver {
     exec(sql: string, params: unknown[]): Promise<Row[]>;
     /** Run `fn` inside a transaction: commit on resolve, roll back on throw. */
     transaction<T>(fn: () => Promise<T>): Promise<T>;
+    /** Run a fixed sequence of write statements ATOMICALLY with FK checks deferred to the
+     * end — for a table rebuild that involves foreign keys (drop + recreate would trip an
+     * immediate FK check). Optional: absent on a driver whose migrate already runs inside a
+     * transaction (the DO), where the migrator falls back to sequential exec. Provided by the
+     * D1 driver (no interactive transactions — uses db.batch(), itself atomic). */
+    batch?(statements: ReadonlyArray<{
+        sql: string;
+        params: unknown[];
+    }>): Promise<void>;
 }
 /** DO SQLite — the in-process store. `SqlStorage` is synchronous; we wrap it as an
  * async Driver. Transactions use the DO's atomic `transaction()`. */
@@ -76,4 +85,11 @@ export declare class D1Driver implements Driver {
      * fresh session at it and read its own writes. */
     getBookmark(): string | null;
     transaction<T>(fn: () => Promise<T>): Promise<T>;
+    /** D1's one atomic primitive: `session.batch()` runs the statements in a single
+     * transaction (rolled back as a unit on failure). Prepend `defer_foreign_keys` so a
+     * table rebuild's transient FK violations are checked only at the batch's commit. */
+    batch(statements: ReadonlyArray<{
+        sql: string;
+        params: unknown[];
+    }>): Promise<void>;
 }

package/dist/runtime/driver.js

@@ -94,4 +94,14 @@ export class D1Driver {
     transaction(fn) {
         return fn();
     }
+    /** D1's one atomic primitive: `session.batch()` runs the statements in a single
+     * transaction (rolled back as a unit on failure). Prepend `defer_foreign_keys` so a
+     * table rebuild's transient FK violations are checked only at the batch's commit. */
+    async batch(statements) {
+        const prepared = [
+            this.session.prepare("PRAGMA defer_foreign_keys = ON"),
+            ...statements.map((s) => (s.params.length ? this.session.prepare(s.sql).bind(...s.params) : this.session.prepare(s.sql))),
+        ];
+        await this.session.batch(prepared);
+    }
 }

package/dist/runtime/migrate.js

@@ -37,7 +37,7 @@
 // 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, defaultSqlValue, indexName, indexStatements, sqlType } from "./ddl";
+import { addColumnSql, compositeKey, createTableSql, declaredForeignKeys, defaultSqlValue, indexName, indexStatements, sqlType } from "./ddl";
 import { digest } from "./digest";
 import { quoteIdent } from "./driver";
 import { entitiesInPartition, partitionOf, validateSchema } from "../sdk/schema";
@@ -54,8 +54,18 @@ function isInternalTable(name) {
 }
 export function schemaHash(schema) {
     const canon = {};
-    for (const [table, def] of Object.entries(schema))
-        canon[table] = def.fields;
+    for (const [table, def] of Object.entries(schema)) {
+        // Keep the bare-`fields` shape when there are no composite uniques AND no FKs so
+        // existing stores' hashes are byte-identical (no spurious migration); fold each in
+        // only when present (composite unique / a belongsTo with onDelete).
+        const fks = declaredForeignKeys(def);
+        const extra = {};
+        if (def.uniques.length)
+            extra.uniques = def.uniques;
+        if (fks.size)
+            extra.fks = Object.fromEntries([...fks].map(([c, s]) => [c, `${s.target}:${s.onDelete}`]));
+        canon[table] = Object.keys(extra).length ? { fields: def.fields, ...extra } : def.fields;
+    }
     return digest(canon);
 }
 /** Live columns of a table -> their declared SQL type (uppercased). Empty if the
@@ -105,6 +115,30 @@ 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;
 }
+/** Managed composite-unique indexes live on `table`: `compositeKey(cols)` → index name.
+ * Only `pramen_uidx_`-prefixed multi-column unique indexes are pramen-managed, so the
+ * reconciler never touches a hand-created index. */
+async function liveCompositeUniques(driver, table) {
+    const idx = (await driver.exec(`PRAGMA index_list(${quoteIdent(table)})`, []));
+    const out = new Map();
+    for (const i of idx) {
+        if (i.unique !== 1 || !i.name.startsWith("pramen_uidx_"))
+            continue;
+        const cols = (await driver.exec(`PRAGMA index_info(${quoteIdent(i.name)})`, []));
+        const names = cols.map((c) => c.name).filter((n) => n != null);
+        if (names.length >= 2)
+            out.set(names.join(","), i.name);
+    }
+    return out;
+}
+/** Does the column tuple hold a duplicate all-non-NULL combination? (A new composite
+ * UNIQUE over such data can't build its index.) Mirrors {@link columnHasDuplicates}. */
+async function compositeHasDuplicates(driver, table, cols) {
+    const notNull = cols.map((c) => `${quoteIdent(c)} IS NOT NULL`).join(" AND ");
+    const group = cols.map((c) => quoteIdent(c)).join(", ");
+    const rows = await driver.exec(`SELECT 1 FROM ${quoteIdent(table)} WHERE ${notNull} GROUP BY ${group} 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
@@ -140,13 +174,44 @@ async function readMeta(driver, key) {
 async function writeMeta(driver, key, value) {
     await driver.exec(`INSERT OR REPLACE INTO _pramen_meta (key, value) VALUES (?, ?)`, [key, value]);
 }
+/** Live tables (excluding internals and `table` itself) holding a foreign key that
+ * REFERENCES `table`, with everything needed to drop + faithfully restore them around a
+ * rebuild of `table`: their column list, their exact CREATE TABLE DDL, and their index
+ * DDL (both verbatim from sqlite_master). Needed because `DROP TABLE parent` performs an
+ * implicit `DELETE FROM parent`, and `defer_foreign_keys` defers only violation CHECKS —
+ * ON DELETE actions still fire (CASCADE/SET NULL corrupt the holders' rows; RESTRICT
+ * aborts immediately). SQLite's official escape (`PRAGMA foreign_keys=OFF`) is
+ * unavailable on DO SQLite and D1, so the holders are quarantined instead. */
+async function liveReferencingHolders(driver, table) {
+    const tables = (await driver.exec(`SELECT name, sql FROM sqlite_master WHERE type = 'table'`, []));
+    const out = [];
+    for (const t of tables) {
+        if (t.name === table || isInternalTable(t.name) || !t.sql)
+            continue;
+        const fks = (await driver.exec(`PRAGMA foreign_key_list(${quoteIdent(t.name)})`, []));
+        if (!fks.some((fk) => fk.table === table))
+            continue;
+        const cols = [...(await tableColumns(driver, t.name)).keys()];
+        const idx = (await driver.exec(`SELECT sql FROM sqlite_master WHERE type = 'index' AND tbl_name = ? AND sql IS NOT NULL`, [t.name]));
+        out.push({ name: t.name, cols, createSql: t.sql, indexSql: idx.map((r) => r.sql) });
+    }
+    return out;
+}
 /** Rebuild a table to exactly the declared schema: create a temp table, copy each
  * desired column from its source (renamed or same-named live column, CAST on a
- * type change; brand-new columns left NULL), drop the old table, rename the temp. */
-async function rebuildTable(driver, table, def, live) {
+ * type change; brand-new columns left NULL), drop the old table, rename the temp.
+ *
+ * FK safety: dropping the old table implicit-DELETEs its rows, which fires the ON DELETE
+ * actions of any live FK that references it — even under `defer_foreign_keys` (deferral
+ * postpones checks, not actions). So every live referencing holder is QUARANTINED first
+ * (bare FK-less copy of its rows, table dropped) and restored from its verbatim DDL after
+ * the swap — all inside the same atomic step, so the holders' rows can never be cascaded
+ * away, nulled, or trip a RESTRICT mid-rebuild. A SELF-referential FK gets the same
+ * treatment applied to the rebuilt table itself: the plain tmp+rename swap would give tmp
+ * a live FK into the old table right when it's dropped, so the swap goes through a bare
+ * (FK-less) copy instead — quarantine out, recreate final, copy back. */
+async function rebuildTable(driver, table, def, live, pkOf, skipFks) {
     const tmp = `__pramen_rebuild_${table}`;
-    await driver.exec(`DROP TABLE IF EXISTS ${quoteIdent(tmp)}`, []);
-    await driver.exec(createTableSql(tmp, def), []);
     const destCols = [];
     const srcExprs = [];
     for (const [name, field] of Object.entries(def.fields)) {
@@ -166,18 +231,107 @@ async function rebuildTable(driver, table, def, live) {
         destCols.push(quoteIdent(name));
         srcExprs.push(expr);
     }
-    if (destCols.length > 0) {
-        await driver.exec(`INSERT INTO ${quoteIdent(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${quoteIdent(table)}`, []);
+    const holders = await liveReferencingHolders(driver, table);
+    // Self-referential FK — declared in the new shape (and surviving skipFks) or live on
+    // the old table — forces the bare-copy swap for the table itself.
+    const declaredSelf = [...declaredForeignKeys(def)].some(([col, s]) => s.target === table && !skipFks?.has(col));
+    const liveSelf = [...(await liveForeignKeys(driver, table)).values()].some((s) => s.target === table);
+    const selfRef = declaredSelf || liveSelf;
+    // The drop+rename would trip an immediate FK check (dropping a referenced table, or a
+    // rebuilt table whose FKs momentarily see stale rows), so run the whole sequence
+    // ATOMICALLY: the D1 driver's batch() defers FK checks to the batch commit, and on the
+    // DO the ambient boot transaction (+ defer set at migrate start) already covers it.
+    const stmts = [];
+    // Quarantine tables are bare column lists — untyped, no constraints, no FKs. Values
+    // round-trip verbatim (they were already coerced by the original table's affinity).
+    const bareCopy = (name, quotedCols) => `CREATE TABLE ${quoteIdent(name)} (${quotedCols.join(", ")})`;
+    // 1. Quarantine every live holder referencing this table (FK-less row copy, then drop),
+    //    so the swap's implicit DELETE has no FK actions left to fire into them.
+    for (const h of holders) {
+        const q = `__pramen_q_${h.name}`;
+        const cols = h.cols.map((c) => quoteIdent(c)).join(", ");
+        stmts.push({ sql: `DROP TABLE IF EXISTS ${quoteIdent(q)}`, params: [] });
+        stmts.push({ sql: bareCopy(q, h.cols.map((c) => quoteIdent(c))), params: [] });
+        stmts.push({ sql: `INSERT INTO ${quoteIdent(q)} (${cols}) SELECT ${cols} FROM ${quoteIdent(h.name)}`, params: [] });
+        stmts.push({ sql: `DROP TABLE ${quoteIdent(h.name)}`, params: [] });
     }
-    await driver.exec(`DROP TABLE ${quoteIdent(table)}`, []);
-    await driver.exec(`ALTER TABLE ${quoteIdent(tmp)} RENAME TO ${quoteIdent(table)}`, []);
+    // 2. Swap the table itself.
+    stmts.push({ sql: `DROP TABLE IF EXISTS ${quoteIdent(tmp)}`, params: [] });
+    if (selfRef) {
+        // Bare-copy swap: out to an FK-less temp, drop, recreate final, copy back. The final
+        // INSERT lists only the copied columns, so a new expr-default column still backfills.
+        stmts.push({ sql: bareCopy(tmp, destCols), params: [] });
+        if (destCols.length > 0) {
+            stmts.push({ sql: `INSERT INTO ${quoteIdent(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${quoteIdent(table)}`, params: [] });
+        }
+        stmts.push({ sql: `DROP TABLE ${quoteIdent(table)}`, params: [] });
+        stmts.push({ sql: createTableSql(table, def, pkOf, skipFks), params: [] });
+        if (destCols.length > 0) {
+            stmts.push({ sql: `INSERT INTO ${quoteIdent(table)} (${destCols.join(", ")}) SELECT ${destCols.join(", ")} FROM ${quoteIdent(tmp)}`, params: [] });
+        }
+        stmts.push({ sql: `DROP TABLE ${quoteIdent(tmp)}`, params: [] });
+    }
+    else {
+        stmts.push({ sql: createTableSql(tmp, def, pkOf, skipFks), params: [] });
+        if (destCols.length > 0) {
+            stmts.push({ sql: `INSERT INTO ${quoteIdent(tmp)} (${destCols.join(", ")}) SELECT ${srcExprs.join(", ")} FROM ${quoteIdent(table)}`, params: [] });
+        }
+        stmts.push({ sql: `DROP TABLE ${quoteIdent(table)}`, params: [] });
+        stmts.push({ sql: `ALTER TABLE ${quoteIdent(tmp)} RENAME TO ${quoteIdent(table)}`, params: [] });
+    }
+    // 3. Restore each holder verbatim (its DDL references this table by name, so its FK
+    //    binds to the rebuilt table). Row order/content unchanged; deferred checks validate
+    //    the restored FKs once at commit.
+    for (const h of holders) {
+        const q = `__pramen_q_${h.name}`;
+        const cols = h.cols.map((c) => quoteIdent(c)).join(", ");
+        stmts.push({ sql: h.createSql, params: [] });
+        stmts.push({ sql: `INSERT INTO ${quoteIdent(h.name)} (${cols}) SELECT ${cols} FROM ${quoteIdent(q)}`, params: [] });
+        stmts.push({ sql: `DROP TABLE ${quoteIdent(q)}`, params: [] });
+        for (const idx of h.indexSql)
+            stmts.push({ sql: idx, params: [] });
+    }
+    if (driver.batch)
+        await driver.batch(stmts);
+    else
+        for (const s of stmts)
+            await driver.exec(s.sql, s.params); // DO: already inside the boot txn
+}
+/** Primary-key column of an entity (the `primaryKey()` field), defaulting to `id`. */
+function pkColumnOf(def) {
+    if (def)
+        for (const [n, f] of Object.entries(def.fields))
+            if (f.primaryKey)
+                return n;
+    return "id";
+}
+/** Live FK columns of a table → {target, onDelete} via PRAGMA foreign_key_list. */
+async function liveForeignKeys(driver, table) {
+    const rows = (await driver.exec(`PRAGMA foreign_key_list(${quoteIdent(table)})`, []));
+    const out = new Map();
+    for (const r of rows)
+        out.set(r.from, { target: r.table, onDelete: (r.on_delete || "NO ACTION").toUpperCase() });
+    return out;
+}
+/** Does the FK column hold a non-NULL value with no matching target row? (Adding the FK
+ * over such data would fail the deferred check at commit.) */
+async function fkColumnHasOrphans(driver, table, col, target, targetPk) {
+    const rows = await driver.exec(`SELECT 1 FROM ${quoteIdent(table)} c WHERE c.${quoteIdent(col)} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${quoteIdent(target)} p WHERE p.${quoteIdent(targetPk)} = c.${quoteIdent(col)}) LIMIT 1`, []);
+    return rows.length > 0;
 }
 export async function migrate(driver, schema, opts = {}) {
     // Static schema invariants (relation targets exist, no cross-partition relations) —
     // checked before any DDL so a bad schema fails fast on boot / the D1 path, not mid-migration.
     validateSchema(schema);
     await driver.exec(`CREATE TABLE IF NOT EXISTS _pramen_meta (key TEXT PRIMARY KEY, value TEXT)`, []);
+    // Defer FK checks to the end of the migration transaction so drop/rebuild steps don't
+    // trip an immediate FK violation. On the DO the whole migrate runs in one transaction, so
+    // this one PRAGMA covers everything; on D1 (no ambient transaction) rebuilds instead go
+    // through driver.batch(), which sets its own defer — so this is a harmless no-op there.
+    await driver.exec(`PRAGMA defer_foreign_keys = ON`, []);
     const allowDestructive = opts.allowDestructive ?? false;
+    // Resolve a referenced entity's PK column (for FOREIGN KEY ... REFERENCES emission).
+    const pkOf = (entity) => pkColumnOf(schema[entity]);
     // When a partition is named, narrow the schema to just that partition's entities —
     // every later pass (create/alter/rebuild/drop/index/hash) iterates this subset, so
     // a partition-DO only ever touches its own tables. Unset ⇒ the whole schema, the
@@ -209,10 +363,13 @@ export async function migrate(driver, schema, opts = {}) {
     // 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();
+    // Per-table: composite-unique tuples (keyed by compositeKey) whose new index can't be
+    // built (duplicate tuples present) — skipped by the index pass, reported in `skipped`.
+    const compositeUniqueSkip = new Map();
     for (const [table, def] of entries) {
         const existing = await tableColumns(driver, table);
         if (existing.size === 0) {
-            await driver.exec(createTableSql(table, def), []);
+            await driver.exec(createTableSql(table, def, pkOf), []);
             created.push(table);
             continue;
         }
@@ -305,6 +462,25 @@ export async function migrate(driver, schema, opts = {}) {
                 dropUniqueCols.push(name); // drop the managed unique index (safe — no data loss)
             }
         }
+        // Foreign keys (belongsTo with onDelete). SQLite can't ALTER a table to add/change an
+        // FK, so any FK delta is enacted by a rebuild (safe — no data loss). An FK being ADDED
+        // over data with orphaned references is skipped (reported) and left out of the rebuild,
+        // mirroring the unique-over-duplicates behavior, so the migration doesn't fail.
+        const declaredFks = declaredForeignKeys(def);
+        const liveFks = await liveForeignKeys(driver, table);
+        const fkSkip = new Set();
+        for (const [col, spec] of declaredFks) {
+            if (!liveFks.has(col) && (await fkColumnHasOrphans(driver, table, col, spec.target, pkOf(spec.target)))) {
+                fkSkip.add(col);
+                skipped.push(`add FK ${table}.${col} → ${spec.target} (orphaned references present)`);
+            }
+        }
+        const applyFks = new Map([...declaredFks].filter(([col]) => !fkSkip.has(col)));
+        const fkChanged = applyFks.size !== liveFks.size ||
+            [...applyFks].some(([col, s]) => {
+                const l = liveFks.get(col);
+                return !l || l.target !== s.target || l.onDelete !== s.onDelete;
+            });
         const destructive = needsDrop || needsTypeChange || renamedSources.size > 0 || modifierRebuildDestructive;
         if (destructive && !allowDestructive) {
             // The destructive part is gated off — skip the whole rebuild (any pending safe
@@ -317,10 +493,10 @@ export async function migrate(driver, schema, opts = {}) {
             ];
             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);
+        else if (destructive || needsAdditiveRebuild || modifierRebuildSafe || fkChanged) {
+            // A safe rebuild (expr-default column, default/notNull modifier change, FK add/change)
+            // needs no permission — it loses no data.
+            await rebuildTable(driver, table, def, live, pkOf, fkSkip);
             rebuilt.push(table);
         }
         // Drop the managed unique index for a column that no longer declares `unique()`. A
@@ -330,6 +506,25 @@ export async function migrate(driver, schema, opts = {}) {
         for (const col of dropUniqueCols) {
             await driver.exec(`DROP INDEX IF EXISTS ${quoteIdent(indexName(table, col))}`, []);
         }
+        // Composite UNIQUE reconciliation (managed pramen_uidx_ indexes). Drop any live one
+        // the schema no longer declares; skip creating a new one whose tuples already have
+        // duplicates (the final index pass would otherwise throw). Creation itself is the
+        // idempotent index pass below.
+        const liveComposite = await liveCompositeUniques(driver, table);
+        const declaredComposite = new Set((def.uniques ?? []).map((c) => compositeKey(c)));
+        for (const [key, idxName] of liveComposite) {
+            if (!declaredComposite.has(key))
+                await driver.exec(`DROP INDEX IF EXISTS ${quoteIdent(idxName)}`, []);
+        }
+        for (const cols of def.uniques ?? []) {
+            const key = compositeKey(cols);
+            if (liveComposite.has(key))
+                continue;
+            if (await compositeHasDuplicates(driver, table, cols)) {
+                (compositeUniqueSkip.get(table) ?? compositeUniqueSkip.set(table, new Set()).get(table)).add(key);
+                skipped.push(`add composite UNIQUE ${table}(${cols.join(", ")}) (duplicate tuples present)`);
+            }
+        }
     }
     // 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
@@ -353,7 +548,7 @@ export async function migrate(driver, schema, opts = {}) {
     // 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, uniqueIndexSkip.get(table)))
+        for (const stmt of indexStatements(table, def, uniqueIndexSkip.get(table), compositeUniqueSkip.get(table)))
             await driver.exec(stmt, []);
     }
     // Drop tables the schema no longer declares (internal bookkeeping tables skipped).