@stonyx/orm 0.3.2-beta.16 → 0.3.2-beta.160

package/src/postgres/connection.ts

@@ -8,6 +8,7 @@ interface PgConfig {
   password: string;
   database: string;
   connectionLimit: number;
+  [key: string]: unknown;
 }
 
 let pool: PgPool | null = null;
@@ -20,15 +21,18 @@ export async function getPool(pgConfig: PgConfig, extensions: string[] = ['vecto
 
   const { default: pg } = await import('pg');
 
+  const { host, port, user, password, database, connectionLimit, migrationsDir, migrationsTable, autoMigrate, ...poolOpts } = pgConfig;
+
   pool = new pg.Pool({
-    host: pgConfig.host,
-    port: pgConfig.port,
-    user: pgConfig.user,
-    password: pgConfig.password,
-    database: pgConfig.database,
-    max: pgConfig.connectionLimit,
+    host,
+    port,
+    user,
+    password,
+    database,
+    max: connectionLimit,
     idleTimeoutMillis: 30000,
     connectionTimeoutMillis: 10000,
+    ...poolOpts,
   });
 
   // Enable requested PostgreSQL extensions

package/src/postgres/postgres-db.ts

@@ -90,6 +90,15 @@ export default class PostgresDB {
   pool!: Pool | null;
   pgConfig!: Record<string, unknown>;
 
+  /**
+   * Promise-chain mutex for write serialization (#156).
+   * All persist() calls chain through this single queue so concurrent
+   * fire-and-forget writes never produce parallel transactions
+   * on FK-linked rows (which cause deadlocks).
+   * Reads are NOT affected — only persist() serializes.
+   */
+  private _writeQueue: Promise<void> = Promise.resolve();
+
   constructor(deps: Partial<PostgresDeps> = {}) {
     const Ctor = this.constructor as typeof PostgresDB;
     if (Ctor.instance) return Ctor.instance;
@@ -125,7 +134,15 @@ export default class PostgresDB {
     if (pending.length > 0) {
       this.deps.log.db?.(`${pending.length} pending migration(s) found.`);
 
-      const shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      let shouldApply: boolean;
+      if (this.pgConfig.autoMigrate === true) {
+        shouldApply = true;
+      } else if (this.pgConfig.autoMigrate === false) {
+        shouldApply = false;
+        this.deps.log.warn?.(`autoMigrate is false — skipping ${pending.length} pending migration(s).`);
+      } else {
+        shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      }
 
       if (shouldApply) {
         for (const filename of pending) {
@@ -146,9 +163,17 @@ export default class PostgresDB {
       const modelCount = Object.keys(schemas).length;
 
       if (modelCount > 0) {
-        const shouldGenerate = await this.deps.confirm(
-          `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
-        );
+        let shouldGenerate: boolean;
+        if (this.pgConfig.autoMigrate === true) {
+          shouldGenerate = true;
+        } else if (this.pgConfig.autoMigrate === false) {
+          shouldGenerate = false;
+          this.deps.log.warn?.(`autoMigrate is false — skipping initial migration generation for ${modelCount} model(s).`);
+        } else {
+          shouldGenerate = await this.deps.confirm(
+            `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
+          );
+        }
 
         if (shouldGenerate) {
           const { generateMigration } = await import('./migration-generator.js');
@@ -468,14 +493,21 @@ export default class PostgresDB {
     const Orm = (await import('@stonyx/orm')).default;
     if ((Orm.instance as { isView?: (name: string) => boolean })?.isView?.(modelName)) return;
 
-    switch (operation) {
-      case 'create':
-        return this._persistCreate(modelName, context, response);
-      case 'update':
-        return this._persistUpdate(modelName, context, response);
-      case 'delete':
-        return this._persistDelete(modelName, context);
-    }
+    const work = async () => {
+      switch (operation) {
+        case 'create':
+          return this._persistCreate(modelName, context, response);
+        case 'update':
+          return this._persistUpdate(modelName, context, response);
+        case 'delete':
+          return this._persistDelete(modelName, context);
+      }
+    };
+
+    // Chain through the write queue — .then(work, work) ensures the queue
+    // advances even when a previous persist rejects (#156).
+    this._writeQueue = this._writeQueue.then(work, work);
+    return this._writeQueue;
   }
 
   private async _persistCreate(modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {

package/src/record.ts

@@ -1,12 +1,29 @@
 import { store } from '@stonyx/orm';
+import log from 'stonyx/log';
 import { getComputedProperties } from "./serializer.js";
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from './plural-registry.js';
 import type Serializer from './serializer.js';
+import type { LinkageFilter } from './types/orm-types.js';
 
 interface ToJSONOptions {
   fields?: Set<string>;
   baseUrl?: string;
+  /**
+   * An ALREADY-RESOLVED linkage decision, supplied by a caller that holds the
+   * request (abofs/stonyx-orm#234). Returning `false` for a related record
+   * drops that record's `{ type, id }` from `relationships.*.data`.
+   *
+   * This method APPLIES a verdict; it never RESOLVES one -- see
+   * `src/access-verdict.ts` for the two measured reasons it cannot. ABSENT is
+   * the default and the default is TODAY'S DOCUMENT, unchanged, because
+   * `toJSON` is also the `JSON.stringify` hook and an implicit caller has no
+   * syntactic place to pass this (abofs/stonyx-orm#230).
+   *
+   * ABSENT and UNUSABLE are read differently, and the difference is a security
+   * decision -- see the three-way reading at the call site below.
+   */
+  linkage?: LinkageFilter;
 }
 
 interface SerializeOptions {
@@ -38,6 +55,25 @@ interface JSONAPIResult {
   links?: { self: string };
 }
 
+
+/**
+ * Name a non-boolean `linkage` return for the one log line that reports it.
+ *
+ * A thenable is called out BY NAME because it is the shape a consumer produces
+ * by accident -- an `async` resolver, or one that returns the promise of an
+ * authorization lookup -- and the one whose truthiness silently GRANTED every
+ * relationship before the ANSWER was checked (abofs/stonyx-orm#234).
+ */
+function describeNonVerdict(verdict: unknown): string {
+  if (verdict === null) return 'null';
+  if (Array.isArray(verdict)) return 'an array';
+
+  if ((typeof verdict === 'object' || typeof verdict === 'function')
+    && typeof (verdict as { then?: unknown }).then === 'function') return 'a Promise (or other thenable)';
+
+  return `a value of type ${typeof verdict}`;
+}
+
 export default class Record {
   /** @private */
   __data: { [key: string]: unknown } = {};
@@ -87,12 +123,15 @@ export default class Record {
 
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (Array.isArray(childRecord)) {
+        // Filter out cleaned records (those with no __model)
+        const live = childRecord.filter((r: Record) => r?.__model);
+
         // Deduplicate by record ID — keep last occurrence (latest data wins)
         const seen = new Set<unknown>();
         const unique: Record[] = [];
 
-        for (let i = childRecord.length - 1; i >= 0; i--) {
-          const r = childRecord[i] as Record;
+        for (let i = live.length - 1; i >= 0; i--) {
+          const r = live[i] as Record;
           if (!seen.has(r.id)) {
             seen.add(r.id);
             unique.push(r);
@@ -102,7 +141,7 @@ export default class Record {
         unique.reverse();
         records[key] = unique.map((r: Record) => r.serialize());
       } else {
-        records[key] = (childRecord as Record)?.serialize() ?? null;
+        records[key] = (childRecord as Record)?.__model ? (childRecord as Record).serialize() : null;
       }
     }
 
@@ -113,7 +152,13 @@ export default class Record {
   toJSON(options: ToJSONOptions = {}): JSONAPIResult {
     if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
 
-    const { fields, baseUrl } = options;
+    // DESTRUCTURED FROM A VALUE THAT IS NOT ALWAYS AN OBJECT. `toJSON` is the
+    // ECMAScript serialization hook, so `JSON.stringify({ data: record })`
+    // arrives here as `toJSON('data')` -- a STRING in the options slot.
+    // Destructuring a string yields `undefined` for every key, which is exactly
+    // the no-argument default, so the implicit path keeps working and keeps
+    // emitting today's document (abofs/stonyx-orm#230).
+    const { fields, baseUrl, linkage } = options;
     const { __data: data } = this;
     const modelName = this.__model.__name;
     const pluralizedModelName = getPluralName(modelName);
@@ -132,12 +177,143 @@ export default class Record {
       attributes[key] = (getter as () => unknown).call(this);
     }
 
+    // `linkage` is a PUBLIC option -- it is on `OrmRecord.toJSON`
+    // (src/types/orm-types.ts) and the README tells consumers to pass one -- so
+    // it arrives from outside this package, may be ANY value, and whatever it
+    // is, it gets INVOKED here. That makes this the trust boundary, and it was
+    // the LAX side of one: the internal `createLinkageFilter` coerces and
+    // try/catches the consumer predicate it wraps, while this -- the site that
+    // consumes the PUBLIC option -- did neither.
+    //
+    // THREE QUESTIONS. Every wrong answer below was measured, on a two-
+    // relationship record, emitting the full pre-#234 document or throwing out
+    // of `JSON.stringify`.
+    //
+    //   1. IS IT SUPPLIED? ABSENT (`undefined`) means no verdict was supplied:
+    //      emit today's document. Load-bearing and asserted (AC5/AC5b) --
+    //      `toJSON` is also the `JSON.stringify` hook, so the implicit caller
+    //      arrives as `toJSON('data')`, a STRING, which destructures to
+    //      `undefined` here (abofs/stonyx-orm#230).
+    //
+    //   2. IS ITS SHAPE USABLE? `[object Function]` only, because
+    //      `typeof x === 'function'` is NOT the question "can this answer a
+    //      synchronous boolean".
+    //
+    //      A NON-FUNCTION denies. Reading it as absent is what `!linkage ||`
+    //      did, and a resolver returning `null` because it could not resolve a
+    //      session is the natural shape of that value and the fail-closed
+    //      INTENT -- measured, `toJSON({ linkage: null })` emitted the full
+    //      pre-#234 linkage with no signal, byte-identical to unpatched dev.
+    //
+    //      AN `AsyncFunction`, `GeneratorFunction` or `AsyncGeneratorFunction`
+    //      denies for that SAME reason, one branch over -- and a `typeof`-only
+    //      check left the whole defect standing there. `async (type, r) =>
+    //      false` returns a PROMISE, a promise is TRUTHY, so every relationship
+    //      was emitted in full with ZERO log, again byte-identical to unpatched
+    //      dev. An awaited authorization lookup is at least as natural a
+    //      resolver as a nullish one -- the README's own Consumer Contracts
+    //      section points consumers at queue payloads and websocket frames,
+    //      where lookups are routinely awaited -- and it landed on the GRANT
+    //      side of the same branch the `null` reading closed.
+    //
+    //   3. IS ITS ANSWER A VERDICT? It must BE a boolean, not merely coerce to
+    //      one. `Boolean(...)` -- the coercion `createLinkageFilter` applies to
+    //      a consumer `access()` predicate, whose truthy contract predates this
+    //      option and is deliberately NOT changed -- is not enough here, and
+    //      was measured not to be: with `Boolean(...)` plus a try/catch in
+    //      place, `async () => false`, `function* () {}`,
+    //      `() => Promise.resolve(false)`, `() => ({})` and `() => 'no'` ALL
+    //      still emitted the full pre-#234 linkage with no log, because
+    //      truthiness is what they already had. A non-boolean is a resolver
+    //      that did not answer, and the only safe reading of a non-answer is a
+    //      denial.
+    //
+    // AND IT NEVER THROWS -- which is now true rather than only written down.
+    // A throw here escapes the enclosing `JSON.stringify` and takes
+    // `console.log` and `Orm.db.save()`'s neighbours with it, a far worse
+    // failure mode than a status. `class Klass {}`, `Klass.bind(null)` and any
+    // predicate that dereferences something undefined were all measured raising
+    // out of the `stringify`; all three are caught and denied.
+    //
+    // Logged once per DOCUMENT, not once per relationship key or per related
+    // record: an emptied relationship is deliberately indistinguishable from a
+    // genuinely empty one on the wire, so the log is the ONLY signal a consumer
+    // whose resolver quietly returned `null`, or a promise, will ever get.
+    const linkageSupplied = linkage !== undefined;
+
+    // Read the tag DEFENSIVELY. `Object.prototype.toString` consults
+    // `Symbol.toStringTag`, so a Proxy with a throwing `get` trap would throw
+    // out of the validation whose entire job is that nothing throws.
+    let linkageShape = 'a non-function';
+
+    if (typeof linkage === 'function') {
+      try {
+        linkageShape = Object.prototype.toString.call(linkage);
+      } catch {
+        linkageShape = '[object Unreadable]';
+      }
+    }
+
+    const linkageUsable = linkageShape === '[object Function]';
+
+    let linkageReported = false;
+
+    const denyAllLinkage = (reason: string) => {
+      if (linkageReported) return;
+      linkageReported = true;
+
+      log.error?.(`[@stonyx/orm] toJSON() received an unusable \`linkage\` option -- ${reason}, so ALL relationship linkage on this \`${modelName}\` document is denied.`);
+    };
+
+    if (linkageSupplied && !linkageUsable) {
+      denyAllLinkage(typeof linkage !== 'function'
+        ? `it is of type ${linkage === null ? 'null' : typeof linkage} and it must be a function`
+        : `it is ${linkageShape} and it must be a SYNCHRONOUS function -- \`toJSON\` is the \`JSON.stringify\` hook and cannot await a verdict`);
+    }
+
+    const linkageVerdict: LinkageFilter | undefined = !linkageSupplied
+      ? undefined
+      : linkageUsable ? linkage as LinkageFilter : () => false;
+
+    // Applied per related record, alongside the existing `__model` liveness
+    // check, and producing exactly the shapes that check already produces: a
+    // dropped hasMany member leaves `data: []`, a dropped belongsTo leaves
+    // `data: null`. Both already ship -- a genuinely-empty hasMany emits
+    // `data: []` with links, and a cleaned belongsTo emits `data: null` -- so a
+    // filtered relationship is BYTE-IDENTICAL to an empty one and there is no
+    // new wire shape and no oracle.
+    const isLinkable = (r: Record): boolean => {
+      if (!linkageVerdict) return true;
+
+      try {
+        const verdict = linkageVerdict(r.__model.__name, r);
+
+        if (typeof verdict === 'boolean') return verdict;
+
+        denyAllLinkage(`it answered with ${describeNonVerdict(verdict)} rather than a boolean`);
+      } catch (error) {
+        // Building the report is itself a throw site -- `throw Symbol('x')`
+        // makes `String(error)` throw, and a getter on `.message` can throw --
+        // and a throw from the reporter would escape the catch that exists so
+        // that nothing escapes.
+        let detail = 'a value that could not be described';
+
+        try {
+          detail = error instanceof Error ? error.message : String(error);
+        } catch { /* keep the fallback -- the denial matters, the text does not */ }
+
+        denyAllLinkage(`it threw (${detail})`);
+      }
+
+      return false;
+    };
+
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (fields && !fields.has(key)) continue;
 
       const relationshipData = Array.isArray(childRecord)
-        ? childRecord.map((r: Record) => ({ type: r.__model.__name, id: r.id }))
-        : childRecord ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
+        ? childRecord.filter((r: Record) => r?.__model).filter(isLinkable).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
+        : (childRecord && (childRecord as Record).__model && isLinkable(childRecord as Record)) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
 
       // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
       const dasherizedKey = camelCaseToKebabCase(key);

package/src/relationships.ts

@@ -51,4 +51,4 @@ export function getPendingBelongsToRegistry(): PendingBelongsToMap {
   return relationships.get('pendingBelongsTo') as PendingBelongsToMap;
 }
 
-export const TYPES: string[] = ['global', 'hasMany', 'belongsTo', 'pending'];
+export const TYPES: string[] = ['global', 'hasMany', 'belongsTo', 'pending', 'pendingBelongsTo'];

package/src/serializer.ts

@@ -94,8 +94,45 @@ export default class Serializer {
         const handlerOptions = { ...options, _relationshipKey: key };
         const childRecord = handler(record, data, handlerOptions);
 
-        rec[key] = childRecord;
-        relatedRecords[key] = childRecord;
+        // hasMany relationships use a getter so format()/toJSON() always read
+        // the live registry array instead of a stale snapshot captured at
+        // serialization time.  This is critical when child records are created
+        // in a later async frame — the belongsTo inverse wiring pushes into
+        // the shared registry array, and the getter ensures the parent sees it.
+        const isHasMany = (handler as { __relationshipType?: string }).__relationshipType === 'hasMany';
+
+        if (isHasMany) {
+          // `childRecord` IS the shared registry array — define a getter that
+          // always dereferences through the same array reference.
+          const registryArray = childRecord as unknown[];
+          Object.defineProperty(rec, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => registryArray,
+            set(v: unknown) { relatedRecords[key] = v; }
+          });
+          Object.defineProperty(relatedRecords, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => registryArray,
+            set(v: unknown) { Object.defineProperty(relatedRecords, key, { value: v, writable: true, enumerable: true, configurable: true }); }
+          });
+        } else {
+          rec[key] = childRecord;
+          relatedRecords[key] = childRecord;
+
+          // Preserve the raw FK value in __data when the belongsTo handler
+          // couldn't resolve the target (e.g., memory:false model not loaded).
+          // This allows adapters to read the FK from __data as a fallback
+          // when __relationships[key] is null.  Only store when `data` is a
+          // truthy non-object — i.e., a raw FK string/number that the handler
+          // attempted but failed to resolve.  When `data` is null/undefined
+          // (optional empty relationship) we intentionally skip to preserve
+          // the existing behavior of not populating __data for empty FKs.
+          if (childRecord === null && data && typeof data !== 'object') {
+            parsedData[key] = data;
+          }
+        }
 
         continue;
       }

package/src/setup-rest-server.ts

@@ -1,5 +1,5 @@
 import { waitForModule } from 'stonyx';
-import { store } from '@stonyx/orm';
+import Orm, { store } from '@stonyx/orm';
 import OrmRequest from './orm-request.js';
 import MetaRequest from './meta-request.js';
 import RestServer from '@stonyx/rest-server';
@@ -7,14 +7,20 @@ import { forEachFileImport } from '@stonyx/utils/file';
 import { dbKey } from './db.js';
 import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
+import type { AccessFunction } from './types/orm-types.js';
 
 interface AccessInstance {
   models: string[] | '*';
-  access: (request: unknown) => unknown;
+  /**
+   * The consumer predicate. Called as `access(request, { model, operation })`
+   * -- the second argument is additive (abofs/stonyx-orm#202), so a predicate
+   * declared with a single parameter is still valid and still works.
+   */
+  access: AccessFunction;
 }
 
 export default async function(route: string, accessPath: string, metaRoute: boolean): Promise<void> {
-  const accessFiles: Record<string, (request: unknown) => unknown> = {};
+  const accessFunctions: Record<string, AccessFunction> = {};
 
   try {
     await forEachFileImport(accessPath, (accessClass: unknown) => {
@@ -31,9 +37,9 @@ export default async function(route: string, accessPath: string, metaRoute: bool
       for (const model of models === '*' ? availableModels : models) {
         if (model === dbKey) continue;
         if (!store.data.has(model)) throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
-        if (accessFiles![model]) throw new Error(`Access for model "${model}" has already been defined by another access class.`);
+        if (accessFunctions![model]) throw new Error(`Access for model "${model}" has already been defined by another access class.`);
 
-        accessFiles![model] = accessInstance.access;
+        accessFunctions![model] = accessInstance.access;
       }
     });
   } catch (error) {
@@ -41,13 +47,60 @@ export default async function(route: string, accessPath: string, metaRoute: bool
     log.warn?.('You must define a valid access configuration file in order to access ORM generated REST endpoints.');
   }
 
+  // -------------------------------------------------------------------------
+  // #202 -- the registry has to survive this function.
+  //
+  // `accessFunctions` used to be a function-local that was discarded at the return
+  // below, so the only thing that ever saw it was the mount loop. Each mounted
+  // OrmRequest then held its OWN model's predicate and nothing held the map, so
+  // at request time there was no route from a model NAME to that model's
+  // predicate -- which is what abofs/stonyx-orm#196 and #207 need in order to
+  // ask model X's predicate about a request routed to model Y.
+  //
+  // Published BEFORE `await waitForModule('rest-server')`, deliberately: that
+  // await is the ONLY yield point in this function, and the rest-server module
+  // may already be listening by the time it reports ready, so an assignment
+  // after it would leave a window in which a route is live and the registry is
+  // not.
+  //
+  // It is NOT before the mount loop for that reason, and the comment here used
+  // to say it was. `RestServer.mountRoute` is fully synchronous -- construct,
+  // registerCalls(), api.use() -- and nothing between the loop and this
+  // function's closing brace yields, so the event loop cannot deliver a request
+  // in there and the window that clause described cannot open. Measured:
+  // moving this assignment to the last statement of the function leaves the
+  // suite at 951 pass / 0 fail. Being ahead of the mount loop is free and
+  // harmless; it is not what makes the ordering correct.
+  //
+  // Assigned unconditionally, including when the try above failed and the map
+  // is empty or partial: the mount loop below is driven by this exact object,
+  // so at the moment of assignment whatever is reachable through
+  // `Orm.instance` is the same set of predicates that is about to enforce.
+  // A guard such as `if (Object.keys(accessFunctions).length)` would let the
+  // registry go silently missing on a total load failure, and a later consumer
+  // would read `undefined` from `getAccess` and have to distinguish "no access
+  // class" from "the registry was never published" -- which it cannot. That is
+  // the reasoning, and it is REASONING, not something this suite tests: the
+  // guarded variant is also 951 pass / 0 fail, AC8 included, because every boot
+  // in this suite loads a non-empty access map so the guard never fires. AC8
+  // demonstrably cannot catch it. Catching it needs a boot with
+  // `orm.paths.access` pointed at an empty directory, which this suite has no
+  // harness for.
+  //
+  // One further limit on "by construction": the mount loop passes `access` BY
+  // VALUE into each OrmRequest, so the enforcing set is a snapshot taken here,
+  // while `getAccess` reads the map live. The two are the same set at boot and
+  // stay the same set only for as long as nobody writes to the public field.
+  // The equality is a boot-time fact, not an invariant.
+  Orm.instance.accessFunctions = accessFunctions;
+
   await waitForModule('rest-server');
 
   // Remove "/" prefix and name mount point accordingly
   const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
 
   // Configure endpoints for models and views with access configuration
-  for (const [model, access] of Object.entries(accessFiles!)) {
+  for (const [model, access] of Object.entries(accessFunctions!)) {
     const pluralizedModel = getPluralName(model);
     const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
     RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });

package/src/standalone-db.ts

@@ -8,6 +8,10 @@
 
 import fs from 'fs/promises';
 import path from 'path';
+// `./utils.js` pulls in `@stonyx/utils/string` and nothing else -- no ORM
+// bootstrap, no `@stonyx/orm` index, no side effects -- so the "no framework
+// dependencies" property above still holds.
+import { maxNumericId } from './utils.js';
 
 interface StandaloneDBOptions {
   dbPath?: string;
@@ -131,12 +135,19 @@ export default class StandaloneDB {
     const records = await this.readCollection(collection);
 
     if (!data.id) {
-      const maxId = records.reduce((max, r) => {
-        const rid = typeof r.id === 'number' ? r.id : 0;
-        return rid > max ? rid : max;
-      }, 0);
-
-      data.id = maxId + 1;
+      // SHARED WITH `assignRecordId` (src/manage-record.ts), which is the other
+      // place this repo picks a server-assigned id. It was a second copy of the
+      // reduce, and nothing here pointed at it — a maintainer editing this
+      // method could not discover the other existed. See `maxNumericId` for why
+      // it is not `Math.max` (abofs/stonyx-orm#203).
+      //
+      // THE TWO ARE NOT THE SAME FUNCTION beyond this line, deliberately.
+      // `StandaloneDB` has no model, id-type or transform concept, so `maxId + 1`
+      // IS its store key; `assignRecordId` has to map the candidate through the
+      // model's declared id transform first, and then walk past occupied keys.
+      // Transplanting this method's remaining logic into the ORM reproduces
+      // #203's landing-key defect exactly — which is what AC4 pins.
+      data.id = maxNumericId(records) + 1;
     }
 
     // Check for duplicate id