@stonyx/orm 0.3.2-alpha.66 → 0.3.2-alpha.68

package/dist/utils.js

@@ -15,3 +15,50 @@ export function pluralize(word) {
     }
     return basePluralize(word);
 }
+/**
+ * The highest NUMERIC id held by a set of records, or `0` when there is none.
+ *
+ * ONE COPY, and the duplication it replaces is the reason it lives here. Three
+ * near-identical reduces existed at once: `assignRecordId` (server-assigned id
+ * selection), `StandaloneDB.create` (src/standalone-db.ts) and the #203 test
+ * helper. `docs/improvements.md`'s standing WET Code category prescribes
+ * exactly this remedy -- extract into the module that already acts as the
+ * shared utility -- and `assignRecordId` already imported `isOrmRecord` from
+ * here.
+ *
+ * NON-NUMBERS ARE SKIPPED RATHER THAN COERCED TO `0`, AND THAT IS STYLISTIC.
+ * `StandaloneDB`'s shape mapped them to `0`, which can never beat a seed of
+ * `0`. Measured over eleven input classes (`[]`, `1`, `NaN`, `'5'`, `'abc'`,
+ * `-3`, `0`, `null`, `undefined`, `Infinity`, and mixed arrays) the two shapes
+ * produce IDENTICAL output on every one. In particular `typeof NaN` is
+ * `'number'`, so NEITHER shape coerces `NaN` -- both reject it on `NaN > max`,
+ * which is `false`. An earlier revision of this code asserted that the skip was
+ * what made the `NaN` case work; it is not, the comparison is, and that claim
+ * has been removed rather than left standing.
+ *
+ * WHAT IS LOAD-BEARING is that this is not `Math.max(...ids)`. `Math.max`
+ * returns `NaN` if any operand is `NaN`, and a record CAN be held under the key
+ * `NaN` -- so the obvious fix assigns `NaN`, lands on that slot and overwrites
+ * it, which is abofs/stonyx-orm#203 in a new disguise. Pinned by
+ * test/unit/assign-record-id-test.ts AC2; before that file existed the whole
+ * suite scored 951/0 under exactly that fix.
+ */
+export function maxNumericId(records) {
+    return records.reduce((max, record) => {
+        const { id } = record;
+        return typeof id === 'number' && id > max ? id : max;
+    }, 0);
+}
+/**
+ * The message prefix `assignRecordId` throws with when no free id can be
+ * derived for a model, and the ONE string `createHandler` matches on to answer
+ * `409` instead of letting the rejection reach express's default handler.
+ *
+ * It lives here rather than in either file because both need it and neither
+ * should own a copy: a literal in two places is how the two id coercions in
+ * orm-request.ts drifted apart (see `coerceId`). The repo has no error codes
+ * and no custom error classes -- 24 bare `throw new Error` sites across `src/`
+ * -- so a shared prefix is the narrowest way to make ONE failure distinguishable
+ * without inventing an error taxonomy this codebase does not use.
+ */
+export const NO_FREE_ID_ERROR = 'Cannot assign record ID: no free id available';

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.66",
+  "version": "0.3.2-alpha.68",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/access-verdict.ts

