@pramen/server 0.0.35 → 0.0.36

package/src/runtime/migrate.ts

@@ -38,7 +38,7 @@
 // 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, type Driver } from "./driver";
 import { entitiesInPartition, partitionOf, validateSchema } from "../sdk/schema";
@@ -88,7 +88,16 @@ function isInternalTable(name: string): boolean {
 
 export function schemaHash(schema: SchemaDef): string {
   const canon: Record<string, unknown> = {};
-  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: Record<string, unknown> = {};
+    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);
 }
 
@@ -161,6 +170,30 @@ async function columnHasDuplicates(driver: Driver, table: string, col: string):
   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: Driver, table: string): Promise<Map<string, string>> {
+  const idx = (await driver.exec(`PRAGMA index_list(${quoteIdent(table)})`, [])) as { name: string; unique: number }[];
+  const out = new Map<string, string>();
+  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)})`, [])) as { name: string | null }[];
+    const names = cols.map((c) => c.name).filter((n): n is string => 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: Driver, table: string, cols: readonly string[]): Promise<boolean> {
+  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
@@ -197,14 +230,53 @@ async function writeMeta(driver: Driver, key: string, value: string): Promise<vo
   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: Driver,
+  table: string,
+): Promise<{ name: string; cols: string[]; createSql: string; indexSql: string[] }[]> {
+  const tables = (await driver.exec(`SELECT name, sql FROM sqlite_master WHERE type = 'table'`, [])) as { name: string; sql: string | null }[];
+  const out: { name: string; cols: string[]; createSql: string; indexSql: string[] }[] = [];
+  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)})`, [])) as { table: string }[];
+    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])) as { sql: string }[];
+    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: Driver, table: string, def: { fields: EntityFields }, live: Map<string, string>): Promise<void> {
+ * 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: Driver,
+  table: string,
+  def: { fields: EntityFields; relations?: import("../sdk/schema").RelationDefs },
+  live: Map<string, string>,
+  pkOf?: (entity: string) => string,
+  skipFks?: ReadonlySet<string>,
+): Promise<void> {
   const tmp = `__pramen_rebuild_${table}`;
-  await driver.exec(`DROP TABLE IF EXISTS ${quoteIdent(tmp)}`, []);
-  await driver.exec(createTableSql(tmp, def), []);
-
   const destCols: string[] = [];
   const srcExprs: string[] = [];
   for (const [name, field] of Object.entries(def.fields)) {
@@ -222,11 +294,92 @@ async function rebuildTable(driver: Driver, table: string, def: { fields: Entity
     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: { sql: string; params: unknown[] }[] = [];
+  // 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: string, quotedCols: string[]): string => `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: { fields: EntityFields } | undefined): string {
+  if (def) for (const [n, f] of Object.entries(def.fields)) if ((f as FieldDef).primaryKey) return n;
+  return "id";
+}
+
+/** Live FK columns of a table → {target, onDelete} via PRAGMA foreign_key_list. */
+async function liveForeignKeys(driver: Driver, table: string): Promise<Map<string, { target: string; onDelete: string }>> {
+  const rows = (await driver.exec(`PRAGMA foreign_key_list(${quoteIdent(table)})`, [])) as { table: string; from: string; on_delete: string }[];
+  const out = new Map<string, { target: string; onDelete: string }>();
+  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: Driver, table: string, col: string, target: string, targetPk: string): Promise<boolean> {
+  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: Driver, schema: SchemaDef, opts: MigrateOptions = {}): Promise<MigrationReport> {
@@ -234,7 +387,14 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
   // 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: string): string => 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
@@ -268,11 +428,14 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
   // Per-table: columns whose new `unique()` can't be indexed (duplicate values) — the
   // index pass must skip them so it doesn't throw. They're already reported in `skipped`.
   const uniqueIndexSkip = new Map<string, Set<string>>();
+  // 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<string, Set<string>>();
 
   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;
     }
@@ -367,6 +530,27 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
       }
     }
 
+    // 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<string>();
+    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
@@ -378,10 +562,10 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
         ...destructiveReasons,
       ];
       skipped.push(`rebuild ${table} (${reasons.join(", ")})`);
-    } else if (destructive || needsAdditiveRebuild || modifierRebuildSafe) {
-      // A safe rebuild (expr-default column, default/notNull modifier change) needs no
-      // permission — it loses no data.
-      await rebuildTable(driver, table, def, live);
+    } 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);
     }
 
@@ -392,6 +576,24 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
     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
@@ -419,7 +621,7 @@ export async function migrate(driver: Driver, schema: SchemaDef, opts: MigrateOp
   // 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))) await driver.exec(stmt, []);
+    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).

package/src/runtime/read-engine.ts

