@zerotal/orm 1.3.0 → 1.5.0

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 };
@@ -29,6 +30,8 @@ export { columnRegistry };
  * | `"date"`    | `{ type: "datetime", cast: "date" }`            |
  * | `"json"`    | `{ type: "json", cast: "json" }`                |
  * | `"array"`   | `{ type: "json", cast: "array" }`               |
+ * | `"encrypted"` | `{ type: "text", cast: "encrypted" }`         |
+ * | `"encrypted:json"` | `{ type: "text", cast: "encrypted:json" }` |
  */
 export type ColumnShorthand =
   | "string"
@@ -40,7 +43,9 @@ export type ColumnShorthand =
   | "datetime"
   | "date"
   | "json"
-  | "array";
+  | "array"
+  | "encrypted"
+  | "encrypted:json";
 
 /**
  * Full option object accepted by `@column({ ... })`.
@@ -105,6 +110,12 @@ export interface ColumnOptions {
    * - 'integer'        — parseInt on both read and write
    * - 'float'          — parseFloat on both read and write
    * - 'enum'           — pass-through; pairs with `enumValues` for TS enum columns
+   * - 'encrypted'      — AES-256-GCM at rest under `APP_KEY`, plaintext on the model
+   * - 'encrypted:json' — the same, for a structured value (stringified, then encrypted)
+   *
+   * Encrypted columns need `type: "text"` (a payload outgrows the plaintext) and
+   * cannot be filtered on — `where()` against one throws, because a fresh IV per
+   * write means the ciphertext never repeats. See `casts/encrypted.ts`.
    */
   cast?:
     | "datetime"
@@ -116,6 +127,8 @@ export interface ColumnOptions {
     | "float"
     | "enum"
     | "immutable_datetime"
+    | "encrypted"
+    | "encrypted:json"
     | `decimal:${number}`
     | {
         get?: (dbValue: unknown) => unknown;
@@ -140,6 +153,10 @@ const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   date: { type: "datetime", cast: "date" },
   json: { type: "json", cast: "json" },
   array: { type: "json", cast: "array" },
+  // TEXT, not string: the stored payload is ~1.4× the plaintext plus 28 bytes of
+  // IV and auth tag, so a VARCHAR that held the value will not hold its ciphertext.
+  encrypted: { type: "text", cast: "encrypted" },
+  "encrypted:json": { type: "text", cast: "encrypted:json" },
 };
 
 /**
@@ -315,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

@@ -1,6 +1,9 @@
 import path from "node:path";
 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 ───────────────────────────────────────────────────
 
@@ -48,18 +51,28 @@ 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);
 }
 
-function toModelColumns(fields: Map<string, ColumnOptions>): ModelColumn[] {
+function toModelColumns(
+  fields: Map<string, ColumnOptions>,
+  encrypted: ReadonlySet<string>,
+): ModelColumn[] {
   const columns: ModelColumn[] = [];
   for (const [name, opts] of fields.entries()) {
     columns.push({
       name,
-      type: opts.type,
+      // An encrypted column is generated as TEXT whatever it was declared as. The
+      // stored payload is the plaintext plus 28 bytes of IV and auth tag, base64'd —
+      // about 1.4× longer — so a VARCHAR(255) that comfortably held the value no
+      // longer holds its ciphertext. MySQL outside strict mode truncates rather than
+      // failing, and a truncated payload will not decrypt: the row is lost, quietly,
+      // at write time. The generated migration says `table.text(...)`, so the
+      // widening is visible in review rather than only here.
+      type: encrypted.has(name) ? "text" : opts.type,
       nullable: opts.nullable ?? false,
       primary: opts.primary ?? false,
       default: opts.default,
@@ -70,6 +83,21 @@ function toModelColumns(fields: Map<string, ColumnOptions>): ModelColumn[] {
   return columns;
 }
 
+/** Columns encrypted by either route — `cast: "encrypted…"` or `static encryptable`. */
+function encryptedColumns(
+  chain: readonly object[],
+  fields: Map<string, ColumnOptions>,
+): Set<string> {
+  const names = new Set<string>();
+  for (const [name, opts] of fields.entries()) {
+    if (isEncryptedCast(opts.cast)) names.add(name);
+  }
+  for (const entry of chain) {
+    for (const key of (entry as { encryptable?: string[] }).encryptable ?? []) names.add(key);
+  }
+  return names;
+}
+
 // ── ModelInspector ────────────────────────────────────────────────────────────
 
 /**
@@ -120,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;
@@ -133,7 +161,7 @@ export const ModelInspector = {
       primaryKey: (M["primaryKey"] as string | undefined) ?? "id",
       timestamps: (M["timestamps"] as boolean | undefined) ?? true,
       softDeletes: (M["softDeletes"] as boolean | undefined) ?? false,
-      columns: toModelColumns(fields),
+      columns: toModelColumns(fields, encryptedColumns(ctorChain(ctor), fields)),
     };
   },
 };

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;
 }