@stonyx/orm 0.3.2-alpha.105 → 0.3.2-alpha.106

package/README.md

@@ -322,19 +322,17 @@ export default class OwnerAccess {
   models = ['owner'];
 
   access(request) {
-    // `access` runs after route matching, so `request.params` is populated and
-    // `id` has already been URL-decoded. Authorize on it, never on a URL.
-    const { id } = request.params;
-
-    // `id` is still raw client text. Normalise it the way the record lookup
-    // does, or your predicate and the lookup disagree — see "Numeric ids" below.
-    // No radix on parseInt: that is deliberate, and it must stay that way.
-    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+    // `request.recordId` is the id the ORM resolves the record by. The ORM
+    // computes it before `access()` runs, from `request.params.id`, using the
+    // same function the record lookup uses — so your predicate and the lookup
+    // cannot disagree. Authorize on it, never on a URL and never on raw
+    // `params.id`.
+    const { recordId } = request;
 
     // Returning false explicitly denies access to this record
     if (recordId === 'angela') return false;
 
-    // No `id` means the collection route. Returning a function plugs it in to
+    // No `recordId` means the collection route. Returning a function plugs it in to
     // the response object as a filter. NOTE: a function return authorizes the
     // request outright — the operations list below is not consulted — so this
     // branch permits POST /owners as well as reads.
@@ -367,31 +365,43 @@ unrecognised spelling falls through to whatever your method returns next, so
 prefer one class per model. A class may still list several models in `models`
 when they share one rule.
 
-**Numeric ids: normalise before you compare.** `request.params.id` is raw text
-from the client. When it looks numeric the ORM coerces it — `isNaN(id) ? id :
-parseInt(id)` — *before* it resolves the record, so `7`, `007`, `7.0`, `7.9`,
-`7e0`, `0x7`, `+7`, `%207` (a leading space), `%097` (a tab) and `7%0A` (a
-trailing newline) all address record `7`, while a `===` against the raw text
-matches only the one spelling you wrote down. Every other spelling falls through
-to whatever your method returns next — which, in the shape above, is a full CRUD
-grant. All of them are plain address-bar requests.
-
-Two details are load-bearing. `parseInt` is called with **no radix**, so `0x7`
-is `7` and not `0`; writing `parseInt(id, 10)` in your predicate re-opens the
-hex spelling. And the coercion applies only when the id looks numeric, so a
-model with string ids (like `owner` above) is unaffected — which is exactly why
-this is easy to miss. Normalise the same way the lookup does:
+**Numeric ids: authorize on `request.recordId`, not on `request.params.id`.**
+`params.id` is raw text from the client. When it looks numeric the ORM coerces
+it *before* it resolves the record, so `7`, `007`, `7.0`, `7.9`, `7e0`, `0x7`,
+`+7`, `%207` (a leading space), `%097` (a tab) and `7%0A` (a trailing newline)
+all address record `7`, while a `===` against the raw text matches only the one
+spelling you wrote down. Every other spelling would fall through to whatever
+your method returns next — which, in the shape above, is a full CRUD grant. All
+of them are plain address-bar requests.
+
+**The ORM does that normalisation for you and hands you the result.** `access()`
+is called with `request.recordId` already set to the value the record will be
+resolved by, so there is no arithmetic to copy into your predicate and nothing
+to keep in sync — abofs/stonyx-orm#270. It is `undefined` on collection routes,
+which is how you tell a collection request from a record request. `params.id` is
+left untouched, so anything that needs the raw client text still has it.
+
+The same function is exported for the places `access()` does not reach — hooks,
+custom handlers, your own lookups:
+
+```javascript
+import { normalizeRecordId } from '@stonyx/orm';
+
+normalizeRecordId('0x7'); // 7 — the same value the ORM resolves by
+```
+
+Do not re-implement it. A hand-written copy is correct only for as long as it
+happens to match, and nothing holds the two together.
 
 ```javascript
 export default class AnimalAccess {
   models = ['animal'];
 
   access(request) {
-    const { id } = request.params;
-
-    // Agrees with the lookup for every spelling of 7 above. Compare the
-    // coerced value, which for a numeric-id model is a number, not a string.
-    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+    // Already normalised by the ORM, and it agrees with the lookup for every
+    // spelling of 7 above. For a numeric-id model it is a NUMBER, not a
+    // string, so compare it against a number.
+    const { recordId } = request;
 
     if (recordId === 7) return false;
 

package/dist/index.d.ts

@@ -12,4 +12,5 @@ export type { PersistErrorDetail } from './main.js';
 export { Model, View, Serializer };
 export { attr, belongsTo, hasMany, createRecord, updateRecord };
 export { count, avg, sum, min, max };
+export { default as normalizeRecordId } from './normalize-record-id.js';
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js';

package/dist/index.js

@@ -26,6 +26,7 @@ export { store, relationships } from './main.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers
+export { default as normalizeRecordId } from './normalize-record-id.js'; // canonical URL-id -> record-id resolution (#270)
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
 // Store API:
 // store.get(model, id)   -- sync, memory-only

package/dist/main.js

@@ -19,6 +19,7 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
+import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -130,13 +131,6 @@ export default class Orm {
             promises.push(db.init());
         }
         if (restServer.enabled === 'true') {
-            // Lazy-imported so the optional `@stonyx/rest-server` peer is only resolved
-            // when the consumer has actually enabled REST. A static import here pulls
-            // setup-rest-server -> orm-request/meta-request -> '@stonyx/rest-server'
-            // into the entry graph, so `import('@stonyx/orm')` throws
-            // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
-            // optional peer. Same reason the SQL/DynamoDB drivers above are lazy. (#280)
-            const { default: setupRestServer } = await import('./setup-rest-server.js');
             promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
         }
         // Wire up memory resolver so store.find() can check model memory flags

package/dist/normalize-record-id.d.ts

@@ -0,0 +1,53 @@
+/**
+ * The ONE place a URL id is turned into the value a record is resolved by —
+ * abofs/stonyx-orm#270.
+ *
+ * Before this existed the same expression was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. The framework's copy — `getId()`, module-private in
+ * orm-request.ts, unreachable through the package `exports` map — was the one
+ * that decided which record a request addressed, and a consumer's `access()`
+ * predicate had no way to obtain it. So the framework resolved the record by
+ * one value and asked the consumer to authorize on a different one.
+ *
+ * Measured consequence at the time of filing: with the documented predicate
+ * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
+ * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
+ * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
+ * those onto `7` while `'007' === '7'` is false.
+ *
+ * Two things follow from this being a single exported function, and both are
+ * the point:
+ *
+ *  1. A permissive change here is HARMLESS, because both sides move together.
+ *     Lowercasing string ids used to disclose and destroy `owner:angela` with
+ *     the whole suite green; with one implementation the predicate simply sees
+ *     the same lowercased value and still refuses.
+ *  2. A divergence — a second, private normaliser at the resolution site — is
+ *     what is now dangerous, and that is what the tests pin, by observing the
+ *     key the resolution path actually used.
+ *
+ * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
+ * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
+ * question, and it is a behaviour change on the record-resolution path for
+ * every consumer rather than an authorization fix — it belongs in its own
+ * issue with its own compatibility argument (issue body scope item 4). #270
+ * preserves today's semantics exactly and makes both sides agree on them.
+ *
+ * Two details are load-bearing and are pinned by
+ * test/unit/normalize-record-id-test.ts:
+ *
+ *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
+ *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
+ *    silently changes which record every hex-spelled URL addresses.
+ *  - The coercion applies only when the id LOOKS numeric, so a model with
+ *    string ids is passed through untouched, case included.
+ *
+ * Must stay synchronous: `auth()` is invoked without `await` by
+ * @stonyx/rest-server, so a promise here would be handed to `access()` as the
+ * record id.
+ *
+ * @param id the raw, already-URL-decoded id text from `request.params.id`
+ * @returns the value the ORM resolves the record by
+ */
+export default function normalizeRecordId(id?: string | null): string | number;

package/dist/normalize-record-id.js

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an 'AS IS' BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * The ONE place a URL id is turned into the value a record is resolved by —
+ * abofs/stonyx-orm#270.
+ *
+ * Before this existed the same expression was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. The framework's copy — `getId()`, module-private in
+ * orm-request.ts, unreachable through the package `exports` map — was the one
+ * that decided which record a request addressed, and a consumer's `access()`
+ * predicate had no way to obtain it. So the framework resolved the record by
+ * one value and asked the consumer to authorize on a different one.
+ *
+ * Measured consequence at the time of filing: with the documented predicate
+ * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
+ * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
+ * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
+ * those onto `7` while `'007' === '7'` is false.
+ *
+ * Two things follow from this being a single exported function, and both are
+ * the point:
+ *
+ *  1. A permissive change here is HARMLESS, because both sides move together.
+ *     Lowercasing string ids used to disclose and destroy `owner:angela` with
+ *     the whole suite green; with one implementation the predicate simply sees
+ *     the same lowercased value and still refuses.
+ *  2. A divergence — a second, private normaliser at the resolution site — is
+ *     what is now dangerous, and that is what the tests pin, by observing the
+ *     key the resolution path actually used.
+ *
+ * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
+ * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
+ * question, and it is a behaviour change on the record-resolution path for
+ * every consumer rather than an authorization fix — it belongs in its own
+ * issue with its own compatibility argument (issue body scope item 4). #270
+ * preserves today's semantics exactly and makes both sides agree on them.
+ *
+ * Two details are load-bearing and are pinned by
+ * test/unit/normalize-record-id-test.ts:
+ *
+ *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
+ *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
+ *    silently changes which record every hex-spelled URL addresses.
+ *  - The coercion applies only when the id LOOKS numeric, so a model with
+ *    string ids is passed through untouched, case included.
+ *
+ * Must stay synchronous: `auth()` is invoked without `await` by
+ * @stonyx/rest-server, so a promise here would be handed to `access()` as the
+ * record id.
+ *
+ * @param id the raw, already-URL-decoded id text from `request.params.id`
+ * @returns the value the ORM resolves the record by
+ */
+export default function normalizeRecordId(id) {
+    if (!id)
+        return '';
+    if (isNaN(id))
+        return id;
+    return parseInt(id);
+}

package/dist/orm-request.d.ts

@@ -6,6 +6,7 @@ interface OrmRequest$ extends Request {
     params: {
         [key: string]: string;
     };
+    recordId?: string | number;
     body?: {
         [key: string]: unknown;
     };

package/dist/orm-request.js

@@ -5,6 +5,7 @@ import { getPluralName } from './plural-registry.js';
 import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
 import { isOrmRecord } from './utils.js';
+import normalizeRecordId from './normalize-record-id.js';
 const methodAccessMap = {
     GET: 'read',
     POST: 'create',
@@ -65,13 +66,13 @@ function getBaseUrl(request, pluralizedModel) {
     const prefix = mountPath.endsWith(modelSegment) ? mountPath.slice(0, -modelSegment.length) : '';
     return `${protocol}://${host}${prefix}`;
 }
+// Kept as a name because twelve call sites read `getId(request.params)`, and
+// docs/hooks.md documents that spelling. It is now a thin delegate: there is
+// exactly ONE normalisation in the repo, and it is the exported one a consumer
+// can import. A second implementation here is the defect abofs/stonyx-orm#270
+// exists to remove — see src/normalize-record-id.ts.
 function getId(params) {
-    const id = params.id;
-    if (!id)
-        return '';
-    if (isNaN(id))
-        return id;
-    return parseInt(id);
+    return normalizeRecordId(params.id);
 }
 function buildResponse(data, includeParam, recordOrRecords, options = {}) {
     const { links, baseUrl } = options;
@@ -481,6 +482,35 @@ export default class OrmRequest extends Request {
         return routes;
     }
     auth(request, state) {
+        // abofs/stonyx-orm#270 — hand the predicate the value the record is
+        // ACTUALLY resolved by, rather than the raw text it was parsed from.
+        //
+        // This is the default path precisely because it requires the consumer to
+        // remember nothing. Exporting `normalizeRecordId` alone would leave the
+        // framework owning resolution while asking every consumer to call one
+        // function, with no signal when they forget — the same silent fail-open,
+        // one step over. The export is the escape hatch for hooks and custom
+        // handlers; this line is the contract.
+        //
+        // `request.params` is deliberately NOT mutated. Twelve `getId(...)` call
+        // sites, the serializer, and consumer hooks (docs/hooks.md documents
+        // `getId(request.params)`) all read it, and changing `params.id` from
+        // string to number underneath them is a silent behaviour change on paths
+        // this issue is not about.
+        //
+        // Synchronous by necessity: @stonyx/rest-server calls auth() without
+        // awaiting it.
+        //
+        // The `undefined` branch is a PRESENCE check, not a second normalisation:
+        // it answers "does this route carry an :id at all", which is how both
+        // documented samples tell a collection request from a record request. It
+        // cannot be folded into normalizeRecordId, because that function must keep
+        // returning '' for a falsy id — `store.get(key, undefined)` returns the
+        // whole model Map rather than a record (abofs/stonyx-orm#167, pinned by
+        // test/unit/store-get-falsy-id-test.ts), so the resolution path depends on
+        // the '' it returns today.
+        const rawId = request.params?.id;
+        request.recordId = rawId === undefined ? undefined : normalizeRecordId(rawId);
         const access = this.access(request);
         if (!access)
             return 403;

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.105",
+  "version": "0.3.2-alpha.106",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -106,7 +106,7 @@
     "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts' && ORM_TEST_ROUTE=/ pnpm test:mounted && ORM_TEST_ROUTE=/api pnpm test:mounted && ORM_TEST_ROUTE=api pnpm test:mounted && ORM_TEST_ROUTE=/api/v1 pnpm test:mounted && ORM_TEST_ROUTE=/api/ pnpm test:mounted && pnpm test:readme && pnpm test:reference",
     "test:mounted": "node --import tsx/esm --import ./test/integration/mounted-route/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/mounted-route/links-mounted.ts' 'test/zz-exit-test.ts'",
     "test:readme": "pnpm build && node --import tsx/esm --import ./test/integration/readme-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/readme-access/readme-sample.ts' 'test/zz-exit-test.ts'",
-    "test:reference": "pnpm build && node --import tsx/esm --import ./test/integration/reference-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/reference-access/reference-sample.ts' 'test/zz-exit-test.ts'",
+    "test:reference": "pnpm build && node --import tsx/esm --import ./test/integration/reference-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/reference-access/reference-sample.ts' 'test/integration/reference-access/record-id-resolution.ts' 'test/zz-exit-test.ts'",
     "test:dynamodb": "pnpm build && node --import tsx/esm --import ./test/integration/dynamodb/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/dynamodb/**/*-test.ts'"
   }
 }

package/src/index.ts

@@ -30,6 +30,7 @@ export type { PersistErrorDetail } from './main.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers
+export { default as normalizeRecordId } from './normalize-record-id.js'; // canonical URL-id -> record-id resolution (#270)
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
 
 // Store API:

package/src/main.ts

@@ -20,6 +20,7 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
+import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -176,13 +177,6 @@ export default class Orm {
     }
 
     if (restServer.enabled === 'true') {
-      // Lazy-imported so the optional `@stonyx/rest-server` peer is only resolved
-      // when the consumer has actually enabled REST. A static import here pulls
-      // setup-rest-server -> orm-request/meta-request -> '@stonyx/rest-server'
-      // into the entry graph, so `import('@stonyx/orm')` throws
-      // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
-      // optional peer. Same reason the SQL/DynamoDB drivers above are lazy. (#280)
-      const { default: setupRestServer } = await import('./setup-rest-server.js');
       promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
     }
 

package/src/normalize-record-id.ts

@@ -0,0 +1,74 @@
+/*
+ * Copyright 2025 Stone Costa
+ *
+ * Licensed under the Apache License, Version 2.0 (the 'License');
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an 'AS IS' BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * The ONE place a URL id is turned into the value a record is resolved by —
+ * abofs/stonyx-orm#270.
+ *
+ * Before this existed the same expression was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. The framework's copy — `getId()`, module-private in
+ * orm-request.ts, unreachable through the package `exports` map — was the one
+ * that decided which record a request addressed, and a consumer's `access()`
+ * predicate had no way to obtain it. So the framework resolved the record by
+ * one value and asked the consumer to authorize on a different one.
+ *
+ * Measured consequence at the time of filing: with the documented predicate
+ * applied verbatim to a numeric-id model, `GET /animals/007`, `/7.9`, `/7e0`,
+ * `/0x7`, `/%207`, `/%2B7` and `/7%0A` each served the protected record, and
+ * `DELETE /animals/007` destroyed it — because `parseInt` folds every one of
+ * those onto `7` while `'007' === '7'` is false.
+ *
+ * Two things follow from this being a single exported function, and both are
+ * the point:
+ *
+ *  1. A permissive change here is HARMLESS, because both sides move together.
+ *     Lowercasing string ids used to disclose and destroy `owner:angela` with
+ *     the whole suite green; with one implementation the predicate simply sees
+ *     the same lowercased value and still refuses.
+ *  2. A divergence — a second, private normaliser at the resolution site — is
+ *     what is now dangerous, and that is what the tests pin, by observing the
+ *     key the resolution path actually used.
+ *
+ * SEMANTICS ARE UNCHANGED FROM `getId()`, deliberately and byte-for-byte.
+ * Whether `7.9` / `0x7` / `%0A` *should* resolve to record 7 at all is a real
+ * question, and it is a behaviour change on the record-resolution path for
+ * every consumer rather than an authorization fix — it belongs in its own
+ * issue with its own compatibility argument (issue body scope item 4). #270
+ * preserves today's semantics exactly and makes both sides agree on them.
+ *
+ * Two details are load-bearing and are pinned by
+ * test/unit/normalize-record-id-test.ts:
+ *
+ *  - `parseInt` is called with NO RADIX. `parseInt('0x7')` is 7;
+ *    `parseInt('0x7', 10)` is 0. Adding the radix looks like a cleanup and
+ *    silently changes which record every hex-spelled URL addresses.
+ *  - The coercion applies only when the id LOOKS numeric, so a model with
+ *    string ids is passed through untouched, case included.
+ *
+ * Must stay synchronous: `auth()` is invoked without `await` by
+ * @stonyx/rest-server, so a promise here would be handed to `access()` as the
+ * record id.
+ *
+ * @param id the raw, already-URL-decoded id text from `request.params.id`
+ * @returns the value the ORM resolves the record by
+ */
+export default function normalizeRecordId(id?: string | null): string | number {
+  if (!id) return '';
+  if (isNaN(id as unknown as number)) return id;
+
+  return parseInt(id);
+}

package/src/orm-request.ts

@@ -7,6 +7,7 @@ import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import type { OrmRecord } from './types/orm-types.js';
 import { isOrmRecord } from './utils.js';
+import normalizeRecordId from './normalize-record-id.js';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -16,6 +17,10 @@ interface OrmRequest$ extends Request {
   baseUrl?: string;
   method: string;
   params: { [key: string]: string };
+  // Attached by auth() before access() runs — abofs/stonyx-orm#270. This is the
+  // value the ORM resolves the record by; `params.id` remains the raw client
+  // text it was parsed from.
+  recordId?: string | number;
   body?: { [key: string]: unknown };
   query?: { [key: string]: string };
   get(header: string): string;
@@ -107,12 +112,13 @@ function getBaseUrl(request: OrmRequest$, pluralizedModel: string): string {
   return `${protocol}://${host}${prefix}`;
 }
 
+// Kept as a name because twelve call sites read `getId(request.params)`, and
+// docs/hooks.md documents that spelling. It is now a thin delegate: there is
+// exactly ONE normalisation in the repo, and it is the exported one a consumer
+// can import. A second implementation here is the defect abofs/stonyx-orm#270
+// exists to remove — see src/normalize-record-id.ts.
 function getId(params: { id?: string; [key: string]: unknown }): string | number {
-  const id = params.id;
-  if (!id) return '';
-  if (isNaN(id as unknown as number)) return id;
-
-  return parseInt(id);
+  return normalizeRecordId(params.id);
 }
 
 function buildResponse(
@@ -598,6 +604,37 @@ export default class OrmRequest extends Request {
   }
 
   auth(request: OrmRequest$, state: { [key: string]: unknown }): number | undefined {
+    // abofs/stonyx-orm#270 — hand the predicate the value the record is
+    // ACTUALLY resolved by, rather than the raw text it was parsed from.
+    //
+    // This is the default path precisely because it requires the consumer to
+    // remember nothing. Exporting `normalizeRecordId` alone would leave the
+    // framework owning resolution while asking every consumer to call one
+    // function, with no signal when they forget — the same silent fail-open,
+    // one step over. The export is the escape hatch for hooks and custom
+    // handlers; this line is the contract.
+    //
+    // `request.params` is deliberately NOT mutated. Twelve `getId(...)` call
+    // sites, the serializer, and consumer hooks (docs/hooks.md documents
+    // `getId(request.params)`) all read it, and changing `params.id` from
+    // string to number underneath them is a silent behaviour change on paths
+    // this issue is not about.
+    //
+    // Synchronous by necessity: @stonyx/rest-server calls auth() without
+    // awaiting it.
+    //
+    // The `undefined` branch is a PRESENCE check, not a second normalisation:
+    // it answers "does this route carry an :id at all", which is how both
+    // documented samples tell a collection request from a record request. It
+    // cannot be folded into normalizeRecordId, because that function must keep
+    // returning '' for a falsy id — `store.get(key, undefined)` returns the
+    // whole model Map rather than a record (abofs/stonyx-orm#167, pinned by
+    // test/unit/store-get-falsy-id-test.ts), so the resolution path depends on
+    // the '' it returns today.
+    const rawId = request.params?.id;
+
+    request.recordId = rawId === undefined ? undefined : normalizeRecordId(rawId);
+
     const access = this.access(request);
 
     if (!access) return 403;