@stonyx/orm 0.3.2-alpha.111 → 0.3.2-alpha.113

package/README.md

@@ -370,19 +370,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 +419,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 +653,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 +671,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 +709,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 +756,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 +802,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,6 +1012,48 @@ 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
 

package/dist/column-conversion.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+/**
+ * A driver-supplied per-column conversion rule.
+ *
+ * @param value      the raw value about to be bound into the query
+ * @param columnType the column's declared type from `schema.columns`, or
+ *                   `undefined` when the column is not an attribute column
+ *                   (e.g. `updated_at`, FK columns and `id`, which are added
+ *                   outside the attribute loop). Rules MUST be a no-op for
+ *                   `undefined`.
+ */
+export type ColumnRule = (value: unknown, columnType: string | undefined) => unknown;
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export declare function convertRow(row: Record<string, unknown>, columns: Record<string, string>, rule: ColumnRule): Record<string, unknown>;

package/dist/column-conversion.js

@@ -0,0 +1,29 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export function convertRow(row, columns, rule) {
+    const converted = {};
+    for (const [col, value] of Object.entries(row)) {
+        converted[col] = rule(value, columns[col]);
+    }
+    return converted;
+}

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/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/dist/postgres/column-rules.d.ts

@@ -0,0 +1,24 @@
+import type { ColumnRule } from '../column-conversion.js';
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts` (`getPgType`/`mysqlTypeToPg`), which is the only
+ * producer of the values in `schema.columns`.
+ */
+export declare const postgresJsonRule: ColumnRule;

package/dist/postgres/column-rules.js

@@ -0,0 +1,25 @@
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts` (`getPgType`/`mysqlTypeToPg`), which is the only
+ * producer of the values in `schema.columns`.
+ */
+export const postgresJsonRule = (value, columnType) => columnType === 'JSONB' && typeof value !== 'string'
+    ? JSON.stringify(value)
+    : value;

