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

package/src/orm-request.ts

@@ -69,15 +69,6 @@
  * 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
@@ -167,11 +158,6 @@
  * `/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
@@ -187,26 +173,12 @@
  *   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.
@@ -216,20 +188,6 @@
  * 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
@@ -238,12 +196,6 @@
  * 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.
@@ -269,6 +221,7 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 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';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -481,6 +434,13 @@ 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 }));
   }
 
@@ -681,7 +641,14 @@ export default class OrmRequest extends Request {
       if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate as (record: OrmRecord) => boolean);
 
       const baseUrl = getBaseUrl(request);
-      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
+
+      // ONE filter per REQUEST, not one per record: it carries the per-type
+      // verdict cache and the per-(type, id) decision cache, and both are
+      // worthless if it is rebuilt inside the map. Measured on this exact
+      // surface with no `include=`: 48 linkage entries collapse to 7 distinct
+      // (type, id) pairs.
+      const linkage = createLinkageFilter(request);
+      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl, linkage }));
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
@@ -701,7 +668,25 @@ export default class OrmRequest extends Request {
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
       const baseUrl = getBaseUrl(request);
-      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
+      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.
+      //
+      // 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
       });
@@ -1331,14 +1316,21 @@ 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.
+        const linkage = createLinkageFilter(request);
+
         let data: unknown;
         if (info.isArray) {
           // hasMany - return array
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-          data = related.map(r => r.toJSON?.({ baseUrl }));
+          data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
         } else {
           // belongsTo - return single or null
-          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
+          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
         }
 
         return {
@@ -1437,53 +1429,10 @@ 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;
@@ -1498,24 +1447,23 @@ export default class OrmRequest extends Request {
       return 403; // Forbidden
     }
 
-    if (!access) return 403;
-    if (typeof access === 'function') {
-      state.filter = access;
-      return undefined;
-    }
-    if (access === true) return undefined;
-
-    // `AccessMethod` declares `string` legal and it fell through every branch
-    // above, returning undefined -- i.e. FULL CRUD, no filter. `return 'read'`
-    // is the natural reading of a type that lists `string` first, and it
-    // granted DELETE. A bare string is one permission, not a grant of all four.
-    const permitted = typeof access === 'string' ? [access] : access;
-
-    // Anything that is not a permission array by this point -- an object, a
-    // number, a Symbol -- is a consumer mistake, and the only safe reading of a
-    // shape the contract does not define is a denial. Fail CLOSED.
-    if (!Array.isArray(permitted)) return 403;
-    if (!permitted.includes(methodAccessMap[request.method])) return 403;
+    // THE READING OF THE RETURN SHAPE LIVES IN ONE PLACE (#234).
+    //
+    // It used to be inline here, and it was the only copy, which was fine while
+    // `auth()` was the only thing that had to ask. It is not any more: the
+    // linkage path has to ask model X's predicate about model X's records while
+    // servicing a request routed to model Y, and a second inline copy of these
+    // six branches would be a second authorization vocabulary -- one that can
+    // drift, and that reviewers would have to notice had drifted. The branch
+    // order in `interpretAccess` is this block, moved, not rewritten.
+    const verdict = interpretAccess(access, methodAccessMap[request.method]);
+
+    if (!verdict.granted) return 403;
+
+    // The function return shape is the per-record hook, and `state` is the
+    // whole transport for it: @stonyx/rest-server memoises one state object per
+    // request and hands the same one to `auth()` and to the handler.
+    if (verdict.filter) state.filter = verdict.filter;
 
     return undefined;
   }

package/src/record.ts

@@ -1,12 +1,29 @@
 import { store } from '@stonyx/orm';
+import log from 'stonyx/log';
 import { getComputedProperties } from "./serializer.js";
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from './plural-registry.js';
 import type Serializer from './serializer.js';
+import type { LinkageFilter } from './types/orm-types.js';
 
 interface ToJSONOptions {
   fields?: Set<string>;
   baseUrl?: string;
+  /**
+   * An ALREADY-RESOLVED linkage decision, supplied by a caller that holds the
+   * request (abofs/stonyx-orm#234). Returning `false` for a related record
+   * drops that record's `{ type, id }` from `relationships.*.data`.
+   *
+   * This method APPLIES a verdict; it never RESOLVES one -- see
+   * `src/access-verdict.ts` for the two measured reasons it cannot. ABSENT is
+   * the default and the default is TODAY'S DOCUMENT, unchanged, because
+   * `toJSON` is also the `JSON.stringify` hook and an implicit caller has no
+   * syntactic place to pass this (abofs/stonyx-orm#230).
+   *
+   * ABSENT and UNUSABLE are read differently, and the difference is a security
+   * decision -- see the three-way reading at the call site below.
+   */
+  linkage?: LinkageFilter;
 }
 
 interface SerializeOptions {
@@ -116,7 +133,13 @@ export default class Record {
   toJSON(options: ToJSONOptions = {}): JSONAPIResult {
     if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
 
-    const { fields, baseUrl } = options;
+    // DESTRUCTURED FROM A VALUE THAT IS NOT ALWAYS AN OBJECT. `toJSON` is the
+    // ECMAScript serialization hook, so `JSON.stringify({ data: record })`
+    // arrives here as `toJSON('data')` -- a STRING in the options slot.
+    // Destructuring a string yields `undefined` for every key, which is exactly
+    // the no-argument default, so the implicit path keeps working and keeps
+    // emitting today's document (abofs/stonyx-orm#230).
+    const { fields, baseUrl, linkage } = options;
     const { __data: data } = this;
     const modelName = this.__model.__name;
     const pluralizedModelName = getPluralName(modelName);
@@ -135,12 +158,62 @@ export default class Record {
       attributes[key] = (getter as () => unknown).call(this);
     }
 
+    // `linkage` is a PUBLIC option -- it is on `OrmRecord.toJSON`
+    // (src/types/orm-types.ts) and the README tells consumers to pass one -- so
+    // it arrives from outside this package and may be ANY value. Three
+    // readings, and the difference between the second and the third is a
+    // security decision:
+    //
+    //   ABSENT (`undefined`). No verdict was supplied. Emit today's document.
+    //   Load-bearing and asserted (AC5/AC5b): `toJSON` is also the
+    //   `JSON.stringify` hook, so the implicit caller arrives as
+    //   `toJSON('data')` -- a STRING, which destructures to `undefined` here
+    //   (abofs/stonyx-orm#230).
+    //
+    //   A FUNCTION. Apply it per related record.
+    //
+    //   ANYTHING ELSE -- `null`, `0`, `false`, `''`, `true`, a string, an
+    //   object. DENY, and say so. Neither of the two obvious alternatives is
+    //   available. Reading it as absent is what `!linkage ||` did, and a
+    //   resolver returning `null` because it could not resolve a session is the
+    //   natural shape of that value and the fail-closed INTENT -- measured,
+    //   `toJSON({ linkage: null })` emitted the full pre-#234 linkage with no
+    //   signal, byte-identical to unpatched dev. Reading it as a function
+    //   raises `TypeError: linkage is not a function` out of the enclosing
+    //   `JSON.stringify` -- measured on `true`, `'x'` and `{}` -- which is
+    //   exactly the outcome the comment below promises cannot happen.
+    //
+    // Logged once per DOCUMENT, not once per relationship key or per related
+    // record: an emptied relationship is deliberately indistinguishable from a
+    // genuinely empty one on the wire, so the log is the only signal a consumer
+    // whose resolver silently returned `null` will ever get.
+    const linkageSupplied = linkage !== undefined;
+    const linkageVerdict: LinkageFilter | undefined = !linkageSupplied
+      ? undefined
+      : typeof linkage === 'function' ? linkage : () => false;
+
+    if (linkageSupplied && typeof linkage !== 'function') {
+      log.error?.(`[@stonyx/orm] toJSON() received a \`linkage\` option of type ${linkage === null ? 'null' : typeof linkage} -- it must be a function, so ALL relationship linkage on this \`${modelName}\` document is denied.`);
+    }
+
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (fields && !fields.has(key)) continue;
 
