@zerotal/orm 1.14.3 → 1.15.1

package/CHANGELOG.md

@@ -8,6 +8,90 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.15.1] — 2026-09-13
+
+### Fixed
+
+- **A model with a primary key other than `id` could not be updated, deleted or
+  reloaded.** `static primaryKey = "uuid"` (and the `@(table("…").primaryKey("…"))` chain)
+  configured the column name everywhere the key was written into SQL, but the value bound
+  against it came from `this.id` — a property such a model never has. Every statement
+  therefore went out as `WHERE uuid = NULL`: `save()` on a loaded instance and `delete()`
+  each matched zero rows and returned as though they had written, `refresh()` and `fresh()`
+  threw `ModelNotFoundError` for a row that was sitting in the table, and `increment()`,
+  `decrement()`, `loadCount()` and the relation aggregate loads no-opped or reported zero.
+
+  The insert was worse than a silent no-op. It wrote the row correctly, then read it back
+  by `last_insert_rowid()` / `LAST_INSERT_ID()`, which answer with a rowid that no `TEXT`
+  key ever equals — so the re-read matched nothing and the instance came back with no
+  timestamps, no database defaults, and still marked as not yet resident. The next `save()`
+  on it was a second INSERT and a duplicate-key error rather than the UPDATE the caller
+  asked for.
+
+  Every one of those paths now reads the key by its declared name, preferring the loaded
+  value so reassigning a key updates the row it was read from. An insert whose key the app
+  minted skips the generated-id round-trip and reads the row back by the key it just wrote.
+  `replicate()` drops the declared key instead of only `id`, so the copy is insertable.
+  A write against an instance whose key is genuinely absent — a row hydrated by
+  `select("title")`, say — now throws `E_NO_PRIMARY_KEY` instead of binding NULL and
+  looking like a success.
+
+- **A primary key the app mints was stripped from the INSERT.** `id` was treated as
+  database-generated unconditionally, so a table whose key is a `TEXT id` the application
+  supplies took the value on the instance, dropped it from the statement, and stored NULL
+  while the in-memory model went on holding the value it thought it had written. The key is
+  now omitted only when it has no value, which is what leaves AUTOINCREMENT to the database.
+
+- **Hardening: a MySQL adapter that offers `reserve()` may still refuse it.**
+  `LAST_INSERT_ID()` is scoped per connection, so a MySQL insert pins its INSERT and the
+  SELECT that reads the id to one connection, reserving one where the adapter supports it
+  and falling back to a short transaction where it does not. The check was
+  `typeof conn.reserve === "function"`, and presence is not support — an adapter can expose
+  the method and throw `"This adapter doesn't support connection reservation"` when it is
+  called, which is what Bun's SQLite adapter does.
+
+  The reservation is now attempted and the transaction path used when it refuses. Only the
+  acquisition is guarded: a failure inside the insert is a real error and is not retried
+  against a second connection. `try`/`catch` rather than `.catch()`, since an adapter that
+  refuses may throw synchronously.
+
+  No released version was affected — this path was only reachable through a test that had
+  leaked a dialect (see below). Changed because the detection was wrong either way.
+
+- **A dialect-coverage test left the ORM in MySQL mode for the rest of the process.**
+  `server.smoke.test.ts` sets four globals in `beforeAll` and restored three — the
+  BaseModel dialect stayed on whatever server it had just tested. Every later file in that
+  process then took the MySQL insert branch, which reads the new row's id with
+  `LAST_INSERT_ID()`; against the SQLite connection those tests actually use, that is
+  `no such function`.
+
+  Test-only, and it never reached a release: the leak needs `ZT_MYSQL_URL` set, which
+  happens in one CI job. Postgres hid it for months — its branch uses `RETURNING`, which
+  SQLite also supports — so only the MySQL job could go red, and only when the file order
+  put the smoke test first. Bun walks test files in directory order, which is arbitrary on
+  Linux, so "when" was a coin flip on every run.
+
+## [1.15.0] — 2026-09-04
+
+### Changed — **BREAKING**
+
+- **BREAKING: `createdAt`, `updatedAt` and `deletedAt` are `Carbon`, not `Date`.** Every
+  `datetime` column hydrates as `Carbon`, these three included — so the declared type was
+  wrong on a freshly loaded row, and `order.createdAt.getTime()` type-checked and threw,
+  because `Carbon` has `toISOString()` and `valueOf()` but no `getTime()`.
+
+  Worse, the runtime class depended on how you got there: `Carbon` after a load, a raw
+  `Date` after a `save()`, a `touch()`, or a soft `delete()` wrote one straight back onto
+  the instance. The same property on the same model, matching its declared type in neither
+  case, and with no `@column` declaration to check the truth against.
+
+  All three are now `Carbon` everywhere, declared and at runtime. Code calling a `Date`
+  method on them was already failing at runtime and now fails to compile; `.toISOString()`
+  gives a string, `.valueOf()` epoch milliseconds, and `.toDate()` a native `Date`.
+
+  Compile and follow the errors — every one is a line that would have thrown against a
+  loaded row. See the [Upgrade Guide](/docs/upgrade#114-to-115).
+
 ## [1.12.0] — 2026-08-31
 
 ### Changed — **BREAKING**

package/api-surface.md

@@ -3,6 +3,9 @@
 <!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
      Run `bun run api:surface` to regenerate after an intentional API change. -->
 
+> Not a guide — this is a flat, alphabetical snapshot used to detect unintended
+> API changes. For how to use these, read the [documentation](https://zerotal.dev/docs).
+
 ## .  `(./src/index.ts)`
 
 class ArrayCast = {
@@ -78,7 +81,7 @@ class BaseModel = {
   $dirty: () => Record<string, unknown>
   append: (...keys: string[]) => BaseModel
   associate: (relation: string, model: BaseModel) => BaseModel
-  createdAt?: Date
+  createdAt?: Carbon
   decrement: (column: 'id' | 'createdAt' | 'updatedAt' | '__isZerotalModel' | 'fill' | 'forceFill' | 'save' | 'delete' | 'load' | 'loadMissing' | 'fresh' | 'refresh' | 'replicate' | 'touch' | 'is' | 'isNot' | 'increment' | 'decrement' | 'loadCount' | 'loadSum' | 'loadAvg' | 'loadMin' | 'loadMax' | 'makeHidden' | 'makeVisible' | 'append' | 'associate' | 'dissociate' | 'isDirty' | '$dirty' | 'markDirty' | 'toJSON', amount?: number) => Promise<BaseModel>
   delete: () => Promise<void>
   dissociate: (relation: string) => BaseModel
@@ -106,7 +109,7 @@ class BaseModel = {
   save: () => Promise<BaseModel>
   toJSON: () => Record<string, unknown>
   touch: () => Promise<BaseModel>
-  updatedAt?: Date
+  updatedAt?: Carbon
 }
 
 class Blueprint = {
@@ -392,7 +395,7 @@ class Model = {
   $dirty: () => Record<string, unknown>
   append: (...keys: string[]) => BaseModel
   associate: (relation: string, model: BaseModel) => BaseModel
-  createdAt?: Date
+  createdAt?: Carbon
   decrement: (column: 'id' | 'createdAt' | 'updatedAt' | '__isZerotalModel' | 'fill' | 'forceFill' | 'save' | 'delete' | 'load' | 'loadMissing' | 'fresh' | 'refresh' | 'replicate' | 'touch' | 'is' | 'isNot' | 'increment' | 'decrement' | 'loadCount' | 'loadSum' | 'loadAvg' | 'loadMin' | 'loadMax' | 'makeHidden' | 'makeVisible' | 'append' | 'associate' | 'dissociate' | 'isDirty' | '$dirty' | 'markDirty' | 'toJSON', amount?: number) => Promise<BaseModel>
   delete: () => Promise<void>
   dissociate: (relation: string) => BaseModel
@@ -420,7 +423,7 @@ class Model = {
   save: () => Promise<BaseModel>
   toJSON: () => Record<string, unknown>
   touch: () => Promise<BaseModel>
-  updatedAt?: Date
+  updatedAt?: Carbon
 }
 
 class ModelChanged = {

package/package.json

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

package/src/model/BaseModel.ts

@@ -1,6 +1,6 @@
 import type { SQLInstance } from "../db/sql-types.ts";
 import type { PaginateResult } from "../db/types.ts";
-import { RequestContext, FrameworkEvents } from "@zerotal/core";
+import { RequestContext, FrameworkEvents, ZerotalError } from "@zerotal/core";
 import { ModelChanged } from "../events.ts";
 import { Carbon } from "@zerotal/core/carbon";
 import { toCamelKey as toCamel, toSnakeColumn as toSnake } from "../support/identifiers.ts";
@@ -923,6 +923,10 @@ export class BaseModel {
    * Primary-key value. Populated after {@link save} inserts a new row, or when
    * the instance is hydrated from the database.
    *
+   * A model that overrides {@link primaryKey} carries its key under that name
+   * instead (`uuid`, `user_id`, …) and leaves this one unset — every persistence
+   * method reads the declared key, not this property.
+   *
    * @category Attributes & mass assignment
    */
   id!: number;
@@ -930,16 +934,75 @@ export class BaseModel {
   /**
    * Creation timestamp, set on insert when {@link timestamps} is enabled.
    *
+   * A {@link Carbon}, like every other `datetime` column — not a `Date`. These
+   * two were declared as `Date` while hydration produced a `Carbon`, so
+   * `order.createdAt.getTime()` type-checked and threw, and `.slice(0, 10)` on
+   * a value assumed to be an ISO string threw differently. Neither has a column
+   * declaration in the model to read the truth off, which is exactly why the
+   * declaration here has to be right.
+   *
+   * Use `.toISOString()` for a string, `.valueOf()` for epoch milliseconds, and
+   * `.toDate()` when something really needs a native `Date`.
+   *
    * @category Timestamps
    */
-  createdAt?: Date;
+  createdAt?: Carbon;
 
   /**
    * Last-update timestamp, bumped on every save when {@link timestamps} is enabled.
    *
+   * A {@link Carbon} — see {@link createdAt}. It used to depend on how you got
+   * here: a `Carbon` on a freshly loaded row, a raw `Date` on one you had just
+   * saved, from the same property on the same model.
+   *
    * @category Timestamps
    */
-  updatedAt?: Date;
+  updatedAt?: Carbon;
+
+  /**
+   * The value every `WHERE <primary key> = …` this instance issues is keyed on:
+   * update, delete, refresh, fresh, increment/decrement and the relation
+   * aggregate loads.
+   *
+   * Reads the property named by {@link primaryKey} rather than `id`, because a
+   * model that overrides the key has no `id` — these all used `this.id`, so an
+   * `uuid`-keyed model issued `WHERE uuid = NULL`: an update and a delete both
+   * reported success having touched no row, and `refresh()` threw
+   * {@link ModelNotFoundError} for a row that was sitting right there.
+   *
+   * Prefers the loaded snapshot so reassigning the key updates the row it was
+   * read from (`SET uuid = new WHERE uuid = old`) instead of a row that does not
+   * exist yet.
+   *
+   * @internal
+   */
+  private get _keyValue(): unknown {
+    const pk = toCamel((this.constructor as typeof BaseModel).primaryKey);
+    const loaded = (this._original as Record<string, unknown>)[pk];
+    return loaded !== undefined ? loaded : (this as unknown as Record<string, unknown>)[pk];
+  }
+
+  /**
+   * Throw rather than build a `WHERE <key> = NULL` that quietly matches nothing.
+   * Reached when a row was hydrated without its key column (`select("name")`),
+   * where the silent version of this looked exactly like a successful write.
+   *
+   * @internal
+   */
+  private _requireKey(operation: string): unknown {
+    const key = this._keyValue;
+    if (key === undefined || key === null) {
+      const ModelClass = this.constructor as typeof BaseModel;
+      throw new ZerotalError(
+        `Cannot ${operation} ${ModelClass.name}: its primary key "${ModelClass.primaryKey}" is not set. ` +
+          `Load the row including its key column, or set the key before saving.`,
+        "E_NO_PRIMARY_KEY",
+        500,
+        { model: ModelClass.name, primaryKey: ModelClass.primaryKey, operation },
+      );
+    }
+    return key;
+  }
 
   /** @internal Snapshot of attribute values at load/last-save, for dirty tracking. */
   private _original: Record<string, unknown> = {};
@@ -1748,13 +1811,25 @@ export class BaseModel {
     const colReg = columnsFor(ModelClass as unknown as ClassRef);
     const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
 
+    const pkProp = toCamel(ModelClass.primaryKey);
+    const pkColumn = toSnake(ModelClass.primaryKey);
+
     if (!this._exists) {
       // ── INSERT ──
       await HookRegistry.run(ModelClass, "beforeCreate", this);
 
+      // The primary key is a system column only while the DATABASE mints it. When the
+      // app mints it — `static primaryKey = "uuid"`, or a TEXT `id` — it has to reach
+      // the INSERT, so drop it from the skip set here (it is added back explicitly
+      // below, since the key is often not `@column`-registered and `colKeys` would
+      // filter it out). An unset key is still omitted, so AUTOINCREMENT is untouched.
+      const insertSkip = SYSTEM_KEYS.has(pkProp)
+        ? new Set([...SYSTEM_KEYS].filter((k) => k !== pkProp))
+        : SYSTEM_KEYS;
+
       const row: Record<string, unknown> = _writeDialect.run(dialect, () => {
         const r: Record<string, unknown> = {};
-        for (const [key, val] of ownDataEntries(this, SYSTEM_KEYS, rels, colKeys)) {
+        for (const [key, val] of ownDataEntries(this, insertSkip, rels, colKeys)) {
           // A declared field that was never assigned is `undefined`, and writing that
           // as an explicit NULL made `@column({ default: … })` inert: the INSERT named
           // the column, so the database never applied its own default and a NOT NULL
@@ -1774,6 +1849,12 @@ export class BaseModel {
           }
           r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg, ModelClass.name);
         }
+        // An app-minted key that is not `@column`-registered (the common shape for a
+        // plain `id`) never reaches the loop above, so take it straight off the instance.
+        const minted = self[pkProp];
+        if (minted !== undefined && minted !== null && !(pkColumn in r)) {
+          r[pkColumn] = _serializeForWrite(pkProp, minted, casts, colReg, ModelClass.name);
+        }
         if (ModelClass.timestamps) {
           const now = _serializeDate(new Date());
           r["created_at"] = now;
@@ -1792,11 +1873,22 @@ export class BaseModel {
       });
       segs.push(")");
 
-      let newId: number;
-      if (dialect === "postgres") {
+      // The key to read the row back by. When the app minted it there is nothing to
+      // ask the database for — and asking was the bug: `last_insert_rowid()` /
+      // `LAST_INSERT_ID()` answer with a rowid, which no TEXT key ever equals, so the
+      // re-read below matched no row and left the instance with no timestamps, no
+      // database defaults and `_exists` still false — making the NEXT save() insert
+      // the same row a second time instead of updating it.
+      const mintedKey = pkColumn in row ? row[pkColumn] : undefined;
+
+      let newId: unknown;
+      if (mintedKey !== undefined && mintedKey !== null) {
+        await runSegs(conn, segs);
+        newId = mintedKey;
+      } else if (dialect === "postgres") {
         segs.push(` RETURNING ${ModelClass.primaryKey}`);
-        const [returning] = await runQuery<Record<string, number>>(conn, segs);
-        newId = returning![ModelClass.primaryKey as string] as number;
+        const [returning] = await runQuery<Record<string, unknown>>(conn, segs);
+        newId = returning![ModelClass.primaryKey as string];
       } else if (dialect === "mysql") {
         // LAST_INSERT_ID() is scoped per connection, so the INSERT and the
         // SELECT must be pinned to the SAME connection — under concurrency a
@@ -1819,15 +1911,33 @@ export class BaseModel {
         };
         if (inTx) {
           newId = await insertAndReadId(conn);
-        } else if (typeof reservable.reserve === "function") {
-          const pinned = await reservable.reserve();
-          try {
-            newId = await insertAndReadId(pinned);
-          } finally {
-            pinned.release();
-          }
         } else {
-          newId = await conn.begin((tx) => insertAndReadId(tx));
+          // Presence is not support. Bun's MySQL adapter now exposes `reserve()`
+          // and throws "This adapter doesn't support connection reservation" when
+          // it is called, so `typeof … === "function"` stopped distinguishing the
+          // two and every MySQL insert failed on a runtime that had merely been
+          // updated. Only the acquisition is guarded — a failure inside the insert
+          // is a real error and must not be retried against a second connection.
+          let pinned: (SQLInstance & { release(): void }) | undefined;
+          if (typeof reservable.reserve === "function") {
+            try {
+              // try/catch rather than `.catch()`: an adapter that refuses may throw
+              // synchronously, before there is a promise to attach a handler to.
+              pinned = await reservable.reserve();
+            } catch {
+              pinned = undefined;
+            }
+          }
+
+          if (pinned) {
+            try {
+              newId = await insertAndReadId(pinned);
+            } finally {
+              pinned.release();
+            }
+          } else {
+            newId = await conn.begin((tx) => insertAndReadId(tx));
+          }
         }
       } else {
         await runSegs(conn, segs);
@@ -1841,7 +1951,17 @@ export class BaseModel {
         `SELECT * FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
         { val: newId },
       ]);
-      if (rows[0]) _applyRow(this, rows[0]);
+      if (rows[0]) {
+        _applyRow(this, rows[0]);
+      } else {
+        // The INSERT succeeded, so the instance is resident whether or not the row came
+        // back (a trigger may have moved it, the target may be a view). Record that much
+        // instead of leaving `_exists` false, which turns the next save() into a second
+        // INSERT and a duplicate-key error rather than the UPDATE the caller asked for.
+        if (newId !== undefined && newId !== null) self[pkProp] = newId;
+        this._exists = true;
+        this._original = { ...this._original, [pkProp]: self[pkProp] };
+      }
 
       await HookRegistry.run(ModelClass, "afterCreate", this);
     } else {
@@ -1849,7 +1969,10 @@ export class BaseModel {
       await HookRegistry.run(ModelClass, "beforeUpdate", this);
 
       const dirty = this.$dirty();
-      if (ModelClass.timestamps) dirty["updatedAt"] = new Date();
+      // Carbon, not `new Date()`. The entries below are written back onto the
+      // instance, so a plain Date here left `updatedAt` holding a different class
+      // after a save than after a load — with the declared type matching neither.
+      if (ModelClass.timestamps) dirty["updatedAt"] = Carbon.now();
 
       if (Object.keys(dirty).length > 0) {
         const entries = _writeDialect.run(dialect, () =>
@@ -1869,7 +1992,7 @@ export class BaseModel {
           segs.push({ val });
         });
         segs.push(` WHERE ${ModelClass.primaryKey} = `);
-        segs.push({ val: this.id });
+        segs.push({ val: this._requireKey("update") });
         await runSegs(conn, segs);
 
         const self = this as unknown as Record<string, unknown>;
@@ -1900,20 +2023,21 @@ export class BaseModel {
     await HookRegistry.run(ModelClass, "beforeDelete", this);
 
     if (ModelClass.softDeletes) {
-      const now = new Date();
+      const now = Carbon.now();
       await runSegs(conn, [
         `UPDATE ${ModelClass.table} SET deleted_at = `,
-        { val: _writeDialect.run(dialect, () => _serializeDate(now)) },
+        { val: _writeDialect.run(dialect, () => _serializeDate(now.toDate())) },
         ` WHERE ${ModelClass.primaryKey} = `,
-        { val: this.id },
+        { val: this._requireKey("delete") },
       ]);
       // `deletedAt` lives on the SoftDeletes mixin; this branch only runs for models
-      // that compose it (softDeletes === true).
-      (this as { deletedAt?: Date | null }).deletedAt = now;
+      // that compose it (softDeletes === true). Carbon, to match what a reload of
+      // this same row would put there.
+      (this as { deletedAt?: Carbon | null }).deletedAt = now;
     } else {
       await runSegs(conn, [
         `DELETE FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
-        { val: this.id },
+        { val: this._requireKey("delete") },
       ]);
     }
 
@@ -1975,11 +2099,12 @@ export class BaseModel {
   async fresh(): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
+    const key = this._requireKey("reload");
     const rows = await runQuery<Record<string, unknown>>(conn, [
       `SELECT * FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
-      { val: this.id },
+      { val: key },
     ]);
-    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, this.id);
+    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, key as number | string);
     return ModelClass.fromRow(rows[0]) as this;
   }
 
@@ -1993,11 +2118,12 @@ export class BaseModel {
   async refresh(): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     const conn = _resolveConn(ModelClass);
+    const key = this._requireKey("reload");
     const rows = await runQuery<Record<string, unknown>>(conn, [
       `SELECT * FROM ${ModelClass.table} WHERE ${ModelClass.primaryKey} = `,
-      { val: this.id },
+      { val: key },
     ]);
-    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, this.id);
+    if (!rows[0]) throw new ModelNotFoundError(ModelClass.name, key as number | string);
     _applyRow(this, rows[0]);
     return this;
   }
@@ -2012,7 +2138,13 @@ export class BaseModel {
     const ModelClass = this.constructor as typeof BaseModel;
     const rels = relNames(ModelClass as unknown as ClassRef);
     const colKeys = _allColumnKeys(ModelClass as unknown as ClassRef);
-    const skip = new Set<string>([...SYSTEM_KEYS, ...(except ?? [])]);
+    // The declared key, not just `id` — copying a `uuid` forward produced a replica
+    // that could only ever fail on save with a duplicate-key error.
+    const skip = new Set<string>([
+      ...SYSTEM_KEYS,
+      toCamel(ModelClass.primaryKey),
+      ...(except ?? []),
+    ]);
     const inst = new (this.constructor as new () => this)();
     for (const [k, v] of ownDataEntries(this, skip, rels, colKeys)) {
       (inst as unknown as Record<string, unknown>)[k] = v;
@@ -2028,7 +2160,7 @@ export class BaseModel {
   async touch(): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     if (!ModelClass.timestamps) return this;
-    this.updatedAt = new Date();
+    this.updatedAt = Carbon.now();
     this.markDirty("updatedAt" as keyof this);
     return this.save();
   }
@@ -2086,7 +2218,7 @@ export class BaseModel {
       `UPDATE ${ModelClass.table} SET ${col} = ${col} ${op} `,
       { val: Math.abs(delta) },
       ` WHERE ${ModelClass.primaryKey} = `,
-      { val: this.id },
+      { val: this._requireKey(delta >= 0 ? "increment" : "decrement") },
     ]);
     const self = this as unknown as Record<string, unknown>;
     const current = Number(self[column] ?? 0);
@@ -2104,7 +2236,7 @@ export class BaseModel {
     const rels = Array.isArray(relations) ? relations : [relations];
     const ModelClass = this.constructor as typeof BaseModel;
     const qb = new ModelQueryBuilder(ModelClass.table, _resolveConn(ModelClass), ModelClass);
-    qb.where(ModelClass.primaryKey, this.id);
+    qb.where(ModelClass.primaryKey, this._keyValue as number | string);
     for (const r of rels) qb.withCount(r);
     const fresh = (await qb.limit(1).get<BaseModel>())[0] ?? null;
     const src = fresh as unknown as Record<string, unknown> | null;
@@ -2135,15 +2267,18 @@ export class BaseModel {
   ): Promise<T[]> {
     if (models.length === 0) return models;
     const rels = Array.isArray(relations) ? relations : [relations];
-    const idOf = (m: T): unknown => (m as unknown as { id: unknown }).id;
+    // Read the declared key, not `id`: on a model that overrides `primaryKey` this
+    // collected a list of `undefined` and set every count to 0.
+    const keyProp = toCamel(this.primaryKey);
+    const idOf = (m: BaseModel): unknown => (m as unknown as Record<string, unknown>)[keyProp];
 
     const qb = new ModelQueryBuilder(this.table, _resolveConn(this), this);
-    qb.whereIn(this.primaryKey, models.map(idOf));
+    qb.whereIn(this.primaryKey, models.map(idOf) as (number | string)[]);
     for (const r of rels) qb.withCount(r);
     const fresh = await qb.get<BaseModel>();
 
     const byId = new Map<unknown, Record<string, unknown>>();
-    for (const f of fresh) byId.set((f as unknown as { id: unknown }).id, f as never);
+    for (const f of fresh) byId.set(idOf(f), f as never);
 
     for (const m of models) {
       const src = byId.get(idOf(m));
@@ -2164,7 +2299,7 @@ export class BaseModel {
   ): Promise<this> {
     const ModelClass = this.constructor as typeof BaseModel;
     const qb = new ModelQueryBuilder(ModelClass.table, _resolveConn(ModelClass), ModelClass);
-    qb.where(ModelClass.primaryKey, this.id);
+    qb.where(ModelClass.primaryKey, this._keyValue as number | string);
     (qb as unknown as Record<string, (r: string, c: string) => void>)[`with${fn}`]?.(
       relation,
       column,

package/src/model/SoftDeletes.ts

@@ -24,6 +24,7 @@ import { _resolveConn, type BaseModel } from "./BaseModel.ts";
 import { ModelQueryBuilder } from "./ModelQueryBuilder.ts";
 import { QueryBuilder } from "../db/QueryBuilder.ts";
 import type { Constructor } from "./mixins.ts";
+import type { Carbon } from "@zerotal/core/carbon";
 
 // Structural view of the concrete model class used by the static scopes.
 interface SoftDeleteModelClass<T extends BaseModel> {
@@ -63,8 +64,13 @@ export function SoftDeletes<TBase extends Constructor>(Base: TBase) {
     /** Engine switch — query scoping + schema `deleted_at` provisioning read this. */
     static softDeletes = true;
 
-    /** When the row was soft-deleted, or null/undefined when live. */
-    declare deletedAt?: Date | null;
+    /**
+     * When the row was soft-deleted, or null/undefined when live.
+     *
+     * A {@link Carbon}, like `createdAt`/`updatedAt` and every other `datetime`
+     * column — `.toISOString()` for a string, `.toDate()` for a native `Date`.
+     */
+    declare deletedAt?: Carbon | null;
 
     /** A query that INCLUDES soft-deleted rows (bypasses the default scope). */
     static withTrashed<T extends BaseModel>(this: SoftDeleteModelClass<T>): ModelQueryBuilder<T> {