@zerotal/orm 1.9.0 → 1.11.0

package/CHANGELOG.md

@@ -8,6 +8,94 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.11.0] — 2026-08-31
+
+### Changed
+
+- **BREAKING: SQLite enforces foreign keys.** `database.sqlite.foreignKeys` now
+  defaults to `true`, so `PRAGMA foreign_keys = ON` is set on every connection.
+  Until now SQLite ignored them, which made `constrained()` and `cascadeOnDelete()`
+  in a migration a statement of intent the database would not perform — deleting a
+  parent left its children, silently, and an app's data-erasure path missed three
+  tables because of it.
+
+  **What can break:** a child row whose parent is missing was legal without
+  enforcement and is a violation with it, so a write touching one now fails. Run
+  `zt db:check-foreign-keys` before deploying — it lists every offending row by table
+  and rowid and exits non-zero, so a release script can gate on it. `zt doctor`
+  reports the same. To take the release without dealing with it yet, set
+  `sqlite: { foreignKeys: false }`, and remove the override afterwards; with it in
+  place `cascadeOnDelete()` does nothing. See
+  [the upgrade guide](/docs/upgrade#1-10-to-1-11).
+
+- **BREAKING: a renumbered migration is refused rather than re-run.** A migration is
+  recorded under its filename, so renaming one makes an applied migration look
+  pending — the runner tried it again and failed on `table already exists`, which is a
+  failed boot with an error naming a table rather than the rename. An app renumbered
+  `001_` to `0001_` to match this framework's own scaffold convention and would have
+  made all nine of its production migrations look unrun.
+
+  `migrate` now recognises a pending migration whose name matches a recorded one once
+  the leading digits are stripped, and stops with both spellings and the fix. It
+  refuses rather than warns because the alternative is running it, and running it is
+  the outage.
+
+### Added
+
+- **`Migration.id`** — a declared identity that decouples a migration from its
+  filename. Set it to what the database already recorded and the file is free to be
+  renamed. Deliberately not a content hash: a migration's content is edited far more
+  often than its name, and a hash would make every edit look like a new migration.
+
+- **`zt db:check-foreign-keys`** — lists the rows enforcement would reject, by table
+  and rowid, and exits non-zero when there are any.
+
+### Changed
+
+- **`@column({ type: "integer" })` compiles.** `ColumnShorthand` has twelve names and
+  `ColumnOptions["type"]` had six, so `@column("integer")` worked and
+  `@column({ type: "integer", default: 0 })` did not — the vocabulary shrank by half
+  exactly when a caller needed `default`, `nullable` or `unique`, which is most real
+  columns. The error listed the six without mentioning that `integer` resolves to
+  `{ type: "number", cast: "integer" }`, so the way out was reading `SHORTHAND_MAP` in
+  the source.
+
+  The object form now takes either vocabulary and resolves a shorthand the way the
+  string form does. An explicit `cast` alongside one still wins: somebody who wrote
+  both meant the one they spelled out.
+
+### Fixed
+
+- **Migration names no longer carry the platform that recorded them.** `Bun.Glob`
+  yields native separators, and the prefix strip was a forward-slash-only pattern —
+  so on Windows the whole joined path went into the `migrations` table. An app found
+  `database\migrations\010_add_tenant_limits` in ten dev rows and
+  `010_add_tenant_limits` in production, from the same files.
+
+  A database moved between the two re-runs every migration: every recorded name
+  misses, all of them look pending, and the first fails on `table already exists` —
+  a failed boot, not a graceful skip. The name is now the bare filename on both.
+
+  Note the half this does _not_ fix: the recorded identity is still the filename, so
+  renaming a migration makes it look unrun. The same app nearly took an outage
+  renumbering `001_` to `0001_` to match this framework's own scaffold convention.
+
+### Added
+
+- **`database.sqlite.foreignKeys`**, and a `zt doctor` check for the schemas that
+  need it. **SQLite ignores foreign keys unless the connection asks it not to**, so
+  `constrained()` and `cascadeOnDelete()` in a migration described behaviour the
+  database would not perform: deleting a parent left its children, silently, and
+  every child had to be removed by hand in the right order by code that remembered
+  to. An app's data-erasure path swept fifteen tables and missed three — including
+  both holding uploaded files — so an erasure left the paperwork on disk.
+
+  Off by default, because turning it on can fail writes an existing database already
+  permits: a row whose parent is missing is legal without enforcement and a violation
+  with it. Run `PRAGMA foreign_key_check` before enabling on an existing database. The
+  doctor check warns only when the schema actually declares a foreign key, so an app
+  with none hears nothing.
+
 ## [1.9.0] — 2026-08-29
 
 ### Changed

package/api-surface.md

@@ -287,6 +287,7 @@ class JsonCast = {
 
 class Migration = {
   new (): Migration
+  static id?: string
   down: () => Promise<void>
   up: () => Promise<void>
 }
@@ -806,14 +807,14 @@ interface CastField = {
 }
 
 interface ColumnOptions = {
-  cast?: 'boolean' | 'date' | 'datetime' | 'array' | 'integer' | 'json' | 'float' | 'enum' | 'immutable_datetime' | 'encrypted' | 'encrypted:json' | `decimal:${number}` | {    get?: (dbValue: unknown) => unknown;    set?: (jsValue: unknown) => unknown;} | CastContract<unknown>
+  cast?: 'boolean' | 'date' | 'datetime' | 'array' | 'integer' | 'json' | 'float' | 'enum' | 'immutable_datetime' | 'encrypted' | 'encrypted:json' | `decimal:${number}` | {    get?: (dbValue: unknown) => unknown;    set?: (jsValue: unknown) => unknown;} | CastContract<unknown> | undefined
   default?: unknown
-  enumValues?: Record<string, string | number>
-  index?: boolean
-  nullable?: boolean
-  primary?: boolean
-  type?: 'string' | 'number' | 'boolean' | 'text' | 'datetime' | 'json'
-  unique?: boolean
+  enumValues?: Record<string, string | number> | undefined
+  index?: boolean | undefined
+  nullable?: boolean | undefined
+  primary?: boolean | undefined
+  type?: 'string' | 'number' | 'boolean' | 'text' | 'datetime' | 'json' | undefined
+  unique?: boolean | undefined
 }
 
 interface Compose = {
@@ -836,10 +837,10 @@ interface CursorPaginateResult = {
 
 interface DatabaseConfigShape = {
   driver: 'sqlite' | 'postgres' | 'mysql'
-  pool?: {    max?: number;    idleTimeout?: number;}
-  replicas?: string[]
-  sqlite: {    path: string;}
-  synchronize?: boolean | {    enabled: boolean;    disruptive?: boolean;}
+  pool?: {    max?: number;    idleTimeout?: number;} | undefined
+  replicas?: string[] | undefined
+  sqlite: {    path: string;    foreignKeys?: boolean | undefined;}
+  synchronize?: boolean | {    enabled: boolean;    disruptive?: boolean;} | undefined
   url: string
 }
 
@@ -850,9 +851,9 @@ interface HasMany = {
 
 interface HasManyThroughOptions = {
   firstKey: string
-  localKey?: string
+  localKey?: string | undefined
   secondKey: string
-  throughLocalKey?: string
+  throughLocalKey?: string | undefined
 }
 
 interface HasOne = {
@@ -861,10 +862,10 @@ interface HasOne = {
 }
 
 interface KeysetOptions = {
-  column?: string
-  cursor?: string | null
-  direction?: 'asc' | 'desc'
-  limit?: number
+  column?: string | undefined
+  cursor?: string | null | undefined
+  direction?: 'asc' | 'desc' | undefined
+  limit?: number | undefined
 }
 
 interface KeysetPaginateResult = {
@@ -890,13 +891,13 @@ interface ManyToMany = {
 }
 
 interface ManyToManyOptions = {
-  localKey?: string
+  localKey?: string | undefined
   pivotForeignKey: string
   pivotRelatedKey: string
   pivotTable: string
-  relatedKey?: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  relatedKey?: string | undefined
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MigrationEntry = {
@@ -931,9 +932,9 @@ interface ModelObserver = {
 interface MorphedByManyOptions = {
   morphName: string
   parentPivotKey: string
-  pivotTable?: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  pivotTable?: string | undefined
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MorphMany = {
@@ -942,7 +943,7 @@ interface MorphMany = {
 }
 
 interface MorphManyOptions = {
-  localKey?: string
+  localKey?: string | undefined
   morphName: string
 }
 
@@ -952,7 +953,7 @@ interface MorphOne = {
 }
 
 interface MorphOneOptions = {
-  localKey?: string
+  localKey?: string | undefined
   morphName: string
 }
 
@@ -963,21 +964,21 @@ interface MorphTo = {
 
 interface MorphToManyOptions = {
   morphName: string
-  pivotTable?: string
+  pivotTable?: string | undefined
   relatedPivotKey: string
-  withPivot?: string[]
-  withTimestamps?: boolean
+  withPivot?: string[] | undefined
+  withTimestamps?: boolean | undefined
 }
 
 interface MorphToOptions = {
-  morphForeignKey?: string
+  morphForeignKey?: string | undefined
   morphMap: Record<string, () => unknown>
-  morphTypeColumn?: string
+  morphTypeColumn?: string | undefined
 }
 
 interface NPlusOneOptions = {
-  mode?: 'warn' | 'throw'
-  threshold?: number
+  mode?: 'warn' | 'throw' | undefined
+  threshold?: number | undefined
 }
 
 interface PaginateMeta = {
@@ -1067,8 +1068,8 @@ interface TableDecoratorBuilder = {
 }
 
 interface TableOptions = {
-  primaryKey?: string
-  timestamps?: boolean
+  primaryKey?: string | undefined
+  timestamps?: boolean | undefined
 }
 
 interface TransitionContext = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -31,8 +31,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.9.0",
-    "@zerotal/validator": "1.9.0"
+    "@zerotal/core": "1.11.0",
+    "@zerotal/validator": "1.11.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/commands/CheckForeignKeysCommand.ts

@@ -0,0 +1,80 @@
+import { Command } from "@zerotal/core";
+import { _getConnection } from "../db/DB.ts";
+
+/** One row `PRAGMA foreign_key_check` objects to. */
+interface Violation {
+  table: string;
+  rowid: number | null;
+  parent: string;
+  fkid: number;
+}
+
+/**
+ * `bun zt db:check-foreign-keys` — list the rows enforcement would reject.
+ *
+ * SQLite ignores foreign keys unless the connection asks it not to, and Zerotal now
+ * asks by default. That is the right default — a `cascadeOnDelete()` the database
+ * will not perform is worse than no cascade at all — but it changes what an
+ * *existing* database accepts: a child row whose parent is missing is perfectly legal
+ * without enforcement and a constraint violation with it. So an app that has been
+ * running without it may already hold rows that a write will now fail on.
+ *
+ * This is how you find out before your users do. It reports every offending row by
+ * table and rowid, and exits non-zero when there are any, so a deploy script can gate
+ * on it.
+ *
+ * @example
+ * ```bash
+ * # before taking the upgrade, or any time after
+ * bun zt db:check-foreign-keys
+ * ```
+ *
+ * @category Database
+ */
+export class CheckForeignKeysCommand extends Command {
+  static override commandName = "db:check-foreign-keys";
+  static override description = "List rows that violate a foreign key constraint";
+  static override needsApp = true;
+
+  async run(): Promise<void> {
+    const sql = _getConnection();
+
+    let violations: Violation[];
+    try {
+      violations = await sql<Violation>`PRAGMA foreign_key_check`;
+    } catch (error) {
+      // Postgres and MySQL always enforce, so they have no such pragma and nothing
+      // to report. Saying that is more useful than an error about syntax.
+      this.info(
+        `No foreign-key check to run on this driver — only SQLite can have enforcement off. ` +
+          `(${(error as Error).message})`,
+      );
+      return;
+    }
+
+    if (violations.length === 0) {
+      this.info("No foreign-key violations. Enforcement is safe to leave on.");
+      return;
+    }
+
+    this.error(`${violations.length} row(s) violate a foreign key:`);
+    this.newLine();
+    this.table(
+      violations.map((v) => [
+        `${v.table} rowid ${v.rowid ?? "?"}`,
+        `references ${v.parent}, which has no matching row`,
+      ]) as [string, string][],
+    );
+    this.newLine();
+    this.line(
+      "Each of these is a row whose parent is missing. With enforcement on, a write\n" +
+        "touching one fails. Delete them, or repoint them at a parent that exists.\n\n" +
+        "To keep deploying while you sort it out, set sqlite.foreignKeys: false in\n" +
+        "config/database.ts — and take the override back off afterwards, because with\n" +
+        "it in place cascadeOnDelete() does nothing.",
+    );
+
+    // Non-zero so a release script can gate on this the way it gates on tests.
+    process.exitCode = 1;
+  }
+}

package/src/commands/_backup.ts

@@ -45,15 +45,15 @@ export interface BackupOptions {
    * it". An empty `bookings` table in a snapshot of a live system is not a small
    * discrepancy, it is the whole failure — and it is invisible in a byte count.
    */
-  requireRows?: string[];
+  requireRows?: string[] | undefined;
   /**
    * Perform the restore, not just a read of the snapshot: copy it to a scratch
    * path, open the copy, and check it there. Exercises the operation an incident
    * actually needs, rather than the one that is convenient to test.
    */
-  rehearse?: boolean;
+  rehearse?: boolean | undefined;
   /** Clock, so the snapshot name is deterministic under test. */
-  now?: Date;
+  now?: Date | undefined;
 }
 
 /** What a completed backup wrote and proved. */

package/src/commands/_loadMigrations.ts

@@ -26,9 +26,40 @@ export async function loadMigrations(): Promise<MigrationRecord[]> {
     const mod = await import(`${process.cwd()}/${file}`);
     const Ctor = mod.default as (new () => MigrationRecord["instance"]) | undefined;
     if (!Ctor) continue;
-    const name = file.replace(/^database\/migrations\//, "").replace(/\.ts$/, "");
-    records.push({ name, instance: new Ctor() });
+    // A declared `static id` wins over the filename — see `Migration.id`.
+    const declared = (Ctor as { id?: string }).id;
+    records.push({ name: declared ?? _migrationName(file), instance: new Ctor() });
   }
 
   return records;
 }
+
+/**
+ * The identity a migration is recorded under: its bare filename, no directory, no
+ * extension, no platform in it.
+ *
+ * `Bun.Glob` yields native separators, so on Windows this receives
+ * `database\migrations\010_x.ts`. The prefix used to be stripped with a
+ * forward-slash-only pattern, which matched nothing there — and the value written
+ * into the `migrations` table was the whole joined path, backslashes and all.
+ *
+ * Two ways that hurts, and the second is the dangerous one:
+ *
+ * - **A database moved between platforms re-runs every migration.** Every recorded
+ *   name misses, all of them look pending, and the first one fails on `table
+ *   already exists`. That is a failed boot rather than a graceful skip.
+ * - **The recorded name is compared against the file's**, so anything that changes
+ *   the string makes a migration look unrun. An app renumbered `001_` to `0001_` to
+ *   match this framework's own scaffold convention and nearly took an outage: nine
+ *   applied migrations would have looked pending. Normalising the separator does not
+ *   fix that half — a rename is still a new identity — but it stops the *platform*
+ *   from being part of the string, which is the half nobody can see coming.
+ *
+ * @param file - Path as the glob yielded it, relative to the project root.
+ * @returns The bare migration name.
+ * @internal
+ */
+export function _migrationName(file: string): string {
+  const normalised = file.split("\\").join("/");
+  return (normalised.split("/").at(-1) ?? normalised).replace(/\.[cm]?[jt]s$/, "");
+}

package/src/config.ts

@@ -28,21 +28,51 @@ export interface DatabaseConfigShape {
    *   env('REPLICA_2_URL'),
    * ].filter((url) => url !== undefined)
    */
-  replicas?: string[];
+  replicas?: string[] | undefined;
   /**
    * Connection pool options (PostgreSQL and MySQL only).
    * Bun.sql manages the pool automatically - these tune its behaviour.
    */
-  pool?: {
-    /** Maximum number of connections in the pool. Default: 10 */
-    max?: number;
-    /** Seconds an idle connection is kept before being closed. Default: 30 */
-    idleTimeout?: number;
-  };
+  pool?:
+    | {
+        /** Maximum number of connections in the pool. Default: 10 */
+        max?: number;
+        /** Seconds an idle connection is kept before being closed. Default: 30 */
+        idleTimeout?: number;
+      }
+    | undefined;
   /** SQLite-specific options */
   sqlite: {
     /** Path to the SQLite file. Use ':memory:' for in-memory database. */
     path: string;
+    /**
+     * Enforce foreign keys on every SQLite connection (`PRAGMA foreign_keys = ON`).
+     *
+     * **SQLite ignores foreign keys unless you ask it not to**, and it is the only
+     * supported dialect that does. Without this, `cascadeOnDelete()` and
+     * `constrained()` in a migration are a statement of intent that the database
+     * will not perform: deleting a parent leaves its children behind, and every
+     * child has to be deleted by hand, in the right order, by application code that
+     * remembers to.
+     *
+     * That is not a theoretical cost. An app's data-erasure path swept fifteen
+     * tables and missed three — including both tables holding uploaded files — so an
+     * account erasure left the paperwork on disk and its rows in the database. They
+     * found it by having a second person write the runbook and compare the prose
+     * against the code.
+     *
+     * **On by default**, because an API describing behaviour the database will not
+     * perform is the worst of the available states — worse than not offering it.
+     *
+     * Set it to `false` for an existing database that may already hold rows a
+     * constraint would reject: a child whose parent is missing is legal without
+     * enforcement and a violation with it, so turning it on can fail a write the app
+     * has always made. `zt db:check-foreign-keys` lists exactly those rows, and
+     * `zt doctor` reports them too. Fix them, then remove the override.
+     *
+     * Default: `true`. Postgres and MySQL always enforce, so this is ignored there.
+     */
+    foreignKeys?: boolean | undefined;
   };
   /**
    * Auto-sync the schema to your models at boot (TypeORM-style). Opt-in, and
@@ -58,13 +88,13 @@ export interface DatabaseConfigShape {
    * synchronize: { enabled: true, disruptive: false }     // explicit, additive
    * synchronize: { enabled: true, disruptive: true }      // also drops removed columns
    */
-  synchronize?: boolean | { enabled: boolean; disruptive?: boolean };
+  synchronize?: boolean | { enabled: boolean; disruptive?: boolean } | undefined;
 }
 
 const defaults: DatabaseConfigShape = {
   driver: "sqlite",
   url: "./database/db.sqlite",
-  sqlite: { path: "./database/db.sqlite" },
+  sqlite: { path: "./database/db.sqlite", foreignKeys: true },
 };
 
 /**

package/src/db/NPlusOneDetector.ts

@@ -104,12 +104,12 @@ let _forced = false; // true when explicitly configured via preventNPlusOne()
 
 export interface NPlusOneOptions {
   /** How many identical query shapes in one request triggers a violation. Default: 5. */
-  threshold?: number;
+  threshold?: number | undefined;
   /**
    * 'warn'  → console.warn (default — non-breaking, still visible)
    * 'throw' → throws NPlusOneError (good for CI / strict mode)
    */
-  mode?: "warn" | "throw";
+  mode?: "warn" | "throw" | undefined;
 }
 
 /**

package/src/db/types.ts

@@ -159,7 +159,7 @@ function _pageUrl(baseUrl: string, page: number, extra: Record<string, string> =
 /** Options accepted by the pagination helper factories. */
 export interface PaginationHelperOptions {
   /** Base path used by no-argument URL helpers and `meta.path`. Default: `''`. */
-  path?: string;
+  path?: string | undefined;
 }
 
 /** Attach URL helper methods + metadata to a plain paginate result object. */
@@ -276,13 +276,13 @@ export interface KeysetOptions {
    * Opaque cursor string from the previous page's `nextCursor`.
    * `null` or omitted = first page.
    */
-  cursor?: string | null;
+  cursor?: string | null | undefined;
   /** Column used for keyset ordering. Must be a safe SQL identifier. Default: `'id'`. */
-  column?: string;
+  column?: string | undefined;
   /** Sort direction. Default: `'asc'`. */
-  direction?: "asc" | "desc";
+  direction?: "asc" | "desc" | undefined;
   /** Items per page. Default: `15`. */
-  limit?: number;
+  limit?: number | undefined;
 }
 
 /** Result of {@link QueryBuilder.keysetPaginate} — opaque-cursor keyset pagination. */

package/src/doctor/foreignKeys.ts

@@ -0,0 +1,130 @@
+/**
+ * The check for a migration that promises a cascade the database will not perform.
+ *
+ * SQLite ignores foreign keys unless the connection asks it not to, and it is the
+ * only supported dialect that does. So a migration reading
+ *
+ * ```ts
+ * table.foreignId("transaction_id").constrained("transactions").cascadeOnDelete();
+ * ```
+ *
+ * describes behaviour that does not happen: deleting a parent leaves its children,
+ * and every child has to be removed by hand, in the right order, by application code
+ * that remembers to. Nothing errors. Nothing logs. The declaration reads like a
+ * guarantee and is a comment.
+ *
+ * An app's data-erasure path swept fifteen tables and missed three, including both
+ * that held uploaded files — so an account erasure left the paperwork on disk and its
+ * rows in the database. That is a compliance failure produced by an API that reads
+ * like a promise, which is why this warns rather than staying quiet: an API
+ * describing behaviour the database will not perform is worse than either turning it
+ * on or not offering it.
+ *
+ * @module
+ */
+import type { Application } from "@zerotal/core";
+import type { DoctorCheck, DoctorCheckResult } from "@zerotal/core";
+import type { SQLInstance } from "../db/sql-types.ts";
+
+/** Whether this connection enforces foreign keys right now. */
+async function _enforcing(sql: SQLInstance): Promise<boolean | null> {
+  try {
+    const rows = (await sql`PRAGMA foreign_keys`) as { foreign_keys?: number }[];
+    const value = rows[0]?.foreign_keys;
+    return value === undefined ? null : Number(value) === 1;
+  } catch {
+    return null;
+  }
+}
+
+/** Tables that declare at least one foreign key, so the promise is actually being made. */
+async function _tablesWithForeignKeys(sql: SQLInstance): Promise<number> {
+  try {
+    const rows = (await sql`
+      SELECT COUNT(*) AS n
+      FROM sqlite_master AS m
+      WHERE m.type = 'table'
+        AND m.sql LIKE '%REFERENCES%'
+    `) as { n?: number }[];
+    return Number(rows[0]?.n ?? 0);
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Report a schema that declares foreign keys on a connection that ignores them.
+ *
+ * Silent when the app declares none — plenty of schemas legitimately have no
+ * constraints, and warning about an unused setting is how a doctor becomes noise.
+ */
+export const foreignKeysCheck: DoctorCheck = {
+  id: "sqlite-foreign-keys",
+  label: "Foreign keys",
+  async run(app: Application): Promise<DoctorCheckResult> {
+    let driver = "sqlite";
+    let sql: SQLInstance | undefined;
+    try {
+      const config = app.container.makeSync("config") as { get<T>(k: string, d: T): T };
+      driver = config.get<string>("database.driver", "sqlite");
+      sql = app.container.makeSync("db") as SQLInstance;
+    } catch {
+      return { status: "ok", message: "no database connection to check" };
+    }
+
+    // Postgres and MySQL always enforce; there is nothing to get wrong.
+    if (driver !== "sqlite") return { status: "ok", message: `${driver} enforces them` };
+    if (!sql) return { status: "ok", message: "no database connection to check" };
+
+    const enforcing = await _enforcing(sql);
+    if (enforcing === null) return { status: "ok", message: "could not read the pragma" };
+
+    // Enforced: the remaining question is whether the data already agrees. A row whose
+    // parent is missing was legal before enforcement and is a violation now, so an
+    // upgraded database can carry rows that the next write touching them will fail on.
+    if (enforcing) {
+      const violations = await _violationCount(sql);
+      if (violations === 0) return { status: "ok", message: "enforced, and the data agrees" };
+      return {
+        status: "fail",
+        message:
+          `Foreign keys are enforced and ${violations} row(s) already violate one — rows whose ` +
+          `parent is missing, which were legal before enforcement and are not now. A write ` +
+          `touching one of them fails.`,
+        fix:
+          "Run `zt db:check-foreign-keys` to see them by table and rowid. Delete them or " +
+          "repoint them at a parent that exists. To keep deploying meanwhile, set " +
+          "sqlite.foreignKeys: false in config/database.ts — and take it back off after, " +
+          "because with it in place cascadeOnDelete() does nothing.",
+      };
+    }
+
+    const declaring = await _tablesWithForeignKeys(sql);
+    if (declaring === 0) {
+      return { status: "ok", message: "not enforced, and nothing declares one" };
+    }
+
+    return {
+      status: "warn",
+      message:
+        `${declaring} table(s) declare a foreign key, and this SQLite connection does not ` +
+        `enforce them — so \`constrained()\` and \`cascadeOnDelete()\` in your migrations ` +
+        `describe behaviour the database will not perform. Deleting a parent leaves its ` +
+        `children, silently.`,
+      fix:
+        "Set database.sqlite.foreignKeys: true in config/database.ts. On an existing " +
+        "database, run `PRAGMA foreign_key_check` first — enforcement turns an already-" +
+        "orphaned row into a write that fails.",
+    };
+  },
+};
+
+/** How many rows violate a foreign key right now. `0` when the pragma is unavailable. */
+async function _violationCount(sql: SQLInstance): Promise<number> {
+  try {
+    const rows = (await sql`PRAGMA foreign_key_check`) as unknown[];
+    return rows.length;
+  } catch {
+    return 0;
+  }
+}

package/src/model/decorators/belongsTo.ts

@@ -5,9 +5,9 @@ export interface BelongsToOptions {
   /** FK column on this (child) model pointing to the related row (e.g. `user_id`). */
   foreignKey: string;
   /** Key on the related model the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Return a default (unsaved) related model instead of null when absent. */
-  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void);
+  withDefault?: boolean | Record<string, unknown> | ((model: unknown) => void) | undefined;
 }
 
 /**

package/src/model/decorators/column.ts

@@ -82,11 +82,14 @@ export interface ColumnOptions {
    *
    * @default "string"
    */
-  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json";
+  // Spelled out rather than written as {@link ColumnStorageType}: this line is the
+  // recorded public surface, and replacing a union with an alias of identical members
+  // reads as a removal in the diff even though nothing changed.
+  type?: "string" | "text" | "number" | "boolean" | "datetime" | "json" | undefined;
   /** Mark this column as the table's primary key. */
-  primary?: boolean;
+  primary?: boolean | undefined;
   /** Allow SQL `NULL` for this column. */
-  nullable?: boolean;
+  nullable?: boolean | undefined;
   /** Default value applied when none is provided. */
   default?: unknown;
   /**
@@ -96,9 +99,9 @@ export interface ColumnOptions {
    * usually a correctness property (a webhook idempotency key, an invoice number),
    * and `migrate:generate` can only emit constraints it can see declared.
    */
-  unique?: boolean;
+  unique?: boolean | undefined;
   /** Add a plain (non-unique) index on this column. */
-  index?: boolean;
+  index?: boolean | undefined;
   /**
    * Shorthand cast types automatically serialize/deserialize the column value.
    * Can also be a custom object with `get`/`set` functions for full control.
@@ -134,14 +137,37 @@ export interface ColumnOptions {
         get?: (dbValue: unknown) => unknown;
         set?: (jsValue: unknown) => unknown;
       }
-    | CastContract<unknown>;
+    | CastContract<unknown>
+    | undefined;
   /** Enum object (e.g. the imported TS enum) used alongside cast: 'enum'. */
-  enumValues?: Record<string, string | number>;
+  enumValues?: Record<string, string | number> | undefined;
 }
 
 /**
  * Map each ColumnShorthand to its resolved ColumnOptions.
  */
+/**
+ * The types a column is actually *stored* as — what schema generation emits.
+ *
+ * Distinct from {@link ColumnShorthand}, which is the larger vocabulary a caller may
+ * write. `integer`, `float`, `date` and the encrypted forms are shorthands that
+ * resolve to one of these plus a cast.
+ */
+export type ColumnStorageType = "string" | "text" | "number" | "boolean" | "datetime" | "json";
+
+/**
+ * What `@column({ … })` accepts, as opposed to what it resolves to.
+ *
+ * The difference is `type`: a caller may write any {@link ColumnShorthand} there and
+ * it is resolved to a storage type plus a cast, exactly as the string form is.
+ * {@link ColumnOptions} — the resolved shape held in metadata and read back by
+ * schema generation — keeps the narrow storage union, because widening a property
+ * people *read* breaks the ones who assigned it to the narrower type.
+ */
+export type ColumnOptionsInput = Omit<ColumnOptions, "type"> & {
+  type?: ColumnStorageType | ColumnShorthand | undefined;
+};
+
 const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   string: { type: "string" },
   text: { type: "text" },
@@ -169,7 +195,7 @@ const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
  * `Omit<ColumnOptions, "type">`, so it cannot contradict the type it is modifying.
  */
 function resolveOptions(
-  arg?: ColumnShorthand | ColumnOptions,
+  arg?: ColumnShorthand | ColumnOptionsInput,
   extra?: Omit<ColumnOptions, "type">,
 ): ColumnOptions {
   const base = _resolveBase(arg);
@@ -183,7 +209,7 @@ function resolveOptions(
   return merged;
 }
 
-function _resolveBase(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
+function _resolveBase(arg?: ColumnShorthand | ColumnOptionsInput): ColumnOptions {
   if (arg === undefined) return { type: "string" };
   if (typeof arg === "string") {
     const a = arg as string;
@@ -196,7 +222,36 @@ function _resolveBase(arg?: ColumnShorthand | ColumnOptions): ColumnOptions {
       } as ColumnOptions;
     return SHORTHAND_MAP[a as ColumnShorthand] ?? { type: "string" };
   }
-  return arg;
+  return _resolveOptionType(arg);
+}
+
+/**
+ * Let the object form take a shorthand `type`, resolving it the way the string form
+ * would.
+ *
+ * `@column("integer")` compiled and `@column({ type: "integer", default: 0 })` did
+ * not — so the vocabulary shrank from twelve names to six exactly when a caller
+ * needed `default`, `nullable` or `unique`, which is most real columns. And the
+ * error listed the six without mentioning that `integer` means
+ * `{ type: "number", cast: "integer" }`, so the way out was reading this file.
+ *
+ * An explicit `cast` wins over the shorthand's own: someone who wrote both meant the
+ * one they spelled out.
+ *
+ * @param options - The options object as written.
+ * @returns The same options with any shorthand `type` resolved to storage type + cast.
+ */
+function _resolveOptionType(options: ColumnOptionsInput): ColumnOptions {
+  const declared = options.type;
+  if (declared === undefined) return options as ColumnOptions;
+
+  const shorthand = SHORTHAND_MAP[declared as ColumnShorthand];
+  // A storage type maps to itself with no cast — `string`, `text`, `number`,
+  // `boolean`, `datetime` and `json` appear in both vocabularies and mean the same
+  // thing in each, so there is nothing to resolve.
+  if (!shorthand || shorthand.type === declared) return options as ColumnOptions;
+
+  return { ...shorthand, ...options, type: shorthand.type };
 }
 
 // ── Reactivity ────────────────────────────────────────────────────────────────
@@ -307,7 +362,7 @@ export function column(
   options: Omit<ColumnOptions, "type">,
 ): ColumnDecorator;
 export function column(
-  arg?: ColumnShorthand | ColumnOptions,
+  arg?: ColumnShorthand | ColumnOptionsInput,
   extra?: Omit<ColumnOptions, "type">,
 ): ColumnDecorator {
   const options = resolveOptions(arg, extra);

package/src/model/decorators/hasMany.ts

@@ -5,7 +5,7 @@ export interface HasManyOptions {
   /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
   foreignKey: string;
   /** Parent local key the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/hasManyThrough.ts

@@ -6,9 +6,9 @@ export interface HasManyThroughOptions {
   /** FK on the related table referencing the through model (e.g. 'user_id' on posts). */
   secondKey: string;
   /** Parent local key the firstKey references. Default 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Through local key the secondKey references. Default 'id'. */
-  throughLocalKey?: string;
+  throughLocalKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/hasOne.ts

@@ -5,7 +5,7 @@ export interface HasOneOptions {
   /** FK column on the related table pointing back to the parent (e.g. `user_id`). */
   foreignKey: string;
   /** Parent local key the FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/manyToMany.ts

@@ -9,13 +9,13 @@ export interface ManyToManyOptions {
   /** Pivot column referencing the related model (e.g. `role_id`). */
   pivotRelatedKey: string;
   /** Parent local key the pivot FK references. Defaults to `'id'`. */
-  localKey?: string;
+  localKey?: string | undefined;
   /** Related local key the pivot relatedKey references. Defaults to `'id'`. */
-  relatedKey?: string;
+  relatedKey?: string | undefined;
   /** Extra pivot columns to hydrate onto each related model's `pivot` bag. */
-  withPivot?: string[];
+  withPivot?: string[] | undefined;
   /** Maintain created_at / updated_at on the pivot table during attach/sync. */
-  withTimestamps?: boolean;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/morphMany.ts

@@ -7,7 +7,7 @@ export interface MorphManyOptions {
    */
   morphName: string;
   /** Override the local key. Defaults to 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/morphOne.ts

@@ -7,7 +7,7 @@ export interface MorphOneOptions {
    */
   morphName: string;
   /** Override the local key. Defaults to 'id'. */
-  localKey?: string;
+  localKey?: string | undefined;
 }
 
 /**

package/src/model/decorators/morphTo.ts

@@ -7,12 +7,12 @@ export interface MorphToOptions {
    * Override the _type column name. Defaults to `<propertyName>_type`.
    * e.g. property `commentable` → `commentable_type`.
    */
-  morphTypeColumn?: string;
+  morphTypeColumn?: string | undefined;
   /**
    * Override the _id column name. Defaults to `<propertyName>_id`.
    * e.g. property `commentable` → `commentable_id`.
    */
-  morphForeignKey?: string;
+  morphForeignKey?: string | undefined;
 }
 
 function _toSnake(s: string): string {

package/src/model/decorators/morphToMany.ts

@@ -6,11 +6,11 @@ export interface MorphToManyOptions {
   /** FK on the pivot table referencing the related model (e.g. 'tag_id'). */
   relatedPivotKey: string;
   /** Pivot table name. Defaults to `{morphName}s`. */
-  pivotTable?: string;
+  pivotTable?: string | undefined;
   /** Extra pivot columns to hydrate. */
-  withPivot?: string[];
+  withPivot?: string[] | undefined;
   /** Maintain pivot timestamps. */
-  withTimestamps?: boolean;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/morphedByMany.ts

@@ -6,9 +6,9 @@ export interface MorphedByManyOptions {
   /** FK on the pivot referencing the parent model (e.g. 'tag_id'). */
   parentPivotKey: string;
   /** Pivot table name. Defaults to `{morphName}s`. */
-  pivotTable?: string;
-  withPivot?: string[];
-  withTimestamps?: boolean;
+  pivotTable?: string | undefined;
+  withPivot?: string[] | undefined;
+  withTimestamps?: boolean | undefined;
 }
 
 /**

package/src/model/decorators/table.ts

@@ -11,9 +11,9 @@ import type { ClassRef } from "../../support/classRef.ts";
  */
 export interface TableOptions {
   /** Enable / disable automatic timestamp columns. @default true */
-  timestamps?: boolean;
+  timestamps?: boolean | undefined;
   /** Override the primary key column name. @default "id" */
-  primaryKey?: string;
+  primaryKey?: string | undefined;
 }
 
 /**

package/src/provider/DatabaseProvider.ts

@@ -5,6 +5,7 @@ import type { ConfigManager } from "@zerotal/core/config";
 import { SQL } from "bun";
 import { DB, _getConnection } from "../db/DB.ts";
 import { preventNPlusOne } from "../db/NPlusOneDetector.ts";
+import { foreignKeysCheck } from "../doctor/foreignKeys.ts";
 import {
   _setBaseModelConnection,
   _setBaseModelDialect,
@@ -118,6 +119,10 @@ export class DatabaseProvider extends ServiceProvider {
         pool?.max !== undefined || pool?.idleTimeout !== undefined ? { url, ...pool } : url;
       const primary = new SQL(sqlArg as unknown as string);
 
+      const driver = config.get<string>("database.driver", "sqlite");
+      const enforceForeignKeys = config.get<boolean>("database.sqlite.foreignKeys", true);
+      await _applySqlitePragmas(primary, driver, enforceForeignKeys);
+
       if (replicaUrls.length === 0) return primary;
 
       // Build read replicas and wrap in a transparent read/write router.
@@ -131,6 +136,9 @@ export class DatabaseProvider extends ServiceProvider {
             : replicaUrl;
         return new SQL(replicaSqlArg as unknown as string);
       });
+      for (const replica of replicas) {
+        await _applySqlitePragmas(replica, driver, enforceForeignKeys);
+      }
 
       return createReadWriteRouter(primary, replicas);
     });
@@ -214,7 +222,7 @@ export class DatabaseProvider extends ServiceProvider {
    * it — `doctor` already boots the app and already holds the connection.
    */
   override doctorChecks(): DoctorCheck[] {
-    return [pendingMigrationsCheck];
+    return [pendingMigrationsCheck, foreignKeysCheck];
   }
 
   override async onBooted(): Promise<void> {
@@ -252,6 +260,9 @@ export class DatabaseProvider extends ServiceProvider {
     runner.registerLazy("migrate:refresh", () =>
       import("../commands/MigrateRefreshCommand.ts").then((m) => m.MigrateRefreshCommand),
     );
+    runner.registerLazy("db:check-foreign-keys", () =>
+      import("../commands/CheckForeignKeysCommand.ts").then((m) => m.CheckForeignKeysCommand),
+    );
     runner.registerLazy("migrate:status", () =>
       import("../commands/MigrateStatusCommand.ts").then((m) => m.MigrateStatusCommand),
     );
@@ -323,3 +334,29 @@ function _detectDialect(raw: string): "sqlite" | "postgres" | "mysql" {
   if (raw.startsWith("mysql://") || raw.startsWith("mysql2://")) return "mysql";
   return "sqlite";
 }
+
+/**
+ * Apply the connection-scoped PRAGMAs SQLite needs, if this is SQLite.
+ *
+ * `foreign_keys` is **per connection**, not per database, so it has to be set on
+ * every handle the app opens — including each read replica. Setting it once on the
+ * primary and assuming it stuck is how this ends up half-enforced.
+ *
+ * @param sql - The connection to configure.
+ * @param driver - The configured driver; anything but `sqlite` is left alone.
+ * @param foreignKeys - Whether to enforce foreign keys on this connection.
+ * @internal
+ */
+export async function _applySqlitePragmas(
+  sql: SQLInstance,
+  driver: string,
+  foreignKeys: boolean,
+): Promise<void> {
+  if (driver !== "sqlite" || !foreignKeys) return;
+  try {
+    await sql`PRAGMA foreign_keys = ON`;
+  } catch {
+    // A driver that will not take the pragma is not a reason to refuse the
+    // connection; the doctor check reports the consequence.
+  }
+}

package/src/schema/Migration.ts

@@ -27,6 +27,36 @@
  * ```
  */
 export abstract class Migration {
+  /**
+   * The name this migration is recorded under, instead of its filename.
+   *
+   * **Identity is a filename by default, and a filename is a thing people rename.**
+   * The `migrations` table stores the name a migration ran as, and the next run
+   * compares files against it — so renaming a file makes an applied migration look
+   * pending, the runner tries it again, and it fails on `table already exists`. That
+   * is a failed boot rather than a graceful skip.
+   *
+   * It is not a hypothetical. An app renumbered `001_` to `0001_` to match this
+   * framework's own scaffold convention — exactly what a careful person does — and
+   * would have made all nine of its production migrations look unrun. They caught it
+   * before deploying and renamed the files back.
+   *
+   * Declaring `id` decouples the two. Set it to whatever the file is *already*
+   * recorded as, and the file is then free to be named anything:
+   *
+   * ```ts
+   * export default class AddTenantLimits extends Migration {
+   *   static override id = "010_add_tenant_limits"; // what the table already holds
+   *   async up() { … }
+   * }
+   * ```
+   *
+   * Deliberately not a content hash: a migration's content is edited far more often
+   * than its name, and a hash would make every edit look like a new migration — the
+   * same failure, more often.
+   */
+  static id?: string;
+
   /** Apply the migration's forward schema change. */
   abstract up(): Promise<void>;
   /** Reverse everything {@link Migration.up} did, for rollback. */

package/src/schema/MigrationRunner.ts

@@ -150,6 +150,8 @@ export class MigrationRunner {
     const batch = (await this._lastBatch()) + 1;
 
     const pendingEntries = entries.filter((e) => !ran.has(e.name));
+    _refuseLikelyRenames(pendingEntries, ran);
+
     const executed: string[] = [];
 
     for (const entry of pendingEntries) {
@@ -425,11 +427,75 @@ export class MigrationRunner {
       // Dynamic import — each migration file must have a default export
       const mod = (await import(fullPath)) as { default: new () => Migration };
       const Ctor = mod.default;
+      // A declared `static id` wins over the filename — see `Migration.id`. Without
+      // it, renaming a file makes an applied migration look pending.
+      const declared = (Ctor as { id?: string }).id;
       entries.push({
-        name: file.replace(/\.(ts|js)$/, ""),
+        name: declared ?? file.replace(/\.(ts|js)$/, ""),
         migration: new Ctor(),
       });
     }
     return entries;
   }
 }
+
+/**
+ * Refuse to run a "pending" migration that is almost certainly a renamed applied one.
+ *
+ * A migration is recorded under a name, and the next run compares files against those
+ * names — so renaming a file makes an applied migration look pending. The runner then
+ * tries it again and it fails on `table already exists`, which is a failed boot rather
+ * than a graceful skip, and the error names a table rather than the rename that caused
+ * it.
+ *
+ * An app renumbered `001_` to `0001_` to match this framework's own scaffold
+ * convention and would have made all nine of its production migrations look unrun.
+ * They caught it by reading, not by being told.
+ *
+ * The signal is precise enough to act on: a pending migration whose name matches a
+ * recorded one once the leading digits are stripped is a renumbering, not a new
+ * migration. Nobody writes `0001_create_users` alongside an applied
+ * `001_create_users` and means two different things.
+ *
+ * This refuses rather than warns because the alternative is running it — and running
+ * it is the outage. {@link Migration.id} is the way to make the rename permanent.
+ *
+ * @param pending - Migrations about to run.
+ * @param ran - Names already recorded.
+ * @throws {@link MigrationError} naming both spellings and the fix.
+ * @internal
+ */
+export function _refuseLikelyRenames(pending: MigrationEntry[], ran: Set<string>): void {
+  /** The name with any leading ordinal removed: `0001_create_users` → `create_users`. */
+  const withoutOrdinal = (name: string): string => name.replace(/^[0-9]+[_-]?/, "");
+
+  const appliedBySuffix = new Map<string, string>();
+  for (const name of ran) appliedBySuffix.set(withoutOrdinal(name), name);
+
+  for (const entry of pending) {
+    const suffix = withoutOrdinal(entry.name);
+    // A bare ordinal strips to nothing; two of those are not evidence of anything.
+    if (suffix === "") continue;
+    const applied = appliedBySuffix.get(suffix);
+    if (applied === undefined || applied === entry.name) continue;
+
+    throw new MigrationError(
+      entry.name,
+      new Error(
+        `"${entry.name}" looks like "${applied}", which has already run — the same ` +
+          `migration renumbered rather than a new one. Running it would apply a schema ` +
+          `change that is already applied, and fail on the first table it creates.
+
+` +
+          `  If it IS the same migration: rename the file back to "${applied}", or keep ` +
+          `the new filename and pin the identity to what the database already holds:
+` +
+          `    static override id = "${applied}";
+
+` +
+          `  If it is genuinely a new migration, give it a name that does not collide ` +
+          `once the leading digits are removed.`,
+      ),
+    );
+  }
+}

package/src/schema/autoMigrate.ts

@@ -52,7 +52,7 @@ export interface SynchronizeOptions {
    * declared by any model. Off by default - additive changes are always safe,
    * drops can lose data.
    */
-  disruptive?: boolean;
+  disruptive?: boolean | undefined;
 }
 
 /**