@stonyx/orm 0.3.2-alpha.76 → 0.3.2-alpha.77

package/src/orm-request.ts

@@ -65,9 +65,19 @@
  * warning below sanctions. This repo's own fixture 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, turning a deny into an
- * allow. The related-resource and `?include=` surfaces serve ANOTHER model's
- * records under `model: 'owner'`, and the context gives no signal of that
- * (abofs/stonyx-orm#196).
+ * allow.
+ *
+ * THE RELATED-RESOURCE HALF OF THAT SENTENCE IS NOW OUT OF DATE AND IS
+ * CORRECTED HERE RATHER THAN DELETED. Both relationship route families resolve
+ * the RELATED model's own access class and ask it
+ * `{ model: <related>, operation: 'read', recordId: null }`
+ * (abofs/stonyx-orm#232), so those surfaces no longer serve another model's
+ * records under `model: 'owner'` unexamined. What the context still gives no
+ * signal of is WHICH related record is being asked about -- `recordId` is
+ * `null` there and `request.params` names a record of a different model. See
+ * `AccessContext.recordId` in ./types/orm-types.ts for the full statement of
+ * that limit. `?include=` is still unfiltered and is abofs/stonyx-orm#233 /
+ * #235.
  *
  * 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
@@ -267,7 +277,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, LinkageFilter } from './types/orm-types.js';
+import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
 import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 
@@ -465,9 +475,9 @@ function buildResponse(
   data: unknown,
   includeParam: string | undefined,
   recordOrRecords: OrmRecord | OrmRecord[],
-  options: { links?: { [key: string]: string }; baseUrl?: string; linkage?: LinkageFilter } = {}
+  options: { links?: { [key: string]: string }; baseUrl?: string } = {}
 ): JsonApiResponse {
-  const { links, baseUrl, linkage } = options;
+  const { links, baseUrl } = options;
   const response: JsonApiResponse = { data };
 
   // Add top-level links
@@ -482,49 +492,14 @@ function buildResponse(
 
   const includedRecords = collectIncludedRecords(recordOrRecords, includes);
   if (includedRecords.length > 0) {
-    // 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 }));
+    // 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 }));
   }
 
   return response;
@@ -735,11 +710,7 @@ export default class OrmRequest extends Request {
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
-        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
+        baseUrl
       });
     };
 
@@ -757,29 +728,29 @@ export default class OrmRequest extends Request {
       const baseUrl = getBaseUrl(request);
       const linkage = createLinkageFilter(request);
 
-      // `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.
+      // `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.
       //
-      // 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.
+      // 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.
       return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
-        baseUrl,
-        linkage
+        baseUrl
       });
     };
 
