@stonyx/orm 0.3.2-beta.157 → 0.3.2-beta.159

package/src/access-verdict.ts

@@ -0,0 +1,312 @@
+/**
+ * The shared access-verdict primitive (abofs/stonyx-orm#234).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: ONE INTERPRETER, NOT TWO
+ * ---------------------------------------------------------------------------
+ * A consumer `access()` may return six differently-shaped things -- `false`, a
+ * bare permission string, a permission array, `true`, a per-record function, or
+ * something the contract does not define at all -- and the reading of each one
+ * is a security decision. `auth()` has held that reading inline since #190.
+ * Every surface that needs to ask "may this caller see model X's record?" needs
+ * the SAME reading, or the second copy becomes an unreviewed second
+ * authorization vocabulary that answers differently about the same value.
+ *
+ * So `interpretAccess` is extracted here and `auth()` now calls it. It is the
+ * only place a return shape is classified, and abofs/stonyx-orm#232 and #233
+ * rebase onto it rather than re-deriving it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT A LINKAGE FILTER IS, AND WHY THE CALLER BUILDS IT
+ * ---------------------------------------------------------------------------
+ * `Record.toJSON()` APPLIES a verdict; it never RESOLVES one. That is not a
+ * style choice, it is forced, and it was measured before it was decided:
+ *
+ *   INPUT: origin/dev @ c5f7907, unpatched                  -> 967 pass / 0 fail
+ *   INPUT: same + fail-closed resolution INSIDE toJSON()    -> 964 pass / 3 fail
+ *
+ * and all three reds were over-denial of PERMITTED records, not the leak. Two
+ * independent reasons:
+ *
+ *   1. `toJSON()` has no request. The shipped, documented sample reads
+ *      `request.path` for its `/archived` sub-path rule -- the one read of
+ *      argument one the README sanctions -- and fail-closes when it is absent.
+ *      Measured against the live registry:
+ *
+ *        getAccess('owner')(undefined, { model:'owner',  operation:'read' }) -> false
+ *        getAccess('animal')(undefined,{ model:'animal', operation:'read' }) -> [Function]
+ *
+ *      Same predicate object, two models, two different degradation modes,
+ *      chosen by the consumer. Without a request there is no trustworthy
+ *      answer to get.
+ *
+ *   2. `toJSON` is also the `JSON.stringify` hook, so `JSON.stringify({data:
+ *      record})` calls `record.toJSON('data')` -- a STRING in the options slot.
+ *      An implicit caller has no syntactic place to pass anything
+ *      (abofs/stonyx-orm#230). The no-argument document must therefore stay
+ *      byte-identical to what shipped, which also rules out fail-closed by
+ *      default: `Orm.instance.accessFunctions` is `{}` in any process that
+ *      never ran `setup-rest-server` (CLI, SQL-only, unit tests), so a
+ *      fail-closed default would empty every relationship on every document in
+ *      processes that have no REST surface to protect.
+ *
+ * The caller -- which still holds the request -- resolves the predicate,
+ * interprets it here, caches the answer, and hands `toJSON()` an already-decided
+ * `(type, record) => boolean`.
+ */
+import Orm from '@stonyx/orm';
+import log from 'stonyx/log';
+import type { AccessMethod, AccessOperation, LinkageFilter } from './types/orm-types.js';
+
+/**
+ * The classified reading of one `access()` return value.
+ *
+ * `granted: false` is a total denial. `granted: true` with no `filter` is an
+ * unconditional grant. `granted: true` WITH a filter means "grant, subject to
+ * this per-record predicate" -- the function return shape, which is the
+ * per-record hook `AccessContext` deliberately does not provide.
+ */
+export interface AccessVerdict {
+  granted: boolean;
+  filter?: (record: unknown) => boolean;
+}
+
+const DENIED: AccessVerdict = Object.freeze({ granted: false });
+const GRANTED: AccessVerdict = Object.freeze({ granted: true });
+
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict {
+  if (!access) return DENIED;
+
+  // The function return shape IS the per-record hook. Grant the request and
+  // carry the predicate; the caller applies it per record.
+  if (typeof access === 'function') return { granted: true, filter: access as (record: unknown) => boolean };
+
+  if (access === true) return GRANTED;
+
+  // `AccessMethod` declares `string` legal and it fell through every branch
+  // above. A bare string is ONE permission, not a grant of all four -- reading
+  // it as a full grant is what once let `return 'read'` authorise DELETE.
+  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 DENIED;
+  if (!permitted.includes(operation as string)) return DENIED;
+
+  return GRANTED;
+}
+
+/**
+ * Resolve model `type`'s verdict for a read, against the live `request`.
+ *
+ * Fails closed on both ambiguous inputs:
+ *
+ *   - `getAccess(type)` -> `undefined`. That is NOT "this model is
+ *     unrestricted". `setup-rest-server` catches an access-class load failure,
+ *     warns, and publishes whatever PARTIAL map it had, so `undefined` covers
+ *     both "no access class claims this model" and "the class that claims it
+ *     failed to load" -- and the caller cannot tell them apart. Deny.
+ *   - the predicate THROWS. Same reading `auth()` and `isDenied` already use:
+ *     a throw is a denial, logged, never a 500 and never a grant.
+ *
+ * NOTE ON CROSS-MODEL ASKS -- READ THIS BEFORE REBASING #232 OR #233 ONTO IT.
+ * The predicate is asked about `type` while the request in hand was dispatched
+ * to a DIFFERENT model's route. This function makes another model's class
+ * REACHABLE and asks it the model-correct question (`{ model: type }`); whether
+ * the ANSWER is model-correct is the CONSUMER's, because only a predicate that
+ * READS `context.model` can give one. Since #222 this repo's fixture does. A
+ * consumer's arity-1 predicate does not, and there is no supported way to tell
+ * which kind was resolved (the boot-time arity warning is
+ * abofs/stonyx-orm#213/#221, unshipped).
+ *
+ * BOTH DEGRADATION DIRECTIONS ARE REACHABLE, AND THE SECOND ONE GRANTS. This is
+ * measured, not reasoned:
+ *
+ *   - CLOSED. The migrated fixture's surviving `request.path` read means asking
+ *     the OWNER predicate on a request dispatched to `GET /animals/archived`
+ *     returns a bare `false` -- a whole-request deny bleeding across models,
+ *     treated here as "deny this linkage", not as an error. That over-denies a
+ *     PERMITTED record.
+ *   - OPEN. An arity-1 predicate -- the shape `setup-rest-server.ts:15-18`
+ *     still declares valid and the README calls the default in every consumer
+ *     tree -- identifies its collection from the request, so asked about
+ *     `owner` on a request dispatched to `/animals` it answers about ANIMALS.
+ *     Measured against this repo's own fixture with `reg.owner` replaced by an
+ *     arity-1 predicate that hides angela on `/owners`:
+ *
+ *       GET /owners     -> ["gina","michael","bob"]   angela hidden, correctly
+ *       GET /animals    -> owners named: [angela, ...]              LEAK
+ *       GET /animals/1  -> owner.data {"type":"owner","id":"angela"}
+ *
+ *     That is byte-for-byte the abofs/stonyx-orm#234 defect, on the surface
+ *     #234 was filed for, AFTER this fix. It is not a regression -- dev
+ *     published the same id unconditionally -- and this file cannot close it,
+ *     because the arity signal is #213/#221. Do NOT write, here or anywhere
+ *     else, that the cross-model ask degrades closed. The standing rule this
+ *     paragraph is held to is in docs/project-structure.md.
+ */
+function resolveVerdict(request: unknown, type: string): AccessVerdict {
+  const predicate = Orm.instance?.getAccess?.(type);
+  if (typeof predicate !== 'function') return DENIED;
+
+  let access: AccessMethod;
+
+  try {
+    // `recordId: null`, AND NOT `request.params.id`. THE TEMPTING WRONG ANSWER
+    // IS RIGHT THERE, so this is pinned by assertion as well as by comment --
+    // test/unit/linkage-verdict-test.ts, `#234 + #241 -- recordId is null`.
+    //
+    // `AccessContext.recordId` (src/types/orm-types.ts, abofs/stonyx-orm#236 /
+    // #241) means "the record THIS ROUTE WAS ADDRESSED TO, as the store key of
+    // the model being authorised", and `null` means "addressed to no record".
+    // The id sitting on the request in hand names the PRIMARY record, which
+    // belongs to a DIFFERENT model -- `GET /owners/gina` carries
+    // `params.id === 'gina'`, and the ask being made HERE is about `animal` or
+    // `trait`. Filling this in from the request would hand the related model's
+    // predicate an id belonging to another model, which is byte-for-byte the
+    // cross-model confusion abofs/stonyx-orm#202 introduced this context to
+    // eliminate: the predicate would compare an owner's id against its own
+    // records and answer a question nobody asked. There is no record of THIS
+    // model addressed by this request, so `null` is the honest value -- the
+    // same spelling `auth()` uses for a collection route.
+    //
+    // NOR ANY RECORD'S OWN ID, WHICH IS THE SECOND-MOST TEMPTING ANSWER. This
+    // verdict is resolved ONCE PER TYPE and cached in `byType` below, before
+    // any record has been looked at; there is no per-record `AccessContext`
+    // built anywhere on this path. Seeding it from the first record of a type
+    // would let that record's identity answer for every later record of the
+    // same type -- the same "one record's verdict answers for another" defect
+    // the `decisions` raw-key argument below exists to prevent, just one level
+    // coarser. And it is unnecessary: `AccessContext` deliberately carries no
+    // `record` because auth-time and record-time are separate decision points,
+    // and the per-record point already receives the WHOLE record, id included,
+    // through `verdict.filter(record)`. A predicate that wants a record's id
+    // has the contract's own channel for it.
+    access = predicate(request, { model: type, operation: 'read', recordId: null });
+  } catch (error) {
+    log.error?.(`[@stonyx/orm] access() threw while resolving linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+
+    return DENIED;
+  }
+
+  return interpretAccess(access, 'read');
+}
+
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite. `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay DISTINCT, where `` `${type}:${id}` `` --
+ * or a bare `String(id)` -- collapses them onto one entry and answers the second
+ * record with the first record's verdict.
+ *
+ * WHAT THAT DOES AND DOES NOT PROTECT. It cannot cross MODELS. `decisions` is
+ * already partitioned per type by `byType`, so a composite key inside a per-type
+ * map is one-to-one with the raw one and no owner's verdict could ever answer
+ * for an animal -- the claim that once stood here. The real exposure is narrower
+ * and entirely WITHIN one model: two records of the same type whose ids differ
+ * only by JavaScript type, which a per-record predicate may legitimately answer
+ * differently about (an id read off a JSON body is a string; the same id
+ * assigned by the server is a number). Pinned by unit assertion, because this
+ * fixture cannot produce the collision on its own -- `owner` ids are strings and
+ * `animal` ids are numbers.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ *
+ * A REQUEST IS REQUIRED, AND ITS ABSENCE IS CHECKED HERE RATHER THAN DELEGATED.
+ * This function is EXPORTED (src/index.ts), and the README's Consumer Contracts
+ * section points consumers at exactly the contexts that have no live request --
+ * a queue payload, a websocket frame, a custom route. Without one there is no
+ * caller to authorise against, and this file's header already says so: the
+ * shipped sample reads `request.path` and fail-closes when it is absent, so
+ * `getAccess('owner')(undefined, ...)` is `false`, while
+ * `getAccess('animal')(undefined, ...)` returns a per-record predicate and
+ * GRANTS. Measured on this repo's own fixture before this guard existed:
+ *
+ *   createLinkageFilter(undefined | null | {} | 'x' | 0)
+ *     -> owner=false animal=TRUE trait=TRUE category=TRUE phone-number=TRUE
+ *
+ * Four of five claimed models granted, with no log, because whether an absent
+ * request fails closed was left ENTIRELY to consumer predicates -- and a
+ * predicate that ignores its request cannot fail closed on one that is missing.
+ * A nullish or primitive `request` therefore denies every model outright and
+ * says so once, at construction, so the signal exists even for a caller that
+ * goes on to serialize nothing.
+ *
+ * WHAT THIS CANNOT CHECK: `{}` is an object and passes. There is no request
+ * contract this module owns -- `auth()` reads `.method`, the shipped sample
+ * reads `.path`, a consumer's reads whatever it likes -- so anything past
+ * "is it an object" would be this module inventing a shape for someone else's
+ * framework. The residual is documented in the README under Consumer Contracts.
+ */
+export function createLinkageFilter(request: unknown): LinkageFilter {
+  if (typeof request !== 'object' || request === null) {
+    log.error?.(`[@stonyx/orm] createLinkageFilter() was called with no request (received ${request === null ? 'null' : typeof request}) -- there is no caller to authorise against, so ALL relationship linkage it is asked about is denied.`);
+
+    return function isLinkable(_type: string, _record: unknown): boolean {
+      return false;
+    };
+  }
+
+  const byType = new Map<string, { verdict: AccessVerdict; decisions: Map<unknown, boolean> }>();
+
+  return function isLinkable(type: string, record: unknown): boolean {
+    let entry = byType.get(type);
+
+    if (!entry) {
+      entry = { verdict: resolveVerdict(request, type), decisions: new Map() };
+      byType.set(type, entry);
+    }
+
+    const { verdict, decisions } = entry;
+
+    if (!verdict.granted) return false;
+    if (!verdict.filter) return true;
+
+    const id = (record as { id?: unknown } | null)?.id;
+    const cached = decisions.get(id);
+    if (cached !== undefined) return cached;
+
+    let allowed: boolean;
+
+    try {
+      allowed = Boolean(verdict.filter(record));
+    } catch (error) {
+      // A predicate that throws is a denial -- the same reading `isDenied` uses
+      // one layer down. Logged, because a predicate that throws on every record
+      // empties every relationship and, silently, that is indistinguishable
+      // from a database with no relationships in it.
+      log.error?.(`[@stonyx/orm] access filter threw while filtering linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+
+      allowed = false;
+    }
+
+    decisions.set(id, allowed);
+
+    return allowed;
+  };
+}

package/src/index.ts

@@ -28,6 +28,15 @@ export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
 export type { AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js'; // access() contract (#202)
+export type { LinkageFilter } from './types/orm-types.js'; // linkage verdict contract (#234)
+// The request-scoped linkage-verdict factory (#234). PUBLIC on purpose: the
+// README tells a consumer serializing a `Record` outside the REST layer to pass
+// their own resolved `linkage` option, and without an exported factory the only
+// way to follow that advice is to write a SECOND reading of `access()` in
+// consumer code -- the exact "unreviewed second authorization vocabulary" that
+// src/access-verdict.ts exists to prevent, reproduced where no reviewer sees it
+// drift. Give them the one interpreter instead of an invitation to fork it.
+export { createLinkageFilter } from './access-verdict.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers

package/src/orm-request.ts

@@ -267,8 +267,9 @@ 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';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -464,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
@@ -481,7 +482,53 @@ function buildResponse(
 
   const includedRecords = collectIncludedRecords(recordOrRecords, includes);
   if (includedRecords.length > 0) {
-    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 eight PERMITTED animals in `included` each naming
+    //     `{"type":"owner","id":"angela"}` -- angela's whole `pets` set,
+    //     `[1, 3, 7, 10, 11, 15, 17, 20]`. `included` itself is NINE
+    //     resources there: those eight animals plus the hidden owner, whose
+    //     membership is #233's and not an animal. 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;
@@ -681,11 +728,22 @@ 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}` },
-        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
       });
     };
 
@@ -701,13 +759,31 @@ 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 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 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;
@@ -962,10 +1038,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
@@ -1024,7 +1119,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 }) => {
@@ -1331,14 +1433,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 {
@@ -1348,6 +1457,54 @@ 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`, and the
+      // two write handlers, `POST /:models` and `PATCH /:models/:id` -- all
+      // reach the filter through `record.toJSON()`, which is where the
+      // `linkage` OPTION is applied.
+      //
+      // The related-resource branch above ALSO passes a `linkage` filter, and
+      // it is NOT one of those three: it is abofs/stonyx-orm#234's code and
+      // predates this change. `git diff 8dda5d6..HEAD -- src/orm-request.ts`
+      // leaves that branch byte-unchanged.
+      //
+      // 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;
@@ -1498,24 +1655,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;
   }