@stonyx/orm 0.3.2-alpha.72 → 0.3.2-alpha.74

package/src/orm-request.ts

@@ -69,6 +69,15 @@
  * records under `model: 'owner'`, and the context gives no signal of that
  * (abofs/stonyx-orm#196).
  *
+ * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237, AND KEPT FOR THE
+ * CONSTRAINT IT STATES RATHER THAN AS A DESCRIPTION OF THE CODE. The context
+ * now also carries `recordId` -- the DECODED route-parameter id, see
+ * `AccessContext.recordId` in ./types/orm-types.ts -- so the fixture's
+ * `/archived` deny IS expressible from the context alone, and the shipped
+ * sample no longer reads `request.path` at all. Retiring this wording WITH the
+ * measurement that retires it, rather than by deletion, is
+ * abofs/stonyx-orm#238.
+ *
  * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
  * matching but BEFORE any handler executes (`@stonyx/rest-server`
  * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
@@ -158,6 +167,11 @@
  * `/archived` SUB-PATH rule is still a string match, and abofs/stonyx-orm#228 is
  * a sixth spelling that gets past it.
  *
+ * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: the `/archived` rule is
+ * no longer a string match against the request target -- it compares the
+ * decoded `recordId` the framework supplies -- and abofs/stonyx-orm#228 is
+ * CLOSED. Retirement of this wording: abofs/stonyx-orm#238.
+ *
  *   An intermediate revision of the sample read `request.baseUrl` -- the mount
  *   Express ACTUALLY MATCHED. That closed all five variants (no query string,
  *   not mount-relative, unaffected by absolute-form, already carrying the
@@ -173,12 +187,26 @@
  *   does not decode, so `GET /owners/%61rchived` steps past it. See the
  *   normalisation paragraph below and abofs/stonyx-orm#228.
  *
+ *   SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237. Variant 3 lived in that
+ *   one string comparison, and the comparison is gone: the sample compares the
+ *   decoded `recordId`. Left standing rather than edited because the same
+ *   "variant 3 survives" wording sits at four sites -- this header, README.md
+ *   twice, and test/sample/access/global-access.ts -- three of which SHIP, so
+ *   retiring one of four leaves the shipped copies contradicting each other.
+ *   Retiring all four WITH their measurement is abofs/stonyx-orm#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. The context names which model and which verb, NOT which
  * route, so the sample's `/archived` deny cannot be expressed from the context
  * alone and a context-ONLY rewrite would silently turn that deny into an allow.
  *
+ * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: NO read of argument one
+ * survives in the shipped sample. `recordId` names WHICH RECORD the route was
+ * addressed to, so the `/archived` deny is expressible from the context alone
+ * -- and it still must not be dropped; expressible is not optional. Retirement
+ * of this wording: abofs/stonyx-orm#238.
+ *
  * NORMALISE THE WAY THE ROUTER DOES, AND CASE-FOLDING ALONE IS NOT THAT. The
  * sample lower-cases before comparing, because a matcher stricter than the
  * case-insensitive router can be stepped around. That closes the case gap only.
@@ -188,6 +216,20 @@
  * sample and is tracked as abofs/stonyx-orm#228; the `.toLowerCase()` is not a
  * complete normalisation recipe. Compare record ids at their real case.
  *
+ * DO NOT FOLLOW THE PARAGRAPH ABOVE. SUPERSEDED 2026-09-01 BY
+ * abofs/stonyx-orm#236/#237, and flagged here rather than merely dated because
+ * it is an INSTRUCTION, not a stale observation. `.toLowerCase()` on the access
+ * path 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. A
+ * record id is a VALUE, not a literal route segment, and express's
+ * `case sensitive routing` governs literal segments only. Compare
+ * `context.recordId` AS IT ARRIVES: do not case-fold it, do not decode it, do
+ * not derive it from `request.path`. `AccessContext.recordId` in
+ * ./types/orm-types.ts is the contract and says "Do NOT case-fold it"; the same
+ * published tarball ships both files, and THIS paragraph is the one that is
+ * wrong. Retiring it WITH its measurement is abofs/stonyx-orm#238.
+ *
  * `?? ''` is not a defence. It converts an absent request target into an empty
  * string, which matches no collection, which falls through to the permission
  * array -- a total grant. An input you cannot identify must DENY, and that
@@ -196,6 +238,12 @@
  * argument one. The sample returns `false` for an absent `model` AND for an
  * absent or non-string `request.path`, rather than falling through either way.
  *
+ * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237 as to WHAT is guarded --
+ * the principle is unchanged. The sample no longer reads `request.path`, so it
+ * returns `false` for an absent `model` AND for an absent `recordId`
+ * (`undefined`, the one spelling `auth()` never produces). Retirement of this
+ * wording: abofs/stonyx-orm#238.
+ *
  * THE REAL FIX IS abofs/stonyx-orm#202: `access()` should receive the model,
  * the operation and the record. Prefer the array shape (`['read']`) or `false`
  * until #202 lands; the function shape is what requires any matching at all.
@@ -219,7 +267,7 @@ import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
-import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
+import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation, LinkageFilter } from './types/orm-types.js';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
 import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 
@@ -417,9 +465,9 @@ function buildResponse(
   data: unknown,
   includeParam: string | undefined,
   recordOrRecords: OrmRecord | OrmRecord[],
-  options: { links?: { [key: string]: string }; baseUrl?: string } = {}
+  options: { links?: { [key: string]: string }; baseUrl?: string; linkage?: LinkageFilter } = {}
 ): JsonApiResponse {
-  const { links, baseUrl } = options;
+  const { links, baseUrl, linkage } = options;
   const response: JsonApiResponse = { data };
 
   // Add top-level links
@@ -434,14 +482,49 @@ function buildResponse(
 
   const includedRecords = collectIncludedRecords(recordOrRecords, includes);
   if (includedRecords.length > 0) {
-    // NO `linkage` ARGUMENT, deliberately, and abofs/stonyx-orm#235 owns adding
-    // one. Until it does, a PERMITTED record here emits the full pre-#234
-    // document: `GET /animals/1?include=owner` filters the primary document's
-    // `owner.data` to `null` and then names `owner:angela` in `included`.
-    // Whether a resource reaches this array at all is a different question
-    // (membership, abofs/stonyx-orm#233) and closing that one does not close
-    // this one.
-    response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
+    // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
+    // line is one story's and the line above it is another's
+    // (abofs/stonyx-orm#235 and #233 respectively).
+    //
+    //   - WHICH RESOURCES REACH THIS ARRAY is decided by
+    //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
+    //     #233's, and it is deliberately untouched here: a hidden owner is
+    //     still a member of `included` after this change. Pinned green by
+    //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
+    //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
+    //     `relationships.*.data` is LINKAGE -- the same question #234 answers
+    //     for the primary document -- and that is what the `linkage` option
+    //     below decides. Before it, `GET /animals/1?include=owner,owner.pets`
+    //     filtered the primary document's `owner.data` to `null` and then
+    //     handed back nine PERMITTED animals in `included` each naming
+    //     `{"type":"owner","id":"angela"}`. Neither #233 nor #234 closes that.
+    //
+    // THE FILTER IS THE CALLER'S, PASSED IN, NOT BUILT HERE. Both call sites
+    // already hold one for the primary document, and sharing it is what keeps
+    // the per-type verdict cache and the per-(type, id) decision cache alive
+    // across the primary document AND the sideload -- one verdict resolution
+    // per type for the whole response, pinned by `[GUARD] #235 C1`. Building a
+    // fresh filter here would resolve the consumer's `access()` once per
+    // included record instead.
+    //
+    // `linkage` IS OPTIONAL IN THE TYPE AND IS NOT OPTIONAL IN PRACTICE.
+    // Stating it precisely because the opposite claim stood here in an earlier
+    // draft of this change: BOTH of this function's callers supply a filter
+    // (`getCollectionHandler` and `getSingleHandler`, the only two), so the
+    // `undefined` branch has no live caller in this module today. It is
+    // optional so that omitting it degrades to the PRE-#234 document rather
+    // than to a denial -- `Record.toJSON` reads an ABSENT option as "no verdict
+    // was supplied" and emits linkage in full.
+    //
+    // WHAT IT MUST NEVER BE HANDED IS A NON-FUNCTION. `toJSON` does NOT read a
+    // non-function as absent: `Object.prototype.toString.call(linkage)` must be
+    // `'[object Function]'`, and anything else -- `null`, an `AsyncFunction`,
+    // and INCLUDING the primitive `true` -- DENIES every relationship on the
+    // document and logs once. `toJSON({ linkage: true })` emits `null` linkage.
+    // So do not "simplify" this to a boolean, and do not make it default to
+    // `true`: both spellings look like "allow everything" and mean the exact
+    // opposite (abofs/stonyx-orm#224).
+    response.included = includedRecords.map(record => record.toJSON?.({ baseUrl, linkage }));
   }
 
   return response;
@@ -652,7 +735,11 @@ export default class OrmRequest extends Request {
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
-        baseUrl
+        baseUrl,
+        // THE SAME filter object the primary documents above were serialized
+        // with, deliberately: it carries the caches, and rebuilding one here
+        // would re-resolve every type (abofs/stonyx-orm#235).
+        linkage
       });
     };
 
@@ -670,29 +757,29 @@ export default class OrmRequest extends Request {
       const baseUrl = getBaseUrl(request);
       const linkage = createLinkageFilter(request);
 
-      // `buildResponse` is deliberately NOT given the linkage filter, and the
-      // residual that leaves is NOT the one #233 owns. Two different questions:
-      //
-      //   - WHETHER A RESOURCE APPEARS in `included` at all is MEMBERSHIP ->
-      //     abofs/stonyx-orm#233.
-      //   - What a record already IN `included` may NAME is LINKAGE -- the same
-      //     question #234 answers for the primary document -- and it is
-      //     abofs/stonyx-orm#235, which also owns createHandler/updateHandler.
+      // `buildResponse` IS given the filter now (abofs/stonyx-orm#235), and it
+      // is the SAME object the primary document is serialized with -- one
+      // verdict per type for the whole response, sideload included.
       //
-      // The residual, stated so the next reader does not have to derive it:
-      // `buildResponse` calls `record.toJSON?.({ baseUrl })` with no `linkage`
-      // argument, so a PERMITTED record in `included` emits the full pre-#234
-      // document. Measured: `GET /animals/1?include=owner` returns
-      // `owner.data: null` on the primary document and `owner:angela` in
-      // `included`. One query parameter deep. Only the PRIMARY document's
-      // linkage is filtered here.
+      // The boundary that remains, so the next reader does not have to derive
+      // it: this closes what a record already in `included` may NAME. WHETHER a
+      // resource appears in `included` at all is MEMBERSHIP and it is
+      // abofs/stonyx-orm#233's -- a hidden owner is still a member here.
+      // Neither question closes the other.
       return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
-        baseUrl
+        baseUrl,
+        linkage
       });
     };
 