-    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 createHandler: HandlerFn = async ({ body, query }, { filter }) => {
       const { type, id, attributes, relationships: rels } = (body?.data || {}) as {
         type?: string;
         id?: string | number;
@@ -1034,29 +1005,10 @@ export default class OrmRequest extends Request {
         return 403;
       }
 
-      // 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) }) };
+      return { data: record.toJSON?.({ fields: modelFields }) };
     };
 
-    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 updateHandler: HandlerFn = async ({ body, params }, { filter }) => {
       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
@@ -1115,14 +1067,7 @@ export default class OrmRequest extends Request {
         }
       }
 
-      // 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) }) };
+      return { data: record.toJSON?.() };
     };
 
     const deleteHandler: HandlerFn = async ({ params }, { filter }) => {
@@ -1429,21 +1374,101 @@ export default class OrmRequest extends Request {
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
-        // LINKAGE ONLY. This filter decides which ids the emitted documents may
-        // NAME in their own `relationships.*.data`; it does NOT decide whether
-        // the related records themselves are served -- that is the parent-only
-        // filtering this route has done since #190, and widening it to the
-        // related record is abofs/stonyx-orm#196.
+        // ONE FILTER, TWO JOBS, AND abofs/stonyx-orm#232 IS THE SECOND ONE.
+        //
+        // As LINKAGE (#234) it decides which ids the emitted documents may NAME
+        // in their own `relationships.*.data`. As MEMBERSHIP (this issue) it
+        // decides whether the related record is served here AT ALL -- the
+        // related resource is PRIMARY data on this route, so there is no
+        // linkage-consistency question to answer separately.
+        //
+        // Until #232 this route filtered only the PARENT, so a record its own
+        // model's predicate hides was served in full from another model's
+        // route, at ZERO query parameters. Measured on dev @ 8dda5d6:
+        //
+        //     GET /owners/angela          -> 404
+        //     GET /animals/1/owner        -> 200, owner:angela, full attributes
+        //     GET /traits/2/tag           -> 200, a model NO access class
+        //                                    claims, on a collection that has
+        //                                    no mounted route at all
+        //
+        // ARGUMENT ONE IS THE LIVE REQUEST, NOT A DERIVED ONE. A fabricated
+        // request addressing the RELATED resource was the original design and
+        // it is dropped: #241 removed the shipped fixture's read of argument
+        // one, so a fabricated value changes nothing it could observe.
+        // `createLinkageFilter` is also a published public export
+        // (src/index.ts) whose resolution granularity is per TYPE; supplying a
+        // per-RECORD request would mean widening it, which takes a consumer
+        // `access()` from ~2 calls to ~7 on a plain `GET /animals`. That is a
+        // separate, consumer-visible story.
+        //
+        // GUARDED BY OWN-PROPERTY IDENTITY, NOT BY THE #234 AC13 PIN. That pin
+        // (test/unit/linkage-verdict-test.ts, `strictEqual(seen[0].request,
+        // READ_REQUEST)`) calls `createLinkageFilter` DIRECTLY, so it pins the
+        // function's pass-through and constrains no call site -- an earlier
+        // revision of this comment cited it for this decision and was wrong.
+        // `Object.create(request)` here measured 1015 / 0 with nothing red.
+        // test/integration/orm-test.ts, `#232 AC9`, now asserts that the object
+        // the predicate is handed OWNS `params` (`Object.hasOwn`) and has
+        // nothing request-shaped behind it on the prototype chain. A derived
+        // request inherits `params` -- so it satisfies every value assertion
+        // there -- and reds on those two. Measured: with the derived request in
+        // place, 1014 / 1, and that one is this guard.
+        //
+        // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
+        // `recordId` is `null` here and the request names a record of a
+        // DIFFERENT model, so a consumer predicate can express a model-level or
+        // a request-level deny for a related resource, but NOT a per-record
+        // one. README.md and docs/usage-patterns.md say so; a ledger assertion
+        // in test/unit/relationship-route-access-test.ts keeps them saying it.
         const linkage = createLinkageFilter(request);
 
+        // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED. `isLinkable` is
+        // keyed on the model name; without one there is no predicate to ask,
+        // and an unidentifiable input must never be the permissive path.
+        const isLinkable = (r: OrmRecord) => {
+          const type = (r as { __model?: { __name?: string } }).__model?.__name;
+
+          return typeof type === 'string' && type !== '' && linkage(type, r);
+        };
+
         let data: unknown;
         if (info.isArray) {
-          // hasMany - return array
+          // hasMany - return array, MINUS the members this caller may not see.
+          // Dropped, never errored: the result is byte-identical to a genuinely
+          // empty relationship, so this route is not an existence oracle.
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-          data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
+          data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
         } else {
-          // belongsTo - return single or null
-          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
+          // belongsTo - return single or null. A DENIED target is `data: null`,
+          // BYTE-IDENTICAL to a relationship that is genuinely empty, for the
+          // same reason the hasMany branch above drops rather than errors: this
+          // route must not be an existence oracle for the RELATED record.
+          //
+          // THE OTHER SPELLING WAS 404 AND IT WAS MEASURED AS A DISCLOSURE.
+          // Unauthenticated, zero query parameters, one request each, on `tag`
+          // -- the model with no route mounted at all, which is exactly what
+          // #240 AC5 exists to protect:
+          //
+          //     GET /traits/1/tag  [ABSENT]  -> 200  application/json  len 68
+          //     GET /traits/2/tag  [DENIED]  -> 404  text/plain        len  9
+          //
+          // and `GET /traits/1` and `GET /traits/2` both report
+          // `relationships.tag = {"data":null}` byte-identical modulo the id,
+          // because #234 closed THAT oracle deliberately. A 404 here would let
+          // a caller ask which of those two nulls was a denial. Under
+          // `data: null` the pair closes completely: 200/200, same
+          // content-type, same content-length, bodies identical modulo the
+          // parent id the caller put in the URL. It opens nothing -- `links`
+          // are entirely parent-derived, there is no `meta` and no counts.
+          //
+          // This is also what README.md's module-wide rule already demanded:
+          // every status on a record route must be identical for filtered-out
+          // and does-not-exist. The route now CONFORMS to that rule rather than
+          // carving an exception out of it.
+          if (!isOrmRecord(relatedData)) data = null;
+          else if (!isLinkable(relatedData)) data = null;
+          else data = relatedData.toJSON?.({ baseUrl, linkage });
         }
 
         return {
@@ -1453,47 +1478,6 @@ export default class OrmRequest extends Request {
       };
 
       // Relationship linkage route: GET /:id/relationships/{relationship}
-      //
-      // NO `linkage` FILTER FROM abofs/stonyx-orm#235, AND THAT IS A SCOPE
-      // BOUNDARY RATHER THAN AN OVERSIGHT -- abofs/stonyx-orm#232 OWNS THIS
-      // ROUTE, and PR #247 is IN FLIGHT against it in this same sprint. If you
-      // are reading this after #247 landed, the filtering below is #232's and
-      // this note records why it was never #235's to add.
-      //
-      // The three sites #235 does own (`buildResponse`'s `included`, the
-      // related-resource branch above, and the two write handlers) all reach
-      // the filter through `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 the `linkage` option cannot
-      // reach it -- whatever this route filters, it has to filter itself, which
-      // is precisely why doing so is a separate change with a separate owner.
-      //
-      // It is also a DIFFERENT QUESTION. Everywhere #235 touches, 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. Against this
-      // branch's baseline of 1011/0, wiring `createLinkageFilter` into the
-      // belongsTo branch below takes the suite to 1009/2, reddening
-      // `[GUARD] #235 X2` and the
-      // `GET /animals/:id/relationships/owner returns relationship linkage`
-      // test -- the latter is #232's own reproduction, not a regression.
-      //
-      // THE BASELINE IS QUOTED WITH THE RESULT BECAUSE AN EARLIER REVISION OF
-      // THIS COMMENT SAID 993/2 AND SHIPPED IT. This file lands in consumers'
-      // `node_modules`, so a wrong number here is a wrong number in the
-      // published package. 993+2 = 995 is the DEV baseline, carried over from
-      // a branch on which `[GUARD] #235 X2` does not exist. A pass/fail pair
-      // with no baseline beside it cannot be checked by reading, which is how
-      // it survived three artifacts and a review; the qualitative claim was
-      // right the whole time and only the count was wrong.
-      //
-      // `[GUARD] #235 X2` in test/integration/orm-test.ts pins the OWNERSHIP
-      // BOUNDARY here rather than this route's current answer, so that it
-      // survives #247 landing. Read its comment before changing it.
       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;
@@ -1502,16 +1486,44 @@ export default class OrmRequest extends Request {
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
+        // THE ONE READ SURFACE THAT DOES NOT GO THROUGH `toJSON()`. It builds
+        // `{ type, id }` BY HAND, which is why #234's linkage filter never
+        // reached it and why this half belongs to abofs/stonyx-orm#232 rather
+        // than to #234: on this route the linkage IS the primary data of an
+        // opt-in request, so filtering it changes the route's MEMBERSHIP
+        // semantics, not the ids named inside somebody else's document.
+        //
+        // DELIBERATELY NOT STATED AS A COUNT. README.md's Consumer Contracts
+        // section enumerates the surfaces on which the framework resolves a
+        // verdict and hands it to `toJSON()`, and that enumeration GROWS --
+        // abofs/stonyx-orm#235 adds the two write handlers and the `included`
+        // records. This route is not on that list under any count, because it
+        // never calls `toJSON()`: whatever it filters, it filters here. A
+        // number written into this comment would be false the next time that
+        // list changes, and the README already carries the enumeration.
+        //
+        // Same filter, same argument-one decision, same residual as
+        // `/:id/{relationship}` above -- read the block there.
+        const linkage = createLinkageFilter(request);
+        const isLinkable = (r: OrmRecord) => {
+          const type = (r as { __model?: { __name?: string } }).__model?.__name;
+
+          return typeof type === 'string' && type !== '' && linkage(type, r);
+        };
+
         let data: unknown;
         if (info.isArray) {
           // hasMany - return array of linkage objects
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
           data = related
             .filter((r): r is OrmRecord & { __model: { __name: string } } => Boolean(r.__model))
+            .filter(isLinkable)
             .map(r => ({ type: r.__model.__name, id: r.id }));
         } else {
-          // belongsTo - return single linkage or null
-          if (isOrmRecord(relatedData) && relatedData.__model) {
+          // belongsTo - return single linkage or null. A DENIED target is
+          // `data: null`, indistinguishable from a genuinely empty one -- see
+          // the measured oracle in the `/:id/{relationship}` block above.
+          if (isOrmRecord(relatedData) && relatedData.__model && isLinkable(relatedData)) {
             data = { type: relatedData.__model.__name, id: relatedData.id };
           } else {
             data = null;

package/src/types/orm-types.ts

@@ -350,10 +350,36 @@ export interface AccessContext {
    * 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.
+   * IT NAMES WHICH RECORD OF THE MODEL BEING ASKED ABOUT, NOT WHICH SURFACE,
+   * AND THE ANSWER DEPENDS ON WHICH MODEL IS BEING ASKED ABOUT.
+   *
+   * For the ask about the ROUTE'S OWN model, all three of `GET /owners/gina`,
+   * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` carry
+   * `recordId: 'gina'` -- `auth()` reads it off `request.params`.
+   *
+   * FOR THE ASK ABOUT A RELATED MODEL, IT IS `null`, AND THAT IS A LIMIT ON
+   * WHAT A PREDICATE CAN EXPRESS (abofs/stonyx-orm#232). The two relationship
+   * route families resolve the RELATED model's own predicate -- `animal` on
+   * `GET /owners/gina/pets`, `owner` on `GET /animals/4/owner` -- and that ask
+   * carries `recordId: null` while `request.params` names a record of a
+   * DIFFERENT model. So a predicate answering about a related model gets the
+   * model name, the operation and the request, and CANNOT branch on which
+   * related record it is being asked about.
+   *
+   * The rule, so it is not re-derived wrong: `recordId` may name a record only
+   * where the route addresses exactly one record OF THE MODEL BEING ASKED
+   * ABOUT. A `hasMany` related-resource route returns many records of one type
+   * and the verdict is resolved ONCE PER TYPE, before any record is examined --
+   * seeding it from a record would let the first one decide for all of them.
+   *
+   * What still works, and what does not, is pinned as behaviour by `#232 AC10`
+   * in test/integration/orm-test.ts and stated for consumers in README.md:
+   * model-level denies work, request-level denies work, and the per-record
+   * FILTER shape works because `access()` may return a function and that
+   * function receives the whole record. Branching on identity BEFORE returning
+   * does not.
+   *
+   * `?include=` is a separate surface and is abofs/stonyx-orm#233 / #235.
    */
   recordId: string | number | null;
 }