@zerotal/orm 1.3.0 → 1.5.0

package/src/model/BaseModel.ts

@@ -36,9 +36,17 @@ import { installReactiveAccessors, type ColumnOptions } from "./decorators/colum
 import { _compose } from "./mixins.ts";
 import type { Compose } from "./mixins.ts";
 import { columnsFor, relationsFor } from "./decorators/_metadata.ts";
+import {
+  collectEncryptable,
+  decryptColumn,
+  encryptColumn,
+  isEncryptedCast,
+  type EncryptedCastName,
+} from "../casts/encrypted.ts";
 import { TransactionContext } from "../db/TransactionContext.ts";
 import type { InsertPayload, UpdatePayload, FillablePayload } from "./payload.ts";
 import type { WhereOperator, OrderDirection } from "../db/types.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 let _dialect: "sqlite" | "postgres" | "mysql" = "sqlite";
 
@@ -222,18 +230,26 @@ type StringCast =
   | "float"
   | "enum"
   | "immutable_datetime"
+  | EncryptedCastName
   | `decimal:${number}`;
 type CastOption = ColumnOptions["cast"];
 
-function getCasts(ctor: Function): Record<string, CastOption> {
+function getCasts(ctor: ClassRef): Record<string, CastOption> {
   const merged: Record<string, CastOption> = {};
-  const chain: Function[] = [];
-  let current: Function | null = ctor;
+  const chain: ClassRef[] = [];
+  let current: ClassRef | null = ctor;
   while (current && current !== Function.prototype) {
     chain.push(current);
-    current = Object.getPrototypeOf(current) as Function | null;
+    current = Object.getPrototypeOf(current) as ClassRef | null;
   }
   chain.reverse();
+  // `static encryptable` first, so an explicit cast on the same column still wins —
+  // spelling one out is the more specific statement of intent.
+  const colReg = columnsFor(ctor);
+  Object.assign(
+    merged,
+    collectEncryptable(chain, (key) => colReg?.get(key)?.type),
+  );
   for (const entry of chain) {
     const casts = (entry as { casts?: Record<string, CastOption> }).casts;
     if (casts) Object.assign(merged, casts);
@@ -241,8 +257,9 @@ function getCasts(ctor: Function): Record<string, CastOption> {
   return merged;
 }
 
-function applyCastGet(value: unknown, cast: StringCast): unknown {
+function applyCastGet(value: unknown, cast: StringCast, label: string): unknown {
   if (value === null || value === undefined) return value;
+  if (isEncryptedCast(cast)) return decryptColumn(value, cast, label);
   const cstr = cast as unknown as string;
   if (cstr.startsWith("decimal:")) {
     const n = parseInt(cstr.slice(8), 10) || 0;
@@ -294,8 +311,9 @@ function tryParseJson(s: string): unknown {
   }
 }
 
-function applyCastSet(value: unknown, cast: StringCast): unknown {
+function applyCastSet(value: unknown, cast: StringCast, label: string): unknown {
   if (value === null || value === undefined) return value;
+  if (isEncryptedCast(cast)) return encryptColumn(value, cast, label);
   const cstr = cast as unknown as string;
   if (cstr.startsWith("decimal:")) {
     const n = parseInt(cstr.slice(8), 10) || 0;
@@ -362,6 +380,7 @@ function _serializeForWrite(
   val: unknown,
   casts: Record<string, CastOption>,
   colReg: Map<string, ColumnOptions> | null,
+  model?: string,
 ): unknown {
   const colMeta = colReg?.get(key);
   const castOpt = casts[key] ?? colMeta?.cast;
@@ -370,7 +389,7 @@ function _serializeForWrite(
   if (castOpt && typeof castOpt === "object" && castOpt.set) {
     serializedVal = castOpt.set(val);
   } else if (typeof castOpt === "string") {
-    serializedVal = applyCastSet(val, castOpt);
+    serializedVal = applyCastSet(val, castOpt, model ? `${model}.${key}` : key);
   } else if (colType === "boolean" && val !== null && val !== undefined) {
     serializedVal = val ? 1 : 0;
   } else if (colType === "json" && val !== null) {
@@ -408,7 +427,7 @@ type ModelCtor<T extends BaseModel> = typeof BaseModel & { new (): T };
  * (`Roles(Permissions(Base))`), where each relation lives on a different
  * class in the chain.
  */
-function relNames(ctor: Function): Set<string> {
+function relNames(ctor: ClassRef): Set<string> {
   return new Set(relationsFor(ctor).keys());
 }
 
@@ -445,7 +464,7 @@ function* ownDataEntries(
  * (rare edge case: a model with zero @column decorators) so callers can fall back
  * to the old unrestricted behaviour.
  */
-function _allColumnKeys(cls: Function): Set<string> | null {
+function _allColumnKeys(cls: ClassRef): Set<string> | null {
   const cols = columnsFor(cls);
   return cols ? new Set(cols.keys()) : null;
 }
@@ -833,6 +852,42 @@ export class BaseModel {
    */
   static hashable?: string[];
 
+  /**
+   * Columns encrypted at rest with AES-256-GCM under `APP_KEY`, and decrypted
+   * transparently on read. Shorthand for putting `cast: "encrypted"` on each one.
+   *
+   * Unlike {@link hashable} this is reversible and non-destructive: the model
+   * property still holds the value you assigned after a `save()`, because the
+   * encryption happens on the way to the database rather than to the instance.
+   * `$dirty` therefore compares plaintext, and an unchanged column is not
+   * rewritten with a new IV on every save.
+   *
+   * A `json` column in this list encrypts as `encrypted:json`, so it round-trips
+   * as the structure it was rather than as `"[object Object]"`.
+   *
+   * @example
+   * ```ts
+   * class Client extends BaseModel {
+   *   static encryptable = ["idNumber", "passportNumber"];
+   *
+   *   // TEXT, not VARCHAR — a payload outgrows its plaintext.
+   *   @column({ type: "text", nullable: true }) idNumber?: string;
+   *   @column({ type: "text", nullable: true }) passportNumber?: string;
+   * }
+   * ```
+   *
+   * @remarks
+   * Encrypted columns cannot be filtered, grouped or usefully sorted — every
+   * write draws a fresh IV, so the ciphertext for a given value never repeats.
+   * `where()` on one throws rather than quietly matching nothing. For lookup,
+   * keep a hashed blind-index column beside it. Add these to {@link hidden} too
+   * if the model is serialized to a client: decryption puts the real value back
+   * on the instance, and `toJSON()` will happily include it.
+   *
+   * @category Persistence
+   */
+  static encryptable?: string[];
+
   /**
    * Register an observer class for this model.
    * The observer's lifecycle methods (creating, created, updating, …) are
@@ -1470,8 +1525,8 @@ export class BaseModel {
     const ModelClass = this as unknown as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
     const dialect = dialectFor(conn as unknown as object);
-    const casts = getCasts(ModelClass as unknown as Function);
-    const colReg = columnsFor(ModelClass as unknown as Function);
+    const casts = getCasts(ModelClass as unknown as ClassRef);
+    const colReg = columnsFor(ModelClass as unknown as ClassRef);
     const useTs = ModelClass.timestamps;
 
     const rows: Record<string, unknown>[] = _writeDialect.run(dialect, () => {
@@ -1480,7 +1535,7 @@ export class BaseModel {
         const row: Record<string, unknown> = {};
         for (const [key, val] of Object.entries(rec as Record<string, unknown>)) {
           if (key.startsWith("_")) continue;
-          row[toSnake(key)] = _serializeForWrite(key, val, casts, colReg);
+          row[toSnake(key)] = _serializeForWrite(key, val, casts, colReg, ModelClass.name);
         }
         if (useTs) {
           row["created_at"] = now;
@@ -1556,13 +1611,13 @@ export class BaseModel {
   ): Promise<void> {
     const conn = _resolveConn(this);
     const dialect = dialectFor(conn as unknown as object);
-    const casts = getCasts(this as unknown as Function);
-    const colReg = columnsFor(this as unknown as Function);
+    const casts = getCasts(this as unknown as ClassRef);
+    const colReg = columnsFor(this as unknown as ClassRef);
 
     const row: Record<string, unknown> = _writeDialect.run(dialect, () => {
       const r: Record<string, unknown> = {};
       for (const [key, val] of Object.entries(data as Record<string, unknown>)) {
-        r[toSnake(key)] = _serializeForWrite(key, val, casts, colReg);
+        r[toSnake(key)] = _serializeForWrite(key, val, casts, colReg, this.name);
       }
       return r;
     });
@@ -1643,8 +1698,8 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
     const dialect = dialectFor(conn as unknown as object);
-    const rels = relNames(ModelClass as unknown as Function);
-    const casts = getCasts(ModelClass as unknown as Function);
+    const rels = relNames(ModelClass as unknown as ClassRef);
+    const casts = getCasts(ModelClass as unknown as ClassRef);
 
     await HookRegistry.run(ModelClass, "beforeSave", this);
 
@@ -1676,8 +1731,8 @@ export class BaseModel {
       }
     }
 
-    const colReg = columnsFor(ModelClass as unknown as Function);
-    const colKeys = _allColumnKeys(ModelClass as unknown as Function);
+    const colReg = columnsFor(ModelClass as unknown as ClassRef);
+    const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
 
     if (!this._exists) {
       // ── INSERT ──
@@ -1703,7 +1758,7 @@ export class BaseModel {
             // value is readable straight after save() without a reload.
             self[key] = effective;
           }
-          r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg);
+          r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg, ModelClass.name);
         }
         if (ModelClass.timestamps) {
           const now = _serializeDate(new Date());
@@ -1785,7 +1840,11 @@ export class BaseModel {
       if (Object.keys(dirty).length > 0) {
         const entries = _writeDialect.run(dialect, () =>
           Object.entries(dirty).map(
-            ([k, v]) => [toSnake(k), _serializeForWrite(k, v, casts, colReg)] as [string, unknown],
+            ([k, v]) =>
+              [toSnake(k), _serializeForWrite(k, v, casts, colReg, ModelClass.name)] as [
+                string,
+                unknown,
+              ],
           ),
         );
         const segs: Seg[] = [`UPDATE ${ModelClass.table} SET `];
@@ -1937,8 +1996,8 @@ export class BaseModel {
    */
   replicate(except?: string[]): this {
     const ModelClass = this.constructor as typeof BaseModel;
-    const rels = relNames(ModelClass as unknown as Function);
-    const colKeys = _allColumnKeys(ModelClass as unknown as Function);
+    const rels = relNames(ModelClass as unknown as ClassRef);
+    const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
     const skip = new Set<string>([...SYSTEM_KEYS, ...(except ?? [])]);
     const inst = new (this.constructor as new () => this)();
     for (const [k, v] of ownDataEntries(this, skip, rels, colKeys)) {
@@ -2182,7 +2241,7 @@ export class BaseModel {
    * @category Relationships
    */
   associate(relation: string, model: BaseModel): this {
-    const meta = relationsFor(this.constructor).get(relation);
+    const meta = relationsFor(this.constructor as ClassRef).get(relation);
     if (!meta || meta.type !== "belongsTo") {
       throw new Error(
         `associate(): "${relation}" is not a belongsTo relation on ${this.constructor.name}`,
@@ -2209,7 +2268,7 @@ export class BaseModel {
    * @category Relationships
    */
   dissociate(relation: string): this {
-    const meta = relationsFor(this.constructor).get(relation);
+    const meta = relationsFor(this.constructor as ClassRef).get(relation);
     if (!meta || meta.type !== "belongsTo") {
       throw new Error(
         `dissociate(): "${relation}" is not a belongsTo relation on ${this.constructor.name}`,
@@ -2249,8 +2308,8 @@ export class BaseModel {
    */
   $dirty(): Record<string, unknown> {
     const ModelClass = this.constructor as typeof BaseModel;
-    const rels = relNames(ModelClass as unknown as Function);
-    const colKeys = _allColumnKeys(ModelClass as unknown as Function);
+    const rels = relNames(ModelClass as unknown as ClassRef);
+    const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
     const out: Record<string, unknown> = {};
     for (const [key, val] of ownDataEntries(this, SYSTEM_KEYS, rels, colKeys)) {
       if (val !== this._original[key] || this._forcedDirty.has(key)) {
@@ -2441,8 +2500,8 @@ function _createLazyPivotProxy(
 function _applyRow(inst: BaseModel, row: Record<string, unknown>): void {
   const self = inst as unknown as Record<string, unknown>;
   const orig: Record<string, unknown> = {};
-  const ctor = inst.constructor;
-  const ModelClass = ctor as typeof BaseModel;
+  const ModelClass = inst.constructor as typeof BaseModel;
+  const ctor: ClassRef = ModelClass;
   const colReg = columnsFor(ctor);
   installReactiveAccessors(inst); // json/array reactiveCasts accessors (registered at decoration)
   const casts = getCasts(ctor);
@@ -2467,7 +2526,7 @@ function _applyRow(inst: BaseModel, row: Record<string, unknown>): void {
       finalVal = castObj.get(rawVal);
     } else if (typeof cast === "string") {
       // Explicit shorthand cast ('boolean', 'json', 'date', etc.)
-      finalVal = applyCastGet(rawVal, cast);
+      finalVal = applyCastGet(rawVal, cast, `${ModelClass.name}.${propKey}`);
     } else if (colType === "boolean" && rawVal !== null && rawVal !== undefined) {
       // Auto-cast based on @column({ type: 'boolean' }) — SQLite stores 0/1
       finalVal = rawVal === 1 || rawVal === "1" || rawVal === true;

package/src/model/ModelQueryBuilder.ts

@@ -6,6 +6,7 @@ import {
   toSnakeColumn as _toSnakeColumn,
   ctorChain,
 } from "../support/identifiers.ts";
+import { collectEncryptable, encryptedQueryError, isEncryptedCast } from "../casts/encrypted.ts";
 import type {
   PaginateResult,
   SimplePaginateResult,
@@ -21,12 +22,21 @@ import type { BaseModel } from "./BaseModel.ts";
 import { type ColumnOptions } from "./decorators/column.ts";
 import { columnsFor, relationsFor } from "./decorators/_metadata.ts";
 import { currentOrmContext } from "./OrmContext.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 type StringCast = "datetime" | "array" | "json" | "date" | "boolean" | "integer" | "float";
 type CastOption = ColumnOptions["cast"];
 
-function _getCasts(ctor: Function): Record<string, CastOption> {
+function _getCasts(ctor: ClassRef): Record<string, CastOption> {
   const merged: Record<string, CastOption> = {};
+  const colReg = columnsFor(ctor);
+  // Mirrors getCasts() in BaseModel: `static encryptable` resolves to casts, and an
+  // explicit cast on the same column wins. Without this the guard below cannot see
+  // a column declared encrypted through the list form.
+  Object.assign(
+    merged,
+    collectEncryptable(ctorChain(ctor), (key) => colReg?.get(key)?.type),
+  );
   for (const entry of ctorChain(ctor)) {
     const casts = (entry as { casts?: Record<string, CastOption> }).casts;
     if (casts) Object.assign(merged, casts);
@@ -265,9 +275,9 @@ function _createPivotCollection<T extends BaseModel>(
 // BaseModel as a type only — no cycle.
 
 export type GlobalScopeCallback = (qb: ModelQueryBuilder<BaseModel>) => void;
-export function _globalScopeRegistry(): Map<Function, Map<string, GlobalScopeCallback>> {
+export function _globalScopeRegistry(): Map<ClassRef, Map<string, GlobalScopeCallback>> {
   return currentOrmContext().globalScopes as unknown as Map<
-    Function,
+    ClassRef,
     Map<string, GlobalScopeCallback>
   >;
 }
@@ -1133,15 +1143,14 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   withScopes(callback: (scopes: any) => void): this {
     const ModelClass = this._ModelClass;
-    const self = this;
     const proxy = new Proxy({} as Record<string, (...args: unknown[]) => void>, {
-      get(_target, prop: string | symbol) {
+      get: (_target, prop: string | symbol) => {
         return (...args: unknown[]) => {
           const fn = (ModelClass as unknown as Record<string | symbol, unknown>)[prop];
           if (typeof fn !== "function") return;
           const result = fn(...args) as { apply?: (q: unknown) => void } | null | undefined;
           if (result != null && typeof result.apply === "function") {
-            result.apply(self);
+            result.apply(this);
           }
         };
       },
@@ -1240,11 +1249,20 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
 
     const rawKey = column.split(".").pop() ?? column;
     const camelKey = rawKey.includes("_") ? _toCamel(rawKey) : rawKey;
-    const casts = _getCasts(this._ModelClass as unknown as Function);
-    const colMeta = columnsFor(this._ModelClass as unknown as Function)?.get(camelKey);
+    const casts = _getCasts(this._ModelClass as unknown as ClassRef);
+    const colMeta = columnsFor(this._ModelClass as unknown as ClassRef)?.get(camelKey);
     const castOpt = casts[rawKey] ?? casts[camelKey] ?? colMeta?.cast;
     const colType = colMeta?.type;
 
+    // Before anything binds: an encrypted column cannot be compared. Running the
+    // cast's set() here would encrypt the search term under a fresh IV, producing
+    // ciphertext that cannot equal what is stored — a query that always returns
+    // nothing and never says why. Same failure the created_at note below describes,
+    // and permanent rather than occasional, so it is refused outright.
+    if (isEncryptedCast(castOpt)) {
+      throw encryptedQueryError(`${this._ModelClass.name}.${camelKey}`);
+    }
+
     if (operator === "in" || operator === "not in") {
       if (Array.isArray(value)) {
         return value.map((v) => this._coerceWhereValue(column, v));
@@ -1306,9 +1324,9 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
       if (spec.children.length > 0 && related.length > 0) {
         if (meta.type === "morphTo") {
           // Mixed related classes — group by constructor and recurse per group.
-          const groups = new Map<Function, BaseModel[]>();
+          const groups = new Map<ClassRef, BaseModel[]>();
           for (const r of related) {
-            const ctor = r.constructor as Function;
+            const ctor = r.constructor as ClassRef;
             if (!groups.has(ctor)) groups.set(ctor, []);
             groups.get(ctor)!.push(r);
           }

package/src/model/Observer.ts

@@ -1,4 +1,5 @@
 import { HookRegistry, type HookName } from "./hooks/HookRegistry.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 /**
  * Observer interface — implement any subset of lifecycle methods to react to a
@@ -61,7 +62,7 @@ const _methodToHook: Record<keyof ModelObserver, HookName> = {
  * @param ObserverClass - An observer class (zero-arg constructor) implementing any subset of {@link ModelObserver}.
  * @internal
  */
-export function registerObserver<T>(ModelClass: Function, ObserverClass: ObserverClass<T>): void {
+export function registerObserver<T>(ModelClass: ClassRef, ObserverClass: ObserverClass<T>): void {
   const instance = new ObserverClass();
 
   for (const [method, hook] of Object.entries(_methodToHook) as [keyof ModelObserver, HookName][]) {

package/src/model/OrmContext.ts

@@ -25,11 +25,11 @@ export class OrmContext {
   /** Connections registered by name, selectable via `static connection`. */
   namedConnections = new Map<string, SQLInstance>();
   /** Per-model `onTransition` callbacks, keyed by target state (see the `State` mixin). */
-  transitionCallbacks = new Map<Function, Map<string, unknown[]>>();
+  transitionCallbacks = new Map<ClassRef, Map<string, unknown[]>>();
   /** Per-model registered global query scopes. */
-  globalScopes = new Map<Function, Map<string, unknown>>();
+  globalScopes = new Map<ClassRef, Map<string, unknown>>();
   /** Per-model lifecycle hooks. */
-  hooks = new Map<Function, Map<string, unknown[]>>();
+  hooks = new Map<ClassRef, Map<string, unknown[]>>();
 }
 
 let _ctx = new OrmContext();
@@ -58,6 +58,7 @@ export function resetOrmContext(): void {
 }
 
 import { registerAppScope } from "@zerotal/core";
+import type { ClassRef } from "../support/classRef.ts";
 
 let _appScopeRegistered = false;
 if (!_appScopeRegistered) {

package/src/model/State.ts

@@ -22,6 +22,7 @@
 import { StateError } from "../errors/index.ts";
 import { currentOrmContext } from "./OrmContext.ts";
 import type { Constructor } from "./mixins.ts";
+import type { ClassRef } from "../support/classRef.ts";
 
 // ── Types ─────────────────────────────────────────────────────────────────────
 
@@ -87,7 +88,7 @@ export type TransitionCallback<T> = (
 // ── Callback registry (execution-scoped on the OrmContext) ────────────────────
 
 /** @internal Register or retrieve transition callbacks for a model class. */
-function _getCallbacks(ModelClass: Function, state: string): TransitionCallback<unknown>[] {
+function _getCallbacks(ModelClass: ClassRef, state: string): TransitionCallback<unknown>[] {
   const reg = currentOrmContext().transitionCallbacks;
   if (!reg.has(ModelClass)) reg.set(ModelClass, new Map());
   const map = reg.get(ModelClass)!;
@@ -169,7 +170,7 @@ export function State<TBase extends Constructor>(Base: TBase) {
       toState: string,
       callback: TransitionCallback<T>,
     ): void {
-      _getCallbacks(this as unknown as Function, toState).push(
+      _getCallbacks(this as unknown as ClassRef, toState).push(
         callback as TransitionCallback<unknown>,
       );
     }
@@ -260,7 +261,7 @@ export function State<TBase extends Constructor>(Base: TBase) {
       await (this as unknown as { save(): Promise<unknown> }).save();
 
       // Fire registered transition callbacks.
-      const map = currentOrmContext().transitionCallbacks.get(this.constructor as Function);
+      const map = currentOrmContext().transitionCallbacks.get(this.constructor as ClassRef);
       const meta = { from: currentState, to: newState };
       const toFns = (map?.get(newState) ?? []) as TransitionCallback<unknown>[];
       const anyFns = (map?.get("*") ?? []) as TransitionCallback<unknown>[];

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