@zerotal/orm 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -8,6 +8,112 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.5.0] — 2026-08-15
+
+### Fixed
+
+- **N+1 detection was running in production.** The gate read `Bun.env.APP_ENV`, which
+  by the time a provider boots holds the runtime mode (`web`) rather than the
+  deployment name — `setAppEnv()` overwrote it. So the check that exists to help in
+  development was wrapping every query on live apps, to warn about something nobody
+  was there to read. It now asks `deployEnv()`, which is what the deployment name
+  survives in.
+
+### Added
+
+- **A missing table now offers to run the migration that would create it.**
+  When a query fails because a table or column does not exist, the development
+  error page reports which migrations have not run and offers to run them.
+  Detection is by driver error code where there is one — `42P01` / `42703` on
+  PostgreSQL, `1146` / `1054` on MySQL — and by message on SQLite, which has
+  none worth branching on.
+
+  **The half that matters is when it does _not_ offer the button.** With nothing
+  pending, running every migration changes nothing and leaves the developer back
+  where they started, so instead it says whether any migration on disk even
+  mentions the missing name — if none does, the migration was probably never
+  written, which is a different problem with a different fix.
+
+  The endpoint behind the button carries three guards, each checked on its own
+  rather than inferred from the overlay being dev-only: `devSurfacesEnabled()`
+  at request time (which **fails closed** — unlike `!isProdLike()`, an unset
+  `APP_ENV` does not qualify), a single-use token minted into the page, and the
+  same origin check the raw Flow endpoints use, since a raw route sits outside
+  CSRF middleware. Outside development the route is never registered at all.
+
+- **`migrate:refresh`** — the same command as `migrate:fresh`, under the name it has
+  elsewhere. Nothing otherwise pushes anyone to run their `down()` methods, and a
+  rollback nobody has exercised is a rollback that does not work.
+
+- **`--seed` on `migrate` and `migrate:fresh`.** Wiping a database and repopulating it is
+  one thought, and it took two commands — `bun zt migrate:fresh && bun zt db:seed` — with
+  the second easy to forget and nothing to remind you. The flag closes that:
+
+  ```bash
+  bun zt migrate:fresh --seed        # rebuild the schema, then seed it
+  bun zt migrate --fresh --seed      # the same thing
+  bun zt migrate --seed              # apply pending migrations, then seed
+  ```
+
+  `migrate --seed` seeds even when nothing was pending, because topping up an
+  already-current dev database is a normal reason to run it.
+
+  A seeding failure is reported but does not fail the command. The migrations above have
+  already committed by then, and exiting non-zero would suggest the whole operation needs
+  repeating when only the seeders do — so the output says the schema was rebuilt and
+  points at `bun zt db:seed` for the retry.
+
+  The seeder-loading logic is now shared with `db:seed` rather than duplicated, so all
+  three commands accept the same shapes: a class-based `DatabaseSeeder` (named or default
+  export) and the legacy `database/seeders/index.ts` default function.
+
+### Changed
+
+- **The N+1 detector reads the bindings, not just the SQL text.** Grouping by SQL alone
+  made a legitimate loop over six months — identical SQL, a different `period` each
+  time — indistinguishable from a per-row lookup, so it told you to eager-load a
+  relation that does not exist. The warning now says which of the two it found: _same
+  SQL, different arguments_ points at eager loading or `whereIn`; _same SQL, same
+  arguments_ points at `RequestContext.remember()`, because there is nothing to
+  eager-load when the answer never changes. `NPlusOneError.distinctArgs` carries the
+  count.
+
+### Fixed
+
+- **A `Date` in a query-builder write is no longer silently discarded.**
+  `update({ read_at: new Date() })` bound the `Date` object straight through; SQLite
+  dropped it and **reported no error**, so a "mark all as read" feature shipped as a
+  latent no-op whose source read correctly. The asymmetry made it easy to write, too —
+  `model.save()` applies casts, so the identical value through a model worked. Dates
+  and `Carbon` instances are now serialised at the single point every bind passes
+  through, dialect-aware (MySQL DATETIME rejects ISO 8601's `T`/`Z`), which covers
+  `update`, `insert`, `where` and every builder at once. The comparison path had
+  already learned this lesson separately; now there is one place it lives.
+
+- **`foreignId(...).nullable().constrained()` type-checks.** `nullable()` returned
+  `ColumnBuilder`, so the chain left `ForeignIdColumnBuilder` and `.constrained()` was
+  gone — the form the class's own docblock documents, and the first one anyone reaches
+  for, since a nullable foreign key is the commonest kind. The two modifiers now
+  preserve the subclass while keeping the `nullability` lock, so
+  `.nullable().notNullable()` is still a compile error.
+
+- **SQLite refuses an impossible `dropColumn` before applying anything.** SQLite cannot
+  drop a column a foreign key still names, and it says so _after_ every earlier
+  statement in the same `Schema.table()` block has run — the difference between a
+  migration that did nothing and one that has to be unpicked by hand. A `PRAGMA
+foreign_key_list` check now runs first and throws a message naming the column, the
+  table it references, and the table-rebuild way out. The rebuild itself is still not
+  implemented; this makes its absence safe rather than expensive.
+
+- **Altering a Postgres column no longer silently drops its NOT NULL and DEFAULT.**
+  The regexes that split a column definition into `ALTER COLUMN` sub-commands
+  carried literal backspace characters (0x08) where `\b` word boundaries were
+  meant — invisible in any editor, and impossible for either pattern to match. So
+  `table.string("email").notNullable().alter()` emitted `DROP NOT NULL`, and a
+  declared default emitted `DROP DEFAULT`, on every alter, regardless of the
+  definition. Found by the lint ratchet (`no-control-regex`); the statements are
+  now pinned by tests, not just the column name.
+
 ## [1.4.0] — 2026-08-10
 
 ### Added

package/package.json

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

package/src/commands/DbSeedCommand.ts

@@ -1,5 +1,5 @@
 import { Command } from "@zerotal/core";
-import type { Seeder } from "../seeding/Seeder.ts";
+import { runSeeders } from "./_runSeeders.ts";
 
 /**
  * Runs the application's database seeders (`bun zt db:seed`).
@@ -21,51 +21,23 @@ export class DbSeedCommand extends Command {
   static needsApp = true;
 
   async run(): Promise<void> {
-    const cwd = process.cwd();
-    const seederPath = `${cwd}/database/seeders/DatabaseSeeder.ts`;
+    this.section("Database Seeding");
+    const outcome = await runSeeders();
 
-    const file = Bun.file(seederPath);
-    if (!(await file.exists())) {
-      // Fall back to legacy index.ts seeder format
-      const legacyPath = `${cwd}/database/seeders/index.ts`;
-      if (await Bun.file(legacyPath).exists()) {
-        try {
-          const mod = await import(legacyPath);
-          const seed = mod.default as (() => Promise<void>) | undefined;
-          if (!seed) {
-            this.error("Seeder index must export a default async function.");
-            return;
-          }
-          await seed();
-          this.info("Database seeded.");
-        } catch (err) {
-          const msg = err instanceof Error ? err.message : String(err);
-          this.error(`Failed to run seeders: ${msg}`);
-        }
+    switch (outcome.status) {
+      case "seeded":
+        this.info("Database seeded successfully.");
         return;
-      }
-
-      this.error(`Seeder not found: ${seederPath}`);
-      this.dim("Create it with: bun zerotal.ts make:seeder DatabaseSeeder");
-      return;
-    }
-
-    try {
-      const mod = await import(seederPath);
-      const SeederClass = (mod.DatabaseSeeder ?? mod.default) as (new () => Seeder) | undefined;
-
-      if (!SeederClass) {
-        this.error("DatabaseSeeder not found as a named or default export.");
+      case "missing":
+        this.error(`Seeder not found: ${outcome.path}`);
+        this.dim("Create it with: bun zerotal.ts make:seeder DatabaseSeeder");
+        return;
+      case "invalid":
+        this.error(outcome.message);
+        return;
+      case "failed":
+        this.error(`Failed to run seeders: ${outcome.message}`);
         return;
-      }
-
-      this.section("Database Seeding");
-      const seeder = new SeederClass();
-      await seeder.run();
-      this.info("Database seeded successfully.");
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      this.error(`Failed to run seeders: ${msg}`);
     }
   }
 }

package/src/commands/MigrateCommand.ts

@@ -1,20 +1,22 @@
-import { Command } from "@zerotal/core";
+import { Command, type FlagDef } from "@zerotal/core";
 import type { MigrationEntry } from "../schema/MigrationRunner.ts";
 import { MigrationRunner } from "../schema/MigrationRunner.ts";
 import { _getConnection } from "../db/DB.ts";
 import { loadMigrations } from "./_loadMigrations.ts";
+import { runSeeders } from "./_runSeeders.ts";
 
 /**
  * Runs all pending database migrations (`bun zt migrate`).
  *
  * Loads every migration under `database/migrations/`, then applies those not
  * yet run. Passing `--fresh` first drops all tables and re-runs every
- * migration from scratch.
+ * migration from scratch; `--seed` runs the seeders afterwards.
  *
  * @example
  * ```bash
  * bun zt migrate
  * bun zt migrate --fresh
+ * bun zt migrate --fresh --seed
  * ```
  *
  * @category Migrations
@@ -24,13 +26,19 @@ export class MigrateCommand extends Command {
   static aliases = ["db:migrate"];
   static description = "Run all pending database migrations";
   static needsApp = true;
-  static flags = [
+  static flags: FlagDef[] = [
     {
       name: "fresh",
-      type: "boolean" as const,
+      type: "boolean",
       description: "Drop all tables and re-run all migrations",
       default: false,
     },
+    {
+      name: "seed",
+      type: "boolean",
+      description: "Run database seeders once migrations have run",
+      default: false,
+    },
   ];
 
   async run(): Promise<void> {
@@ -51,10 +59,41 @@ export class MigrateCommand extends Command {
 
     if (ran.length === 0) {
       this.info("Nothing to migrate.");
-      return;
+    } else {
+      this.info(`Migrated ${ran.length} migration(s).`);
+      this.table(ran.map((name) => [name, "ran"]));
     }
 
-    this.info(`Migrated ${ran.length} migration(s).`);
-    this.table(ran.map((name) => [name, "ran"]));
+    // Seeding runs even when nothing migrated: `migrate --seed` against an
+    // already-current schema is a normal way to top up a dev database.
+    if (this.flags["seed"] as boolean) await this.#seed();
+  }
+
+  /**
+   * Seed after migrating.
+   *
+   * Reported, not thrown: the migrations above already committed, and failing
+   * the command here would suggest they need repeating when only the seeders do.
+   */
+  async #seed(): Promise<void> {
+    this.section("Database Seeding");
+    const outcome = await runSeeders();
+
+    switch (outcome.status) {
+      case "seeded":
+        this.info("Database seeded successfully.");
+        return;
+      case "missing":
+        this.error(`Seeder not found: ${outcome.path}`);
+        this.dim("Create it with: bun zerotal.ts make:seeder DatabaseSeeder");
+        return;
+      case "invalid":
+        this.error(outcome.message);
+        return;
+      case "failed":
+        this.error(`Failed to run seeders: ${outcome.message}`);
+        this.dim("Migrations already ran — re-run `bun zt db:seed` once the seeder is fixed.");
+        return;
+    }
   }
 }