@@ -16,14 +16,22 @@ function bind(v: unknown): unknown {
 
 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" }
   | { t: "false" }
   | { t: "cmp"; op: CmpOp; col: string; value: unknown }
   | { t: "in"; col: string; values: unknown[]; negate: boolean }
   | { t: "null"; col: string; negate: boolean }
+  // Structured substring match — the needle is escaped and wrapped, so `%`/`_` in the
+  // input match literally (unlike raw `like`, where the caller controls wildcards).
+  | { t: "strmatch"; col: string; needle: string; mode: StrMode }
   | { t: "and"; parts: SqlExpr[] }
   | { t: "or"; parts: SqlExpr[] }
+  | { t: "not"; expr: SqlExpr }
   // Relation traversal: `outerCol IN (SELECT selectCol FROM from WHERE where)`.
   // Built by the ACL layer (which knows schema + the target's read scope); the
   // inner predicate compiles inline so placeholders share the outer param sequence.
@@ -34,8 +42,10 @@ export const FALSE: SqlExpr = { t: "false" };
 export const cmp = (op: CmpOp, col: string, value: unknown): SqlExpr => ({ t: "cmp", op, col, value });
 export const isNull = (col: string, negate = false): SqlExpr => ({ t: "null", col, negate });
 export const inList = (col: string, values: unknown[], negate = false): SqlExpr => ({ t: "in", col, values, negate });
+export const strMatch = (col: string, needle: string, mode: StrMode): SqlExpr => ({ t: "strmatch", col, needle, mode });
 export const and = (...parts: SqlExpr[]): SqlExpr => ({ t: "and", parts });
 export const or = (...parts: SqlExpr[]): SqlExpr => ({ t: "or", parts });
+export const not = (expr: SqlExpr): SqlExpr => ({ t: "not", expr });
 
 /** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
 export const eq = (col: string, value: unknown): SqlExpr => (value === null ? isNull(col) : cmp("=", col, value));
@@ -49,6 +59,8 @@ export function compileWhere(input: Record<string, unknown>): SqlExpr {
       parts.push(and(...(v as Record<string, unknown>[]).map(compileWhere)));
     } else if (k === "OR") {
       parts.push(or(...(v as Record<string, unknown>[]).map(compileWhere)));
+    } else if (k === "NOT") {
+      parts.push(not(compileWhere(v as Record<string, unknown>)));
     } else {
       parts.push(columnPredicate(k, v));
     }
@@ -68,6 +80,9 @@ function columnPredicate(col: string, v: unknown): SqlExpr {
         case "lt": ops.push(cmp("<", col, val)); break;
         case "lte": ops.push(cmp("<=", col, val)); break;
         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 as unknown[])); break;
         case "notIn": ops.push(inList(col, val as unknown[], true)); break;
         case "isNull": ops.push(isNull(col, !val)); break; // isNull:true => IS NULL
@@ -101,6 +116,15 @@ export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] =
       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
       const ph = expr.values.map((v) => (params.push(dialect.encode(v)), dialect.placeholder(params.length))).join(", ");
@@ -113,6 +137,8 @@ export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] =
       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 +195,13 @@ export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
       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) return false; // can't demonstrate membership
@@ -180,6 +213,8 @@ export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
       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/src/sdk/infer.ts

@@ -41,7 +41,9 @@ export type InferRow<F extends EntityFields> = { [K in keyof F]: Cell<F[K]> };
  * which can drop columns per row — `InferRow` over-claims presence by design. */
 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;
@@ -52,16 +54,20 @@ 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>;
 };
 
 // --- partition boundary: runtime-only by decision (Issue 08) ---
@@ -141,11 +147,11 @@ 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"; target: infer Tg }
+type RelValue<S extends SchemaDef, Rel> = Rel extends { kind: "belongsTo" | "oneHasOne" | "oneHasOneInverse"; target: infer Tg }
   ? Tg extends keyof S
     ? InferRow<FieldsOf<S[Tg]>> | null
     : never
-  : Rel extends { kind: "hasMany"; target: infer Tg }
+  : Rel extends { kind: "hasMany" | "manyToMany"; target: infer Tg }
     ? Tg extends keyof S
       ? InferRow<FieldsOf<S[Tg]>>[]
       : never

package/src/sdk/schema.ts

@@ -71,11 +71,19 @@ export type EntityFields = Record<string, FieldDef>;
 
 // --- relations ---
 
+/** 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";
@@ -83,12 +91,45 @@ 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>;
 
 const relationBuilders = {
-  belongsTo: <T extends string>(target: T, column: string) => ({ kind: "belongsTo", target, column }) as const,
+  belongsTo: <T extends string>(target: T, column: string, opts?: { onDelete?: OnDelete }) =>
+    ({ kind: "belongsTo", target, column, onDelete: opts?.onDelete }) as const,
   hasMany: <T extends string>(target: T, column: string) => ({ kind: "hasMany", target, column }) as const,
+  oneHasOne: <T extends string>(target: T, column: string, opts?: { onDelete?: OnDelete }) =>
+    ({ kind: "oneHasOne", target, column, onDelete: opts?.onDelete }) as const,
+  oneHasOneInverse: <T extends string>(target: T, column: string) => ({ kind: "oneHasOneInverse", target, column }) as const,
+  manyToMany: <T extends string>(target: T, opts: { through: string; sourceColumn: string; targetColumn: string }) =>
+    ({ kind: "manyToMany", target, through: opts.through, sourceColumn: opts.sourceColumn, targetColumn: opts.targetColumn }) as const,
 };
 export type RelationBuilders = typeof relationBuilders;
 
@@ -137,18 +178,23 @@ 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 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[] },
+  opts?: { partition?: string; triggers?: readonly TriggerDef[]; unique?: readonly (readonly string[])[] },
 ): EntityDef<F, R> {
   return {
     fields: build(builders),
     relations: (relations ? relations(relationBuilders) : {}) as R,
     partition: opts?.partition ?? DEFAULT_PARTITION,
     triggers: opts?.triggers ?? [],
+    uniques: opts?.unique ?? [],
   };
 }
 
@@ -309,6 +355,23 @@ export function validateSchema(schema: SchemaDef): void {
             `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]] as const) {
+          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) throw new Error(`trigger on '${entity}' is missing a 'task'.`);
@@ -322,5 +385,15 @@ export function validateSchema(schema: SchemaDef): void {
         }
       }
     }
+    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}'.`);
+        }
+      }
+    }
   }
 }