@stonyx/orm 0.3.2-alpha.110 → 0.3.2-alpha.112

package/README.md

@@ -40,12 +40,6 @@ All properties prefixed with `__` (`__data`, `__relationships`, `__model`, `__se
 npm install @stonyx/orm
 ````
 
-That is the whole install for an ORM-only app. The database drivers and
-`@stonyx/rest-server` are **optional peer dependencies**: a default install does
-not put them on disk, and none of them is loaded unless your configuration asks
-for it. Add only the ones you actually use — see
-[Optional peer dependencies](#optional-peer-dependencies).
-
 ## Usage example
 
 This module is part of the **Stonyx framework**. To use it, first configure the `restServer` key in your `environment.js` file:
@@ -112,9 +106,7 @@ export default {
       tablePrefix: DYNAMODB_TABLE_PREFIX,   // optional table name prefix
     } : undefined,
     restServer: {
-      // 'true' requires @stonyx/rest-server to be installed — see
-      // "Optional peer dependencies" below.
-      enabled: ORM_USE_REST_SERVER ?? 'false',
+      enabled: ORM_USE_REST_SERVER ?? 'true',
       route: ORM_REST_ROUTE ?? '/'
     }
   }
@@ -135,46 +127,6 @@ stonyx serve
 
 For further framework instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
 
-## Optional peer dependencies
-
-`@stonyx/orm` boots with **none** of its optional peers installed. Each one is
-imported lazily, and only when your configuration selects it:
-
-| Configuration | Package you must install |
-|---|---|
-| `orm.restServer.enabled: 'true'` | `@stonyx/rest-server` |
-| `orm.postgres` or `orm.timescale` | `pg` |
-| `orm.mysql` | `mysql2` |
-| `orm.dynamodb` | `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
-
-If a configuration key selects one that is not on disk, the failure surfaces
-from `Orm.init()` while the framework boots:
-
-```
-Cannot find package '@stonyx/rest-server' imported from .../@stonyx/orm/dist/orm-request.js
-```
-
-**ORM-only, no REST server.** This is the shape the `environment.js` above is
-written for: keep `orm.restServer.enabled` at `'false'` and install nothing
-beyond `@stonyx/orm`. Models, relationships, serializers, transforms and hooks
-work unchanged; only the generated REST routes are absent.
-
-> **The module's own default is the other way round.** The `config/environment.js`
-> that ships inside `@stonyx/orm` defaults `restServer.enabled` to `'true'`, so
-> an app that omits the `restServer` key *entirely* gets REST switched on and
-> needs `@stonyx/rest-server` installed. Set the key explicitly, whichever way
-> you want it.
-
-**Turning REST on.**
-
-```bash
-npm install @stonyx/rest-server
-ORM_USE_REST_SERVER=true stonyx serve
-```
-
-See [REST Server Integration](#rest-server-integration) for access classes and
-route configuration.
-
 ## Models
 
 Define a model with attributes and relationships:
@@ -370,19 +322,23 @@ 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));
+    // Fail closed on a build that predates abofs/stonyx-orm#270: such a build
+    // never attaches `recordId`, so the collection branch below would fire on
+    // the record route and authorize it outright. Exact no-op on a build that
+    // has the change — `recordId` is always assigned, `undefined` included.
+    if (!('recordId' in request)) return false;
+
+    // `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.
@@ -415,31 +371,64 @@ 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 samples above fail *closed* on a build that predates
+abofs/stonyx-orm#270.** That is what the first line of each `access()` is for. A
+build without this change never attaches `recordId`, so `recordId === undefined`
+— the collection branch — fires on the *record* route, and a function return
+authorizes the request outright.
+
+The same normalisation 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.
+
+**`normalizeRecordId(undefined)` is `''`, not `undefined`.** The two values this
+section documents side by side do not agree, and the difference is load-bearing:
+`request.recordId` is `undefined` on a collection route, while
+`normalizeRecordId` returns `''` for any falsy id — including `undefined` — because
+`store.get(key, undefined)` returns the whole model Map rather than a record
+(abofs/stonyx-orm#167). So `normalizeRecordId(context.params.id) === undefined`
+is **never** true and a collection branch written that way never runs. Branch on
+`request.recordId === undefined`, or compare against `''`.
 
 ```javascript
 export default class AnimalAccess {
   models = ['animal'];
 
   access(request) {
-    const { id } = request.params;
+    // Fail closed on a build that predates abofs/stonyx-orm#270: such a build
+    // never attaches `recordId`, so the collection branch below would fire on
+    // the record route and authorize it outright. Exact no-op on a build that
+    // has the change — `recordId` is always assigned, `undefined` included.
+    if (!('recordId' in request)) return false;
 
-    // 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;
 
@@ -616,7 +605,7 @@ Each hook receives a context object with comprehensive information:
   model: 'animal',           // Model name
   operation: 'create',       // Operation type
   request,                   // Express request object
-  params,                    // URL params (e.g., { id: 5 })
+  params,                    // URL params, raw client text (e.g., { id: '5' })
   body,                      // Request body (POST/PATCH)
   query,                     // Query parameters
   state,                     // Request state object
@@ -634,6 +623,7 @@ Each hook receives a context object with comprehensive information:
 - The deep copy is created via JSON serialization (`JSON.parse(JSON.stringify())`) to ensure complete isolation
 - For `delete` operations, `recordId` is provided in after hooks since the record may no longer exist in the store
 - `oldState` is captured as a deep copy of the record's data before the operation, providing access to the previous field values
+- `params.id` is the raw client text as a STRING (`/animals/05` gives `{ id: '05' }`). The id the ORM resolved the record by is `request.recordId`, and for a numeric-id model it is a NUMBER (`5` for both `/animals/5` and `/animals/05`) — abofs/stonyx-orm#270. Key lookups on `request.recordId`, never on `params.id`.
 
 ### Usage Examples
 
@@ -671,9 +661,13 @@ beforeHook('create', 'animal', (context) => {
   }
 });
 
-// Return an object to send a custom response
+// Return an object to send a custom response.
+// Look the record up by `context.request.recordId` — the value the ORM
+// resolved the record by. `context.params.id` is the raw client text and is a
+// different value for every alias of the same id, so a lookup keyed on it
+// finds nothing on a numeric-id model (abofs/stonyx-orm#270).
 beforeHook('delete', 'animal', (context) => {
-  const animal = store.get('animal', context.params.id);
+  const animal = store.get('animal', context.request.recordId);
   if (animal.protected) {
     return { errors: [{ detail: 'Cannot delete protected animals' }] };
   }
@@ -714,9 +708,12 @@ afterHook('update', 'animal', async (context) => {
   }
 });
 
-// Cache invalidation
+// Cache invalidation.
+// Keyed on `recordId`, not `params.id`: `/animals/7` and `/animals/007` are
+// one record but two strings, so a raw-text key invalidates two entries and
+// misses the one the write used.
 afterHook('delete', 'animal', async (context) => {
-  await cache.invalidate(`owner:${context.params.id}:pets`);
+  await cache.invalidate(`owner:${context.request.recordId}:pets`);
 });
 ```
 
@@ -757,10 +754,16 @@ afterHook('delete', 'animal', async (context) => {
 #### Authorization
 
 ```javascript
-// Additional access control - halt with 403 if unauthorized
+// Additional access control - halt with 403 if unauthorized.
+//
+// `context.request.recordId` is the id the ORM resolved the record by — the
+// same value `access()` is handed. Authorizing on `context.params.id` instead
+// looks up the raw client text: on a numeric-id model that lookup returns
+// `undefined` for EVERY spelling, `animal.owner` throws, and the check never
+// runs. Measured; abofs/stonyx-orm#270.
 beforeHook('delete', 'animal', (context) => {
   const user = context.state.currentUser;
-  const animal = store.get('animal', context.params.id);
+  const animal = store.get('animal', context.request.recordId);
 
   if (animal.owner !== user.id && !user.isAdmin) {
     return 403; // Forbidden
@@ -961,12 +964,52 @@ test('validation hook rejects negative age', async () => {
 | `afterHook`     | Register an after hook for post-operation logic.                        |
 | `clearHook`     | Clear hooks for a specific operation:model.                             |
 | `clearAllHooks` | Clear all registered hooks (useful for testing).                        |
+| `normalizeRecordId` | Turn a raw URL id into the value the ORM resolves the record by. |
+
+### `normalizeRecordId(id)`
+
+```ts
+normalizeRecordId(id?: string | null): string | number
+```
+
+The **one** implementation of URL-id normalisation in the package
+(abofs/stonyx-orm#270). `access()` is already handed its result as
+`request.recordId`; import it for the places `access()` does not reach — hooks,
+custom handlers, your own lookups. Synchronous, and it must stay synchronous:
+`auth()` is invoked without `await`.
+
+| Input | Returns | Note |
+| --- | --- | --- |
+| `'7'`, `'007'`, `'7.0'`, `'7.9'`, `'7e0'`, `'0x7'`, `'+7'`, `' 7'` | `7` (number) | `parseInt` with **no radix**; passing a radix of 10 would make this `0` |
+| `'angela'`, `'ANGELA'` | the same string, case included | a non-numeric id is passed through untouched |
+| `'0'`, `'00'`, `'-0'`, `'0x0'` | `0` (number) | falsy, and a legitimate record id |
+| `' '`, `'\t'`, `'\n'`, `'\u00a0'` | `NaN` | whitespace-only ids are numeric to `isNaN` but parse to nothing |
+| `''`, `null`, `undefined` | `''` (empty string) | **not** `undefined` — see the trap below |
+
+**The trap.** `request.recordId` is `undefined` on a collection route;
+`normalizeRecordId(undefined)` is `''`. They are different values and a
+collection check written against the wrong one silently never fires:
+
+```javascript
+// WRONG — never true, so this branch never runs
+if (normalizeRecordId(context.params.id) === undefined) { /* … */ }
+
+// Right — the ORM attaches undefined for "this route carries no :id"
+if (context.request.recordId === undefined) { /* collection route */ }
+```
+
+The `''` is deliberate: `store.get(key, undefined)` returns the whole model Map
+rather than a record (abofs/stonyx-orm#167), so the resolution path depends on
+the empty string this function returns today.
+
+**A normalised id is not a promise that a record exists.** `0` and `NaN` are both
+possible returns and neither addresses a record you can rely on — `NaN` is not
+even `===` itself, so `recordId === NaN` can never be written as a guard. Treat
+`recordId` as "the key the lookup will use", not as "a record is there".
 
 ## Project Structure
 
-For a full architectural reference, see
-[docs/project-structure.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/project-structure.md).
-That file is repo-only — it is not in the published tarball, so the link is absolute.
+For a full architectural reference, see [project-structure.md](project-structure.md).
 
 ## License
 

package/dist/index.d.ts

@@ -12,4 +12,6 @@ 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 type { OrmRequest$ as OrmAccessRequest } from './orm-request.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,25 +131,6 @@ export default class Orm {
             promises.push(db.init());
         }
         if (restServer.enabled === 'true') {
-            // MUST stay dynamic. setup-rest-server.js names the optional
-            // '@stonyx/rest-server' peer in its own static graph — directly, and
-            // through orm-request.ts / meta-request.ts, which import `Request` at
-            // module scope because they extend it (correctly: an `extends` base
-            // class cannot be awaited). Node links a module's entire static graph
-            // before evaluating any of it, so a static import here puts that
-            // specifier on the entry graph and `import('@stonyx/orm')` throws
-            // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
-            // optional peer.
-            //
-            // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
-            // modules carry no static peer specifier that survives to `dist/`
-            // (postgres-db.ts:15 and mysql-db.ts:17 are `import type`, erased by
-            // tsc), so the `await import()` there is not what isolates pg / mysql2 /
-            // @aws-sdk — that happens one layer down, in src/*/connection.ts (and
-            // src/dynamodb/dynamodb-db.ts).
-            // setup-rest-server.js is the only dist module whose laziness is
-            // load-bearing for peer resolution. (#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,67 @@
+/**
+ * The ONE place a URL id is turned into the value a record is resolved by —
+ * abofs/stonyx-orm#270.
+ *
+ * Before this existed this coercion was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. Seven copies, not seven identical copies — the three persistence
+ * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
+ * is the point: nothing held them together, so they had already drifted.
+ * 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.
+ *
+ * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
+ * `''` is returned for any falsy id because `store.get(key, undefined)` returns
+ * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
+ * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
+ * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
+ * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
+ * `store.remove(key, id)` branches on truthiness, so those spellings reach a
+ * fall-through this function does not own. Tracked as #287; every row is pinned
+ * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
+ * boundary #287 is measured against.
+ *
+ * @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,88 @@
+/*
+ * 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 this coercion was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. Seven copies, not seven identical copies — the three persistence
+ * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
+ * is the point: nothing held them together, so they had already drifted.
+ * 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.
+ *
+ * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
+ * `''` is returned for any falsy id because `store.get(key, undefined)` returns
+ * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
+ * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
+ * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
+ * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
+ * `store.remove(key, id)` branches on truthiness, so those spellings reach a
+ * fall-through this function does not own. Tracked as #287; every row is pinned
+ * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
+ * boundary #287 is measured against.
+ *
+ * @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

@@ -1,11 +1,26 @@
 import { Request } from '@stonyx/rest-server';
-interface OrmRequest$ extends Request {
+/**
+ * The request object a consumer's `access()` predicate receives.
+ *
+ * Exported because `recordId` is public API — README's `access()` samples
+ * destructure it — and a public runtime field with an unreachable type asks the
+ * consumer to re-declare something the framework already knows, which is
+ * abofs/stonyx-orm#270's own defect shape one layer over into the type surface.
+ * `HookContext` (src/hooks.ts) is this repo's precedent for exporting the
+ * interface a consumer is handed. Re-exported from the root barrel as
+ * `OrmAccessRequest` (src/index.ts) — NOT as `OrmRequest`, which is already the
+ * default-exported CLASS in this file and means something else. The
+ * `./orm-request` subpath is not in the `exports` map, so the barrel is the
+ * only reachable spelling.
+ */
+export interface OrmRequest$ extends Request {
     protocol?: string;
     baseUrl?: string;
     method: string;
     params: {
         [key: string]: string;
     };
+    recordId?: string | number | undefined;
     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,23 @@ function getBaseUrl(request, pluralizedModel) {
     const prefix = mountPath.endsWith(modelSegment) ? mountPath.slice(0, -modelSegment.length) : '';
     return `${protocol}://${host}${prefix}`;
 }
+// Kept as a name because twelve `getId(...)` call sites read it. It is now a
+// thin delegate: there is exactly ONE normalisation of a URL id in the repo,
+// and it is the exported one a consumer can import.
+//
+// "of a URL id" is the load-bearing qualifier, and it is the same one
+// src/normalize-record-id.ts:18 carries. Three copies of the coercion survive
+// at this head — src/orm-request.ts (the create-response path),
+// src/postgres/postgres-db.ts and src/mysql/mysql-db.ts — but each normalises a
+// RESPONSE id (`response?.data?.id`), not a URL id, and each omits this
+// function's `if (!id) return ''` guard. They are tracked as
+// abofs/stonyx-orm#282 and enumerated by name in AC-5's allowlist
+// (test/integration/readme-sample-test.ts).
+//
+// A second implementation of the URL-id normalisation 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 +492,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 read it, and `_withHooks` assigns `params: request.params` onto the
+        // hook context, so every consumer hook reads the same object. 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.110",
+  "version": "0.3.2-alpha.112",
   "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,8 @@ 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 type { OrmRequest$ as OrmAccessRequest } from './orm-request.js'; // the request access() is handed, incl. recordId (#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,25 +177,6 @@ export default class Orm {
     }
 
     if (restServer.enabled === 'true') {
-      // MUST stay dynamic. setup-rest-server.js names the optional
-      // '@stonyx/rest-server' peer in its own static graph — directly, and
-      // through orm-request.ts / meta-request.ts, which import `Request` at
-      // module scope because they extend it (correctly: an `extends` base
-      // class cannot be awaited). Node links a module's entire static graph
-      // before evaluating any of it, so a static import here puts that
-      // specifier on the entry graph and `import('@stonyx/orm')` throws
-      // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
-      // optional peer.
-      //
-      // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
-      // modules carry no static peer specifier that survives to `dist/`
-      // (postgres-db.ts:15 and mysql-db.ts:17 are `import type`, erased by
-      // tsc), so the `await import()` there is not what isolates pg / mysql2 /
-      // @aws-sdk — that happens one layer down, in src/*/connection.ts (and
-      // src/dynamodb/dynamodb-db.ts).
-      // setup-rest-server.js is the only dist module whose laziness is
-      // load-bearing for peer resolution. (#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,88 @@
+/*
+ * 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 this coercion was written out seven times: twice in
+ * README.md, once in docs/usage-patterns.md, and four times inside the
+ * framework. Seven copies, not seven identical copies — the three persistence
+ * ones (abofs/stonyx-orm#282) omit the `if (!id) return ''` guard below, which
+ * is the point: nothing held them together, so they had already drifted.
+ * 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.
+ *
+ * FALSY AND `NaN` RETURNS ARE LOAD-BEARING ELSEWHERE — abofs/stonyx-orm#287.
+ * `''` is returned for any falsy id because `store.get(key, undefined)` returns
+ * the whole model Map rather than a record (abofs/stonyx-orm#167). But `''` is
+ * not the only falsy return: `'0'`, `'00'`, `'-0'` and `'0x0'` all normalise to
+ * `0`, and `' '`, `'\t'`, `'\n'`, `'\u00a0'` all normalise to `NaN` (their
+ * `Number()` is `0`, so the `isNaN` guard does not fire and `parseInt` runs).
+ * `store.remove(key, id)` branches on truthiness, so those spellings reach a
+ * fall-through this function does not own. Tracked as #287; every row is pinned
+ * in test/unit/normalize-record-id-test.ts so a cleanup here cannot move the
+ * boundary #287 is measured against.
+ *
+ * @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,8 +7,23 @@ 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 {
+/**
+ * The request object a consumer's `access()` predicate receives.
+ *
+ * Exported because `recordId` is public API — README's `access()` samples
+ * destructure it — and a public runtime field with an unreachable type asks the
+ * consumer to re-declare something the framework already knows, which is
+ * abofs/stonyx-orm#270's own defect shape one layer over into the type surface.
+ * `HookContext` (src/hooks.ts) is this repo's precedent for exporting the
+ * interface a consumer is handed. Re-exported from the root barrel as
+ * `OrmAccessRequest` (src/index.ts) — NOT as `OrmRequest`, which is already the
+ * default-exported CLASS in this file and means something else. The
+ * `./orm-request` subpath is not in the `exports` map, so the barrel is the
+ * only reachable spelling.
+ */
+export interface OrmRequest$ extends Request {
   protocol?: string;
   // Express sets this to the path the router was mounted at, e.g. '/api/animals'
   // when orm.restServer.route is '/api'. Optional because non-Express callers
@@ -16,6 +31,14 @@ 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.
+  //
+  // `undefined` is part of the contract, not an absence: it is how a collection
+  // route is told from a record route, and both documented samples branch on
+  // it. Spelled out rather than left to `?:` for that reason.
+  recordId?: string | number | undefined;
   body?: { [key: string]: unknown };
   query?: { [key: string]: string };
   get(header: string): string;
@@ -107,12 +130,23 @@ function getBaseUrl(request: OrmRequest$, pluralizedModel: string): string {
   return `${protocol}://${host}${prefix}`;
 }
 
+// Kept as a name because twelve `getId(...)` call sites read it. It is now a
+// thin delegate: there is exactly ONE normalisation of a URL id in the repo,
+// and it is the exported one a consumer can import.
+//
+// "of a URL id" is the load-bearing qualifier, and it is the same one
+// src/normalize-record-id.ts:18 carries. Three copies of the coercion survive
+// at this head — src/orm-request.ts (the create-response path),
+// src/postgres/postgres-db.ts and src/mysql/mysql-db.ts — but each normalises a
+// RESPONSE id (`response?.data?.id`), not a URL id, and each omits this
+// function's `if (!id) return ''` guard. They are tracked as
+// abofs/stonyx-orm#282 and enumerated by name in AC-5's allowlist
+// (test/integration/readme-sample-test.ts).
+//
+// A second implementation of the URL-id normalisation 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 +632,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 read it, and `_withHooks` assigns `params: request.params` onto the
+    // hook context, so every consumer hook reads the same object. 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;