@pramen/server 0.0.35 → 0.0.36

package/dist/runtime/read-engine.d.ts

@@ -1,5 +1,8 @@
 import type { Dialect } from "./driver";
 export type CmpOp = "=" | "!=" | ">" | ">=" | "<" | "<=" | "LIKE";
+/** Substring match mode for the structured string operators (auto-escaping, so the
+ * needle's `%`/`_` are literal). Case-insensitive, matching SQLite's default LIKE. */
+export type StrMode = "contains" | "prefix" | "suffix";
 export type SqlExpr = {
     t: "true";
 } | {
@@ -18,12 +21,20 @@ export type SqlExpr = {
     t: "null";
     col: string;
     negate: boolean;
+} | {
+    t: "strmatch";
+    col: string;
+    needle: string;
+    mode: StrMode;
 } | {
     t: "and";
     parts: SqlExpr[];
 } | {
     t: "or";
     parts: SqlExpr[];
+} | {
+    t: "not";
+    expr: SqlExpr;
 } | {
     t: "sub";
     outerCol: string;
@@ -37,8 +48,10 @@ export declare const FALSE: SqlExpr;
 export declare const cmp: (op: CmpOp, col: string, value: unknown) => SqlExpr;
 export declare const isNull: (col: string, negate?: boolean) => SqlExpr;
 export declare const inList: (col: string, values: unknown[], negate?: boolean) => SqlExpr;
+export declare const strMatch: (col: string, needle: string, mode: StrMode) => SqlExpr;
 export declare const and: (...parts: SqlExpr[]) => SqlExpr;
 export declare const or: (...parts: SqlExpr[]) => SqlExpr;
+export declare const not: (expr: SqlExpr) => SqlExpr;
 /** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
 export declare const eq: (col: string, value: unknown) => SqlExpr;
 /** Compile a structured user predicate into a SqlExpr.

package/dist/runtime/read-engine.js

@@ -15,8 +15,10 @@ export const FALSE = { t: "false" };
 export const cmp = (op, col, value) => ({ t: "cmp", op, col, value });
 export const isNull = (col, negate = false) => ({ t: "null", col, negate });
 export const inList = (col, values, negate = false) => ({ t: "in", col, values, negate });
+export const strMatch = (col, needle, mode) => ({ t: "strmatch", col, needle, mode });
 export const and = (...parts) => ({ t: "and", parts });
 export const or = (...parts) => ({ t: "or", parts });
+export const not = (expr) => ({ t: "not", expr });
 /** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
 export const eq = (col, value) => (value === null ? isNull(col) : cmp("=", col, value));
 /** Compile a structured user predicate into a SqlExpr.
@@ -30,6 +32,9 @@ export function compileWhere(input) {
         else if (k === "OR") {
             parts.push(or(...v.map(compileWhere)));
         }
+        else if (k === "NOT") {
+            parts.push(not(compileWhere(v)));
+        }
         else {
             parts.push(columnPredicate(k, v));
         }
@@ -62,6 +67,15 @@ function columnPredicate(col, v) {
                 case "like":
                     ops.push(cmp("LIKE", col, val));
                     break;
+                case "contains":
+                    ops.push(strMatch(col, String(val), "contains"));
+                    break;
+                case "startsWith":
+                    ops.push(strMatch(col, String(val), "prefix"));
+                    break;
+                case "endsWith":
+                    ops.push(strMatch(col, String(val), "suffix"));
+                    break;
                 case "in":
                     ops.push(inList(col, val));
                     break;
@@ -96,6 +110,15 @@ export function compileExpr(expr, dialect, params = []) {
             return { sql: `${dialect.id(expr.col)} ${expr.op} ${dialect.placeholder(params.length)}`, params };
         case "null":
             return { sql: `${dialect.id(expr.col)} IS ${expr.negate ? "NOT " : ""}NULL`, params };
+        case "strmatch": {
+            // Escape the LIKE metacharacters in the needle (\, %, _) so they match literally,
+            // then wrap with wildcards per mode. ESCAPE '\' declares the escape char (SQLite +
+            // Postgres both support it). LIKE is ASCII-case-insensitive by default.
+            const esc = expr.needle.replace(/[\\%_]/g, "\\$&");
+            const pattern = expr.mode === "contains" ? `%${esc}%` : expr.mode === "prefix" ? `${esc}%` : `%${esc}`;
+            params.push(dialect.encode(pattern));
+            return { sql: `${dialect.id(expr.col)} LIKE ${dialect.placeholder(params.length)} ESCAPE '\\'`, params };
+        }
         case "in": {
             if (expr.values.length === 0)
                 return { sql: expr.negate ? "1" : "0", params }; // empty: notIn=>all, in=>none
@@ -110,6 +133,8 @@ export function compileExpr(expr, dialect, params = []) {
             const sql = expr.parts.map((p) => compileExpr(p, dialect, params).sql).join(sep);
             return { sql: expr.parts.length > 1 ? `(${sql})` : sql, params };
         }
+        case "not":
+            return { sql: `NOT (${compileExpr(expr.expr, dialect, params).sql})`, params };
         case "sub": {
             // Inner predicate shares `params`, so placeholder numbering stays correct
             // across dialects (? and $n alike).
@@ -169,6 +194,14 @@ export function evalExpr(expr, row) {
             const isNullVal = v === null || v === undefined;
             return expr.negate ? !isNullVal : isNullVal;
         }
+        case "strmatch": {
+            const left = row[expr.col];
+            if (typeof left !== "string")
+                return false;
+            const s = left.toLowerCase();
+            const n = expr.needle.toLowerCase(); // CI, mirroring SQLite's default LIKE
+            return expr.mode === "contains" ? s.includes(n) : expr.mode === "prefix" ? s.startsWith(n) : s.endsWith(n);
+        }
         case "in": {
             const left = bind(row[expr.col]);
             if (left === null || left === undefined)
@@ -182,6 +215,8 @@ export function evalExpr(expr, row) {
             return expr.parts.every((p) => evalExpr(p, row));
         case "or":
             return expr.parts.some((p) => evalExpr(p, row));
+        case "not":
+            return !evalExpr(expr.expr, row);
         case "sub":
             // Relation traversal needs a SQL round-trip; it isn't supported in the
             // in-memory cell-ACL `when` evaluator (those predicates must be single-table).

package/dist/sdk/infer.d.ts

@@ -24,7 +24,9 @@ export type InferRow<F extends EntityFields> = {
 export type ProjectedRow<F extends EntityFields> = {
     [K in keyof F]?: Cell<F[K]>;
 };
-/** Operators available on a column predicate. `like` is string-only. */
+/** Operators available on a column predicate. String ops (`like`/`contains`/
+ * `startsWith`/`endsWith`) are string-only; `contains`/`startsWith`/`endsWith` escape
+ * the needle's wildcards (unlike `like`, where the caller writes `%`/`_`). */
 export interface WhereOps<V> {
     eq?: V | null;
     ne?: V | null;
@@ -35,15 +37,19 @@ export interface WhereOps<V> {
     in?: V[];
     notIn?: V[];
     like?: V extends string ? string : never;
+    contains?: V extends string ? string : never;
+    startsWith?: V extends string ? string : never;
+    endsWith?: V extends string ? string : never;
     isNull?: boolean;
 }
 /** Predicate input: per-column equality shorthand or an operator object, plus
- * nestable AND/OR groups. */
+ * nestable AND/OR/NOT groups. */
 export type WhereInput<F extends EntityFields> = {
     [K in keyof F]?: FieldTsType<F[K]> | null | WhereOps<FieldTsType<F[K]>>;
 } & {
     AND?: WhereInput<F>[];
     OR?: WhereInput<F>[];
+    NOT?: WhereInput<F>;
 };
 type PrevDepth = [never, 0, 1, 2, 3, 4, 5];
 type RelTargetTable<S extends SchemaDef, R> = R extends {
@@ -80,10 +86,10 @@ export type FieldsOf<E> = E extends EntityDef<infer F, RelationDefs> ? F : never
 /** Extract a schema entry's relations. */
 export type RelationsOf<E> = E extends EntityDef<EntityFields, infer R> ? R : Record<string, never>;
 type RelValue<S extends SchemaDef, Rel> = Rel extends {
-    kind: "belongsTo";
+    kind: "belongsTo" | "oneHasOne" | "oneHasOneInverse";
     target: infer Tg;
 } ? Tg extends keyof S ? InferRow<FieldsOf<S[Tg]>> | null : never : Rel extends {
-    kind: "hasMany";
+    kind: "hasMany" | "manyToMany";
     target: infer Tg;
 } ? Tg extends keyof S ? InferRow<FieldsOf<S[Tg]>>[] : never : never;
 /** The relation properties added to a row by `with`. Optional (present only when selected). */

package/dist/sdk/schema.d.ts

@@ -74,11 +74,18 @@ declare const builders: {
 };
 export type FieldBuilders = typeof builders;
 export type EntityFields = Record<string, FieldDef>;
+/** FK ON DELETE behavior for an owning relation's real foreign key. `restrict` (the
+ * default) blocks deleting a referenced row; `cascade` deletes the referencing rows;
+ * `setNull` nulls the FK column (which must be nullable). Enforced by the SQLite engine
+ * at runtime on both DO and D1. */
+export type OnDelete = "cascade" | "setNull" | "restrict";
 export interface BelongsToDef<T extends string = string> {
     readonly kind: "belongsTo";
     readonly target: T;
-    /** Local column holding the target's primary key. */
+    /** Local column holding the target's primary key (a real FK: REFERENCES target(pk)). */
     readonly column: string;
+    /** ON DELETE action for the FK; omitted ⇒ `restrict` (SQLite default). */
+    readonly onDelete?: OnDelete;
 }
 export interface HasManyDef<T extends string = string> {
     readonly kind: "hasMany";
@@ -86,19 +93,73 @@ export interface HasManyDef<T extends string = string> {
     /** Column on the target referring back to this entity's primary key. */
     readonly column: string;
 }
-export type RelationDef = BelongsToDef | HasManyDef;
+/** Many-to-many via an explicit junction entity. Logical (no FK constraints), like the
+ * other relation kinds: `through` is a normal entity you define and write to directly;
+ * `sourceColumn`/`targetColumn` are its columns holding this entity's and the target's
+ * primary keys. Source, junction, and target must share a partition (single-DO traversal). */
+export interface ManyToManyDef<T extends string = string> {
+    readonly kind: "manyToMany";
+    readonly target: T;
+    readonly through: string;
+    readonly sourceColumn: string;
+    readonly targetColumn: string;
+}
+/** One-to-one (owning side): THIS entity holds `column` = the target's primary key, and
+ * the pairing is 1:1 — mark `column` `unique()` for the DB-enforced guarantee. Reads as a
+ * single target (like belongsTo); FK-capable via `onDelete`. */
+export interface OneHasOneDef<T extends string = string> {
+    readonly kind: "oneHasOne";
+    readonly target: T;
+    readonly column: string;
+    readonly onDelete?: OnDelete;
+}
+/** One-to-one (inverse side): the TARGET holds `column` referencing THIS entity's primary
+ * key. Reads as a single target (the reverse of a oneHasOne), or null. */
+export interface OneHasOneInverseDef<T extends string = string> {
+    readonly kind: "oneHasOneInverse";
+    readonly target: T;
+    readonly column: string;
+}
+export type RelationDef = BelongsToDef | HasManyDef | ManyToManyDef | OneHasOneDef | OneHasOneInverseDef;
 export type RelationDefs = Record<string, RelationDef>;
 declare const relationBuilders: {
-    belongsTo: <T extends string>(target: T, column: string) => {
+    belongsTo: <T extends string>(target: T, column: string, opts?: {
+        onDelete?: OnDelete;
+    }) => {
         readonly kind: "belongsTo";
         readonly target: T;
         readonly column: string;
+        readonly onDelete: OnDelete | undefined;
     };
     hasMany: <T extends string>(target: T, column: string) => {
         readonly kind: "hasMany";
         readonly target: T;
         readonly column: string;
     };
+    oneHasOne: <T extends string>(target: T, column: string, opts?: {
+        onDelete?: OnDelete;
+    }) => {
+        readonly kind: "oneHasOne";
+        readonly target: T;
+        readonly column: string;
+        readonly onDelete: OnDelete | undefined;
+    };
+    oneHasOneInverse: <T extends string>(target: T, column: string) => {
+        readonly kind: "oneHasOneInverse";
+        readonly target: T;
+        readonly column: string;
+    };
+    manyToMany: <T extends string>(target: T, opts: {
+        through: string;
+        sourceColumn: string;
+        targetColumn: string;
+    }) => {
+        readonly kind: "manyToMany";
+        readonly target: T;
+        readonly through: string;
+        readonly sourceColumn: string;
+        readonly targetColumn: string;
+    };
 };
 export type RelationBuilders = typeof relationBuilders;
 /** The default partition name for entities that don't declare one. */
@@ -134,10 +195,15 @@ export interface EntityDef<F extends EntityFields = EntityFields, R extends Rela
     readonly partition: string;
     /** Declarative write-triggers (see TriggerDef). Always an array (possibly empty). */
     readonly triggers: readonly TriggerDef[];
+    /** Composite (multi-column) UNIQUE constraints, each a tuple of column names, enforced
+     * via a managed unique index. Single-column uniqueness stays on the field (`unique()`).
+     * Always an array (possibly empty). */
+    readonly uniques: readonly (readonly string[])[];
 }
 export declare function Entity<F extends EntityFields, R extends RelationDefs = Record<string, never>>(build: (t: FieldBuilders) => F, relations?: (r: RelationBuilders) => R, opts?: {
     partition?: string;
     triggers?: readonly TriggerDef[];
+    unique?: readonly (readonly string[])[];
 }): EntityDef<F, R>;
 /** The triggers declared on an entity (empty if none / unknown entity). */
 export declare function triggersOf(schema: SchemaDef, entity: string): readonly TriggerDef[];

package/dist/sdk/schema.js

@@ -25,8 +25,11 @@ const builders = {
     uuid: () => ({ type: "uuid" }),
 };
 const relationBuilders = {
-    belongsTo: (target, column) => ({ kind: "belongsTo", target, column }),
+    belongsTo: (target, column, opts) => ({ kind: "belongsTo", target, column, onDelete: opts?.onDelete }),
     hasMany: (target, column) => ({ kind: "hasMany", target, column }),
+    oneHasOne: (target, column, opts) => ({ kind: "oneHasOne", target, column, onDelete: opts?.onDelete }),
+    oneHasOneInverse: (target, column) => ({ kind: "oneHasOneInverse", target, column }),
+    manyToMany: (target, opts) => ({ kind: "manyToMany", target, through: opts.through, sourceColumn: opts.sourceColumn, targetColumn: opts.targetColumn }),
 };
 /** The default partition name for entities that don't declare one. */
 export const DEFAULT_PARTITION = "default";
@@ -53,6 +56,7 @@ export function Entity(build, relations, opts) {
         relations: (relations ? relations(relationBuilders) : {}),
         partition: opts?.partition ?? DEFAULT_PARTITION,
         triggers: opts?.triggers ?? [],
+        uniques: opts?.unique ?? [],
     };
 }
 /** The triggers declared on an entity (empty if none / unknown entity). */
@@ -185,6 +189,21 @@ export function validateSchema(schema) {
                     `'${pE}' but target '${rel.target}' is in '${pT}'. Relations cannot cross partitions — ` +
                     `put both entities in the same partition or drop the relation.`);
             }
+            if (rel.kind === "manyToMany") {
+                const through = schema[rel.through];
+                if (!through) {
+                    throw new Error(`relation '${entity}.${relName}' names an unknown junction entity '${rel.through}'.`);
+                }
+                for (const [label, col] of [["sourceColumn", rel.sourceColumn], ["targetColumn", rel.targetColumn]]) {
+                    if (!(col in through.fields)) {
+                        throw new Error(`relation '${entity}.${relName}' ${label} '${col}' is not a column of junction '${rel.through}'.`);
+                    }
+                }
+                if (partitionOf(schema, rel.through) !== pE) {
+                    throw new Error(`relation '${entity}.${relName}' junction '${rel.through}' is in a different partition than '${entity}' — ` +
+                        `the source, junction, and target must share a partition (traversal is single-DO).`);
+                }
+            }
         }
         for (const t of def.triggers) {
             if (!t.task)
@@ -199,5 +218,15 @@ export function validateSchema(schema) {
                 }
             }
         }
+        for (const cols of def.uniques) {
+            if (cols.length < 2) {
+                throw new Error(`composite unique on '${entity}' needs at least two columns (use unique() for one).`);
+            }
+            for (const c of cols) {
+                if (!(c in def.fields)) {
+                    throw new Error(`composite unique on '${entity}' references unknown column '${c}'.`);
+                }
+            }
+        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.35",
+  "version": "0.0.36",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/index.ts

@@ -22,6 +22,10 @@ export type {
   RelationDefs,
   BelongsToDef,
   HasManyDef,
+  ManyToManyDef,
+  OneHasOneDef,
+  OneHasOneInverseDef,
+  OnDelete,
 } from "./sdk/schema";
 
 // --- app + handlers ---

package/src/runtime/acl.ts

@@ -22,7 +22,7 @@ import {
   isInputMarker,
   isResolver,
 } from "../sdk/acl";
-import { and, compileWhere, evalExpr, FALSE, or, TRUE, type SqlExpr } from "./read-engine";
+import { and, compileWhere, evalExpr, FALSE, not, or, TRUE, type SqlExpr } from "./read-engine";
 import { BadRequest, PramenError } from "./errors";
 import type { FieldDef, RelationDef, SchemaDef } from "../sdk/schema";
 
@@ -260,6 +260,8 @@ function assertReadableRelationWhere(where: Record<string, unknown>, target: str
   for (const [k, v] of Object.entries(where)) {
     if (k === "AND" || k === "OR") {
       for (const g of v as Record<string, unknown>[]) assertReadableRelationWhere(g, target, fields, ctx);
+    } else if (k === "NOT") {
+      assertReadableRelationWhere(v as Record<string, unknown>, target, fields, ctx);
     } else if (targetRels[k]) {
       continue;
     } else if (!fields.includes(k)) {
@@ -300,7 +302,15 @@ function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: stri
 
   // 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: SqlExpr = { 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 };
 }
@@ -336,6 +346,8 @@ export function compileScopedWhere(
     if (k === "AND" || k === "OR") {
       const groups = (v as Record<string, unknown>[]).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 as Record<string, unknown>, 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/src/runtime/db.ts

@@ -412,6 +412,9 @@ export class Db<S extends SchemaDef = SchemaDef> {
       case "or":
         for (const p of expr.parts) this.addTouchedTables(p);
         break;
+      case "not":
+        this.addTouchedTables(expr.expr);
+        break;
     }
   }
 
@@ -427,6 +430,8 @@ export class Db<S extends SchemaDef = SchemaDef> {
     for (const [k, v] of Object.entries(where as Record<string, unknown>)) {
       if (k === "AND" || k === "OR") {
         for (const g of v as unknown[]) 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
       } else if (!scope.fields.includes(k)) {
@@ -636,12 +641,44 @@ export class Db<S extends SchemaDef = SchemaDef> {
       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<unknown, Row>();
       for (const { key, row } of await fetchBy(this.pkOf(rel.target), keys)) byId.set(key, row);
       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<unknown, Row>();
+      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<unknown, Row>();
+      for (const { key, row } of await fetchBy(this.pkOf(rel.target), targetIds)) byTarget.set(key, row);
+      const grouped = new Map<unknown, Row[]>();
+      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/src/runtime/ddl.ts

@@ -2,7 +2,7 @@
 // for a new column. Runs in TS inside the isolate; see runtime/migrate.ts for how
 // these are applied.
 
-import type { DefaultValue, EntityFields, FieldDef } from "../sdk/schema";
+import type { DefaultValue, EntityFields, FieldDef, RelationDefs } from "../sdk/schema";
 import { quoteIdent } from "./driver";
 
 // SQLite has no boolean type; store as INTEGER 0/1. json + fileRef + uuid are
@@ -57,9 +57,47 @@ function columnSql(name: string, f: FieldDef): string {
   return s;
 }
 
-export function createTableSql(table: string, def: { fields: EntityFields }): string {
+/** 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: { relations?: RelationDefs },
+  pkOf: (entity: string) => string,
+  skip?: ReadonlySet<string>,
+): string[] {
+  const out: string[] = [];
+  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: { relations?: RelationDefs }): Map<string, { target: string; onDelete: string }> {
+  const out = new Map<string, { target: string; onDelete: string }>();
+  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: string,
+  def: { fields: EntityFields; relations?: RelationDefs },
+  pkOf?: (entity: string) => string,
+  skipFks?: ReadonlySet<string>,
+): string {
   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.
@@ -77,12 +115,31 @@ export function indexName(table: string, col: string): string {
   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: string, cols: readonly string[]): string {
+  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: readonly string[]): string {
+  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: string, def: { fields: EntityFields }, skipCols?: ReadonlySet<string>): string[] {
+ * 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: string,
+  def: { fields: EntityFields; uniques?: readonly (readonly string[])[] },
+  skipCols?: ReadonlySet<string>,
+  skipUniques?: ReadonlySet<string>,
+): string[] {
   const out: string[] = [];
   for (const [col, f] of Object.entries(def.fields)) {
     if (!f.unique && !f.index) continue;
@@ -90,5 +147,10 @@ export function indexStatements(table: string, def: { fields: EntityFields }, sk
     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/src/runtime/driver.ts

@@ -69,6 +69,12 @@ 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
@@ -135,4 +141,15 @@ export class D1Driver implements Driver {
   transaction<T>(fn: () => Promise<T>): Promise<T> {
     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: ReadonlyArray<{ sql: string; params: unknown[] }>): Promise<void> {
+    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);
+  }
 }