@@ -0,0 +1,222 @@
+/**
+ * The shared access-verdict primitive (abofs/stonyx-orm#234).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: ONE INTERPRETER, NOT TWO
+ * ---------------------------------------------------------------------------
+ * A consumer `access()` may return six differently-shaped things -- `false`, a
+ * bare permission string, a permission array, `true`, a per-record function, or
+ * something the contract does not define at all -- and the reading of each one
+ * is a security decision. `auth()` has held that reading inline since #190.
+ * Every surface that needs to ask "may this caller see model X's record?" needs
+ * the SAME reading, or the second copy becomes an unreviewed second
+ * authorization vocabulary that answers differently about the same value.
+ *
+ * So `interpretAccess` is extracted here and `auth()` now calls it. It is the
+ * only place a return shape is classified, and abofs/stonyx-orm#232 and #233
+ * rebase onto it rather than re-deriving it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT A LINKAGE FILTER IS, AND WHY THE CALLER BUILDS IT
+ * ---------------------------------------------------------------------------
+ * `Record.toJSON()` APPLIES a verdict; it never RESOLVES one. That is not a
+ * style choice, it is forced, and it was measured before it was decided:
+ *
+ *   INPUT: origin/dev @ c5f7907, unpatched                  -> 967 pass / 0 fail
+ *   INPUT: same + fail-closed resolution INSIDE toJSON()    -> 964 pass / 3 fail
+ *
+ * and all three reds were over-denial of PERMITTED records, not the leak. Two
+ * independent reasons:
+ *
+ *   1. `toJSON()` has no request. The shipped, documented sample reads
+ *      `request.path` for its `/archived` sub-path rule -- the one read of
+ *      argument one the README sanctions -- and fail-closes when it is absent.
+ *      Measured against the live registry:
+ *
+ *        getAccess('owner')(undefined, { model:'owner',  operation:'read' }) -> false
+ *        getAccess('animal')(undefined,{ model:'animal', operation:'read' }) -> [Function]
+ *
+ *      Same predicate object, two models, two different degradation modes,
+ *      chosen by the consumer. Without a request there is no trustworthy
+ *      answer to get.
+ *
+ *   2. `toJSON` is also the `JSON.stringify` hook, so `JSON.stringify({data:
+ *      record})` calls `record.toJSON('data')` -- a STRING in the options slot.
+ *      An implicit caller has no syntactic place to pass anything
+ *      (abofs/stonyx-orm#230). The no-argument document must therefore stay
+ *      byte-identical to what shipped, which also rules out fail-closed by
+ *      default: `Orm.instance.accessFunctions` is `{}` in any process that
+ *      never ran `setup-rest-server` (CLI, SQL-only, unit tests), so a
+ *      fail-closed default would empty every relationship on every document in
+ *      processes that have no REST surface to protect.
+ *
+ * The caller -- which still holds the request -- resolves the predicate,
+ * interprets it here, caches the answer, and hands `toJSON()` an already-decided
+ * `(type, record) => boolean`.
+ */
+import Orm from '@stonyx/orm';
+import log from 'stonyx/log';
+import type { AccessMethod, AccessOperation } from './types/orm-types.js';
+
+/**
+ * The classified reading of one `access()` return value.
+ *
+ * `granted: false` is a total denial. `granted: true` with no `filter` is an
+ * unconditional grant. `granted: true` WITH a filter means "grant, subject to
+ * this per-record predicate" -- the function return shape, which is the
+ * per-record hook `AccessContext` deliberately does not provide.
+ */
+export interface AccessVerdict {
+  granted: boolean;
+  filter?: (record: unknown) => boolean;
+}
+
+/**
+ * A resolved, request-scoped linkage decision: may `record` of model `type` be
+ * NAMED, by id, inside another model's document?
+ *
+ * Arity is `(type, record)` and not `(type, id)` because the per-record filter
+ * the consumer returns is handed the RECORD -- this repo's own fixture reads
+ * `record.owner?.id`, not just `record.id`. The `(type, id)` pair is the CACHE
+ * key, not the input.
+ */
+export type LinkageFilter = (type: string, record: unknown) => boolean;
+
+const DENIED: AccessVerdict = Object.freeze({ granted: false });
+const GRANTED: AccessVerdict = Object.freeze({ granted: true });
+
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict {
+  if (!access) return DENIED;
+
+  // The function return shape IS the per-record hook. Grant the request and
+  // carry the predicate; the caller applies it per record.
+  if (typeof access === 'function') return { granted: true, filter: access as (record: unknown) => boolean };
+
+  if (access === true) return GRANTED;
+
+  // `AccessMethod` declares `string` legal and it fell through every branch
+  // above. A bare string is ONE permission, not a grant of all four -- reading
+  // it as a full grant is what once let `return 'read'` authorise DELETE.
+  const permitted = typeof access === 'string' ? [access] : access;
+
+  // Anything that is not a permission array by this point -- an object, a
+  // number, a Symbol -- is a consumer mistake, and the only safe reading of a
+  // shape the contract does not define is a denial. Fail CLOSED.
+  if (!Array.isArray(permitted)) return DENIED;
+  if (!permitted.includes(operation as string)) return DENIED;
+
+  return GRANTED;
+}
+
+/**
+ * Resolve model `type`'s verdict for a read, against the live `request`.
+ *
+ * Fails closed on both ambiguous inputs:
+ *
+ *   - `getAccess(type)` -> `undefined`. That is NOT "this model is
+ *     unrestricted". `setup-rest-server` catches an access-class load failure,
+ *     warns, and publishes whatever PARTIAL map it had, so `undefined` covers
+ *     both "no access class claims this model" and "the class that claims it
+ *     failed to load" -- and the caller cannot tell them apart. Deny.
+ *   - the predicate THROWS. Same reading `auth()` and `isDenied` already use:
+ *     a throw is a denial, logged, never a 500 and never a grant.
+ *
+ * NOTE ON CROSS-MODEL ASKS. The predicate is asked about `type` while the
+ * request in hand was dispatched to a DIFFERENT model's route. Since #222 this
+ * repo's fixture reads `context.model` and answers correctly; a consumer's
+ * arity-1 predicate does not, and there is no supported way to tell which kind
+ * was resolved (the boot-time arity warning is abofs/stonyx-orm#213). A
+ * consequence to expect rather than debug: the fixture's surviving `request.path`
+ * read means asking the OWNER predicate on a request dispatched to
+ * `GET /animals/archived` returns a bare `false`. That is a whole-request deny
+ * bleeding across models -- harmless, because it is the fail-closed direction,
+ * and it is treated as "deny this linkage", not as an error.
+ */
+function resolveVerdict(request: unknown, type: string): AccessVerdict {
+  const predicate = Orm.instance?.getAccess?.(type);
+  if (typeof predicate !== 'function') return DENIED;
+
+  let access: AccessMethod;
+
+  try {
+    access = predicate(request, { model: type, operation: 'read' });
+  } catch (error) {
+    log.error?.(`[@stonyx/orm] access() threw while resolving linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+
+    return DENIED;
+  }
+
+  return interpretAccess(access, 'read');
+}
+
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite: `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay distinct, where `` `${type}:${id}` ``
+ * would collapse them and let one model's verdict answer for another record.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ */
+export function createLinkageFilter(request: unknown): LinkageFilter {
+  const byType = new Map<string, { verdict: AccessVerdict; decisions: Map<unknown, boolean> }>();
+
+  return function isLinkable(type: string, record: unknown): boolean {
+    let entry = byType.get(type);
+
+    if (!entry) {
+      entry = { verdict: resolveVerdict(request, type), decisions: new Map() };
+      byType.set(type, entry);
+    }
+
+    const { verdict, decisions } = entry;
+
+    if (!verdict.granted) return false;
+    if (!verdict.filter) return true;
+
+    const id = (record as { id?: unknown } | null)?.id;
+    const cached = decisions.get(id);
+    if (cached !== undefined) return cached;
+
+    let allowed: boolean;
+
+    try {
+      allowed = Boolean(verdict.filter(record));
+    } catch (error) {
+      // A predicate that throws is a denial -- the same reading `isDenied` uses
+      // one layer down. Logged, because a predicate that throws on every record
+      // empties every relationship and, silently, that is indistinguishable
+      // from a database with no relationships in it.
+      log.error?.(`[@stonyx/orm] access filter threw while filtering linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+
+      allowed = false;
+    }
+
+    decisions.set(id, allowed);
+
+    return allowed;
+  };
+}

package/src/manage-record.ts

@@ -2,7 +2,7 @@ import Orm, { store } from '@stonyx/orm';
 import OrmRecord from './record.js';
 import { getGlobalRegistry, getPendingRegistry, getPendingBelongsToRegistry, getBelongsToRegistry, getHasManyRegistry } from './relationships.js';
 import type Serializer from './serializer.js';
-import { isOrmRecord } from './utils.js';
+import { isOrmRecord, maxNumericId, NO_FREE_ID_ERROR } from './utils.js';
 
 interface CreateRecordOptions {
   isDbRecord?: boolean;
@@ -195,17 +195,58 @@ export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: C
 }
 
 /**
- * gets the next available id based on last record entry.
+ * gets the next available id, based on the HIGHEST id present.
  *
  * In MySQL mode with numeric IDs, assigns a temporary pending ID.
  * MySQL's AUTO_INCREMENT provides the real ID after INSERT.
+ *
+ * ---------------------------------------------------------------------------
+ * WAS: `Array.from(storeMap.values()).at(-1).id + 1` — the LAST INSERTED id,
+ * not the maximum (abofs/stonyx-orm#203). The store is a Map, so insertion
+ * order stops being ascending the moment a record is deleted and recreated, a
+ * db.json is written out of order, a directory-mode store is read back in file
+ * order, or a caller POSTs a high id and then a low one. After that, every
+ * server-assigned id is one that is ALREADY TAKEN — and `createRecord`'s
+ * last-entry-wins branch then overwrites that record IN PLACE and answers 200.
+ * No error, no 409, and the store's size does not change. That is the whole
+ * defect, and it is reachable from a create with NO id at all, which is the
+ * most ordinary write a consumer performs.
+ *
+ * Covered by test/unit/assign-record-id-test.ts. Note for anyone changing this
+ * function: before that file existed, the whole suite scored 951/0 both on the
+ * defect and on a naive `Math.max` fix that introduced a second one. A green
+ * suite is not evidence here; those assertions are.
+ * ---------------------------------------------------------------------------
  */
 function assignRecordId(modelName: string, rawData: { [key: string]: unknown }): void {
-  if (rawData.id) return;
+  // PRESENCE, not truthiness. `0` is a legal value for an `attr('number')` id,
+  // and `if (rawData.id) return` silently reassigned it, handing the caller back
+  // a different record than the one it named (#203).
+  //
+  // `''` is deliberately NOT honoured here and this is not an oversight: it is
+  // the one string that means "no id". `parseInt('')` is `NaN`, a record CAN be
+  // held under the key `NaN`, and orm-request.ts's body-id normalisation relies
+  // on `''` staying absent — otherwise `POST {"id":""}` answers 409 against a
+  // record it never named.
+  //
+  // WHAT WIDENING THIS TO `!== undefined` ACTUALLY DOES, measured rather than
+  // asserted: `{id: ''}` early-returns, `parseInt('')` NaNs it, and the record
+  // lands on the store's `NaN` slot and OVERWRITES whatever is there — #203's
+  // own defect class. It does NOT turn access-filter-enforcement-test.ts
+  // assertion 44 red; an earlier revision of this comment claimed it did, which
+  // converted an unknown into a false assurance. AC6's BOUNDARY assertions are
+  // what catch it, and they only do so because they seed the `NaN` slot first.
+  if (rawData.id || rawData.id === 0) return;
 
   // In SQL mode with numeric IDs, defer to database auto-increment.
   // Use unique negative integers — they survive the number transform (parseInt preserves negatives)
   // and avoid NaN store-key collisions that string pending IDs caused.
+  //
+  // This early return is ABOVE the max computation on purpose: a pending
+  // negative must never be a candidate for, or be perturbed by, the max path.
+  // Pinned directly (AC5.3) rather than by asserting the max is unaffected —
+  // that assertion could not have failed, because nothing negative ever reaches
+  // the code below.
   if (Orm.instance?.sqlDb && !isStringIdModel(modelName)) {
     rawData.id = -(++pendingIdCounter);
     rawData.__pendingSqlId = true;
@@ -215,15 +256,218 @@ function assignRecordId(modelName: string, rawData: { [key: string]: unknown }):
   const storeMap = store.get(modelName);
   if (!storeMap) throw new Error(`Cannot assign record ID: model "${modelName}" not found in store`);
   const modelStore = Array.from(storeMap.values()).filter(isOrmRecord);
-  const lastRecord = modelStore.at(-1);
-  rawData.id = lastRecord ? (lastRecord.id as number) + 1 : 1;
+
+  // ONE COPY of the max-numeric-id reduce, in src/utils.ts. There were three
+  // (here, StandaloneDB.create, and the #203 test helper) and `docs/
+  // improvements.md`'s WET Code category prescribes the extraction. What that
+  // helper must NOT be is `Math.max(...ids)`; the reason is measured and it is
+  // documented at the helper rather than duplicated here. Pinned by AC2.
+  const maxId = maxNumericId(modelStore);
+
+  // THE OCCUPANCY CHECK RUNS ON THE LANDING KEY, NOT ON THE RAW CANDIDATE, and
+  // the difference is a silent data loss rather than a nicety.
+  //
+  // `createRecord` looks the record up under `rawData.id` (:50) but WRITES it
+  // under `record.id` (:69) — the value after the model's declared id transform
+  // has run inside `serialize`. When the transform is not the identity those two
+  // differ, so a guard written as `storeMap.has(rawData.id)` checks a key the
+  // record will never occupy, misses an occupied slot and overwrites it —
+  // measured on an `uppercase`-id model: the guard checks `owner-1`, the record
+  // lands under `OWNER-1`, store size unchanged, no error. That is
+  // abofs/stonyx-orm#205's lookup-key/landing-key divergence reappearing inside
+  // #203's own fix, which is why AC4 exists and why `rawData.id` is set to the
+  // LANDING key below.
+  //
+  // THE SCOPE OF THAT CLAIM, stated rather than implied. Setting `rawData.id` to
+  // the landing key makes :50 and :69 agree for every IDEMPOTENT id transform —
+  // `number`, `float`, `string`, `passthrough`, `uppercase`, `trim`. It does NOT
+  // make them agree for `date` or `timestamp`: `transforms.date` returns a NEW
+  // object every call and a `Map` keys by identity, so `storeMap.has(landingKey)`
+  // is always `false` there and the occupancy check is vacuous. `dev` is broken
+  // for those types too — this is not a regression — but no comment here may
+  // claim a property it was not measured to have (#212 § AC5).
+  //
+  // Resolved ONCE, outside the walk: `getIdType` instantiates the model class,
+  // so resolving it per candidate would put a model construction on every
+  // iteration of a loop that exists to walk past occupied slots.
+  const toStoreKey = storeKeyDeriver(modelName);
+
+  // DOES THIS MODEL FILE ITS RECORDS UNDER STRING KEYS? Decided by RUNNING the
+  // model's own id transform once, not by matching a type NAME against a list:
+  // `Orm.instance.transforms` (main.ts:70) is a public, MUTABLE instance
+  // property, so any enumeration of "the string-ish types" written here would be
+  // wrong the moment a consumer registers one.
+  const stringKeyed = typeof toStoreKey(maxId + 1) === 'string';
+
+  // THE CANDIDATE FOR A STRING-KEYED MODEL IS NOT A BARE NUMBER, and this is
+  // abofs/stonyx-orm#209 — which is REOPENED — not aesthetics.
+  //
+  // `orm-request.ts`'s `coerceId` (:322) resolves a NUMERIC-LOOKING string to a
+  // NUMBER on every id-bearing surface, while a model declaring
+  // `id = attr('string')` files under the STRING key. So a server-assigned `'1'`
+  // produces a record that is created and then NOT ADDRESSABLE. Measured over
+  // the route, owner store `{'1': ...}`:
+  //
+  //   GET    /owners/1       -> 404      (the record exists)
+  //   DELETE /owners/1       -> 404
+  //   GET    /owners/owner-1 -> 200
+  //
+  // and `_withHooks` (:1185) hands an after-`create` hook
+  // `context.record === undefined` for the same reason. `dev` assigned `'bob1'`,
+  // which is not numeric-looking, so `dev` has neither problem: a bare-number
+  // candidate would move #209 from "a caller supplied a numeric-looking id" onto
+  // the DEFAULT path for every server-assigned create on every string-id model.
+  // Prefixing with the model name keeps #209's population exactly as narrow as
+  // it already was, without touching the one shared coercion or the assertion
+  // that pins #209 open. Pinned by AC3.
+  const toCandidate = stringKeyed
+    ? (value: number) => `${modelName}-${value}`
+    : (value: number) => value;
+
+  // `maxId + 1` is the id AC1 pins: strictly greater than every numeric key
+  // present. IT IS NOT ALWAYS AVAILABLE, and that gap was a live denial of
+  // service. Float64 has no integer successor at or above 2^53, so
+  // `maxId + 1 === maxId` for every `maxId >= 9007199254740992` and `+ 1` inside
+  // the walk is a NO-OP there. One record filed under that key — which an
+  // unauthenticated `POST {"id":9007199254740992}` puts there, and which reaches
+  // even a filter-protected collection through has-many.ts:65 (#207), a channel
+  // GATE 0 does not cover — made the walk unable to advance, so it exhausted its
+  // budget and threw on EVERY subsequent server-assigned create, permanently,
+  // until that record was deleted. Measured over the route: 200, then 500 for
+  // every no-id create. `dev` answers 200.
+  //
+  // So a store holding one adversarial record must not disable its collection.
+  // When "above the max" is not a usable strategy the walk RESTARTS FROM 1: the
+  // store holds at most `size` keys, so one of `1 .. size + 1` is always free
+  // under an injective id transform. Pinned by AC7.
+  const start = maxId + 1;
+  let landingKey = firstFreeKey(storeMap, toStoreKey, toCandidate, start);
+
+  // THE RESTART, and it is the whole of the ceiling fix. Killing mutation:
+  // delete this block -> AC7 goes red (the route answers 409 instead of the
+  // created resource).
+  if (landingKey === NO_FREE_KEY && start !== 1) {
+    landingKey = firstFreeKey(storeMap, toStoreKey, toCandidate, 1);
+  }
+
+  if (landingKey === NO_FREE_KEY) {
+    // Reachable only with a NON-INJECTIVE id transform — see `firstFreeKey`.
+    // `createHandler` matches this message and answers 409 rather than letting it
+    // reach express's default handler, which serialises a stack trace with
+    // absolute install paths outside NODE_ENV=production (the hazard
+    // orm-request.ts:553-558 exists to name). Pinned by AC8.
+    throw new Error(`${NO_FREE_ID_ERROR} for model "${modelName}"`);
+  }
+
+  rawData.id = landingKey;
 }
 
-function isStringIdModel(modelName: string): boolean {
-  const modelClass = Orm.instance.getRecordClasses(modelName).modelClass as (new (name: string) => { [key: string]: unknown }) | undefined;
-  if (!modelClass) return false;
+// Returned instead of a key so that "no key" cannot be confused with a transform
+// that legitimately produced `undefined` or `null`.
+const NO_FREE_KEY = Symbol('no free store key');
+
+/**
+ * The first store key at or above `start` that no record occupies, walking
+ * candidate ids upward, or `NO_FREE_KEY` if the walk cannot reach one.
+ */
+function firstFreeKey(
+  storeMap: Map<number | string, unknown>,
+  toStoreKey: (value: number | string) => number | string,
+  toCandidate: (value: number) => number | string,
+  start: number
+): number | string | typeof NO_FREE_KEY {
+  let candidate = start;
+  let landingKey = toStoreKey(toCandidate(candidate));
+  let attempts = 0;
+
+  while (storeMap.has(landingKey)) {
+    // THE BOUND IS EXACTLY TIGHT, not conservative: this walk tries
+    // `storeMap.size + 1` DISTINCT candidates against at most `storeMap.size`
+    // occupied keys, so under an injective `toStoreKey` it provably cannot fire.
+    // Under a non-injective one it provably terminates — and that is a reachable
+    // consumer state rather than a hypothesis: `transforms.boolean`
+    // (transforms.ts:4) collapses every candidate onto `true`/`false`, and
+    // `Orm.instance.transforms` (main.ts:70) is public and MUTABLE, so a consumer
+    // can register an arbitrary non-injective transform and name it as an id
+    // type. Without this, a no-id create spins forever inside a synchronous store
+    // walk and pins a worker, which is worse than either collision policy. Its
+    // EXISTENCE and its THRESHOLD are both pinned by AC8: deleting it makes AC8
+    // HANG rather than fail, and weakening it to fire on the first collision
+    // makes AC8.1 red.
+    if (++attempts > storeMap.size) return NO_FREE_KEY;
+
+    // NOTE FOR ANYONE ADDING A SECOND EXIT HERE. A `candidate + 1 === candidate`
+    // float-saturation check was written, measured, and REMOVED: with the
+    // restart-from-1 above in place, deleting the saturation check leaves the
+    // whole suite green, because the budget reaches the same `NO_FREE_KEY` one
+    // pass later and the restart still answers. An unkillable guard in a change
+    // whose deliverable is falsifiable coverage is exactly what this story exists
+    // to stop shipping. `+ 1` being a no-op at 2^53 costs `size` extra `Map.has`
+    // calls on that one path and changes no outcome.
+    candidate += 1;
+    landingKey = toStoreKey(toCandidate(candidate));
+  }
+
+  return landingKey;
+}
+
+/**
+ * Returns the derivation that maps an id VALUE to the store KEY a record
+ * carrying it will actually be filed under — the model's declared id transform,
+ * the same one `serialize` runs at createRecord:68 before the `.set` at :69.
+ */
+function storeKeyDeriver(modelName: string): (value: number | string) => number | string {
+  const idType = getIdType(modelName);
+  const transform = idType ? Orm.instance?.transforms?.[idType] : undefined;
+
+  // SURVIVOR, RETAINED, with its reachability condition stated rather than left
+  // silent — `docs/project-structure.md` § "unkillable code reads as coverage and
+  // is not" is the standing rule and it applies outside orm-request.ts too.
+  //
+  // No mutation in this repo can kill this branch, and that is STRUCTURAL rather
+  // than an untested gap: `Model` declares `id = attr('number')` (model.ts:15) so
+  // every registered model has an id type; `ModelProperty` refuses a type with no
+  // registered transform (model-property.ts:4) so a declared type always
+  // resolves; and `getIdType` can therefore only return `undefined` when
+  // `getRecordClasses` yields no `modelClass` — in which case `createRecord`
+  // throws at :62 a few lines later regardless, so no record is ever filed
+  // through this branch.
+  //
+  // BECOMES REACHABLE if a model can be declared without an `id` property, if a
+  // store map can exist for a model with no registered class, or if
+  // `createRecord` stops constructing the model class. Kept rather than deleted
+  // because the alternative on that path is a `transform is not a function`
+  // TypeError, and because identity is exactly what `createRecord` would file
+  // under when no transform exists — the two agree, which is the property AC4 is
+  // about.
+  if (typeof transform !== 'function') return value => value;
+
+  return value => {
+    try {
+      return transform(value) as number | string;
+    } catch {
+      // `uppercase` and `trim` (transforms.ts:11-12) call a string method on the
+      // value directly, so a NUMERIC candidate throws `value?.toUpperCase is not
+      // a function`. On `dev` they never saw one — `lastRecord.id + 1` on a
+      // string id is a string — so feeding them a number here would regress a
+      // legal, registered id type into an uncaught 500. The retry feeds the
+      // string form, which is the shape an id actually arrives in off a JSON body
+      // or a URL param. A transform that throws on BOTH shapes still propagates.
+      // Pinned by AC9.
+      return transform(String(value)) as number | string;
+    }
+  };
+}
+
+function getIdType(modelName: string): string | undefined {
+  const modelClass = Orm.instance?.getRecordClasses(modelName).modelClass as (new (name: string) => { [key: string]: unknown }) | undefined;
+  if (!modelClass) return undefined;
 
   const model = new modelClass(modelName);
 
-  return (model.id as { type?: string } | undefined)?.type === 'string';
+  return (model.id as { type?: string } | undefined)?.type;
+}
+
+function isStringIdModel(modelName: string): boolean {
+  return getIdType(modelName) === 'string';
 }