@stonyx/orm 0.3.2-alpha.7 → 0.3.2-alpha.70

package/README.md

@@ -13,7 +13,7 @@ A lightweight ORM for Stonyx projects, featuring model definitions, serializers,
 - **Models**: Define attributes with type-safe proxies (`attr`) and relationships (`hasMany`, `belongsTo`).
 - **Serializers**: Map raw data into model-friendly structures, including nested properties.
 - **Transforms**: Apply custom transformations on data values automatically.
-- **DB Integration**: Optional file-based persistence with auto-save support, or MySQL for production workloads.
+- **DB Integration**: Optional file-based persistence with auto-save support, or MySQL/PostgreSQL/TimescaleDB/DynamoDB for production workloads.
 - **REST Server Integration**: Automatic route setup with customizable access control.
 - **Lifecycle Hooks**: Middleware-based before/after hooks for validation, authorization, side effects, and auditing.
 
@@ -65,13 +65,16 @@ const {
   MYSQL_DATABASE,
   MYSQL_CONNECTION_LIMIT,
   MYSQL_MIGRATIONS_DIR,
+  DYNAMODB_REGION,
+  DYNAMODB_ENDPOINT,
+  DYNAMODB_TABLE_PREFIX,
 } = process.env;
 
 export default {
   orm: {
     logColor: 'white',
     logMethod: 'db',
-    
+
     db: {
       autosave: DB_AUTO_SAVE ?? 'false',
       file: DB_FILE ?? 'db.json',
@@ -95,6 +98,12 @@ export default {
       connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
       migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
       migrationsTable: '__migrations',
+      autoMigrate: AUTO_MIGRATE === 'true' ? true : AUTO_MIGRATE === 'false' ? false : undefined,
+    } : undefined,
+    dynamodb: DYNAMODB_REGION ? {
+      region: DYNAMODB_REGION,
+      endpoint: DYNAMODB_ENDPOINT,          // optional, for DynamoDB Local
+      tablePrefix: DYNAMODB_TABLE_PREFIX,   // optional table name prefix
     } : undefined,
     restServer: {
       enabled: ORM_USE_REST_SERVER ?? 'true',
@@ -243,6 +252,31 @@ Set the `MYSQL_HOST` environment variable to enable MySQL persistence. The ORM l
 | `stonyx db:migrate` | Apply pending migrations |
 | `stonyx db:migrate:rollback` | Rollback the most recent migration |
 | `stonyx db:migrate:status` | Show migration status |
+| `stonyx db:sync` | Sync DynamoDB table definitions to match current model schemas |
+
+### DynamoDB Mode
+
+Set the `DYNAMODB_REGION` environment variable to enable DynamoDB persistence. Tables are created with PAY_PER_REQUEST (on-demand) billing. Global Secondary Indexes (GSIs) are auto-provisioned at startup based on model `belongsTo` relationships — each FK column gets a GSI. `findAll()` with conditions routes to a GSI Query when the condition key matches a GSI partition key; non-indexed attribute conditions fall back to Scan + FilterExpression (expensive for large tables). ULID generation replaces auto-increment for numeric-ID models.
+
+```javascript
+dynamodb: {
+  region: 'us-east-1',
+  endpoint: 'http://localhost:8000', // optional, for DynamoDB Local
+  tablePrefix: 'myapp-',            // optional table name prefix
+}
+```
+
+Environment variables:
+
+* `DYNAMODB_REGION`: AWS region for DynamoDB (e.g., `'us-east-1'`).
+* `DYNAMODB_ENDPOINT`: Optional custom endpoint URL, useful for DynamoDB Local during development.
+* `DYNAMODB_TABLE_PREFIX`: Optional prefix prepended to all table names (e.g., `'myapp-'` yields `'myapp-animals'`).
+
+**Peer dependencies:** `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` must be installed when using the DynamoDB driver. The AWS SDK is dynamically imported and only loaded when the DynamoDB driver is selected.
+
+```bash
+npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
+```
 
 ### Running MySQL Tests
 
@@ -275,19 +309,800 @@ import setupRestServer from '@stonyx/orm/setup-rest-server';
 await setupRestServer('/', './access');
 ```
 
-Access classes define models and provide custom filtering/authorization logic:
+Access classes define models and provide custom filtering/authorization logic.
+
+> **Do not reconstruct the request path inside `access()`. Read
+> [Identifying the collection](#identifying-the-collection) before copying this.**
+> Every attempt to identify the collection by parsing the request target has
+> failed **open** — five distinct variants of this same example, each found only
+> after the previous was fixed, by five different people. That section is now a
+> record of what not to do, not a matching recipe: the sample below reads `model`
+> from [the access context](#the-access-context-second-argument) and never looks
+> at the mount at all, so variants 1, 2, 4 and 5 are **unconstructible** against
+> it rather than merely handled. **Variant 3 survives.** It is the general shape
+> "a hand-written matcher normalises differently from the router", and the
+> migrated sample still runs one string comparison — the `/archived` sub-path
+> deny — which folds case but does not decode, so `GET /owners/%61rchived` steps
+> past it ([#228](https://github.com/abofs/stonyx-orm/issues/228)).
+>
+> **Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
+> [#237](https://github.com/abofs/stonyx-orm/issues/237), and left standing rather
+> than rewritten.** Both claims above are now false: `#228` is **closed**, and the
+> one string comparison variant 3 lived in is gone — the sample below compares the
+> **decoded `recordId`** the access context supplies, so there is no comparison
+> left to step around. The paragraph about `request.path` further down is
+> superseded the same way. Nothing here is deleted because the same "variant 3
+> survives" wording sits at four sites (this file twice, `src/orm-request.ts`, and
+> the test fixture) and retiring one of four leaves the shipped copies
+> contradicting each other; retiring all four **with the measurement that retires
+> them** is [#238](https://github.com/abofs/stonyx-orm/issues/238), which also owns
+> this blockquote and the reference section below.
+>
+> That is still a stopgap. **The real fix is
+> [#202](https://github.com/abofs/stonyx-orm/issues/202)** — `access()` should
+> receive the model, the operation and the record, so there is nothing to
+> identify. Until it lands, prefer the array shape (`['read']`) or `false` where
+> you can: the **function** shape is the one that requires any matching at all.
+>
+> The one read of argument **one** that survives is `request.path`, for the
+> `/archived` sub-path deny — and it has to. The context names which model and
+> which verb, not which route, so that deny **cannot be expressed from the
+> context alone** and a context-only rewrite would silently turn it into an
+> allow.
+>
+> **Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
+> [#237](https://github.com/abofs/stonyx-orm/issues/237)** — see the dated note
+> above. No read of argument **one** survives in the sample below: the context
+> carries `recordId`, the decoded route-parameter id, so the `/archived` deny **is**
+> expressible from the context alone. It still must not be dropped — expressible is
+> not optional. Retirement of this wording:
+> [#238](https://github.com/abofs/stonyx-orm/issues/238).
+>
+> The same warning is repeated at the top of `src/orm-request.ts`, which ships;
+> the longer write-up in `docs/usage-patterns.md` does **not** ship, so this
+> README and that source header are the two copies a consumer sees.
+>
+> This sample is the same code as the shipped test fixture, and a test asserts
+> the two `access()` bodies are identical line for line. For four rounds they
+> were two independently written copies — and the fifth fail-open variant was
+> found in the one nothing was mutating.
 
 ```js
 export default class GlobalAccess {
   models = ['owner', 'animal'];
 
-  access(request) {
-    if (request.url.endsWith('/owner/angela')) return false;
+  access(request, { model, operation, recordId }) {
+    // `model` is the model this route was mounted for. It is assigned once, at
+    // mount time, and no request can influence it — not a mount prefix, not a
+    // query string, not a case-varied path, not an absolute-form request
+    // target. `recordId` is the record this route was ADDRESSED TO, decoded by
+    // the router and coerced to the key the store lookup uses. Nothing below
+    // parses anything, and since abofs/stonyx-orm#236 nothing below reads
+    // argument one AT ALL. Variants 1, 2, 4 and 5 were already unconstructible;
+    // the sub-path STRING COMPARISON that variant 3 lived in is gone too,
+    // replaced by a comparison against the decoded id. Retiring the "variant 3
+    // survives" wording at the four sites that still carry it — with the
+    // measurement that retires it, rather than by deletion — is
+    // abofs/stonyx-orm#238.
+    //
+    // `operation` is destructured to name the whole contract at the point of
+    // use. This sample's rules are per-model and per-record rather than
+    // per-verb, so it does not branch on it; the permission array at the bottom
+    // is where the verb is answered.
+
+    // FAIL CLOSED ON AN UNIDENTIFIABLE MODEL. `model` is absent for any caller
+    // that resolved this predicate without supplying the context, and a request
+    // this function cannot identify DENIES rather than falling through to the
+    // CRUD grant at the bottom. An unidentifiable input must never be the
+    // permissive path.
+    if (typeof model !== 'string' || model === '') return false;
+
+    if (model === 'owner') {
+      // FAIL CLOSED ON AN ABSENT `recordId` TOO, AND `undefined` IS THE ONLY
+      // SPELLING OF ABSENT. `auth()` ALWAYS sets the key — `null` on a
+      // collection route, which is addressed to no record — so `undefined`
+      // means the context did not come from `auth()`: it was hand-assembled by
+      // a caller resolving this predicate through the documented
+      // `Orm.instance.getAccess()` path. Letting that through would fall
+      // straight to the per-record filter below, which is a DENY becoming an
+      // ALLOW. This is the same rule the old guard on `request.path` enforced,
+      // moved to the argument this predicate now actually reads.
+      if (recordId === undefined) return false;
+
+      // THE `/archived` DENY, EXPRESSED AGAINST THE DECODED ID. It used to be
+      // `request.path.toLowerCase()` compared against `'/archived'`, and that
+      // was wrong in both directions at once.
+      //
+      // TOO PERMISSIVE: express sets `request.path` from the RAW pathname while
+      // the router DECODES `:id`, so `GET /owners/%61rchived` reached the
+      // comparison as `/%61rchived`, walked past the deny and was dispatched as
+      // the record `archived` — 200 with the record in full, and DELETE
+      // answered 204 with the record DESTROYED, unauthenticated. 255
+      // non-canonical spellings of that 8-character id decode to the same key,
+      // so no deny-list of spellings was ever going to close it.
+      //
+      // TOO STRICT: a record id is a VALUE, not a literal route segment, and
+      // express's `case sensitive routing` governs literal segments only. With
+      // a distinct owner seeded at `ARCHIVED`, the `.toLowerCase()` 403'd
+      // `GET /owners/ARCHIVED` — the wrong record — while still admitting
+      // `GET /owners/%41RCHIVED`, the same record encoded.
+      //
+      // SO DO NOT NORMALISE `recordId`. It is already decoded, exactly ONCE,
+      // which is what a route parameter means: `/owners/%2561rchived` is the
+      // legitimate id `%61rchived`, and decoding until stable would deny it. Do
+      // not case-fold it. Do not rebuild it from `request.path` — decoding the
+      // whole path decodes THEN splits while the router splits THEN decodes,
+      // which over-denies the distinct record at `/owners/archived%2fx`.
+      //
+      // THE DENY IS NOW EXPRESSIBLE FROM THE CONTEXT ALONE, which is exactly
+      // what `recordId` bought — and it still must not be dropped. Deleting it
+      // does not remove a rule loudly, it turns a deny into an ALLOW, silently.
+      if (recordId === 'archived') return false;
+
+      // Returning a function plugs it in as a per-record filter, and it is
+      // enforced on every surface addressed to one of these records:
+      //   /owners, /owners/:id, /owners/:id/pets, /owners/:id/relationships/pets
+      // A rejected record is 404 on record routes — the same status as a record
+      // that does not exist — so the filter is not an existence oracle.
+      return record => record.id !== 'angela' && record.id !== 'restricted';
+    }
+
+    // `record.owner` resolves to an OrmRecord, not to the owner's id string —
+    // comparing it directly against a string is the bug that made this predicate
+    // inert. Deliberately NO `?? record.owner` fallback: accepting the raw
+    // shape as well as the resolved one would absorb a resolution regression
+    // silently, which is exactly what blinded this fixture before.
+    if (model === 'animal') return record => record.owner?.id !== 'restricted';
+
+    // Allows full access to all calls that don't match any of the above conditions
     return ['read', 'create', 'update', 'delete'];
   }
 }
 ```
 
+
+### The access context (second argument)
+
+`access()` is called with **two** arguments:
+
+```js
+access(request, { model, operation })
+```
+
+The second is the **access context** — the structural facts about the request,
+which the framework already holds at authorization time. Read these instead of
+parsing anything.
+
+| Key | Value |
+|---|---|
+| `model` | The model this route was mounted for, as a **model name**: kebab-case, exactly as declared under `config.orm.paths.model` and keyed in the store — `'owner'`, `'animal'`, `'phone-number'`. **Not** the pluralized, dasherized, mount-prefixed *route* name. |
+| `operation` | One of **`'read'`, `'create'`, `'update'`, `'delete'`** — and no second vocabulary *on this path*. Never an HTTP method name like `'GET'`, and **not** the hook vocabulary either (see [below](#operation-is-not-the-hook-operation)). `undefined` when the dispatched method has no entry in the framework's method map. |
+
+So a predicate can be written without reference to any URL:
+
+```js
+export default class OwnerAccess {
+  models = ['owner'];
+
+  access(request, { model, operation }) {
+    if (model === 'owner' && operation === 'read') {
+      return record => record.id !== 'angela';
+    }
+
+    return ['read'];
+  }
+}
+```
+
+There is no string to parse, no variant to miss, and no way to fail open through
+a URL shape nobody anticipated. `model` is fixed at mount time and no request
+can influence it — not a mount prefix, not a query string, not a case-varied
+path, not an absolute-form request target.
+
+#### What the context does not tell you: which surface
+
+It names **which model and which verb**, not **which route**. Measured over the
+live router, six surfaces produce one identical context:
+
+```
+GET /owners                          { model: 'owner', operation: 'read' }
+GET /owners/gina                     { model: 'owner', operation: 'read' }
+GET /owners/gina/pets                { model: 'owner', operation: 'read' }
+GET /owners/gina/relationships/pets  { model: 'owner', operation: 'read' }
+GET /owners/archived                 { model: 'owner', operation: 'read' }
+GET /owners/gina?include=pets        { model: 'owner', operation: 'read' }
+```
+
+So a rule that depends on the **sub-path** still needs `request.path` —
+mount-relative and query-free, and the one read of argument one that
+[Identifying the collection](#identifying-the-collection) sanctions. The sample
+access class shipped with this repo has such a rule: its `/archived` deny
+**cannot be expressed from the context alone**, and a predicate migrated to
+context-only would silently drop it — a deny becoming an allow.
+
+**Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
+[#237](https://github.com/abofs/stonyx-orm/issues/237).** The context also carries
+`recordId` — the record this route was addressed to, already decoded — so the
+`/archived` deny **is** expressible from the context alone, and the shipped sample
+no longer reads `request.path`. The full contract is `AccessContext.recordId` in
+`src/types/orm-types.ts`, which ships. This section — the signature, the key table
+and this paragraph — is corrected by
+[#238](https://github.com/abofs/stonyx-orm/issues/238); the pointer is here because
+what it currently says is an instruction, and the instruction is wrong.
+
+Note also that the related-resource and `?include=` surfaces serve *another
+model's* records under `model: 'owner'`, and the context gives a predicate no
+signal that it is authorizing a related-resource route. That is
+[#196](https://github.com/abofs/stonyx-orm/issues/196).
+
+#### `operation` is not the hook `operation`
+
+This module exposes a **second** `operation` vocabulary, on an identically-named
+key of an identically-shaped context object:
+[hook contexts](#hook-context-object) carry `list` / `get` / `create` /
+`update` / `delete`. The access vocabulary collapses `list` and `get` into
+`'read'`, so for one `GET /animals/1` a hook sees `'get'` while `access()` sees
+`'read'` — and a predicate cannot distinguish a collection read from a
+record read.
+
+"No second vocabulary" above is a statement about the **access path**, where
+both the context and the permission array come from one method map. It is not a
+statement about the module. Writing `operation === 'get'` in a predicate never
+matches, and a predicate that stops matching falls through to the permission
+array — so the misreading is fail-open shaped. In TypeScript the exported
+`AccessOperation` union makes it a compile error.
+
+The four `operation` values are the same four strings the permission-array
+return shape is written in (`['read', 'create', 'update', 'delete']`), because
+both come from one method map inside the framework. The two forms cannot
+disagree about the same request.
+
+**`operation` is `undefined`, never defaulted, for an unmapped method.** Express
+delivers `HEAD` to the `GET` handler, so this is reachable. It is deliberately
+not defaulted to `'read'`: a fabricated operation would turn an unclassified
+request into an authorized one. Treat `undefined` as *not classified* and deny.
+
+**The second argument is additive.** JavaScript ignores extra arguments, so an
+existing `access(request)` predicate keeps working exactly as it did. Nothing
+needs to be migrated to keep running — but note that argument **one** is still
+the raw request, so the warning in
+[Identifying the collection](#identifying-the-collection) still applies to any
+predicate that reads it.
+
+#### `record` is not in the context
+
+Deliberately, and it is not an oversight. `auth()` runs after route matching but
+**before any handler executes**, so nothing has been fetched yet. Supplying a
+record would force a pre-fetch on every request — a second store hit, a new
+failure mode, and an ordering change in the middle of an authorization path.
+
+It is also unnecessary: the **function** return shape already *is* the
+per-record hook. Return `(record) => boolean` and the handlers apply it to every
+record the request touches. Auth-time and record-time are separate decision
+points, and the contract keeps them separate.
+
+#### Reaching another model's predicate
+
+The model → predicate map is published on the ORM instance at boot, before any
+route is mounted, so a predicate can be resolved by model name and asked about a
+request routed to a *different* model:
+
+```js
+import Orm from '@stonyx/orm';
+
+const predicate = Orm.instance.getAccess('animal');
+if (!predicate) return deny;
+
+const verdict = predicate(request, { model: 'animal', operation: 'read' });
+```
+
+**`undefined` means no predicate could be resolved — not that the model is
+unrestricted. Treat it as deny.** It covers a model with no access class *and* a
+model whose access class failed to **load**: a load failure is caught and warned
+about, and the partial map is published anyway, so a missing key is not evidence
+of an unrestricted model. This is the same rule as `operation === undefined`
+above, and for the same reason.
+
+The raw map is `Orm.instance.accessFunctions`, keyed by model name; prefer
+`getAccess()` — it is guarded against inherited `Object.prototype` members and a
+direct index is not. Note that it maps a model name to the predicate of the
+access *class* that claims it, which may claim many models: against this repo's
+sample, `getAccess('owner') === getAccess('animal')`.
+
+#### Passing the context makes a model-correct answer *possible*
+
+It does not make the answer model-correct on its own. **The resolved predicate
+has to read the context.** Against a predicate that ignores it the failure is
+measurable. On a request Express dispatched to `GET /owners/angela`, asked about
+**animals**, the sample as it shipped before
+[#222](https://github.com/abofs/stonyx-orm/issues/222) answered:
+
+```
+getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+  ->  record => record.id !== 'angela' && record.id !== 'restricted'
+```
+
+That is the **owners** filter, and it returns `true` for animal 21 — the record
+hidden on every animal surface. Under a mount such a predicate recognizes
+neither way it is worse still: it falls through to
+`['read', 'create', 'update', 'delete']`, a full CRUD grant. Either way the
+context was supplied and the answer is not the animal answer, and it is wrong in
+the direction that **grants** — because that predicate was single-argument and
+identified its collection from the request, so it answered about the collection
+the request was *addressed to* while being asked about another one.
+
+The sample shipped with this repo has since been migrated to read the context,
+and the same call now answers with the **animal** filter:
+
+```
+getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+  ->  record => record.owner?.id !== 'restricted'
+```
+
+A single-argument predicate remains the default in every consumer tree, and a
+caller has no supported way to tell which kind it resolved. The boot-time arity
+warning that surfaces one is
+[#221](https://github.com/abofs/stonyx-orm/issues/221).
+
+So: pass the context, and do not treat a resolved predicate's answer as
+model-specific until that predicate has been migrated to read it.
+
+### Return values
+
+| `access()` returns | Effect |
+|---|---|
+| `false` (or any falsy value) | `403` for the whole request |
+| `true` | full access, no filter |
+| `['read', 'create', 'update', 'delete']` | the listed operations only; anything else is `403` |
+| `'read'` (a bare string) | **one** permission, equivalent to `['read']` |
+| a function | a per-record filter — see below |
+| anything else | `403` — unknown shapes fail **closed** |
+
+A `throw` inside `access()` is a **denial**, not a 500.
+
+### Filter functions
+
+A function return value is a **per-record predicate**, and it is enforced on
+every endpoint that is addressed to a record — not only on the collection.
+
+It is evaluated against the record the route is *addressed to*, **on that model
+only**. It is not a guarantee that a hidden record cannot be reached or modified:
+a write to a *different* collection can still re-parent one. See
+[Known limitations](#known-limitations) and
+[#207](https://github.com/abofs/stonyx-orm/issues/207).
+
+| Endpoint | A record the predicate rejects |
+|---|---|
+| `GET /:models` | omitted from the collection |
+| `GET /:models/:id` | `404` |
+| `GET /:models/:id/{relationship}` | `404` — the **addressed** record is filtered, not the related one |
+| `GET /:models/:id/relationships/{relationship}` | `404` — same |
+| `PATCH /:models/:id` | `404`, no attribute is applied |
+| `DELETE /:models/:id` | `404`, the record is not removed and no SQL `DELETE` is issued |
+| `POST /:models` | `403`, and a record **this request inserted** is rolled back — see [Known limitations](#known-limitations) for why the rollback is conditional |
+
+**Denied record-level requests return 404, not 403.** This is deliberate and it
+is the property most easily "improved" away. 403 would confirm that the record
+exists to a caller who is not allowed to know that, which turns the filter into
+an existence oracle: `404` means "no such record", `403` means "there is one and
+it is not yours". Every status on a record route must therefore be identical for
+"filtered out" and "does not exist" — including `DELETE`, which is why deleting
+a record that never existed also returns 404 rather than 204.
+
+`POST` is the one exception and returns **403**, because 404 on a mounted
+collection route is indistinguishable from "model not mounted" — a genuinely
+different failure a developer needs to diagnose.
+
+**A client-supplied `id` on `POST` is refused with `403` whenever a function
+filter is in force.** This is the part that keeps `POST` from being an
+enumeration oracle, and it is worth understanding rather than working around.
+The duplicate-id check has to run before the filter, and it sees records the
+filter hides, so the *status* of a `POST` otherwise leaks whether an id is
+taken:
+
+| `POST /animals` with a payload the caller may create | before | now |
+|---|---|---|
+| an id held by a record the filter **hides** | `403` | `403` |
+| an id that is **free** | `200` | `403` |
+| an id held by a record the caller **can see** | `409` | `403` |
+
+Three outcomes, one request per id, the whole id space. Filtering only the
+*collision* status narrows that to callers who cannot create a record they are
+allowed to see; it does not close it. It cannot be closed while a caller both
+chooses the id and learns whether the create succeeded — so under a filter the
+caller does not choose the id. The refusal happens before any store lookup, so
+neither the status nor the response time depends on whether the id exists.
+
+Let the server assign the id and read it back from the response — and read it
+back rather than predicting it, because the value it returns is documented but
+not stable across model kinds: a numeric-id model gets `max + 1` (or, at the
+numeric ceiling, the lowest free integer), and a string-id model gets
+`<model>-<n>`. See breaking change 8.
+
+**What a server-assigned id is not.** It is not a secret. On a string-id
+collection it is dense and enumerable from `1`, where previously it inherited
+whatever entropy the last-inserted id happened to carry — a UUID-seeded store
+answered a UUID-derived key. If a collection has **no** `access` config its
+record-level routes are ungated, so the id was the only thing standing between
+an unauthenticated caller and `GET`/`PATCH`/`DELETE` on a record. That was never
+a control and must not become one; configure `access`.
+
+**And the id itself is an occupancy signal — on both model kinds.**
+`assignRecordId` reads the whole store, not the caller's filtered view — it
+never sees `state.filter` — so the id it returns is a function of records the
+caller may not be permitted to read. **This applies to numeric-id collections
+as well as string-id ones**, and the conditions differ, so read both:
+
+- **String-id collections, always.** The assigned `n` is the smallest positive
+  integer whose landing key is free, which tells the caller that every key
+  below it is taken, hidden or not.
+- **Numeric-id collections, once one record sits at the numeric ceiling.** The
+  normal answer is `max + 1`, which discloses only the maximum. But `max + 1`
+  is not representable at or above 2^53, so the walk restarts from `1` (see
+  breaking change 8) and the assigned id becomes the smallest free integer —
+  the same occupancy predicate, now over arbitrary low keys. Each subsequent
+  no-id `POST` names the next free one, so a caller can enumerate the holes in
+  a range it cannot read.
+
+**A ceiling record reaches a filter-protected collection even though `POST`
+refuses caller ids on one.** Breaking change 3 makes
+`POST /animals {"id": 9007199254740992}` answer `403`, but the same id lands
+through a *relationship write on another collection* —
+`POST /owners` carrying `attributes: { pets: [{ "id": 9007199254740992 }] }`
+creates the animal under that key
+([#207](https://github.com/abofs/stonyx-orm/issues/207), the same channel the
+**Known limitations** re-parenting note describes). So the precondition is
+reachable by an unauthenticated caller on exactly the collections `access`
+exists to protect. Measured on the sample fixture, with every animal hidden by
+the `/animals` predicate and keys 4 and 7 deleted:
+
+```
+GET  /animals                                       -> 200  []      (nothing visible)
+GET  /animals/4                                     -> 404          (free — indistinguishable from hidden)
+POST /animals {"id":4}                              -> 403          (breaking change 3)
+POST /owners  {... pets:[{"id":9007199254740992}]}  -> 200          (#207 plants the ceiling record)
+POST /animals (no id)                               -> 200  id=4    <- names a hole in the hidden range
+POST /animals (no id)                               -> 200  id=7    <- and the other one
+POST /animals (no id)                               -> 200  id=13
+POST /animals (no id)                               -> 200  id=14
+```
+
+Closing this requires the assignment to be filter-aware, which is a change to
+the `access` contract rather than a fix; it is stated here rather than left to
+be discovered. Callers with no function-style filter are unaffected — there are
+no hidden records to disclose.
+
+### Identifying the collection
+
+**Do not reconstruct the request path — and since
+[#202](https://github.com/abofs/stonyx-orm/issues/202) you do not have to
+identify the collection at all.** Read `model` from
+[the access context](#the-access-context-second-argument): it is fixed at mount
+time, no request can influence it, and there is nothing left to parse.
+
+**Everything below is the record of what happened when this sample did parse
+it.** It is kept as history, not as a recipe — none of these matching strategies
+should be written into a new predicate. Every version of this sample that tried
+to identify the collection from the request target failed **open**, and each
+variant was found only after the previous one was fixed:
+
+| # | Variant | Why it fails open |
+|---|---|---|
+| 1 | match `request.url` | `RestServer.mountRoute` mounts each model as an Express **sub-app**, so `url` is mount-relative — `GET /owners/angela` arrives as `/angela`. A `/owners` prefix match is **always false**, so the branch never fires and `access()` falls through to whatever it returns last. |
+| 2 | anchored match on a raw `request.originalUrl` | `originalUrl` carries the query string, so `=== '/owners'` misses `/owners?filter[age]=30` and that collection comes back unfiltered. `endsWith('/owners')` is the older half of the same trap: it leaves every record route unguarded. |
+| 3 | case-sensitive matcher | `RestServer` mounts with a bare `express()`, whose default is `caseSensitive: false`. A matcher stricter than the router that dispatched the request can simply be stepped around: `GET /owners/angela` → 404 but `GET /OwNeRs/angela` → 200 in full, and `DELETE /ANIMALS/22` destroyed a hidden record. Router-side fix: [stonyx-rest-server#47](https://github.com/abofs/stonyx-rest-server/issues/47). |
+| 4 | hard-coded `/owners` | With `ORM_REST_ROUTE=/api` every url becomes `/api/owners/...` and the sample matches nothing — environment-specifically, which is harder to notice than failing everywhere. The remediation this document used to give was itself broken: `` `${config.orm.restServer.route}owners` `` evaluates to **`/apiowners`**, so a reader who followed the correction exactly still failed open and believed they had handled it. |
+| 5 | any match on `originalUrl` at all | HTTP/1.1 permits an **absolute-form** request-target. Express routes on `parseurl(req).pathname`, so the request dispatches normally — but `originalUrl` is the raw target. `GET http://anything.example/owners/angela` yields `originalUrl === 'http://anything.example/owners/angela'`, which has no `/owners` prefix. Measured: the record came back in full, `DELETE` succeeded, and it walked past a hard `return false` deny the same way. |
+
+**The fix is not a sixth rule, and it is not a better string to match.** It is
+to stop identifying the collection at all. That is a statement about
+**identifying the collection**, and it is not a statement about the sample as a
+whole: the `/archived` sub-path rule *is* still a string match, and
+[#228](https://github.com/abofs/stonyx-orm/issues/228) is a sixth spelling that
+gets past it. Sub-path rules are the residue this fix does not cover, which is
+why they must normalise the way the router does.
+
+An intermediate revision read **`request.baseUrl`** — the mount Express
+*actually matched*. That closed all five variants: it carries no query string
+(variant 2), it is not mount-relative (variant 1), it already contains the
+configured `ORM_REST_ROUTE` prefix (variant 4 — there is nothing left to derive,
+so `/apiowners` is unconstructible), and it is unaffected by an absolute-form
+target (variant 5). It was still a transport artifact standing in for a
+structural fact, and it is **no longer what the sample does**: the sample reads
+`model`, so variants 1, 2, 4 and 5 are unconstructible against it rather than
+handled. **Variant 3 survives**, in the one string comparison the migration
+leaves behind: the `/archived` sub-path deny folds case but does not decode
+([#228](https://github.com/abofs/stonyx-orm/issues/228)). The table below is
+retained as the measured evidence behind the five variants, not because any of
+these values should be matched on:
+
+| request | `request.url` | `request.originalUrl` | `request.baseUrl` | `request.path` |
+|---|---|---|---|---|
+| `GET /owners` | `/` | `/owners` | `/owners` | `/` |
+| `GET /owners/angela` | `/angela` | `/owners/angela` | `/owners` | `/angela` |
+| `GET /owners/angela?filter[age]=30` | `/angela?filter[age]=30` | `/owners/angela?filter[age]=30` | `/owners` | `/angela` |
+| `GET /OwNeRs/angela` | `/angela` | `/OwNeRs/angela` | `/OwNeRs` | `/angela` |
+| `GET http://anything.example/owners/angela` | `http://anything.example/angela` | `http://anything.example/owners/angela` | `/owners` | `/angela` |
+| `GET /api/animals/22` (`ORM_REST_ROUTE=/api`) | `/22` | `/api/animals/22` | `/api/animals` | `/22` |
+
+**Superseded 2026-09-01 by [#236](https://github.com/abofs/stonyx-orm/issues/236) /
+[#237](https://github.com/abofs/stonyx-orm/issues/237) — "Variant 3 survives" above,
+and the two paragraphs below, are no longer true.** The access context now carries
+`recordId`, the **decoded** route-parameter id, and the sample compares against it:
+the one string comparison variant 3 lived in is gone, `#228` is **closed**, and no
+read of argument one survives in the sample. The wording is left standing rather
+than deleted because it appears at four sites (this file twice,
+`src/orm-request.ts`, and the test fixture) and retiring one of four leaves the
+shipped copies contradicting each other; retiring all four **with the measurement
+that retires them** is [#238](https://github.com/abofs/stonyx-orm/issues/238).
+
+**One read of argument one survives, and it must: `request.path`.** It is
+mount-relative and query-free, and it is for rules that distinguish **sub-paths**
+beneath the mount — as the `/archived` deny in the sample above does. The context
+names which model and which verb, **not which route**, so that deny *cannot be
+expressed from the context alone*, and a context-only rewrite would silently turn
+it into an allow.
+
+**Normalise the way the router that dispatched the request does — and
+case-folding alone does not.** A matcher stricter than the router can be stepped
+around, so the sample lower-cases before comparing (the router matched
+case-insensitively). That closes the case gap and **it is not the whole rule**:
+Express sets `request.path` from the **raw, undecoded** pathname while the router
+**decodes** `:id`, so `GET /owners/%61rchived` reaches a `path === '/archived'`
+comparison as `/%61rchived`, walks past the deny, and is dispatched as the record
+`archived`. That gap is live in the sample above and is tracked as
+[#228](https://github.com/abofs/stonyx-orm/issues/228) — **do not read the
+`.toLowerCase()` there as a complete normalisation recipe.** Record ids are
+case-sensitive and must be compared at their real case.
+
+**Do not follow the two paragraphs above — superseded 2026-09-01 by
+[#236](https://github.com/abofs/stonyx-orm/issues/236) /
+[#237](https://github.com/abofs/stonyx-orm/issues/237).** They are *instructions*,
+not merely stale observations, which is why this note is louder than a date. The
+sample no longer reads `request.path` and no longer calls `.toLowerCase()` on
+anything it compares: `.toLowerCase()` was measured wrong in **both directions at
+once** — with a distinct owner seeded at `ARCHIVED`, `GET /owners/ARCHIVED` was a
+false **deny** on the wrong record and `GET /owners/%41RCHIVED` a false **allow**
+on that same record. Compare `recordId` **as it arrives**: do not case-fold it, do
+not decode it, do not derive it from `request.path`. The contract is
+`AccessContext.recordId` in `src/types/orm-types.ts`, which ships and says "Do NOT
+case-fold it". Retirement of this wording, with its measurement:
+[#238](https://github.com/abofs/stonyx-orm/issues/238).
+
+**Fail closed on anything you cannot identify — on *either* argument.**
+`String(request.originalUrl ?? '')` was once added here to stop a `TypeError`,
+and it traded fail-closed for fail-**open**: an empty string matched no
+collection, so `access()` fell through to the permission array and granted full
+CRUD. The same rule applies to the context — the sample returns `false` for an
+absent `model` rather than falling through. Since #202 the guard and the read can
+sit on **different objects**, and a guard on argument two does not protect a read
+of argument one: the sample therefore also returns `false` when `request.path` is
+absent or is not a string, rather than letting `?? ''` fall through to the
+per-record filter. An input you cannot identify must **deny**.
+
+### Known limitations
+
+- **A function-style filter is not a guarantee that a hidden record cannot be
+  modified.** A write to a *different* collection can re-parent one and de-hide
+  it: `POST /owners` (or `PATCH /owners/{id}`) carrying
+  `relationships: { pets: { data: { id: 21 } } }` — or
+  `attributes: { pets: [21, 22] } `, which never enters the relationships loop at
+  all — re-parents animal 21 onto an owner the caller is permitted to write. The
+  animal's `owner` is the field the `/animals` predicate reads, so the record
+  stops being rejected: it becomes readable through `GET /animals/21` and
+  deletable through `DELETE /animals/21`. **Reachable unauthenticated** wherever
+  one collection is writable and another is filtered on a field the first can
+  set. Blocking it requires checking animal 21 against the **animal** model's
+  predicate while servicing an **owners** route — cross-model access resolution,
+  which the contract could not express before
+  [#202](https://github.com/abofs/stonyx-orm/issues/202): `access()` never
+  received the model structurally and `setup-rest-server.ts` discarded the
+  model→predicate map at boot. **#202 has landed and both halves now exist** —
+  see [The access context](#the-access-context-second-argument):
+  `Orm.instance.getAccess(modelName)` makes another model's predicate
+  **reachable**, and `context.model` makes a **model-correct answer possible** —
+  possible, not guaranteed: the resolved predicate has to read the context. The
+  sample shipped with this repo now does
+  ([#222](https://github.com/abofs/stonyx-orm/issues/222)), so
+  `getAccess('animal')` answers with the animal filter; a predicate that ignores
+  the second argument still answers about the collection the request is
+  addressed to, and the boot-time warning that surfaces one is
+  [#221](https://github.com/abofs/stonyx-orm/issues/221). **The mechanism
+  exists; the ORM does not yet use it on this path.** The re-parenting write above is still
+  **not refused** — that enforcement is
+  [#196](https://github.com/abofs/stonyx-orm/issues/196) and
+  [#207](https://github.com/abofs/stonyx-orm/issues/207), which were blocked on
+  #202 and are now free to proceed. Until they land, do not rely on a filter to
+  keep a record unmodifiable; keep the *writable* collections' predicates as tight as
+  the hidden ones.
+- **Authorization by identifying the collection is a consumer-side
+  reconstruction of information the framework already holds.** `access()`
+  receives a transport artifact and is asked to work out which model, which
+  operation and which record the request addresses. The five variants above are
+  the five ways that has been observed to fail open so far. Tracked as
+  [#202](https://github.com/abofs/stonyx-orm/issues/202).
+- **Related and included records are not filtered.** The predicate is evaluated
+  against the record the route is *addressed to*. `GET /animals/1/owner`,
+  `GET /animals/1/relationships/owner` and `?include=owner` all serialize the
+  related record without resolving that model's own access class, so a filter on
+  `/owners` does not hide an owner reached through `/animals`. Tracked as
+  [#196](https://github.com/abofs/stonyx-orm/issues/196), which covers
+  `include=`, related-resource routes and relationship-linkage routes.
+- **A before-hook that returns a value short-circuits the request.** On write
+  operations addressed to a record the filter is consulted first, so a hook
+  cannot answer for a record the caller may not see. On reads it is not, so a
+  `beforeHook('get', ...)` read-through cache can answer past the filter.
+- **`beforeHook('create', ...)` still runs for a `POST` that is denied.** For
+  `create` there is no record to test until the handler has built one, so the
+  denial is not knowable in time. Every *after*-hook is gated, and every
+  before-hook on `update` and `delete` is gated; before-`create` is the one
+  exception. A before-`create` hook must not assume the create will succeed.
+- **A caller can still learn that a collection *has* a per-record filter**, by
+  observing `403` rather than `409`/`200` for an id-bearing `POST`. That
+  discloses a configuration fact, not the existence of any record.
+- **Enforcement is post-fetch.** The record is loaded and then tested, which
+  leaves a small timing difference between a hidden record and one that never
+  existed. Tracked as [#197](https://github.com/abofs/stonyx-orm/issues/197).
+- **A `relationships` key that is not a declared relationship is still applied
+  to the record.** The key comes verbatim from the request body and is checked
+  against nothing except `id`, which is stripped. On a `POST` that makes an
+  undeclared key a mass-assigned attribute; on a `PATCH` it is passed to
+  `updateRecord`. `id` is stripped in both handlers because it defeats breaking
+  change 3 above; the general form is tracked as
+  [#204](https://github.com/abofs/stonyx-orm/issues/204).
+- **A `POST` body `id` that the duplicate check cannot resolve can still
+  overwrite a different record on an unfiltered collection.** The lookup is
+  correct and deliberately does not coerce: `"9105h"` is rejected as a string
+  rather than truncated, and `9105.5`, `[9105]` and `true` are passed through as
+  themselves. The model's id transform then coerces anyway — a bare `parseInt`
+  with no such guard — so the create lands on `9105` (or on `NaN`) and
+  overwrites whatever is there. **This is not string-only**: any body id whose
+  transform output differs from its lookup key is the same defect. Filtered
+  collections are unaffected — breaking change 3 refuses any client-supplied id
+  — so this reaches consumers with **no** function-style filter. Tracked as
+  [#205](https://github.com/abofs/stonyx-orm/issues/205). Its sibling
+  [#203](https://github.com/abofs/stonyx-orm/issues/203) — a **server-assigned**
+  id landing on an occupied slot — is **fixed**; see breaking change 8. #205 is
+  the client-supplied half and is still open.
+- **`context.record` is `undefined` for an after-`create` hook when a string-id
+  model is given a numeric-looking id.** The post-create lookup uses the same id
+  coercion as every other surface, which resolves `'9107'` to the number `9107`,
+  while a model declaring `id = attr('string')` files the record under the string
+  key. The create itself succeeds and `context.response.data` is correct; only
+  the hook's view of the record is wrong, and it is wrong *silently*. Tracked as
+  [#209](https://github.com/abofs/stonyx-orm/issues/209).
+- **A denied `POST` rolls back only a record it *inserted*.** The rollback
+  requires the store to have grown, because removing by id alone is a write
+  primitive keyed by a caller-supplied value. **The reachability condition this
+  bullet used to state is gone**: it was
+  [#203](https://github.com/abofs/stonyx-orm/issues/203) — `assignRecordId`
+  returned last-*inserted* + 1, so a server-assigned id could land on an
+  occupied slot and `createRecord` would update it in place — and #203 is fixed
+  (breaking change 8). A server-assigned create can no longer overwrite, so on a
+  collection whose only id channel is `createHandler` this guard has no
+  observable effect today. It is kept because a caller-supplied id reaching
+  `createRecord` from another route — a relationship write,
+  [#207](https://github.com/abofs/stonyx-orm/issues/207) — puts the condition
+  back, and without the guard a denied `403` would delete a record the request
+  did not create.
+
+### Breaking changes
+
+These land in the next published build. There is no changelog or release-notes channel yet
+([stonyx-workflows#17](https://github.com/abofs/stonyx-workflows/issues/17)), so
+they are recorded here.
+
+1. **`DELETE /{collection}/{id}` on a record that does not exist returns `404`
+   instead of `204`.** This affects **every** consumer issuing a DELETE against
+   any mounted collection, whether or not an access filter is configured, and
+   `models: '*'` mounts every model by default. It is not optional: if a denied
+   delete returned 404 while a missing one returned 204, the pair would be a
+   perfect existence oracle and the filter would be worthless.
+2. **After-hooks no longer fire for a request that failed** — denied, missing,
+   `400` or `409`. The gate is on the handler's status, not on the operation, so
+   it covers reads as well: a `GET /:id` that answers 404 runs no after-`get`
+   hook either. Previously `afterHook('delete', ...)` ran with a populated
+   `context.recordId` on a request that deleted nothing, so a consumer cascade
+   destroyed children behind a 404.
+3. **`POST` with a client-supplied `id` returns `403` when a function-style
+   `access` filter is in force**, whatever the payload and whether or not the id
+   exists, and *before* any store lookup — so neither the status nor the lookup
+   cost can depend on whether that id exists. Only affects function-style
+   `access` users. See [Filter functions](#filter-functions) for why, and let the
+   server assign the id instead. `409`-on-duplicate is unchanged for everyone
+   else.
+
+   "Whatever the payload" is a statement about the **`id` member of the resource
+   object**, and it holds only because that is the sole channel a caller id can
+   arrive on. It was not always: a caller id moved into
+   `relationships: {"id": {"data": {"id": 21}}}` reached `createRecord` past this
+   refusal and overwrote a hidden record in place. Both strips — `attributes.id`
+   and `relationships.id` — are part of this behaviour, not tidiness. A future
+   change that adds a third channel without stripping it re-opens the oracle;
+   see [#204](https://github.com/abofs/stonyx-orm/issues/204).
+4. **Function-style `access` is now enforced on all seven surfaces.** Records
+   previously reachable by id despite being filtered from the collection now
+   return 404. Only affects function-style `access` users, for whom the old
+   behaviour was the bypass.
+
+   "Seven surfaces" means the seven endpoints of **the filtered model**. A write
+   to another collection can still reach one of its records through a
+   relationship — [#207](https://github.com/abofs/stonyx-orm/issues/207), which
+   is **not** closed here.
+5. **A predicate that throws is treated as a denial** rather than propagating to
+   Express's default 500 handler. So is an `access()` that throws.
+6. **`access()` returning a bare string is one permission, not full access.**
+   `AccessMethod` declares `string` legal, and it previously fell through every
+   branch and granted all four operations — `return 'read'` allowed `DELETE`.
+   It is now equivalent to `['read']`. Any other unrecognised shape (an object,
+   a number) now returns `403` rather than granting full access.
+7. **`POST` with a client-supplied `id` normalises the body id before the
+   duplicate check**, so an id shape that previously *missed* the store's key
+   now finds it. `POST {"id":"0x2391"}` and `POST {"id":"  21  "}` answer `409`
+   where they answered `200`, and the `200` was not a success: the lookup missed,
+   the duplicate check was skipped, and `createRecord` overwrote the colliding
+   record in place. **This one reaches consumers with no filter at all** — the
+   population breaking changes 3 and 4 explicitly exempt. If you were relying on
+   a hex-shaped or whitespace-padded id creating a second record, it never did.
+
+8. **Server-assigned ids change value on string-id models, numeric ids stop
+   being monotonic at the numeric ceiling, and the create route gains a
+   `409`.** Three consumer-visible changes from
+   [#203](https://github.com/abofs/stonyx-orm/issues/203).
+
+   **The value.** A `POST` with no `id` against a model declaring
+   `id = attr('string')` previously produced the *last-inserted* id with `1`
+   concatenated onto it — an owner store holding `['gina', 'bob']` answered
+   `'bob1'`. It now answers `'owner-1'`: the model name, a hyphen, and the
+   lowest positive integer whose landing key is free. **No test in this repo
+   pinned the old value**, so a consumer relying on it gets no failing test, no
+   deprecation and no other signal — which is why it is recorded here. Numeric
+   id models (`id = attr('number')`, the default) are unaffected in shape: they
+   still get an integer, but it is now the **maximum** existing id plus one
+   rather than the last-inserted id plus one, which is the defect #203 is about.
+   They are **not** unaffected in *sequence* — see the monotonicity half below.
+
+   The value is deliberately **not** numeric-looking, and that is not cosmetic.
+   Every id-bearing surface resolves a numeric-looking string id to a **number**
+   (`GET /owners/1` looks up `1`), while a string-id model files its records
+   under the **string** key `'1'`. A server-assigned `'1'` would therefore be a
+   record that was created successfully and could not be fetched, updated or
+   deleted by id, and whose after-`create` hook received
+   `context.record === undefined`
+   ([#209](https://github.com/abofs/stonyx-orm/issues/209)).
+
+   **Numeric ids are no longer monotonic, and deleted ids can be re-issued.**
+   The precondition is narrow but it is reachable, and there is no signal when
+   it is met: **one record filed at or above 2^53** (`9007199254740992`). `max
+   + 1` is not representable there, so assignment restarts from `1` and walks
+   up to the lowest free key — which means the id of a *deleted* record is
+   handed to the next `POST`. Both `dev` and every prior release were strictly
+   monotonic and never re-issued a numeric id, so a consumer that relied on
+   that — audit rows, cursors, cached authorization decisions, external
+   references keyed on the id — now has a stale reference that silently points
+   at a **different record, created by a different caller**, rather than at a
+   deleted one. Nothing fails; the reference simply resolves to the wrong
+   record.
+
+   The restart is deliberate and is not itself optional: without it, one record
+   at the ceiling made every subsequent server-assigned create on that
+   collection fail permanently. Re-use is the cost of keeping the collection
+   writable. **If you need monotonic ids, assign them yourself** rather than
+   letting the server assign, and note that a ceiling record can be planted by
+   an unauthenticated caller — see *And the id itself is an occupancy signal*
+   under [Filter functions](#filter-functions) for the reachability path.
+   String-id models are unaffected by this half: their keys are
+   `<model>-<n>` and were never monotonic over an integer sequence.
+
+   **The status.** `POST /{collection}` can now answer `409` for a reason other
+   than a duplicate id: the server could not derive a free id. That requires a
+   **non-injective** id transform — one that maps distinct candidates onto the
+   same store key, such as `boolean`, or anything you registered on
+   `Orm.instance.transforms` and named as an id type. It is a configuration
+   fault rather than a request fault; the message is logged through
+   `stonyx/log`. Previously this case threw out of the handler and express
+   answered `500` with a stack trace.
+
 ### Include Parameter (Sideloading Relationships)
 
 The ORM supports JSON API-compliant relationship sideloading via the `include` query parameter. This reduces the need for multiple API requests by embedding related records in a single response.
@@ -434,6 +1249,16 @@ Each hook receives a context object with comprehensive information:
 - It contains a deep copy of the record's state **before** the operation executes (captured before the `before` hook fires)
 - 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
+- **`context.recordId` here is NOT `AccessContext.recordId`.** Same name, same-shaped
+  object, different coverage: `_withHooks` sets this key **only** under
+  `operation === 'delete'`, so on `get` / `list` / `create` / `update` the key is
+  **absent** — `beforeHook('update', 'owner', ctx => ctx.recordId === 'archived' ? 403 : undefined)`
+  never fires (measured: `PATCH /owners/{id}` → 200 with `ctx.recordId === undefined`
+  and the id sitting in `ctx.params`). The access context, by contrast, carries
+  `recordId` on every route it classifies and spells absence as `null`, never
+  `undefined`. Tracked as
+  [#242](https://github.com/abofs/stonyx-orm/issues/242); see
+  `AccessContext.recordId` in `src/types/orm-types.ts` for the other side.
 - `oldState` is captured as a deep copy of the record's data before the operation, providing access to the previous field values
 
 ### Usage Examples
@@ -561,7 +1386,19 @@ afterHook('delete', 'animal', async (context) => {
 // Additional access control - halt with 403 if unauthorized
 beforeHook('delete', 'animal', (context) => {
   const user = context.state.currentUser;
-  const animal = store.get('animal', context.params.id);
+
+  // `context.oldState` — NOT a store lookup. For `update` and `delete` the ORM
+  // has already fetched the record (and already applied the access filter to
+  // it) before this hook runs, so re-fetching it here is a fourth id coercion
+  // that has to agree with three others.
+  //
+  // And it would not agree. `context.params.id` is the raw url segment, always
+  // a string, while the store keys numeric-id models by NUMBER — so
+  // `store.get('animal', '21')` misses the record held under `21`, and so does
+  // `store.find('animal', '21')`: neither coerces. The miss reads as "no such
+  // record", which in an authorization hook fails whichever way your code
+  // happens to handle a null.
+  const animal = context.oldState;
 
   if (animal.owner !== user.id && !user.isAdmin) {
     return 403; // Forbidden
@@ -569,6 +1406,10 @@ beforeHook('delete', 'animal', (context) => {
 });
 ```
 
+> If you do need a lookup for some *other* model inside a hook, coerce the id
+> yourself to the type that model's `id` attribute declares — the store is a
+> `Map` and `'21'` and `21` are different keys.
+
 #### Auditing
 
 ```javascript
@@ -702,11 +1543,29 @@ beforeHook('create', 'post', (context) => {
 
 ### Hook Execution Order
 
-1. **Before hooks** fire first (sequentially, in registration order)
-2. **Main operation** executes (if no before hook halted)
-3. **After hooks** fire last (sequentially, in registration order)
-
-Before hooks can halt the operation by returning a value. After hooks run after completion and cannot halt.
+1. **Authorization is evaluated first for `update` and `delete`.** A record the
+   access filter rejects returns `404` **before any before-hook runs**, so a
+   hook never sees a record — or a `context.oldState` — that the caller is not
+   allowed to read. `create` is the exception: there is no record to test until
+   the handler has built one, so `beforeHook('create', ...)` **does** fire for a
+   `POST` that goes on to answer `403`.
+2. **Before hooks** fire next (sequentially, in registration order).
+3. **Main operation** executes (if no before hook halted).
+4. **After hooks** fire last (sequentially, in registration order) — **only if
+   the request succeeded.**
+
+Before hooks can halt the operation by returning a value, and that value becomes
+the response.
+
+**After hooks do not run for a failed request.** Any status `>= 400` — denied,
+missing, `400`, `409` — skips the entire after-hook pipeline, along with SQL
+persistence and `onUpdate` autosave. This is a behaviour change; see
+[Breaking changes](#breaking-changes). It applies to the samples above: the
+`afterHook('delete', ...)` auditing hook writes **no** audit row for a `DELETE`
+that answered `404`, and the `afterHook('update', ...)` change-tracking hook
+writes none for a `PATCH` that answered `404` or `400`. If you need a record of
+refused requests, log them from a before-hook or from your own middleware —
+`after<operation>` fires only for an operation that actually happened.
 
 ### Best Practices