+      // The linkage decision is applied HERE, alongside the existing
+      // `__model` liveness check, and it produces exactly the shapes that
+      // check already produces: a dropped hasMany member leaves `data: []`,
+      // a dropped belongsTo leaves `data: null`. Both already ship -- a
+      // genuinely-empty hasMany emits `data: []` with links, and a cleaned
+      // belongsTo emits `data: null` -- so a filtered relationship is
+      // BYTE-IDENTICAL to an empty one and there is no new wire shape and no
+      // oracle. It never throws: a throw here escapes the enclosing
+      // `JSON.stringify` and takes `console.log` and `Orm.db.save()`'s
+      // neighbours with it, which is a far worse failure mode than a status.
+      const isLinkable = (r: Record) => !linkageVerdict || linkageVerdict(r.__model.__name, r);
+
       const relationshipData = Array.isArray(childRecord)
-        ? childRecord.filter((r: Record) => r?.__model).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
-        : (childRecord && (childRecord as Record).__model) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
+        ? childRecord.filter((r: Record) => r?.__model).filter(isLinkable).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
+        : (childRecord && (childRecord as Record).__model && isLinkable(childRecord as Record)) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
 
       // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
       const dasherizedKey = camelCaseToKebabCase(key);

package/src/types/orm-types.ts

