@zerotal/orm 1.4.0 → 1.5.1

package/src/model/decorators/_metadata.ts

@@ -18,19 +18,20 @@
 import { relationRegistry } from "../relations/RelationRegistry.ts";
 import type { RelationMetadata } from "../relations/RelationRegistry.ts";
 import type { ColumnOptions } from "./column.ts";
+import type { ClassRef } from "../../support/classRef.ts";
 
 /**
  * Per-class OWN column definitions. Readers walk the prototype chain to merge inherited.
  * @internal
  */
-export const columnRegistry = new Map<Function, Map<string, ColumnOptions>>();
+export const columnRegistry = new Map<ClassRef, Map<string, ColumnOptions>>();
 
 // ── Definition-time queue ─────────────────────────────────────────────────────
 
 interface PendingMember {
   /** Field name (captured correctly in the decorator body). */
   name: string;
-  apply: (ctor: Function) => void;
+  apply: (ctor: ClassRef) => void;
 }
 let _pending: PendingMember[] = [];
 
@@ -38,7 +39,7 @@ let _pending: PendingMember[] = [];
  * Enqueue a member registration from a decorator body (name captured correctly there).
  * @internal
  */
-export function enqueueMember(name: string, apply: (ctor: Function) => void): void {
+export function enqueueMember(name: string, apply: (ctor: ClassRef) => void): void {
   _pending.push({ name, apply });
 }
 
@@ -48,7 +49,7 @@ export function enqueueMember(name: string, apply: (ctor: Function) => void): vo
  * contains exactly that class's members and nothing else.
  * @internal
  */
-export function drainPendingMembers(ctor: Function): void {
+export function drainPendingMembers(ctor: ClassRef): void {
   if (_pending.length === 0) return;
   const batch = _pending;
   _pending = [];
@@ -63,7 +64,7 @@ export function drainPendingMembers(ctor: Function): void {
  * `static casts` map (seeded from the parent so a subclass extends rather than mutates it).
  * @internal
  */
-export function registerColumn(ctor: Function, name: string, options: ColumnOptions): void {
+export function registerColumn(ctor: ClassRef, name: string, options: ColumnOptions): void {
   let m = columnRegistry.get(ctor);
   if (!m) {
     m = new Map();
@@ -89,7 +90,7 @@ export function registerColumn(ctor: Function, name: string, options: ColumnOpti
  * Record relation metadata for `ctor`. Invoked from a drained decorator closure.
  * @internal
  */
-export function registerRelation(ctor: Function, name: string, meta: RelationMetadata): void {
+export function registerRelation(ctor: ClassRef, name: string, meta: RelationMetadata): void {
   let m = relationRegistry.get(ctor);
   if (!m) {
     m = new Map();
@@ -100,23 +101,23 @@ export function registerRelation(ctor: Function, name: string, meta: RelationMet
 
 // ── Convention registration (used by the auto-discovery loader) ───────────────
 
-const _registeredModels = new WeakSet<Function>();
+const _registeredModels = new WeakSet<ClassRef>();
 /**
  * class name → model class, for observer/policy association by name.
  * @internal
  */
-export const modelsByName = new Map<string, Function>();
+export const modelsByName = new Map<string, ClassRef>();
 
 /**
  * Look up a model class by its (unqualified) class name.
  * @internal
  */
-export function modelByName(name: string): Function | undefined {
+export function modelByName(name: string): ClassRef | undefined {
   return modelsByName.get(name);
 }
 
 /** Index a model class under its name. Called by @table's drain and by registerModel(). */
-function registerModelName(ctor: Function): void {
+function registerModelName(ctor: ClassRef): void {
   const name = (ctor as { name?: string }).name;
   if (name) modelsByName.set(name, ctor);
 }
@@ -136,7 +137,7 @@ function registerModelName(ctor: Function): void {
  * safe no-op on already-`@table`'d models.
  * @internal
  */
-export function registerModel(ctor: Function): void {
+export function registerModel(ctor: ClassRef): void {
   if (_registeredModels.has(ctor)) return;
   _registeredModels.add(ctor);
 
@@ -170,13 +171,13 @@ export function registerModel(ctor: Function): void {
  * Merged column definitions (own + inherited) for a class, or null if none.
  * @internal
  */
-export function columnsFor(ctor: Function): Map<string, ColumnOptions> | null {
+export function columnsFor(ctor: ClassRef): Map<string, ColumnOptions> | null {
   const merged = new Map<string, ColumnOptions>();
-  let cls: Function | null = ctor;
+  let cls: ClassRef | null = ctor;
   while (cls && cls !== Function.prototype) {
     const c = columnRegistry.get(cls);
     if (c) for (const [k, v] of c) if (!merged.has(k)) merged.set(k, v);
-    cls = Object.getPrototypeOf(cls) as Function | null;
+    cls = Object.getPrototypeOf(cls) as ClassRef | null;
   }
   return merged.size ? merged : null;
 }
@@ -185,13 +186,13 @@ export function columnsFor(ctor: Function): Map<string, ColumnOptions> | null {
  * Merged relation metadata (imperative mixins + @decorators, own + inherited).
  * @internal
  */
-export function relationsFor(ctor: Function): Map<string, RelationMetadata> {
+export function relationsFor(ctor: ClassRef): Map<string, RelationMetadata> {
   const merged = new Map<string, RelationMetadata>();
-  let cls: Function | null = ctor;
+  let cls: ClassRef | null = ctor;
   while (cls && cls !== Function.prototype) {
     const r = relationRegistry.get(cls);
     if (r) for (const [k, v] of r) if (!merged.has(k)) merged.set(k, v);
-    cls = Object.getPrototypeOf(cls) as Function | null;
+    cls = Object.getPrototypeOf(cls) as ClassRef | null;
   }
   return merged;
 }
@@ -200,7 +201,7 @@ export function relationsFor(ctor: Function): Map<string, RelationMetadata> {
  * Names of reactive (json/array cast) columns for a class (own + inherited).
  * @internal
  */
-export function reactiveColumnsFor(ctor: Function): string[] {
+export function reactiveColumnsFor(ctor: ClassRef): string[] {
   const cols = columnsFor(ctor);
   if (!cols) return [];
   const out: string[] = [];

package/src/model/decorators/_registerRelation.ts

@@ -1,5 +1,6 @@
 import type { RelationMetadata } from "../relations/RelationRegistry.ts";
 import { enqueueMember, registerRelation } from "./_metadata.ts";
+import type { ClassRef } from "../../support/classRef.ts";
 
 /**
  * The single plumbing for every relation field decorator (standard TC39 decorators).
@@ -11,7 +12,7 @@ import { enqueueMember, registerRelation } from "./_metadata.ts";
  * with that class so morph/through values depending on the class name resolve correctly.
  */
 export function makeRelationDecorator(
-  metaFor: (ctor: Function, field: string) => RelationMetadata,
+  metaFor: (ctor: ClassRef, field: string) => RelationMetadata,
 ) {
   return function (_value: unknown, context: ClassFieldDecoratorContext): void {
     const name = String(context.name);

package/src/model/decorators/column.ts

@@ -7,6 +7,7 @@ import {
   columnsFor,
   reactiveColumnsFor,
 } from "./_metadata.ts";
+import type { ClassRef } from "../../support/classRef.ts";
 
 // Re-exported here for the public API — populated at class-definition time via @table.
 export { columnRegistry };
@@ -331,9 +332,9 @@ export function column(
  * @internal
  */
 export function installReactiveAccessors(instance: object): void {
-  const reactive = reactiveColumnsFor(instance.constructor as Function);
+  const reactive = reactiveColumnsFor(instance.constructor as ClassRef);
   if (!reactive.length) return;
-  const cols = columnsFor(instance.constructor as Function);
+  const cols = columnsFor(instance.constructor as ClassRef);
   for (const name of reactive) {
     const desc = Object.getOwnPropertyDescriptor(instance, name);
     if (desc && typeof desc.get === "function") continue; // already installed

package/src/model/decorators/table.ts

@@ -1,4 +1,5 @@
 import { drainPendingMembers } from "./_metadata.ts";
+import type { ClassRef } from "../../support/classRef.ts";
 
 /**
  * Options object accepted as the second argument to `@table()`.
@@ -50,7 +51,7 @@ interface TableConfig {
  */
 export interface TableDecoratorBuilder {
   /** Apply the decorator to a class constructor (called automatically by TS). */
-  (target: Function, context?: unknown): void;
+  (target: ClassRef, context?: unknown): void;
 
   /** Enable automatic `created_at` / `updated_at` management. Default: on. */
   withTimestamps(): TableDecoratorBuilder;
@@ -92,7 +93,7 @@ export function table(tableName: string, options: TableOptions = {}): TableDecor
     primaryKey: options.primaryKey ?? "id",
   };
 
-  function apply(target: Function, _context?: unknown): void {
+  function apply(target: ClassRef, _context?: unknown): void {
     // Drain the @column / @relation registrations queued while this class's members were
     // decorated. @table is the definition-time anchor that owns this — see _metadata.ts.
     drainPendingMembers(target);

package/src/model/hooks/HookRegistry.ts

@@ -1,5 +1,6 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { currentOrmContext } from "../OrmContext.ts";
+import type { ClassRef } from "../../support/classRef.ts";
 
 /**
  * The set of model lifecycle points a hook can attach to. Each fires once per
@@ -19,8 +20,8 @@ export type HookName =
 
 type HookFn<T> = (model: T) => Promise<void> | void;
 
-function _registry(): Map<Function, Map<HookName, HookFn<unknown>[]>> {
-  return currentOrmContext().hooks as unknown as Map<Function, Map<HookName, HookFn<unknown>[]>>;
+function _registry(): Map<ClassRef, Map<HookName, HookFn<unknown>[]>> {
+  return currentOrmContext().hooks as unknown as Map<ClassRef, Map<HookName, HookFn<unknown>[]>>;
 }
 
 /**
@@ -56,7 +57,7 @@ export class HookRegistry {
    * Optional post-run callback, invoked after a hook's functions run (and only when hooks
    * are not suppressed). BaseModel sets this to dispatch model events (`dispatchesEvents`).
    */
-  static onAfterRun: ((ModelClass: Function, hook: HookName, model: unknown) => void) | undefined;
+  static onAfterRun: ((ModelClass: ClassRef, hook: HookName, model: unknown) => void) | undefined;
 
   /**
    * Append a hook callback for a model class at a given lifecycle point.
@@ -65,7 +66,7 @@ export class HookRegistry {
    * @param hook - Which lifecycle point to fire on.
    * @param fn - Callback receiving the model instance; may be async.
    */
-  static register<T>(ModelClass: Function, hook: HookName, fn: HookFn<T>): void {
+  static register<T>(ModelClass: ClassRef, hook: HookName, fn: HookFn<T>): void {
     const registry = _registry();
     if (!registry.has(ModelClass)) {
       registry.set(ModelClass, new Map());
@@ -84,15 +85,15 @@ export class HookRegistry {
    * @param hook - Which lifecycle point is firing.
    * @param model - The model instance passed to each callback.
    */
-  static async run<T>(ModelClass: Function, hook: HookName, model: T): Promise<void> {
+  static async run<T>(ModelClass: ClassRef, hook: HookName, model: T): Promise<void> {
     if (_suppressCtx.getStore()) return;
 
     // Walk the prototype chain to collect inherited hooks
-    const chain: Function[] = [];
-    let cur: Function | null = ModelClass;
+    const chain: ClassRef[] = [];
+    let cur: ClassRef | null = ModelClass;
     while (cur && cur !== Function.prototype) {
       chain.unshift(cur);
-      cur = Object.getPrototypeOf(cur) as Function | null;
+      cur = Object.getPrototypeOf(cur) as ClassRef | null;
     }
 
     const registry = _registry();

package/src/model/relations/RelationRegistry.ts

@@ -1,3 +1,5 @@
+import type { ClassRef } from "../../support/classRef.ts";
+
 /** Discriminator for every relation kind the ORM supports. */
 export type RelationType =
   | "hasMany"
@@ -70,7 +72,7 @@ export type RelationDefinition = RelationMetadata;
  * relation (property) name. Populated by the relation decorators at class-definition
  * time and consulted by {@link ModelQueryBuilder} when resolving a relation.
  */
-export const relationRegistry = new Map<Function, Map<string, RelationMetadata>>();
+export const relationRegistry = new Map<ClassRef, Map<string, RelationMetadata>>();
 
 // ── Pivot collection ─────────────────────────────────────────────────────────
 

package/src/observability.ts

@@ -100,7 +100,7 @@ export function installOrmObservability(app: Application): () => void {
         if (e.ctx) store.markNPlus(e.ctx);
         store.recordEvent({
           kind: "nplus",
-          label: e.fingerprint.replace(/\x00/g, "?"),
+          label: e.fingerprint.replaceAll("\x00", "?"),
           status: "warn",
           route: e.ctx ? _ctxPath(e.ctx) : null,
           data: { count: e.count },
@@ -161,7 +161,7 @@ export function installOrmObservability(app: Application): () => void {
       }),
       FrameworkEvents.on(NPlusOneDetected, (e) => {
         if (!e.ctx) return;
-        trace.bufferWarning(e.ctx, { sql: e.fingerprint.replace(/\x00/g, "?"), count: e.count });
+        trace.bufferWarning(e.ctx, { sql: e.fingerprint.replaceAll("\x00", "?"), count: e.count });
       }),
     );
   }

package/src/provider/DatabaseProvider.ts

@@ -1,5 +1,5 @@
 import type { SQLInstance } from "../db/sql-types.ts";
-import { ServiceProvider } from "@zerotal/core";
+import { ServiceProvider, registerErrorDiagnoser, isProdLike, deployEnv } from "@zerotal/core";
 import type { AppEnvironment } from "@zerotal/core";
 import type { ConfigManager } from "@zerotal/core/config";
 import { SQL } from "bun";
@@ -17,6 +17,12 @@ import { validateDatabaseConfig } from "../config.ts";
 import { autoMigrateConcern } from "../schema/autoMigrate.ts";
 import { registerImplicitBinding } from "../implicitBinding.ts";
 import { installOrmObservability } from "../observability.ts";
+import { diagnoseMissingRelation } from "../diagnostics/missingRelation.ts";
+import {
+  registerRunMigrationsEndpoint,
+  RUN_MIGRATIONS_PATH,
+  _mintDiagnosisToken,
+} from "../diagnostics/runMigrationsEndpoint.ts";
 
 // Extend the core container registry so 'db' is a typed binding.
 declare module "@zerotal/core" {
@@ -65,6 +71,19 @@ export class DatabaseProvider extends ServiceProvider {
     // route-compile time, so model registration order doesn't matter.
     registerImplicitBinding();
 
+    // "no such table: assets" arrives with a stack that is entirely SQL-driver
+    // frames, so the overlay can name the failure and nothing else. This turns it
+    // into the list of migrations that have not run — and, when none are pending,
+    // says so instead of offering a button that would change nothing.
+    registerErrorDiagnoser((error) =>
+      diagnoseMissingRelation(error, {
+        endpoint: RUN_MIGRATIONS_PATH,
+        mintToken: _mintDiagnosisToken,
+      }),
+    );
+    // Registers nothing outside development. See the file for the three guards.
+    registerRunMigrationsEndpoint(() => this.app._allowedOrigins?.() ?? []);
+
     setConnectionResolver(() => {
       try {
         return this.app.container.makeSync("db") as SQLInstance;
@@ -180,8 +199,12 @@ export class DatabaseProvider extends ServiceProvider {
 
     // N+1 query detection — enabled outside production. Previously activated by
     // the devtools provider; owned here so devtools needs no ORM import.
-    const env = Bun.env.APP_ENV ?? "";
-    if (env !== "production" && env !== "prod") {
+    //
+    // `deployEnv()`, not `Bun.env.APP_ENV`: the latter holds the runtime mode by
+    // the time a provider boots (`setAppEnv()` overwrote it), so this read was
+    // `"web"` and the detector was installed in production too — wrapping every
+    // query on a live app to warn about something nobody was there to read.
+    if (!isProdLike(deployEnv())) {
       preventNPlusOne({ threshold: 5, mode: "warn" });
     }
 
@@ -199,6 +222,12 @@ export class DatabaseProvider extends ServiceProvider {
     runner.registerLazy("migrate:fresh", () =>
       import("../commands/MigrateFreshCommand.ts").then((m) => m.MigrateFreshCommand),
     );
+    // Same command, the name it has elsewhere. Nothing otherwise pushes anyone to
+    // exercise their `down()` methods, and a rollback nobody has run is a
+    // rollback that does not work.
+    runner.registerLazy("migrate:refresh", () =>
+      import("../commands/MigrateRefreshCommand.ts").then((m) => m.MigrateRefreshCommand),
+    );
     runner.registerLazy("migrate:status", () =>
       import("../commands/MigrateStatusCommand.ts").then((m) => m.MigrateStatusCommand),
     );

package/src/schema/Blueprint.ts

@@ -648,6 +648,19 @@ export class Blueprint {
     return this;
   }
 
+  /**
+   * The columns this blueprint will drop.
+   *
+   * Read by {@link Schema.table} so it can refuse an impossible drop on SQLite
+   * *before* running any statement, rather than after the earlier ones have
+   * already applied.
+   *
+   * @internal
+   */
+  get _pendingDrops(): readonly string[] {
+    return this._drops;
+  }
+
   /**
    * Rename a column (`ALTER TABLE … RENAME COLUMN from TO to`).
    * @category Table modifiers
@@ -893,7 +906,7 @@ function _postgresAlterStatements(table: string, col: IAlterCol): string[] {
   }
 
   // NOT NULL / nullable.
-  if (/NOT NULL/i.test(afterName)) {
+  if (/\bNOT NULL\b/i.test(afterName)) {
     stmts.push(`ALTER TABLE ${table} ALTER COLUMN ${name} SET NOT NULL`);
   } else {
     stmts.push(`ALTER TABLE ${table} ALTER COLUMN ${name} DROP NOT NULL`);
@@ -901,7 +914,7 @@ function _postgresAlterStatements(table: string, col: IAlterCol): string[] {
 
   // DEFAULT.
   const defMatch = afterName.match(
-    /DEFAULT\s+(\S+(?:\s+\S+)*?)(?:\s+(?:NOT NULL|NULL|UNIQUE|CHECK|GENERATED)|$)/i,
+    /\bDEFAULT\s+(\S+(?:\s+\S+)*?)(?:\s+(?:NOT NULL|NULL|UNIQUE|CHECK|GENERATED)\b|$)/i,
   );
   if (defMatch) {
     stmts.push(`ALTER TABLE ${table} ALTER COLUMN ${name} SET DEFAULT ${defMatch[1]}`);

package/src/schema/ColumnDefinition.ts

@@ -362,7 +362,7 @@ export class ColumnBuilder<Locked extends string = never> {
  *   table.foreignId('author_id').constrained('users', 'uuid');  // → users.uuid
  *   table.foreignId('user_id').nullable().constrained().nullOnDelete();
  */
-export class ForeignIdColumnBuilder extends ColumnBuilder {
+export class ForeignIdColumnBuilder<Locked extends string = never> extends ColumnBuilder<Locked> {
   constructor(
     name: string,
     sqlType: string,
@@ -371,6 +371,40 @@ export class ForeignIdColumnBuilder extends ColumnBuilder {
     super(name, sqlType);
   }
 
+  /**
+   * Allow NULL, keeping `.constrained()` reachable.
+   *
+   * The base `nullable()` returns `ColumnBuilder`, which drops the subclass — so
+   * the documented `foreignId('user_id').nullable().constrained()` did not
+   * compile, and a nullable foreign key is the commonest kind there is. These
+   * two overrides re-declare the return as this builder while keeping the
+   * phantom lock, so `.nullable().notNullable()` is still a compile error.
+   *
+   * @locked `nullability` — shared with `notNullable()`.
+   * @category Nullability & defaults
+   */
+  override nullable(): "nullability" extends Locked
+    ? never
+    : ForeignIdColumnBuilder<Locked | "nullability"> {
+    super.nullable();
+    // `as any` per this file's own convention (see the header note): TypeScript
+    // cannot reduce a deferred conditional inside a generic body.
+    return this as any;
+  }
+
+  /**
+   * Enforce NOT NULL explicitly, keeping `.constrained()` reachable.
+   *
+   * @locked `nullability` — shared with `nullable()`.
+   * @category Nullability & defaults
+   */
+  override notNullable(): "nullability" extends Locked
+    ? never
+    : ForeignIdColumnBuilder<Locked | "nullability"> {
+    super.notNullable();
+    return this as any;
+  }
+
   /**
    * Add a `FOREIGN KEY` constraint for this column. The referenced table is
    * inferred from the column name (`user_id` → `users`) unless supplied

package/src/schema/ModelInspector.ts

@@ -3,6 +3,7 @@ import type { ColumnOptions } from "../model/decorators/column.ts";
 import { columnRegistry, columnsFor } from "../model/decorators/_metadata.ts";
 import { ctorChain } from "../support/identifiers.ts";
 import { isEncryptedCast } from "../casts/encrypted.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 // ── Model schema descriptor ───────────────────────────────────────────────────
 
@@ -50,7 +51,7 @@ export function columnDbName(name: string): string {
  * declared on `User` appear in `AdminUser`'s schema without needing to be
  * re-declared.
  */
-function collectColumns(ctor: Function): Map<string, ColumnOptions> | null {
+function collectColumns(ctor: ClassRef): Map<string, ColumnOptions> | null {
   // columnsFor walks the prototype chain (child overrides parent) and mirrors each
   // class's metadata into columnRegistry on first read.
   return columnsFor(ctor);
@@ -147,7 +148,7 @@ export const ModelInspector = {
    * Returns null if the class has no `static table` or no `@column()` fields
    * anywhere in its prototype chain.
    */
-  fromClass(ctor: Function): ModelSchema | null {
+  fromClass(ctor: ClassRef): ModelSchema | null {
     const M = ctor as unknown as Record<string, unknown>;
     const table = M["table"] as string | undefined;
     if (!table) return null;

package/src/schema/Schema.ts

@@ -28,6 +28,54 @@ async function query<T = Record<string, unknown>>(sql: string, params: unknown[]
   return conn<T>(tpl, ...params);
 }
 
+/**
+ * Throw if a column this blueprint drops is named by a foreign key on the table.
+ *
+ * SQLite has no way to drop an FK constraint through `ALTER TABLE`, so while the
+ * constraint names the column the column cannot go — the engine answers
+ * `unknown column "x" in foreign key definition`, and it answers *after* every
+ * earlier statement in the block has run. The standard way out is SQLite's own
+ * 12-step table rebuild; until that exists here, failing before the
+ * first statement is the difference between a migration that did nothing and
+ * one that has to be unpicked by hand.
+ *
+ * The message names the constraint and the way out, because "rebuild the table"
+ * is not obvious from the engine's own error.
+ */
+async function _assertDroppableOnSqlite(table: string, bp: Blueprint): Promise<void> {
+  const drops = bp._pendingDrops;
+  if (drops.length === 0) return;
+
+  // `PRAGMA foreign_key_list` takes no bind parameters, and the table name here
+  // comes from the migration's own source rather than from a request.
+  const fks = await query<{ id: number; from: string; table: string }>(
+    `PRAGMA foreign_key_list(${table})`,
+    [],
+  );
+  if (fks.length === 0) return;
+
+  const blocked = drops.filter((column) =>
+    fks.some((fk) => String(fk.from).toLowerCase() === column.toLowerCase()),
+  );
+  if (blocked.length === 0) return;
+
+  const referenced = blocked
+    .map((column) => {
+      const fk = fks.find((f) => String(f.from).toLowerCase() === column.toLowerCase());
+      return `'${column}' (references ${fk?.table ?? "another table"})`;
+    })
+    .join(", ");
+
+  throw new Error(
+    `[Zerotal ORM] SQLite cannot drop ${referenced} from '${table}' while a foreign key ` +
+      `names the column — the constraint has to go first, and SQLite cannot drop one through ` +
+      `ALTER TABLE.\n\n` +
+      `Rebuild the table instead: create a replacement with the columns you want, copy the ` +
+      `rows across, drop the original, and rename. Nothing has been applied — this migration ` +
+      `stopped before its first statement, so the schema is exactly as it was.`,
+  );
+}
+
 // ── Schema facade ─────────────────────────────────────────────────────────────
 
 /**
@@ -96,7 +144,19 @@ export const Schema = {
   async table(name: string, callback: (bp: Blueprint) => void): Promise<void> {
     const bp = new Blueprint();
     callback(bp);
-    for (const sql of bp.toAlterSQL(name, _getDialect())) {
+    const dialect = _getDialect();
+
+    // Refuse before the first statement, not in the middle of the list.
+    //
+    // SQLite cannot drop a column a foreign key still names, and the error it
+    // raises — `unknown column "x" in foreign key definition` — arrives *after*
+    // every earlier statement in the same `Schema.table()` block has run. That
+    // is the difference between a migration that does nothing and one that has
+    // to be unpicked by hand. The check costs a single PRAGMA on the only path
+    // that can hit it.
+    if (dialect === "sqlite") await _assertDroppableOnSqlite(name, bp);
+
+    for (const sql of bp.toAlterSQL(name, dialect)) {
       await ddl(sql);
     }
   },
@@ -104,7 +164,7 @@ export const Schema = {
   /**
    * Alias of {@link Schema.table}, for modifying an existing table.
    *
-   * `alter` is the name Laravel and Knex use, so it is the first thing reached for — and
+   * `alter` is the name most schema builders use, so it is the first thing reached for — and
    * because the blueprint callback is loosely typed, `Schema.alter(...)` was not a type
    * error, only a `TypeError` at run time. A migration that fails there has already run
    * whatever statements preceded it, leaving the schema half-changed, which is a worse

package/src/support/classRef.ts

@@ -0,0 +1,23 @@
+/**
+ * The ORM's class-keyed registries — columns, relations, hooks, observers, global
+ * scopes, state-machine callbacks — all key on the model class and read back by
+ * walking its prototype chain. They share the framework's `ClassRef` rather than
+ * spelling the constructor type per registry; this module exists so the ORM's own
+ * modules import it from one place.
+ */
+import type { ClassRef as CoreClassRef } from "@zerotal/core";
+
+/**
+ * A model class used as a metadata key — the constructor, not an instance.
+ *
+ * This is the framework-wide `ClassRef` from `@zerotal/core`, re-exported because
+ * every ORM signature that registers or reads per-class metadata takes one:
+ * `registerColumn`, `registerRelation`, `columnsFor`, `relationsFor`,
+ * `registerObserver` and the hook registry all key on it. Being `abstract` with
+ * `never[]` constructor arguments, it accepts abstract bases and mixin-composed
+ * classes alike, while rejecting the plain callbacks the old `Function` typing let
+ * through.
+ *
+ * @internal Every ORM signature that takes one is itself `@internal`.
+ */
+export type ClassRef = CoreClassRef;

package/src/support/identifiers.ts

@@ -12,6 +12,7 @@
  * helper that reads a property off a hydrated instance must derive the same
  * name hydration produced.
  */
+import type { ClassRef } from "./classRef.ts";
 
 // DB schemas are static: the same names appear on every row. Caching the regex
 // result turns thousands of executions into Map lookups after the first query.
@@ -51,12 +52,12 @@ export function toSnakeColumn(s: string): string {
  * `Function.prototype` (not a falsy `.name`) so anonymous mixin classes are
  * still visited. Shared by cast collection and global-scope merging.
  */
-export function ctorChain(ctor: Function): Function[] {
-  const chain: Function[] = [];
-  let current: Function | null = ctor;
+export function ctorChain(ctor: ClassRef): ClassRef[] {
+  const chain: ClassRef[] = [];
+  let current: ClassRef | null = ctor;
   while (current && current !== Function.prototype) {
     chain.unshift(current);
-    current = Object.getPrototypeOf(current) as Function | null;
+    current = Object.getPrototypeOf(current) as ClassRef | null;
   }
   return chain;
 }