package/src/commands/MigrateFreshCommand.ts

@@ -1,18 +1,21 @@
-import { Command } from "@zerotal/core";
+import { Command, type FlagDef } from "@zerotal/core";
 import type { MigrationEntry } from "../schema/MigrationRunner.ts";
 import { MigrationRunner } from "../schema/MigrationRunner.ts";
 import { _getConnection } from "../db/DB.ts";
 import { loadMigrations } from "./_loadMigrations.ts";
+import { runSeeders } from "./_runSeeders.ts";
 
 /**
  * Rolls back every migration, then re-runs them from scratch (`bun zt migrate:fresh`).
  *
  * Resets the database by reversing all applied migrations and then re-applying
- * the full set, giving a clean, fully-migrated schema in one step.
+ * the full set, giving a clean, fully-migrated schema in one step. Pass
+ * `--seed` to repopulate it afterwards, which is the usual reason for wiping it.
  *
  * @example
  * ```bash
  * bun zt migrate:fresh
+ * bun zt migrate:fresh --seed
  * ```
  *
  * @category Migrations
@@ -22,6 +25,15 @@ export class MigrateFreshCommand extends Command {
   static description = "Roll back every migration, then re-run them from scratch";
   static needsApp = true;
 
+  static flags: FlagDef[] = [
+    {
+      name: "seed",
+      type: "boolean",
+      description: "Run database seeders once the schema has been rebuilt",
+      default: false,
+    },
+  ];
+
   async run(): Promise<void> {
     const records = await loadMigrations();
     const entries: MigrationEntry[] = records.map((r) => ({
@@ -37,5 +49,36 @@ export class MigrateFreshCommand extends Command {
     if (ran.length > 0) {
       this.table(ran.map((name) => [name, "migrated"]));
     }
+
+    if (this.flags["seed"] as boolean) await this.#seed();
+  }
+
+  /**
+   * Seed the freshly-migrated schema.
+   *
+   * A seeding failure is reported but does not fail the command: the migrations
+   * above already ran and committed, and exiting non-zero here would suggest the
+   * whole operation needs repeating when only the seeders do.
+   */
+  async #seed(): Promise<void> {
+    this.section("Database Seeding");
+    const outcome = await runSeeders();
+
+    switch (outcome.status) {
+      case "seeded":
+        this.info("Database seeded successfully.");
+        return;
+      case "missing":
+        this.error(`Seeder not found: ${outcome.path}`);
+        this.dim("Create it with: bun zerotal.ts make:seeder DatabaseSeeder");
+        return;
+      case "invalid":
+        this.error(outcome.message);
+        return;
+      case "failed":
+        this.error(`Failed to run seeders: ${outcome.message}`);
+        this.dim("The schema was rebuilt — re-run `bun zt db:seed` once the seeder is fixed.");
+        return;
+    }
   }
 }

package/src/commands/MigrateRefreshCommand.ts

@@ -0,0 +1,28 @@
+import { MigrateFreshCommand } from "./MigrateFreshCommand.ts";
+
+/**
+ * `bun zt migrate:refresh` — a second name for `migrate:fresh`, pointing at the
+ * same command.
+ *
+ * `migrate:fresh` already runs every migration's `down()` and then every `up()`
+ * again, which is what "refresh" means to most people arriving here; elsewhere
+ * the two names are split, and "fresh" is the one that drops the tables outright
+ * without touching `down()`. So the behaviour was always there — only the name
+ * people reach for was missing, and reaching for a command that does not exist
+ * is how a broken `down()` stays unexercised until the day it matters.
+ *
+ * A subclass rather than a second implementation: one code path, two names.
+ *
+ * @example
+ * ```bash
+ * bun zt migrate:refresh
+ * bun zt migrate:refresh --seed
+ * ```
+ *
+ * @category Migrations
+ */
+export class MigrateRefreshCommand extends MigrateFreshCommand {
+  static override commandName = "migrate:refresh";
+  static override description =
+    "Roll every migration back through down(), then re-run them (alias of migrate:fresh)";
+}

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 "?";
+  }
+}