@@ -89,7 +89,15 @@ export interface OrmRecord {
   __model?: { __name: string };
   __data: Record<string, unknown> & { id?: string | number; __pendingSqlId?: boolean };
   __relationships: Record<string, unknown>;
-  toJSON?(options?: { fields?: Set<string>; baseUrl?: string }): Record<string, unknown>;
+  /**
+   * `linkage` is an ALREADY-RESOLVED decision supplied by a caller that holds
+   * the request (abofs/stonyx-orm#234): return `false` for a related record and
+   * its `{ type, id }` is dropped from `relationships.*.data`. Omitting it is
+   * the default, and the default is the pre-#234 document unchanged -- this
+   * method is also the `JSON.stringify` hook, so an implicit caller has no
+   * syntactic place to pass it (abofs/stonyx-orm#230).
+   */
+  toJSON?(options?: { fields?: Set<string>; baseUrl?: string; linkage?: LinkageFilter }): Record<string, unknown>;
   [key: string]: unknown;
 }
 
@@ -252,102 +260,6 @@ 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;
 }
 
 /**
@@ -370,3 +282,22 @@ export interface AccessContext {
  * context gets `TS2554: Expected 2 arguments, but got 1`.
  */
 export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;
+
+/**
+ * A resolved, request-scoped linkage decision: may `record` of model `type` be
+ * NAMED, by id, inside another model's document (abofs/stonyx-orm#234)?
+ *
+ * Arity is `(type, record)` and not `(type, id)` because the per-record filter
+ * a consumer returns is handed the RECORD -- this repo's own fixture reads
+ * `record.owner?.id`, not just `record.id`. The `(type, id)` pair is the CACHE
+ * key inside `createLinkageFilter`, not the input.
+ *
+ * DECLARED HERE, with the rest of the access vocabulary, and imported by every
+ * site that names it. It had three structurally-identical hand-written copies
+ * (`access-verdict.ts`, `record.ts`, `OrmRecord.toJSON` below) bridged to each
+ * other by nothing, so a drift in nullability or a widening of `type` would
+ * have landed on one and not the others -- which is the same "second,
+ * unreviewed vocabulary" failure `src/access-verdict.ts` exists to prevent, one
+ * level up in the type system.
+ */
+export type LinkageFilter = (type: string, record: unknown) => boolean;