-    const createHandler: HandlerFn = async ({ body, query }, { filter }) => {
+    const createHandler: HandlerFn = async (request, { filter }) => {
+      // BOUND, not destructured (abofs/stonyx-orm#235). `HandlerFn` has always
+      // delivered the request as argument one; this handler simply discarded
+      // the binding, which is why its response document named ids every read
+      // surface withholds. `createLinkageFilter` needs the live request and
+      // there is no signature change involved in giving it one.
+      const { body, query } = request;
       const { type, id, attributes, relationships: rels } = (body?.data || {}) as {
         type?: string;
         id?: string | number;
@@ -947,10 +1034,29 @@ export default class OrmRequest extends Request {
         return 403;
       }
 
-      return { data: record.toJSON?.({ fields: modelFields }) };
+      // The filter is built HERE, per invocation, and never hoisted into the
+      // OrmRequest constructor where the other per-mount values live: a verdict
+      // cached across requests answers a second caller with the first caller's
+      // authorization (src/access-verdict.ts says so at the constructor an
+      // implementer would reach for).
+      //
+      // AND IT IS BUILT AFTER `createRecord`, AFTER THE ROLLBACK WINDOW AND
+      // AFTER `isDenied`, so the record is in its final form at the call. The
+      // filter is lazy per type and per (type, id), so it cannot observe a
+      // pre-write state even if it were built earlier.
+      //
+      // `fields` is passed here and NOT in `updateHandler`: the two handlers
+      // are asymmetric on purpose (`updateHandler` has no `fieldsMap` in
+      // scope), and a single copy-pasted wiring would drop it from one of them.
+      return { data: record.toJSON?.({ fields: modelFields, linkage: createLinkageFilter(request) }) };
     };
 
-    const updateHandler: HandlerFn = async ({ body, params }, { filter }) => {
+    const updateHandler: HandlerFn = async (request, { filter }) => {
+      // Bound rather than destructured, for the reason given in
+      // `createHandler` above (abofs/stonyx-orm#235). `PATCH /animals/1`
+      // returned 200 naming angela seconds after `GET /animals/1` returned
+      // `owner.data: null` for the same record -- one HTTP verb apart.
+      const { body, params } = request;
       const found = await store.find(model, getId(params));
       if (!found || !isOrmRecord(found)) return 404;
       // Checked BEFORE any attribute is applied. 404 rather than 403 for the
@@ -1009,7 +1115,14 @@ export default class OrmRequest extends Request {
         }
       }
 
-      return { data: record.toJSON?.() };
+      // No `fields` and no `baseUrl`, both unchanged: `updateHandler` has no
+      // `fieldsMap` in scope, and adding `baseUrl` would put `links` on a
+      // document that has never carried them -- an unrelated behaviour change.
+      // #224 AC6's "emits `data: []` WITH links" is a statement about the READ
+      // surfaces; on these two handlers a filtered relationship and a
+      // genuinely-empty one are both a bare `{ data }`, which is what makes
+      // them indistinguishable here too.
+      return { data: record.toJSON?.({ linkage: createLinkageFilter(request) }) };
     };
 
     const deleteHandler: HandlerFn = async ({ params }, { filter }) => {
@@ -1340,6 +1453,28 @@ export default class OrmRequest extends Request {
       };
 
       // Relationship linkage route: GET /:id/relationships/{relationship}
+      //
+      // NO `linkage` FILTER HERE, AND IT IS NOT AN OVERSIGHT --
+      // abofs/stonyx-orm#232 OWNS THIS ROUTE. The three sites that carry the
+      // filter (`buildResponse`'s `included`, the related-resource branch
+      // above, and the two write handlers) all call `record.toJSON()`, which is
+      // where the `linkage` option is applied. This branch builds its
+      // `{ type, id }` objects BY HAND and never calls `toJSON` at all, so it
+      // cannot see a filter no matter who passes one.
+      //
+      // It is also a DIFFERENT QUESTION. Everywhere else, linkage is metadata
+      // ABOUT a document. Here the linkage IS the primary data, so dropping an
+      // entry is a MEMBERSHIP decision about what this route serves -- the same
+      // class as abofs/stonyx-orm#233 and #196, not the class #234/#235 close.
+      // That is why it is absent from #224 §2a's seven-site inventory.
+      //
+      // MEASURED, so the next person does not re-derive it: this route answers
+      // `GET /animals/1/relationships/owner` with
+      // `{"type":"owner","id":"angela"}` while `GET /owners/angela` is 404.
+      // Wiring the filter in here takes the suite to 993/2 and turns the
+      // `GET /animals/:id/relationships/owner returns relationship linkage`
+      // test red -- which is #232's own reproduction, not a regression.
+      // Pinned unchanged by `[GUARD] #235 X2` in test/integration/orm-test.ts.
       routes[`/:id/relationships/${dasherizedName}`] = async (request: OrmRequest$, { filter }: { [key: string]: unknown } = {}) => {
         const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
         if (!record) return 404;
@@ -1429,10 +1564,53 @@ export default class OrmRequest extends Request {
     // src/types/orm-types.ts. Nothing is fetched at this point and adding a
     // lookup here would put a store read in the middle of an authorization
     // path. The function return shape below IS the per-record hook.
+    //
+    // -------------------------------------------------------------------------
+    // #236 -- `recordId`, the DECODED route-parameter id, for the same reason.
+    //
+    // WHICH RECORD is the third structural fact the framework already holds and
+    // the consumer was left to re-derive, and re-deriving it failed OPEN. The
+    // documented sample compared `request.path` -- the RAW, undecoded pathname
+    // -- against a literal `/archived`, while the router DECODES `:id`. So
+    // `GET /owners/%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. Four spellings measured, all
+    // four through; 255 non-canonical spellings of that 8-character id decode
+    // to the same key, so this was never a deny-list of one.
+    //
+    // TWO CONSUMER-SIDE NORMALISATIONS WERE MEASURED WRONG IN OPPOSITE
+    // DIRECTIONS, which is the argument for doing it once, here.
+    // `.toLowerCase()` case-folds a route-parameter VALUE on the axis that
+    // governs literal SEGMENTS: 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 one.
+    // `decodeURIComponent(request.path)` decodes THEN splits while the router
+    // splits THEN decodes, so it over-denied `/owners/archived%2fx` -- 403 for
+    // a genuinely distinct record. Failing closed there was luck, not design.
+    //
+    // `getId(request.params)` AND NOT `request.params.id`, for exactly the
+    // reason `operation` is a `methodAccessMap` lookup: it is the SAME single
+    // coercion the store lookup one layer down performs, so the predicate and
+    // the dispatch cannot disagree about which record a request addresses.
+    // The raw string would reintroduce that divergence on hex-shaped ids --
+    // `GET /animals/0x2391` looks up record `9105`.
+    //
+    // NOTHING HERE PARSES THE REQUEST TARGET EITHER. `request.params` is what
+    // the router matched, so a mount prefix, an absolute-form target, a query
+    // string or a case-varied mount cannot move this value -- the same
+    // guarantee `model` carries, by the same means.
+    //
+    // `null` and not `undefined` on a collection route, so the KEY IS ALWAYS
+    // PRESENT -- the rule `operation`'s own docblock already establishes. A
+    // context reaching a predicate WITHOUT the key therefore did not come from
+    // here; it was hand-assembled by a caller resolving the predicate through
+    // `Orm.instance.getAccess()`, and that absence stays deniable only because
+    // `auth()` never produces it.
     // -------------------------------------------------------------------------
     const context: AccessContext = {
       model: this.model,
       operation: methodAccessMap[request.method],
+      recordId: request.params && 'id' in request.params ? getId(request.params) : null,
     };
 
     let access: AccessMethod;

package/src/types/orm-types.ts

@@ -260,6 +260,102 @@ export interface AccessContext {
    * from one that classified the request and found nothing.
    */
   operation: AccessOperation | undefined;
+
+  /**
+   * The record this route was addressed to, as the store key -- or `null` on a
+   * collection route, which is addressed to no record (abofs/stonyx-orm#236).
+   *
+   * IT IS ALREADY DECODED, AND THAT IS THE WHOLE POINT. Express decodes route
+   * PARAMETERS while leaving `request.path` raw, so a consumer comparing
+   * `request.path` against a literal compares an undecoded string against a
+   * decoded dispatch. `GET /owners/%61rchived` reached such a comparison as
+   * `/%61rchived`, walked past a `/archived` deny, and was dispatched as the
+   * record `archived` -- 200 with the record in full, and `DELETE` destroyed
+   * it, unauthenticated. 255 non-canonical spellings of an 8-character id
+   * decode to the same key, so a deny-list of spellings is the wrong shape.
+   *
+   * SO DO NOT NORMALISE THIS, AND DO NOT NORMALISE ANYTHING ELSE INSTEAD:
+   *
+   * - Do NOT decode it. Express decodes exactly ONCE, which is what a route
+   *   parameter means. `GET /owners/%2561rchived` is the legitimate id
+   *   `%61rchived`, not a second-order spelling of `archived`; a predicate that
+   *   decoded until stable would deny a record it was never asked about.
+   * - Do NOT case-fold it. 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`, `.toLowerCase()` was measured
+   *   wrong in BOTH directions at once: `GET /owners/ARCHIVED` 403 (a false
+   *   deny, on the wrong record) and `GET /owners/%41RCHIVED` 200 (a false
+   *   allow, on that same record).
+   * - Do NOT derive it from `request.path` or the request target. Decoding the
+   *   whole path decodes THEN splits, while the router splits THEN decodes, so
+   *   `/owners/archived%2fx` -- a genuinely distinct record whose id is
+   *   `archived/x` -- was measured over-denied 403.
+   *
+   * IT IS `getId(request.params)`, BYTE FOR BYTE -- the same single coercion
+   * the store lookup uses, exactly as `operation` is the same `methodAccessMap`
+   * lookup the permission-array branch uses. The predicate and the dispatch
+   * therefore cannot disagree about which record a request addresses. Handing
+   * over the raw `request.params.id` instead would reintroduce that divergence
+   * on hex-shaped ids: `GET /animals/0x2391` looks up record `9105`.
+   *
+   * It inherits abofs/stonyx-orm#209 along with that coercion -- on a model
+   * declaring `id = attr('string')`, `'9107'` arrives here as the number
+   * `9107`. That is consistency WITH THE LOOKUP, which is the property this key
+   * exists to buy; it is not a defect to repair here.
+   *
+   * `null`, not `undefined`, on a collection route -- and the KEY IS ALWAYS
+   * PRESENT, the same rule `operation` states above. `auth()` always sets it,
+   * so a context arriving WITHOUT the key did not come from `auth()`: it was
+   * hand-assembled by a caller resolving the predicate through
+   * `Orm.instance.getAccess()`. That absence stays a distinguishable, deniable
+   * signal only because the framework never produces it.
+   *
+   * IT DISAGREES WITH THE HOOK VOCABULARY, AND NOT ONLY ON THE ABSENCE
+   * SPELLING. `HookContext.recordId` (`src/hooks.ts`) is an identically-named
+   * key on an identically-shaped context object, which is the exact
+   * configuration that makes `operation` fail-open shaped -- a hook sees
+   * `'get'` where `access()` sees `'read'`. An earlier revision of THIS
+   * docblock asserted the opposite ("here they AGREE... they differ in ONE way
+   * and it is the absence spelling"). That was measured false, in the fail-open
+   * direction, and it is corrected here rather than deleted.
+   *
+   * MEASURED over the live dispatch, before-hooks registered for all five
+   * operations on one model:
+   *
+   *     before:list    key ABSENT      ('recordId' in context === false)
+   *     before:get     key ABSENT      params={"id":"visible1"}
+   *     before:create  key ABSENT
+   *     before:update  key ABSENT      params={"id":"visible2"}
+   *     before:delete  recordId="visible3"
+   *     after:delete   recordId="visible3"
+   *
+   * `_withHooks` assigns `context.recordId` at exactly TWO sites in
+   * `src/orm-request.ts`, and BOTH sit inside an `operation === 'delete'`
+   * branch. So the two keys differ in COVERAGE, on four of five operations: on
+   * a hook context the key is absent for get, list, create and update, while
+   * this key is present on every route `auth()` classifies. The absence
+   * spelling is the smaller half of the difference, not the whole of it.
+   *
+   * AND THAT INVERTS THE ARGUMENT ABOVE WHEN IT IS READ ACROSS THE TWO. Here,
+   * a missing `recordId` means "did not come from `auth()`" and is deniable.
+   * On a hook context it means "this is a get / list / create / update" -- an
+   * ordinary request. A consumer who writes the hook-side half of the same
+   * rule --
+   *
+   *     beforeHook('update', 'owner', ctx => ctx.recordId === 'archived' ? 403 : undefined)
+   *
+   * -- gets a deny that NEVER FIRES: measured, `PATCH /owners/visible2` -> 200,
+   * with `ctx.recordId === undefined` while the addressed record sits in
+   * `ctx.params`. The hook side is abofs/stonyx-orm#242 and is deliberately not
+   * repaired here. A predicate must not read `undefined` here as "collection",
+   * and nothing in this contract makes it safe to read the two keys as one key.
+   *
+   * IT NAMES WHICH RECORD, NOT WHICH SURFACE. `GET /owners/gina`,
+   * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` all
+   * carry `recordId: 'gina'`; the related-resource gap is abofs/stonyx-orm#196
+   * and is untouched by this key.
+   */
+  recordId: string | number | null;
 }
 
 /**