@zerotal/orm 1.3.0 → 1.5.0

package/src/commands/_runSeeders.ts

@@ -0,0 +1,71 @@
+import type { Seeder } from "../seeding/Seeder.ts";
+
+/**
+ * What running the app's seeders came to.
+ *
+ * Seeding is reported rather than thrown because two commands consume it and
+ * they want different things from a failure: `db:seed` has nothing else to do
+ * and simply reports, while `migrate:fresh --seed` has already rebuilt the
+ * schema by the time seeding runs and must not present that work as undone.
+ */
+export type SeedOutcome =
+  | { status: "seeded" }
+  /** No seeder file exists. `path` is where one was looked for. */
+  | { status: "missing"; path: string }
+  /** A seeder file exists but does not export what it should. */
+  | { status: "invalid"; message: string }
+  /** The seeder ran and threw. */
+  | { status: "failed"; message: string };
+
+/**
+ * Run the application's database seeders.
+ *
+ * Prefers the class-based `database/seeders/DatabaseSeeder.ts`, falling back to
+ * a legacy `database/seeders/index.ts` exporting a default async function.
+ *
+ * @param cwd Project root to resolve `database/seeders/` against.
+ *
+ * @internal
+ */
+export async function runSeeders(cwd: string = process.cwd()): Promise<SeedOutcome> {
+  const seederPath = `${cwd}/database/seeders/DatabaseSeeder.ts`;
+
+  if (!(await Bun.file(seederPath).exists())) {
+    const legacyPath = `${cwd}/database/seeders/index.ts`;
+    if (!(await Bun.file(legacyPath).exists())) {
+      return { status: "missing", path: seederPath };
+    }
+
+    try {
+      const module = (await import(legacyPath)) as { default?: () => Promise<void> };
+      const seed = module.default;
+      if (!seed) {
+        return { status: "invalid", message: "Seeder index must export a default async function." };
+      }
+      await seed();
+      return { status: "seeded" };
+    } catch (error) {
+      return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  try {
+    const module = (await import(seederPath)) as {
+      DatabaseSeeder?: new () => Seeder;
+      default?: new () => Seeder;
+    };
+    const SeederClass = module.DatabaseSeeder ?? module.default;
+
+    if (!SeederClass) {
+      return {
+        status: "invalid",
+        message: "DatabaseSeeder not found as a named or default export.",
+      };
+    }
+
+    await new SeederClass().run();
+    return { status: "seeded" };
+  } catch (error) {
+    return { status: "failed", message: error instanceof Error ? error.message : String(error) };
+  }
+}

package/src/commands/index.ts

@@ -22,6 +22,7 @@ export { MigrateCommand } from "./MigrateCommand.ts";
 export { MigrateRollbackCommand } from "./MigrateRollbackCommand.ts";
 export { MigrateStatusCommand } from "./MigrateStatusCommand.ts";
 export { MigrateFreshCommand } from "./MigrateFreshCommand.ts";
+export { MigrateRefreshCommand } from "./MigrateRefreshCommand.ts";
 export { MakeMigrationCommand } from "./MakeMigrationCommand.ts";
 export { MigrateGenerateCommand } from "./MigrateGenerateCommand.ts";
 export { MakeModelCommand } from "./MakeModelCommand.ts";

package/src/conventions.ts

@@ -3,6 +3,7 @@ import { tableNameFor } from "@zerotal/core";
 import { BaseModel } from "./model/BaseModel.ts";
 import { registerModel, modelByName } from "./model/decorators/_metadata.ts";
 import { frameworkLog } from "@zerotal/core/logger";
+import type { ClassRef } from "./support/classRef.ts";
 
 function isModelClass(v: unknown): boolean {
   return (
@@ -26,7 +27,7 @@ export const modelsConcern: ConcernDescriptor = {
     for (const exported of Object.values(mod)) {
       if (!isModelClass(exported)) continue;
       const Model = exported as unknown as { name: string; table?: string };
-      registerModel(Model as unknown as Function);
+      registerModel(Model as unknown as ClassRef);
       // Convention table name — explicit @table / static table always wins.
       if (!Model.table) Model.table = tableNameFor(Model.name);
     }

package/src/db/NPlusOneDetector.ts

@@ -25,15 +25,36 @@ import { NPlusOneDetected } from "../events.ts";
 export class NPlusOneError extends ZerotalError {
   readonly fingerprint: string;
   readonly count: number;
+  /**
+   * How many distinct argument tuples the shape ran with.
+   *
+   * The difference between the two diagnoses. `1` means the same query with the
+   * same arguments ran N times — nothing to eager-load, the answer is to ask
+   * once. Anything higher is the classic per-row lookup.
+   */
+  readonly distinctArgs: number;
+
+  constructor(fingerprint: string, count: number, distinctArgs = 0) {
+    const sql = fingerprint.replaceAll("\x00", "?");
+    // Sending someone to look for a relation to eager-load, when the query is
+    // the *same* one repeated with the *same* arguments, wastes the time the
+    // warning was supposed to save. Say which of the two this is.
+    const diagnosis =
+      distinctArgs === 1
+        ? `with the same arguments every time. That is not a per-row lookup — nothing to\n` +
+          `eager-load — it is the same answer fetched repeatedly.\n\n` +
+          `Fix: ask once per request.\n` +
+          `  const rows = await RequestContext.remember('key', () => …);\n`
+        : `with ${distinctArgs > 0 ? `${distinctArgs} different argument sets` : "varying arguments"}. ` +
+          `This is the classic N+1 access pattern.\n\n` +
+          `Fix: load the relation eagerly using .with('relation') on your query,\n` +
+          `call await model.load('relation') before the loop, or collapse the loop\n` +
+          `into a single .whereIn(...).\n`;
 
-  constructor(fingerprint: string, count: number) {
-    const sql = fingerprint.replace(/\x00/g, "?");
     super(
       `NPlusOneError: The query\n\n` +
         `  ${sql}\n\n` +
-        `was executed ${count} times in a single request. This is an N+1 query.\n\n` +
-        `Fix: load the relation eagerly using .with('relation') on your query,\n` +
-        `or call await model.load('relation') before the loop.\n\n` +
+        `was executed ${count} times in a single request, ${diagnosis}\n` +
         `To suppress for a specific table or pattern:\n` +
         `  DB.allowNPlusOne('table_name')           // permanent\n` +
         `  DB.allowNPlusOne('table_name', { once: true })  // this request only\n\n` +
@@ -43,13 +64,30 @@ export class NPlusOneError extends ZerotalError {
     );
     this.fingerprint = fingerprint;
     this.count = count;
+    this.distinctArgs = distinctArgs;
   }
 }
 
 // ── State ─────────────────────────────────────────────────────────────────────
 
-/** Per-request query-shape hit counts. Keyed by the HttpContext object. */
-const _counts = new WeakMap<object, Map<string, number>>();
+/** What one query shape did during one request. */
+interface ShapeStats {
+  count: number;
+  /**
+   * Distinct argument tuples seen, capped.
+   *
+   * Capped because a genuine 500-iteration loop would otherwise hold 500 keys
+   * for the life of the request to answer a question — "is this one argument or
+   * many?" — that a handful already settles.
+   */
+  args: Set<string>;
+}
+
+/** How many distinct argument tuples to remember per shape before giving up counting. */
+const _ARG_SAMPLE_CAP = 32;
+
+/** Per-request query-shape stats. Keyed by the HttpContext object. */
+const _counts = new WeakMap<object, Map<string, ShapeStats>>();
 
 /** Once-per-request suppressions. Cleared automatically when the context is GC'd. */
 const _onceSuppressed = new WeakMap<object, Set<string>>();
@@ -126,8 +164,18 @@ export function _resetNPlusOne(): void {
 
 // ── Core tracking ─────────────────────────────────────────────────────────────
 
-/** @internal — called by QueryBuilder._run() on every query execution. */
-export function trackQuery(ctx: object | null | undefined, fingerprint: string): void {
+/**
+ * @internal — called by QueryBuilder._run() on every query execution.
+ *
+ * @param values - The bound parameters. Optional so older call sites still
+ *   compile; without them the detector cannot tell a per-row lookup from the
+ *   same read repeated, and says so less precisely.
+ */
+export function trackQuery(
+  ctx: object | null | undefined,
+  fingerprint: string,
+  values?: readonly unknown[],
+): void {
   if (!ctx) return;
 
   // Honour explicit opt-in or auto-enable in local/development only
@@ -158,15 +206,19 @@ export function trackQuery(ctx: object | null | undefined, fingerprint: string):
   // Count this fingerprint for the current request
   if (!_counts.has(ctx)) _counts.set(ctx, new Map());
   const map = _counts.get(ctx)!;
-  const count = (map.get(fingerprint) ?? 0) + 1;
-  map.set(fingerprint, count);
+  const stats = map.get(fingerprint) ?? { count: 0, args: new Set<string>() };
+  stats.count++;
+  if (values !== undefined && stats.args.size < _ARG_SAMPLE_CAP) {
+    stats.args.add(_argKey(values));
+  }
+  map.set(fingerprint, stats);
 
-  if (count >= _threshold) {
+  if (stats.count >= _threshold) {
     // Only fire once (at exactly the threshold), not on every subsequent hit
-    if (count > _threshold) return;
+    if (stats.count > _threshold) return;
 
-    const err = new NPlusOneError(fingerprint, count);
-    FrameworkEvents.emit(new NPlusOneDetected(fingerprint, count, ctx ?? undefined));
+    const err = new NPlusOneError(fingerprint, stats.count, stats.args.size);
+    FrameworkEvents.emit(new NPlusOneDetected(fingerprint, stats.count, ctx ?? undefined));
     if (_mode === "throw") {
       throw err;
     } else {
@@ -174,3 +226,29 @@ export function trackQuery(ctx: object | null | undefined, fingerprint: string):
     }
   }
 }
+
+/**
+ * A comparable key for one call's bound parameters.
+ *
+ * Only ever compared against other keys for the same SQL shape, so it needs to
+ * separate arguments rather than describe them. A value JSON cannot represent
+ * degrades to its `String()` form, which is enough to tell two calls apart.
+ */
+function _argKey(values: readonly unknown[]): string {
+  let key = "";
+  for (const value of values) {
+    if (value instanceof Date) key += `d${value.getTime()}|`;
+    else if (value === null || value === undefined) key += "∅|";
+    else if (typeof value === "object") key += `${_safeJson(value)}|`;
+    else key += `${String(value)}|`;
+  }
+  return key;
+}
+
+function _safeJson(value: object): string {
+  try {
+    return JSON.stringify(value) ?? "?";
+  } catch {
+    return "?";
+  }
+}

package/src/db/QueryBuilder.ts

@@ -216,6 +216,32 @@ function _getCachedTemplate(strings: string[]): TemplateStringsArray {
   return tpl;
 }
 
+/**
+ * Turn a JS value into something the driver can actually bind.
+ *
+ * Only dates need this, and they need it badly. A `Date` handed to Bun's SQLite
+ * driver as a bind parameter does not land: `update({ read_at: new Date() })`
+ * left the column NULL and **reported no error**, so a "mark all as read"
+ * feature shipped as a latent no-op that read correctly in the source. The
+ * asymmetry made it easy to write, too — `model.save()` applies casts, so the
+ * identical value through a model worked.
+ *
+ * The comparison path already learned this (see `ModelQueryBuilder._bindValue`:
+ * a `Date` in a `where` used to match zero rows). Doing it here covers every
+ * bind on every builder — `DB.table()` writes included — from one place, so the
+ * next path someone adds cannot reintroduce it.
+ *
+ * Dialect-aware because MySQL DATETIME rejects ISO 8601's `T`/`Z`; SQLite and
+ * PostgreSQL take it as-is.
+ */
+function _bindable(value: unknown, dialect: Dialect): unknown {
+  const date = value instanceof Carbon ? value.toDate() : value;
+  if (!(date instanceof Date)) return value;
+  return dialect === "mysql"
+    ? date.toISOString().replace("T", " ").slice(0, 19)
+    : date.toISOString();
+}
+
 /**
  * @internal Execute compiled segments on `conn` with prepared-template
  * interning and QueryExecuted telemetry. Shared by `QueryBuilder._run` and
@@ -230,6 +256,7 @@ export async function _runSegments<T = Record<string, unknown>>(
   const strings: string[] = [];
   const values: unknown[] = [];
   let current = "";
+  const dialect = dialectFor(conn);
 
   for (const seg of segs) {
     if (typeof seg === "string") {
@@ -237,7 +264,7 @@ export async function _runSegments<T = Record<string, unknown>>(
     } else {
       strings.push(current);
       current = "";
-      values.push(seg.val);
+      values.push(_bindable(seg.val, dialect));
     }
   }
   strings.push(current);
@@ -245,14 +272,18 @@ export async function _runSegments<T = Record<string, unknown>>(
   const cacheKey = strings.join("\x00");
   const tpl = _getCachedTemplate(strings);
   const ctx = RequestContext.tryGet();
-  if (trackNPlusOne) trackQuery(ctx, cacheKey);
+  // Bindings go through too: without them the detector groups a six-month
+  // reporting loop — identical SQL, a different `period` each time — with a
+  // genuine per-row lookup, and sends you hunting for a relation to eager-load
+  // that does not exist.
+  if (trackNPlusOne) trackQuery(ctx, cacheKey, values);
 
   const startMs = Date.now();
   const rows = await conn<T>(tpl, ...values);
   const durationMs = Date.now() - startMs;
   FrameworkEvents.emit(
     new QueryExecuted(
-      cacheKey.replace(/\x00/g, "?"),
+      cacheKey.replaceAll("\x00", "?"),
       values,
       startMs,
       durationMs,

package/src/diagnostics/missingRelation.ts

@@ -0,0 +1,187 @@
+/**
+ * "no such table: assets", answered.
+ *
+ * The message is exact and the stack is useless — every frame is inside the SQL
+ * driver, because that is where the failure surfaces, not where it comes from.
+ * The answer is almost always "you have migrations you have not run", and that
+ * lives here, one package away from the error page that needs it.
+ *
+ * The half that earns this feature is refusing to offer the button when it would
+ * not help. There are two situations and they need different answers: a table
+ * missing because a migration is pending, and a table missing because nobody ever
+ * wrote one. Running every pending migration in the second case changes nothing,
+ * leaves the developer where they started, and teaches them not to trust the
+ * panel.
+ */
+import type { ErrorDiagnosis } from "@zerotal/core";
+import { loadMigrations } from "../commands/_loadMigrations.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+
+/** What the database said is missing. */
+export interface MissingRelation {
+  kind: "table" | "column";
+  name: string;
+}
+
+/** Dialect error codes, checked before the message text. */
+const CODES: Record<string, MissingRelation["kind"]> = {
+  // PostgreSQL SQLSTATE
+  "42P01": "table", // undefined_table
+  "42703": "column", // undefined_column
+  // MySQL
+  "1146": "table", // ER_NO_SUCH_TABLE
+  "1054": "column", // ER_BAD_FIELD_ERROR
+  ER_NO_SUCH_TABLE: "table",
+  ER_BAD_FIELD_ERROR: "column",
+};
+
+/**
+ * Message shapes, as a fallback.
+ *
+ * SQLite has no error code worth branching on — everything arrives as
+ * `SQLITE_ERROR` — so its two messages are matched directly. Postgres and MySQL
+ * are matched by code above; their text is included because a driver that wraps
+ * the error can drop the code while keeping the message.
+ */
+const PATTERNS: Array<{ re: RegExp; kind: MissingRelation["kind"] }> = [
+  // Each captures the whole identifier — quotes, schema qualifier and all — and
+  // leaves the tidying to `bareName`. Capturing only the last segment needs a
+  // lazy qualifier prefix, and getting that subtly wrong is how `app.assets`
+  // came back as an empty name.
+  { re: /no such table:\s*([\w".`]+)/i, kind: "table" },
+  { re: /no such column:\s*([\w".`]+)/i, kind: "column" },
+  { re: /relation\s+([\w".]+)\s+does not exist/i, kind: "table" },
+  { re: /column\s+([\w".]+)\s+does not exist/i, kind: "column" },
+  { re: /table\s+'([\w.]+)'\s+doesn'?t exist/i, kind: "table" },
+  { re: /unknown column\s+'([\w.]+)'/i, kind: "column" },
+];
+
+/** Strip a qualifier and quoting: `"public"."assets"` → `assets`. */
+function bareName(raw: string): string {
+  const parts = raw.replace(/["`']/g, "").split(".");
+  return parts[parts.length - 1] ?? raw;
+}
+
+/**
+ * Whether this error is a database complaining about something that is not there.
+ *
+ * Returns `null` for everything else, including every other database error — a
+ * diagnoser that recognises errors it does not own is worse than none.
+ */
+export function detectMissingRelation(error: Error): MissingRelation | null {
+  const message = error.message ?? "";
+
+  // Code first: it is unambiguous where it exists, and message text is localised
+  // on some MySQL builds.
+  const code = (error as { code?: string | number; errno?: number }).code;
+  const errno = (error as { errno?: number }).errno;
+  const kindFromCode = CODES[String(code)] ?? CODES[String(errno)];
+
+  for (const { re, kind } of PATTERNS) {
+    const match = re.exec(message);
+    if (match?.[1]) return { kind: kindFromCode ?? kind, name: bareName(match[1]) };
+  }
+
+  // A recognised code with an unrecognised message still tells us the kind, but
+  // not the name — worth reporting, because "some table is missing" plus the
+  // pending list is still the answer.
+  if (kindFromCode) return { kind: kindFromCode, name: "" };
+  return null;
+}
+
+/** Migrations that exist on disk and have not run. */
+export async function pendingMigrations(): Promise<string[]> {
+  const records = await loadMigrations();
+  if (records.length === 0) return [];
+  const entries: MigrationEntry[] = records.map((r) => ({ name: r.name, migration: r.instance }));
+  const runner = new MigrationRunner({ connection: _getConnection() });
+  const statuses = await runner.status(entries);
+  return statuses.filter((s) => !s.ran).map((s) => s.name);
+}
+
+/**
+ * Does any migration on disk so much as mention this name?
+ *
+ * A weak signal used only to sharpen the message in the nothing-pending case:
+ * "no migration mentions `assets`" is a better sentence than anything generic,
+ * and it is usually right, because a migration that creates a table names it.
+ */
+async function anyMigrationMentions(name: string): Promise<boolean> {
+  if (name === "") return false;
+  const glob = new Bun.Glob("database/migrations/*.ts");
+  for await (const file of glob.scan({ cwd: process.cwd() })) {
+    try {
+      const source = await Bun.file(file).text();
+      if (source.includes(name)) return true;
+    } catch {
+      // Unreadable file — treat as no evidence rather than failing the diagnosis.
+    }
+  }
+  return false;
+}
+
+/**
+ * Build the diagnosis, given a token minter for the action.
+ *
+ * `mintToken` is passed in rather than imported so this stays testable without a
+ * running server, and so the endpoint owns its own token lifetime.
+ */
+export async function diagnoseMissingRelation(
+  error: Error,
+  options: { endpoint: string; mintToken: () => string },
+): Promise<ErrorDiagnosis | null> {
+  const missing = detectMissingRelation(error);
+  if (!missing) return null;
+
+  const subject = missing.name === "" ? `A ${missing.kind}` : `${missing.kind} \`${missing.name}\``;
+
+  let pending: string[];
+  try {
+    pending = await pendingMigrations();
+  } catch {
+    // No connection, no migrations directory, a driver that cannot answer — the
+    // detection still stands, so say what is missing without guessing why.
+    return {
+      title: `${subject} does not exist.`,
+      detail:
+        "The migration state could not be read, so this cannot say whether a pending " +
+        "migration would create it. Run `bun zt migrate:status` to see where things stand.",
+    };
+  }
+
+  if (pending.length > 0) {
+    return {
+      title: `${subject} does not exist, and ${pending.length} migration${
+        pending.length === 1 ? " has" : "s have"
+      } not run.`,
+      detail:
+        "Running them is very likely the fix. This runs the same migrations " +
+        "`bun zt migrate` would, in the same order, against the same connection — " +
+        "and it is available here only because the app is in development.",
+      items: pending,
+      action: {
+        label: `Run ${pending.length} migration${pending.length === 1 ? "" : "s"}`,
+        url: options.endpoint,
+        token: options.mintToken(),
+        pendingLabel: "Migrating…",
+      },
+    };
+  }
+
+  // Nothing pending. Deliberately no button: it would run nothing and change
+  // nothing, and the developer would be back here having been told to try.
+  const mentioned = await anyMigrationMentions(missing.name);
+  return {
+    title: `${subject} does not exist, and every migration has already run.`,
+    detail: mentioned
+      ? `A migration does mention \`${missing.name}\`, so this is more likely a rollback ` +
+        `that left the schema behind, or a migration that did not create what its name ` +
+        `suggests. \`bun zt migrate:status\` shows what ran, and \`migrate:refresh\` ` +
+        `rebuilds from scratch — it will destroy the data in this database.`
+      : `No migration in \`database/migrations\` mentions \`${missing.name}\`, which usually ` +
+        `means the migration that would create it was never written. \`bun zt make:migration\` ` +
+        `scaffolds one.`,
+  };
+}

package/src/diagnostics/runMigrationsEndpoint.ts

@@ -0,0 +1,124 @@
+/**
+ * The endpoint behind the error page's "Run migrations" button.
+ *
+ * This mutates a database in response to a request originating from a page that
+ * was rendered by a GET, which is a shape worth being paranoid about: a dev
+ * server on `localhost:3000` is reachable by any site the developer has open in
+ * another tab, and "run every pending migration" is not something a random page
+ * should be able to trigger.
+ *
+ * So it carries three independent guards, and each is checked here rather than
+ * inferred from the fact that the overlay is dev-only:
+ *
+ * 1. **`devSurfacesEnabled()`**, decided at request time. Note this is not
+ *    `!isProdLike(...)`: `isProdLike("")` is false, so an unset `APP_ENV` would
+ *    have *passed* that check. This one fails closed — only an explicitly
+ *    non-production environment, or a process the dev orchestrator supervises,
+ *    qualifies. It also reads the right thing: `setAppEnv()` overwrites
+ *    `APP_ENV` with a runtime mode before boot, so reading it directly is wrong.
+ * 2. **A single-use token**, minted per error page and spent on first use. This
+ *    is what a cross-origin caller cannot obtain: it would have to read the
+ *    page, and the same-origin policy stops it.
+ * 3. **The origin guard**, the same one the raw Flow endpoints use — because
+ *    this is registered as a raw route and so sits outside the CSRF middleware.
+ *
+ * The route is registered only when dev surfaces are enabled, so in production it
+ * does not exist at all. Guard 1 is the belt to that braces.
+ */
+import { Router, devSurfacesEnabled } from "@zerotal/core";
+import { isAllowedOrigin } from "@zerotal/core/http";
+import { loadMigrations } from "../commands/_loadMigrations.ts";
+import { MigrationRunner } from "../schema/MigrationRunner.ts";
+import type { MigrationEntry } from "../schema/MigrationRunner.ts";
+import { _getConnection } from "../db/DB.ts";
+
+/** Path the button posts to. */
+export const RUN_MIGRATIONS_PATH = "/__zerotal/run-migrations";
+/** Header carrying the single-use token. */
+const TOKEN_HEADER = "X-Zerotal-Diagnosis-Token";
+
+/**
+ * Outstanding tokens.
+ *
+ * In memory and per process, which is right: a token is only ever handed to the
+ * page this process just rendered, and a restart invalidating them is correct
+ * rather than inconvenient — the page is stale by then anyway.
+ */
+const _tokens = new Set<string>();
+/** Tokens outlive one render but not a session; a bounded set cannot grow without limit. */
+const MAX_TOKENS = 32;
+
+/** Mint a token for one error page. @internal */
+export function _mintDiagnosisToken(): string {
+  // The oldest token is dropped rather than letting a long dev session
+  // accumulate them. Insertion order is iteration order for a Set.
+  if (_tokens.size >= MAX_TOKENS) {
+    const oldest = _tokens.values().next().value;
+    if (oldest !== undefined) _tokens.delete(oldest);
+  }
+  const token = crypto.randomUUID();
+  _tokens.add(token);
+  return token;
+}
+
+/** Spend a token. Returns false when it was never minted, or was already used. @internal */
+export function _spendDiagnosisToken(token: string | null): boolean {
+  if (!token) return false;
+  return _tokens.delete(token);
+}
+
+/** Forget every outstanding token. Tests. @internal */
+export function _resetDiagnosisTokens(): void {
+  _tokens.clear();
+}
+
+/**
+ * Run every pending migration, and report what ran.
+ *
+ * Separated from the route so a test can drive it without a server.
+ */
+export async function _runPendingMigrations(): Promise<string[]> {
+  const records = await loadMigrations();
+  const entries: MigrationEntry[] = records.map((r) => ({ name: r.name, migration: r.instance }));
+  const runner = new MigrationRunner({ connection: _getConnection() });
+  return runner.run(entries);
+}
+
+/**
+ * Register the endpoint, unless this is production.
+ *
+ * Called from `DatabaseProvider.onRegister()`.
+ */
+export function registerRunMigrationsEndpoint(allowedOrigins: () => string[]): void {
+  if (!devSurfacesEnabled()) return;
+
+  Router.raw("POST", RUN_MIGRATIONS_PATH, async (req: Request): Promise<Response> => {
+    // Guard 1 — re-checked at request time, not inherited from registration.
+    if (!devSurfacesEnabled()) {
+      return new Response("Not available.", { status: 404 });
+    }
+
+    // Guard 2 — a raw route bypasses the middleware pipeline, so CSRF protection
+    // does not apply and this is the check standing in for it.
+    if (!isAllowedOrigin(req, allowedOrigins())) {
+      return new Response("Forbidden origin.", { status: 403 });
+    }
+
+    // Guard 3 — single use. A caller that cannot read the error page cannot have
+    // this, and replaying a captured one does not work twice.
+    if (!_spendDiagnosisToken(req.headers.get(TOKEN_HEADER))) {
+      return new Response("Invalid or already-used token.", { status: 403 });
+    }
+
+    try {
+      const ran = await _runPendingMigrations();
+      if (ran.length === 0) return new Response("Nothing to run.", { status: 200 });
+      return new Response(`Ran ${ran.length}: ${ran.join(", ")}`, { status: 200 });
+    } catch (error) {
+      // The migration itself failed — which is a real answer, and more useful
+      // than a generic 500. It goes back as text so the panel can show it.
+      const message = error instanceof Error ? error.message : String(error);
+      return new Response(`Migration failed: ${message}`, { status: 500 });
+    }
+  });
+}

package/src/index.ts

@@ -75,6 +75,9 @@ export { Model, BaseModel } from "./model/BaseModel.ts";
 // Mixin authoring types. Compose them onto a model with the `Model.using(...)` static —
 // `class User extends Model.using(Authenticatable, Roles)`.
 export type { Constructor, Mixin, Compose } from "./model/mixins.ts";
+// The type every metadata registry keys on — a model class rather than an instance.
+// Packages that register columns or relations from outside the ORM take it as a parameter.
+export type { ClassRef } from "./support/classRef.ts";
 // State-machine behaviour is an opt-in mixin — compose with `Model.using(State)`.
 export { State } from "./model/State.ts";
 // Soft deletes are opt-in — compose with `Model.using(SoftDeletes)`.
@@ -244,6 +247,11 @@ export type { DatabaseConfigShape } from "./config.ts";
 // Casts
 export { Cast, JsonCast, ArrayCast, json, objectOf, arrayOf } from "./casts/Cast.ts";
 export type { CastContract, CastMapper, CastField } from "./casts/Cast.ts";
+// Encrypted columns — `cast: "encrypted"` / `static encryptable`. The error is
+// exported so an app can catch an unreadable row (a rotated APP_KEY) and say
+// something useful instead of 500ing.
+export { EncryptedColumnError, isEncryptedCast } from "./casts/encrypted.ts";
+export type { EncryptedCastName } from "./casts/encrypted.ts";
 
 // Framework events emitted by the ORM (subscribe via core's FrameworkEvents bus).
 export {