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

package/README.md

@@ -930,20 +930,47 @@ per-record filter. An input you cannot identify must **deny**.
   `include=`, related-resource routes and relationship-linkage routes. This is
   **membership** — whether the related resource is served at all — and it is a
   different question from which ids a document may *name*, immediately below.
-- **Relationship linkage is filtered on the four request-bound read surfaces,
-  and only there.** A document's `relationships.*.data` used to publish the id
-  of every related record unconditionally, so a record hidden on every one of
-  its own surfaces was still named inside another model's document — with no
-  `include=`, no relationship route and no query string
+- **Relationship linkage is filtered on every request-bound surface that
+  serializes a record — the reads, the two writes, and `included`.** A
+  document's `relationships.*.data` used to publish the id of every related
+  record unconditionally, so a record hidden on every one of its own surfaces
+  was still named inside another model's document — with no `include=`, no
+  relationship route and no query string
   ([#234](https://github.com/abofs/stonyx-orm/issues/234)). The ORM now resolves
-  the **related** model's own access class on `GET /:models`, `GET /:models/:id`
-  and both `GET /:models/:id/{relationship}` shapes, and asks it
-  `{ model: <related>, operation: 'read' }`. An unresolvable class
-  (`getAccess()` → `undefined`) and a predicate that throws both **deny**. A
+  the **related** model's own access class on `GET /:models`, `GET /:models/:id`,
+  both `GET /:models/:id/{relationship}` shapes, the `POST /:models` and
+  `PATCH /:models/:id` **response documents**, and every record inside an
+  `?include=` **`included`** array
+  ([#235](https://github.com/abofs/stonyx-orm/issues/235)), and asks it
+  `{ model: <related>, operation: 'read' }`. **`operation` is `'read'` even on a
+  write route, and that is correct rather than an oversight** — the question
+  asked of the *related* model is "may this caller **read** this id", not "may
+  they update it". An access class that grants `['create']` but not `['read']`
+  on the related model therefore denies that linkage on its own `POST`
+  response; that is the fail-closed direction. Do **not** wire these handlers to
+  `methodAccessMap[request.method]`: it would ask a different question on a
+  write route than on a read route, which is the two-vocabularies failure
+  `createLinkageFilter` exists to prevent. An unresolvable class
+  (`getAccess()` → `undefined`) and a predicate that throws both **deny**.
+
+  **What the two write surfaces cost before #235, measured rather than
+  described:** one HTTP verb defeated the filter on the same record. On
+  `dev @ 8dda5d6`, seconds apart, with no query string and no relationship
+  route, `GET /animals/1` returned `owner.data: null` while `PATCH /animals/1`
+  returned **200 naming angela**. Any caller who could read a record could also
+  write it and be handed the id the read withheld. That consequence is kept here
+  after the fix, and stated as a measurement, because **naming the two handlers
+  is not a substitute for it** — a reader who is told only that `POST` and
+  `PATCH` are now covered cannot tell what was wrong, and a reviewer cannot tell
+  whether the fix addressed it. A
   filtered-out relationship is **indistinguishable from a genuinely empty one** —
   an emptied `hasMany` is `data: []` and an emptied `belongsTo` is `data: null`,
   both **keeping their `links`**, which are built from the serialized record's
-  own id and never from the related one. Nothing errors and no status changes,
+  own id and never from the related one. On the two **write** surfaces there are
+  no `links` to keep: neither handler passes a `baseUrl`, so a filtered and a
+  genuinely-empty relationship are both a bare `{ "data": … }` there. That is
+  pre-existing and deliberate — adding `baseUrl` to the write handlers would be
+  an unrelated change to their response shape. Nothing errors and no status changes,
   because throwing here would be an existence oracle *and* would throw out of
   the enclosing `JSON.stringify`.
 
@@ -967,31 +994,50 @@ per-record filter. An input you cannot identify must **deny**.
   *permitted* related record, which is recorded in the release notes as a
   breaking change.
 
-  **Not yet covered, and each one still publishes ids the surfaces above
-  withhold:**
-
-  - **`included`** — [#235](https://github.com/abofs/stonyx-orm/issues/235). A
-    permitted record sideloaded by `?include=` emits its **own**
-    `relationships.*.data` unfiltered, so `GET /animals/1?include=owner,owner.pets`
-    returns `owner.data: null` on the primary document and then names angela in
-    `included`, along with eight permitted animals that each name
-    `{"type":"owner","id":"angela"}`. Separately,
+  **Not yet covered by #235. Each still publishes ids the surfaces above
+  withhold, except where its own owning issue has since closed it — the first
+  entry names an issue that is in flight as this is written:**
+
+  - **`GET /:models/:id/relationships/{relationship}`, and its state is #232's
+    to report rather than this entry's.**
+    [#232](https://github.com/abofs/stonyx-orm/issues/232) owns the
+    relationships-linkage route. Its *primary data* is linkage,
+    so filtering it is a **membership** decision — which is why it is the filed
+    child of [#196](https://github.com/abofs/stonyx-orm/issues/196) and not of
+    #234. The route builds its `{type, id}` objects by hand and never calls
+    `toJSON`, so the `linkage` **option** never reaches it; whatever that route
+    filters, it filters itself. Measured **on `dev @ 8dda5d6`**, the commit
+    #235 branched from: `GET /animals/1/relationships/owner` answered
+    `{"type":"owner","id":"angela"}` while `GET /owners/angela` was `404`. That
+    measurement is pinned to a commit on purpose, so that it does not quietly
+    become a false claim about `dev`. **PR
+    [#247](https://github.com/abofs/stonyx-orm/pull/247) is in flight against
+    this entry**; if it has landed, this route is covered and the bullet #247
+    adds above supersedes this one.
+  - **Whether a related resource appears in `included` at all.**
     [#233](https://github.com/abofs/stonyx-orm/issues/233) owns whether a
-    resource appears in `included` **at all** — that is membership, a different
-    question, and following it will not lead you to this residual.
-  - **The `POST`/`PATCH` response documents** —
-    [#235](https://github.com/abofs/stonyx-orm/issues/235). `createHandler` and
-    `updateHandler` destructure the request rather than binding it, so wiring
-    them needs a signature change rather than an argument. Until then **one HTTP
-    verb defeats the filter on the same record**: measured, `GET /animals/1`
-    returns `owner.data: null` and `PATCH /animals/1` returns **200 naming
-    angela**, seconds apart, with no query string and no relationship route. Any
-    caller who can read a record can also write it and be handed the id the read
-    withheld.
-  - **`GET /:models/:id/relationships/{relationship}`**, whose *primary data* is
-    linkage, so filtering it is a **membership** decision —
-    [#232](https://github.com/abofs/stonyx-orm/issues/232), the filed child of
-    [#196](https://github.com/abofs/stonyx-orm/issues/196).
+    related resource appears in `included`. #235 filters what a record
+    *already in* `included` may **name**; a hidden record is still a
+    **member** of that array. The two are different questions and neither closes
+    the other: after #235, `GET /animals/1?include=owner,owner.pets` returns
+    `owner.data: null` on every permitted animal it sideloads **and still
+    includes the hidden owner as a resource**.
+  - **A computed attribute that interpolates a related record's id.**
+    [#245](https://github.com/abofs/stonyx-orm/issues/245) owns this channel,
+    and **it is open as this is written**. `relationships.*.data` is a structure
+    this module builds, so it can be filtered; a computed property is arbitrary
+    consumer code returning an arbitrary value. Whether that makes the channel a
+    **framework defect** the ORM should close — by handing computed getters a
+    verdict, or by refusing to run them while a filter is in force — or a
+    **consumer contract** the ORM should only document, is the question #245
+    must decide. **This README does not decide it; neither reading should be
+    read out of the text here.** Measured on this repo's own fixture, where the
+    `animal` model has a `get tag()` that interpolates `owner.id`: **every**
+    animal document on **every** surface — including the ones above — carries
+    `attributes.tag: "angela's small dog"` for an owner that answers `404`. That
+    measurement is where #245 starts, and it holds whichever way the decision
+    lands. Until it lands, if your access rules hide a record, audit your
+    computed properties for its identifiers.
 - **A bare `toJSON()` still emits unfiltered linkage, and that is deliberate.**
   `Record.toJSON()` **applies** a verdict; it never **resolves** one. It has no
   request, and the documented `access()` contract permits a predicate to read
@@ -1085,11 +1131,29 @@ read all of these.
 
 #### `Record.toJSON()` does not filter relationship linkage unless you pass a verdict
 
-**The framework owns this on four surfaces. You own it everywhere else.**
-
-`GET /:models`, `GET /:models/:id` and both `GET /:models/:id/{relationship}`
-shapes resolve a linkage verdict and pass it to `toJSON()` for you. Any other
-path to a document — `JSON.stringify(record)`, `res.json(record)`,
+**The framework resolves a verdict for you on every request-bound surface that
+serializes a record through `toJSON()`. You own it everywhere else.**
+
+Those surfaces are `GET /:models`, `GET /:models/:id`, both shapes of
+`GET /:models/:id/{relationship}`, the `POST /:models` and `PATCH /:models/:id`
+**response documents**, and every record inside an `?include=` **`included`**
+array ([#234](https://github.com/abofs/stonyx-orm/issues/234) for the four
+reads, [#235](https://github.com/abofs/stonyx-orm/issues/235) for the two
+writes and `included`). Each resolves a linkage verdict and passes it to
+`toJSON()` for you.
+
+**`GET /:models/:id/relationships/{relationship}` is not on that list, and its
+state is not this section's to report.** It builds its `{ type, id }` objects by
+hand instead of calling `toJSON()`, so the `linkage` **option** never reaches it
+— whatever that route filters, it filters itself. And because its linkage *is*
+its primary data, filtering it is a **membership** decision rather than a
+linkage one. Membership on both relationship route families is owned by
+[#232](https://github.com/abofs/stonyx-orm/issues/232) (PR
+[#247](https://github.com/abofs/stonyx-orm/pull/247), in flight as this is
+written); read that issue for its state rather than inferring it here, because
+this section describes only what `toJSON()` filters.
+
+Any other path to a document — `JSON.stringify(record)`, `res.json(record)`,
 `console.log(record)`, a custom route, a queue payload, a websocket frame —
 calls `toJSON()` with no verdict, and **the no-verdict document names every
 related id, including records hidden on every one of their own surfaces**
@@ -1389,13 +1453,15 @@ GET /animals/1
 #### Limitations
 
 - Only available on GET endpoints (not POST/PATCH)
-- **`included` records are not access-filtered, on either question.** Whether a
-  resource appears in `included` at all is
-  [#233](https://github.com/abofs/stonyx-orm/issues/233); a record that *is*
-  permitted still emits its **own** `relationships.*.data` unfiltered, so
-  `?include=` republishes ids the primary document withholds
-  ([#235](https://github.com/abofs/stonyx-orm/issues/235)). See
-  [Consumer Contracts](#consumer-contracts).
+- **`included` is access-filtered on one of the two questions, not both.** What
+  a record already in `included` may **name** in its own
+  `relationships.*.data` is filtered
+  ([#235](https://github.com/abofs/stonyx-orm/issues/235)) — `?include=` no
+  longer republishes ids the primary document withholds. Whether a resource
+  appears in `included` **at all** is *membership* and is still unfiltered
+  ([#233](https://github.com/abofs/stonyx-orm/issues/233)): a record that is
+  404 on its own routes is still served as an `included` resource, attributes
+  and all. See [Consumer Contracts](#consumer-contracts).
 
 ## Lifecycle Hooks
 

package/dist/orm-request.js

@@ -424,7 +424,7 @@ function normalizeBodyId(id) {
     return coerceId(id);
 }
 function buildResponse(data, includeParam, recordOrRecords, options = {}) {
-    const { links, baseUrl } = options;
+    const { links, baseUrl, linkage } = options;
     const response = { data };
     // Add top-level links
     if (links) {
@@ -437,14 +437,53 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
         return response;
     const includedRecords = collectIncludedRecords(recordOrRecords, includes);
     if (includedRecords.length > 0) {
-        // NO `linkage` ARGUMENT, deliberately, and abofs/stonyx-orm#235 owns adding
-        // one. Until it does, a PERMITTED record here emits the full pre-#234
-        // document: `GET /animals/1?include=owner` filters the primary document's
-        // `owner.data` to `null` and then names `owner:angela` in `included`.
-        // Whether a resource reaches this array at all is a different question
-        // (membership, abofs/stonyx-orm#233) and closing that one does not close
-        // this one.
-        response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
+        // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
+        // line is one story's and the line above it is another's
+        // (abofs/stonyx-orm#235 and #233 respectively).
+        //
+        //   - WHICH RESOURCES REACH THIS ARRAY is decided by
+        //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
+        //     #233's, and it is deliberately untouched here: a hidden owner is
+        //     still a member of `included` after this change. Pinned green by
+        //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
+        //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
+        //     `relationships.*.data` is LINKAGE -- the same question #234 answers
+        //     for the primary document -- and that is what the `linkage` option
+        //     below decides. Before it, `GET /animals/1?include=owner,owner.pets`
+        //     filtered the primary document's `owner.data` to `null` and then
+        //     handed back 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;
 }
@@ -626,7 +665,11 @@ export default class OrmRequest extends 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
             });
         };
         const getSingleHandler = async (request, { filter }) => {
@@ -642,28 +685,28 @@ export default class OrmRequest extends Request {
             const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
             const baseUrl = getBaseUrl(request);
             const linkage = createLinkageFilter(request);
-            // `buildResponse` is deliberately NOT given the linkage filter, and the
-            // residual that leaves is NOT the one #233 owns. Two different questions:
+            // `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.
             //
-            //   - 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.
+            // 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 = async ({ body, query }, { filter }) => {
+        const createHandler = 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 || {});
             if (!type)
                 return 400; // Bad request
@@ -902,9 +945,28 @@ 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 = async ({ body, params }, { filter }) => {
+        const updateHandler = 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;
@@ -961,7 +1023,14 @@ export default class OrmRequest extends Request {
                     updateRecord(record, relUpdates, { _skipAutoPersist: true });
                 }
             }
-            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 = async ({ params }, { filter }) => {
             // Coerced ONCE. `getId(params)` was evaluated twice here -- once to find
@@ -1267,6 +1336,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, { filter } = {}) => {
                 const record = await store.find(model, getId(request.params));
                 if (!record)

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-beta.158",
+  "version": "0.3.2-beta.159",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/orm-request.ts

@@ -267,7 +267,7 @@ import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
-import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
+import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation, LinkageFilter } from './types/orm-types.js';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
 import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 
@@ -465,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
@@ -482,14 +482,53 @@ function buildResponse(
 
   const includedRecords = collectIncludedRecords(recordOrRecords, includes);
   if (includedRecords.length > 0) {
-    // NO `linkage` ARGUMENT, deliberately, and abofs/stonyx-orm#235 owns adding
-    // one. Until it does, a PERMITTED record here emits the full pre-#234
-    // document: `GET /animals/1?include=owner` filters the primary document's
-    // `owner.data` to `null` and then names `owner:angela` in `included`.
-    // Whether a resource reaches this array at all is a different question
-    // (membership, abofs/stonyx-orm#233) and closing that one does not close
-    // this one.
-    response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
+    // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
+    // line is one story's and the line above it is another's
+    // (abofs/stonyx-orm#235 and #233 respectively).
+    //
+    //   - WHICH RESOURCES REACH THIS ARRAY is decided by
+    //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
+    //     #233's, and it is deliberately untouched here: a hidden owner is
+    //     still a member of `included` after this change. Pinned green by
+    //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
+    //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
+    //     `relationships.*.data` is LINKAGE -- the same question #234 answers
+    //     for the primary document -- and that is what the `linkage` option
+    //     below decides. Before it, `GET /animals/1?include=owner,owner.pets`
+    //     filtered the primary document's `owner.data` to `null` and then
+    //     handed back 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;
@@ -700,7 +739,11 @@ export default class OrmRequest extends Request {
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
-        baseUrl
+        baseUrl,
+        // THE SAME filter object the primary documents above were serialized
+        // with, deliberately: it carries the caches, and rebuilding one here
+        // would re-resolve every type (abofs/stonyx-orm#235).
+        linkage
       });
     };
 
@@ -718,29 +761,29 @@ export default class OrmRequest extends Request {
       const baseUrl = getBaseUrl(request);
       const linkage = createLinkageFilter(request);
 
-      // `buildResponse` is deliberately NOT given the linkage filter, and the
-      // residual that leaves is NOT the one #233 owns. Two different questions:
+      // `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.
       //
-      //   - 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.
+      // 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;
@@ -995,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
@@ -1057,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 }) => {
@@ -1388,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;