package/dist/postgres/postgres-db.d.ts

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import path from 'path';
@@ -57,6 +59,8 @@ interface PostgresDeps {
     confirm: typeof confirm;
     readFile: typeof readFile;
     getPluralName: typeof getPluralName;
+    convertRow: typeof convertRow;
+    postgresJsonRule: typeof postgresJsonRule;
     config: typeof config;
     log: typeof log;
     path: typeof path;

package/dist/postgres/postgres-db.js

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import { isDbError } from '../utils.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
@@ -18,7 +20,8 @@ const defaultDeps = {
     introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
     loadLatestSnapshot, detectSchemaDrift,
     buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
-    createRecord, store, confirm, readFile, getPluralName, config, log, path
+    createRecord, store, confirm, readFile, getPluralName, config, log, path,
+    convertRow, postgresJsonRule
 };
 export default class PostgresDB {
     /** PostgreSQL extensions to enable on pool init. Subclasses can override. */
@@ -417,7 +420,9 @@ export default class PostgresDB {
         if (isPendingId) {
             delete insertData.id;
         }
-        const { sql, values } = this.deps.buildInsert(schema.table, insertData);
+        // Convert the *complete* payload (attributes + id + FKs) in one place (#292).
+        const row = this.deps.convertRow(insertData, schema.columns, this.deps.postgresJsonRule);
+        const { sql, values } = this.deps.buildInsert(schema.table, row);
         const result = await this.requirePool().query(sql, values);
         // Re-key the record in the store if PostgreSQL generated the ID (via RETURNING)
         if (isPendingId && result.rows.length > 0) {
@@ -469,7 +474,11 @@ export default class PostgresDB {
             return;
         // PostgreSQL doesn't have ON UPDATE CURRENT_TIMESTAMP -- set updated_at manually
         changedData.updated_at = new Date();
-        const { sql, values } = this.deps.buildUpdate(schema.table, id, changedData);
+        // Same conversion, same choke point as the create path (#292). Columns
+        // appended after the attribute loop (FKs, updated_at) are absent from
+        // schema.columns and pass through untouched.
+        const row = this.deps.convertRow(changedData, schema.columns, this.deps.postgresJsonRule);
+        const { sql, values } = this.deps.buildUpdate(schema.table, id, row);
         await this.requirePool().query(sql, values);
     }
     async _persistDelete(modelName, context) {
@@ -490,13 +499,11 @@ export default class PostgresDB {
         if (data.id !== undefined) {
             row.id = data.id;
         }
-        // Attribute columns
-        for (const [col, pgType] of Object.entries(schema.columns)) {
+        // Attribute columns. Type conversion is NOT applied here -- it is applied
+        // once to the finished payload by the caller, via convertRow (#292).
+        for (const col of Object.keys(schema.columns)) {
             if (data[col] !== undefined) {
-                // JSONB columns: stringify non-string values for PostgreSQL JSONB storage
-                row[col] = pgType === 'JSONB' && typeof data[col] !== 'string'
-                    ? JSON.stringify(data[col])
-                    : data[col];
+                row[col] = data[col];
             }
         }
         // FK columns from relationships

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.111",
+  "version": "0.3.2-alpha.113",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,10 +61,10 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.122",
+    "@stonyx/cron": "0.2.1-beta.146",
     "@stonyx/events": "0.1.1-beta.64",
     "@stonyx/utils": "0.2.3-beta.27",
-    "stonyx": "0.2.3-beta.94"
+    "stonyx": "0.2.3-beta.98"
   },
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.0.0",
@@ -91,7 +91,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.123",
+    "@stonyx/rest-server": "0.2.1-beta.147",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",
@@ -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/column-conversion.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+
+/**
+ * A driver-supplied per-column conversion rule.
+ *
+ * @param value      the raw value about to be bound into the query
+ * @param columnType the column's declared type from `schema.columns`, or
+ *                   `undefined` when the column is not an attribute column
+ *                   (e.g. `updated_at`, FK columns and `id`, which are added
+ *                   outside the attribute loop). Rules MUST be a no-op for
+ *                   `undefined`.
+ */
+export type ColumnRule = (value: unknown, columnType: string | undefined) => unknown;
+
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export function convertRow(
+  row: Record<string, unknown>,
+  columns: Record<string, string>,
+  rule: ColumnRule
+): Record<string, unknown> {
+  const converted: Record<string, unknown> = {};
+
+  for (const [col, value] of Object.entries(row)) {
+    converted[col] = rule(value, columns[col]);
+  }
+
+  return converted;
+}

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/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;

package/src/postgres/column-rules.ts

@@ -0,0 +1,28 @@
+import type { ColumnRule } from '../column-conversion.js';
+
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts` (`getPgType`/`mysqlTypeToPg`), which is the only
+ * producer of the values in `schema.columns`.
+ */
+export const postgresJsonRule: ColumnRule = (value, columnType) =>
+  columnType === 'JSONB' && typeof value !== 'string'
+    ? JSON.stringify(value)
+    : value;

package/src/postgres/postgres-db.ts

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import { isDbError } from '../utils.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
@@ -61,6 +63,8 @@ interface PostgresDeps {
   confirm: typeof confirm;
   readFile: typeof readFile;
   getPluralName: typeof getPluralName;
+  convertRow: typeof convertRow;
+  postgresJsonRule: typeof postgresJsonRule;
   config: typeof config;
   log: typeof log;
   path: typeof path;
@@ -73,7 +77,8 @@ const defaultDeps: PostgresDeps = {
   introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
   loadLatestSnapshot, detectSchemaDrift,
   buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
-  createRecord, store, confirm, readFile, getPluralName, config, log, path
+  createRecord, store, confirm, readFile, getPluralName, config, log, path,
+  convertRow, postgresJsonRule
 };
 
 export default class PostgresDB {
@@ -535,7 +540,10 @@ export default class PostgresDB {
       delete insertData.id;
     }
 
-    const { sql, values } = this.deps.buildInsert(schema.table, insertData);
+    // Convert the *complete* payload (attributes + id + FKs) in one place (#292).
+    const row = this.deps.convertRow(insertData, schema.columns, this.deps.postgresJsonRule);
+
+    const { sql, values } = this.deps.buildInsert(schema.table, row);
 
     const result = await this.requirePool().query(sql, values);
 
@@ -600,7 +608,12 @@ export default class PostgresDB {
     // PostgreSQL doesn't have ON UPDATE CURRENT_TIMESTAMP -- set updated_at manually
     changedData.updated_at = new Date();
 
-    const { sql, values } = this.deps.buildUpdate(schema.table, id, changedData);
+    // Same conversion, same choke point as the create path (#292). Columns
+    // appended after the attribute loop (FKs, updated_at) are absent from
+    // schema.columns and pass through untouched.
+    const row = this.deps.convertRow(changedData, schema.columns, this.deps.postgresJsonRule);
+
+    const { sql, values } = this.deps.buildUpdate(schema.table, id, row);
     await this.requirePool().query(sql, values);
   }
 
@@ -626,13 +639,11 @@ export default class PostgresDB {
       row.id = data.id;
     }
 
-    // Attribute columns
-    for (const [col, pgType] of Object.entries(schema.columns)) {
+    // Attribute columns. Type conversion is NOT applied here -- it is applied
+    // once to the finished payload by the caller, via convertRow (#292).
+    for (const col of Object.keys(schema.columns)) {
       if (data[col] !== undefined) {
-        // JSONB columns: stringify non-string values for PostgreSQL JSONB storage
-        row[col] = pgType === 'JSONB' && typeof data[col] !== 'string'
-          ? JSON.stringify(data[col])
-          : data[col];
+        row[col] = data[col];
       }
     }