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

package/README.md

@@ -452,7 +452,11 @@ export default class GlobalAccess {
     // inert. Deliberately NO `?? record.owner` fallback: accepting the raw
     // shape as well as the resolved one would absorb a resolution regression
     // silently, which is exactly what blinded this fixture before.
-    if (model === 'animal') return record => record.owner?.id !== 'restricted';
+    // `record.id !== 18` hides one animal whose OWNER is permitted. It is the
+    // fixture that makes the `hasMany` half of the relationship-route rules
+    // observable: gina is served, animal 18 is not, and every surface that
+    // names gina's pets has to drop it.
+    if (model === 'animal') return record => record.owner?.id !== 'restricted' && record.id !== 18;
 
     // Allows full access to all calls that don't match any of the above conditions
     return ['read', 'create', 'update', 'delete'];
@@ -921,45 +925,81 @@ per-record filter. An input you cannot identify must **deny**.
   operation and which record the request addresses. The five variants above are
   the five ways that has been observed to fail open so far. Tracked as
   [#202](https://github.com/abofs/stonyx-orm/issues/202).
-- **Related and included records are not filtered.** The predicate is evaluated
-  against the record the route is *addressed to*. `GET /animals/1/owner`,
-  `GET /animals/1/relationships/owner` and `?include=owner` all serialize the
-  related record without resolving that model's own access class, so a filter on
-  `/owners` does not hide an owner reached through `/animals`. Tracked as
-  [#196](https://github.com/abofs/stonyx-orm/issues/196), which covers
-  `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 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
+- **The two relationship route families now resolve the *related* model's own
+  access class — `GET /:models/:id/{relationship}` and
+  `GET /:models/:id/relationships/{relationship}`**
+  ([#232](https://github.com/abofs/stonyx-orm/issues/232)). This is
+  **membership**: the related resource is the route's *primary* data, so the
+  filter decides whether it is served at all, not merely which ids a document
+  may name. A denied `hasMany` member is **dropped from the array** — the result
+  is shaped exactly like a genuinely empty relationship, `links` intact, no
+  `errors` member, same status. A denied `belongsTo` target answers **404**, the
+  same status the route already answered for a denied parent and for a parent
+  that does not exist. The `/relationships/` family built its `{type, id}` by
+  hand rather than through `toJSON()`, which is why the linkage filter shipped in
+  [#234](https://github.com/abofs/stonyx-orm/issues/234) did not reach it.
+
+  Before this, both families served a record hidden on every one of its own
+  surfaces, in full, from another model's route, at **zero query parameters**.
+  The severe case is a model **claimed by no access class**: `getAccess()`
+  returns `undefined`, no route is mounted for it at all, and it was still
+  readable as a related resource — a collection the consumer deliberately never
+  exposed.
+
+  **Residual on the `belongsTo` shape, stated rather than left to be found:** a
+  denied target answers 404 while a genuinely *absent* one answers 200 with
+  `data: null`, so those two cases are distinguishable. That asymmetry is
+  inherited — a denied *parent* has always answered 404 while an existing parent
+  with an empty relationship answers 200 — and changing it is a change to this
+  module's whole spelling of denial, not to these two routes.
+
+  **Per-record denies for a related resource are not expressible.** A predicate resolved for a
+  related resource on these routes receives `recordId: null` and a `request`
+  whose `params` name a record of a **different model**. So the inputs it has
+  are the model name, the operation and the request — and **a rule that needs to
+  know *which* related record it is being asked about cannot be written**.
+  Model-level denies (`return false` for a model) work. Request-level denies (a
+  rule reading a header, a tenant, the method) work. The per-record **filter**
+  shape works too — `access()` may return a function, and that function receives
+  the whole record, id included. What does not work is branching on the record's
+  identity *before* returning, because `access()` is not told it.
+
+  This is not an oversight and it is not closed here. The verdict is resolved
+  **once per type**, cached, before any record has been examined — a `hasMany`
+  related-resource route returns many records of one type, so seeding `recordId`
+  from a record would let the first one decide the context for all of them. The
+  rule the framework holds to is: **`recordId` may name a record only where the
+  route addresses exactly one record of the model being asked about.** That is
+  true for `GET /owners/{id}`, false for linkage, and false for a `hasMany`
+  related-resource route.
+
+- **`?include=` records are still not filtered — the relationship routes now
+  are.** *Re-specified by [#232](https://github.com/abofs/stonyx-orm/issues/232);
+  the sentence this replaces said all three surfaces were unfiltered, and two of
+  them no longer are.* `GET /animals/1/owner` and
+  `GET /animals/1/relationships/owner` resolve the related model's own access
+  class (see the bullet above). **`?include=owner` still does not**: it
+  serializes the related record without resolving that class, so a filter on
+  `/owners` does not hide an owner reached through `?include=` on `/animals`.
+  Tracked as [#233](https://github.com/abofs/stonyx-orm/issues/233), the
+  remaining child of [#196](https://github.com/abofs/stonyx-orm/issues/196).
+  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
   ([#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`,
-  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
+  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
   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. 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,
+  own id and never from the related one. Nothing errors and no status changes,
   because throwing here would be an existence oracle *and* would throw out of
   the enclosing `JSON.stringify`.
 
@@ -986,32 +1026,32 @@ per-record filter. An input you cannot identify must **deny**.
   **Not yet covered, and each one still publishes ids the surfaces above
   withhold:**
 
-  - **`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). This route builds
-    its `{type, id}` objects by hand and never calls `toJSON`, so it does not
-    see a `linkage` option no matter who supplies one. Measured:
-    `GET /animals/1/relationships/owner` answers
-    `{"type":"owner","id":"angela"}` while `GET /owners/angela` is `404`.
-  - **Whether a related resource appears in `included` at all** —
-    [#233](https://github.com/abofs/stonyx-orm/issues/233). #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.** This is a
-    **consumer-side** residual and the ORM cannot close it. `relationships.*.data`
-    is a structure this module builds, so it can be filtered; a computed
-    property is arbitrary consumer code returning an arbitrary value, and
-    deciding which substrings of it are identifiers is not something the
-    framework can do. 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`. If
-    your access rules hide a record, audit your computed properties for its
-    identifiers.
+  - **`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,
+    [#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}`**~~ — **covered as of
+    [#232](https://github.com/abofs/stonyx-orm/issues/232)**, together with
+    `GET /:models/:id/{relationship}`. Left in place rather than deleted because
+    this list is what a reader consults to find out what is *not* covered, and a
+    silently vanishing entry reads as an entry that was never there. Its
+    *primary data* is linkage, so filtering it was a **membership** decision —
+    which is why it belonged to #232 and not to
+    [#234](https://github.com/abofs/stonyx-orm/issues/234).
 - **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
@@ -1409,15 +1449,13 @@ GET /animals/1
 #### Limitations
 
 - Only available on GET endpoints (not POST/PATCH)
-- **`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).
+- **`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).
 
 ## 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, linkage } = options;
+    const { links, baseUrl } = options;
     const response = { data };
     // Add top-level links
     if (links) {
@@ -437,49 +437,14 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
         return response;
     const includedRecords = collectIncludedRecords(recordOrRecords, includes);
     if (includedRecords.length > 0) {
-        // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
-        // line is one story's and the line above it is another's
-        // (abofs/stonyx-orm#235 and #233 respectively).
-        //
-        //   - WHICH RESOURCES REACH THIS ARRAY is decided by
-        //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
-        //     #233's, and it is deliberately untouched here: a hidden owner is
-        //     still a member of `included` after this change. Pinned green by
-        //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
-        //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
-        //     `relationships.*.data` is LINKAGE -- the same question #234 answers
-        //     for the primary document -- and that is what the `linkage` option
-        //     below decides. Before it, `GET /animals/1?include=owner,owner.pets`
-        //     filtered the primary document's `owner.data` to `null` and then
-        //     handed back nine PERMITTED animals in `included` each naming
-        //     `{"type":"owner","id":"angela"}`. Neither #233 nor #234 closes that.
-        //
-        // THE FILTER IS THE CALLER'S, PASSED IN, NOT BUILT HERE. Both call sites
-        // already hold one for the primary document, and sharing it is what keeps
-        // the per-type verdict cache and the per-(type, id) decision cache alive
-        // across the primary document AND the sideload -- one verdict resolution
-        // per type for the whole response, pinned by `[GUARD] #235 C1`. Building a
-        // fresh filter here would resolve the consumer's `access()` once per
-        // included record instead.
-        //
-        // `linkage` IS OPTIONAL IN THE TYPE AND IS NOT OPTIONAL IN PRACTICE.
-        // Stating it precisely because the opposite claim stood here in an earlier
-        // draft of this change: BOTH of this function's callers supply a filter
-        // (`getCollectionHandler` and `getSingleHandler`, the only two), so the
-        // `undefined` branch has no live caller in this module today. It is
-        // optional so that omitting it degrades to the PRE-#234 document rather
-        // than to a denial -- `Record.toJSON` reads an ABSENT option as "no verdict
-        // was supplied" and emits linkage in full.
-        //
-        // WHAT IT MUST NEVER BE HANDED IS A NON-FUNCTION. `toJSON` does NOT read a
-        // non-function as absent: `Object.prototype.toString.call(linkage)` must be
-        // `'[object Function]'`, and anything else -- `null`, an `AsyncFunction`,
-        // and INCLUDING the primitive `true` -- DENIES every relationship on the
-        // document and logs once. `toJSON({ linkage: true })` emits `null` linkage.
-        // So do not "simplify" this to a boolean, and do not make it default to
-        // `true`: both spellings look like "allow everything" and mean the exact
-        // opposite (abofs/stonyx-orm#224).
-        response.included = includedRecords.map(record => record.toJSON?.({ baseUrl, linkage }));
+        // NO `linkage` ARGUMENT, deliberately, and abofs/stonyx-orm#235 owns adding
+        // one. Until it does, a PERMITTED record here emits the full pre-#234
+        // document: `GET /animals/1?include=owner` filters the primary document's
+        // `owner.data` to `null` and then names `owner:angela` in `included`.
+        // Whether a resource reaches this array at all is a different question
+        // (membership, abofs/stonyx-orm#233) and closing that one does not close
+        // this one.
+        response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
     }
     return response;
 }
@@ -661,11 +626,7 @@ 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,
-                // THE SAME filter object the primary documents above were serialized
-                // with, deliberately: it carries the caches, and rebuilding one here
-                // would re-resolve every type (abofs/stonyx-orm#235).
-                linkage
+                baseUrl
             });
         };
         const getSingleHandler = async (request, { filter }) => {
@@ -681,28 +642,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 given the filter now (abofs/stonyx-orm#235), and it
-            // is the SAME object the primary document is serialized with -- one
-            // verdict per type for the whole response, sideload included.
+            // `buildResponse` is deliberately NOT given the linkage filter, and the
+            // residual that leaves is NOT the one #233 owns. Two different questions:
+            //
+            //   - WHETHER A RESOURCE APPEARS in `included` at all is MEMBERSHIP ->
+            //     abofs/stonyx-orm#233.
+            //   - What a record already IN `included` may NAME is LINKAGE -- the same
+            //     question #234 answers for the primary document -- and it is
+            //     abofs/stonyx-orm#235, which also owns createHandler/updateHandler.
             //
-            // The boundary that remains, so the next reader does not have to derive
-            // it: this closes what a record already in `included` may NAME. WHETHER a
-            // resource appears in `included` at all is MEMBERSHIP and it is
-            // abofs/stonyx-orm#233's -- a hidden owner is still a member here.
-            // Neither question closes the other.
+            // The residual, stated so the next reader does not have to derive it:
+            // `buildResponse` calls `record.toJSON?.({ baseUrl })` with no `linkage`
+            // argument, so a PERMITTED record in `included` emits the full pre-#234
+            // document. Measured: `GET /animals/1?include=owner` returns
+            // `owner.data: null` on the primary document and `owner:angela` in
+            // `included`. One query parameter deep. Only the PRIMARY document's
+            // linkage is filtered here.
             return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
                 links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
-                baseUrl,
-                linkage
+                baseUrl
             });
         };
-        const createHandler = async (request, { filter }) => {
-            // BOUND, not destructured (abofs/stonyx-orm#235). `HandlerFn` has always
-            // delivered the request as argument one; this handler simply discarded
-            // the binding, which is why its response document named ids every read
-            // surface withholds. `createLinkageFilter` needs the live request and
-            // there is no signature change involved in giving it one.
-            const { body, query } = request;
+        const createHandler = async ({ body, query }, { filter }) => {
             const { type, id, attributes, relationships: rels } = (body?.data || {});
             if (!type)
                 return 400; // Bad request
@@ -941,28 +902,9 @@ export default class OrmRequest extends Request {
                 }
                 return 403;
             }
-            // The filter is built HERE, per invocation, and never hoisted into the
-            // OrmRequest constructor where the other per-mount values live: a verdict
-            // cached across requests answers a second caller with the first caller's
-            // authorization (src/access-verdict.ts says so at the constructor an
-            // implementer would reach for).
-            //
-            // AND IT IS BUILT AFTER `createRecord`, AFTER THE ROLLBACK WINDOW AND
-            // AFTER `isDenied`, so the record is in its final form at the call. The
-            // filter is lazy per type and per (type, id), so it cannot observe a
-            // pre-write state even if it were built earlier.
-            //
-            // `fields` is passed here and NOT in `updateHandler`: the two handlers
-            // are asymmetric on purpose (`updateHandler` has no `fieldsMap` in
-            // scope), and a single copy-pasted wiring would drop it from one of them.
-            return { data: record.toJSON?.({ fields: modelFields, linkage: createLinkageFilter(request) }) };
+            return { data: record.toJSON?.({ fields: modelFields }) };
         };
-        const updateHandler = async (request, { filter }) => {
-            // Bound rather than destructured, for the reason given in
-            // `createHandler` above (abofs/stonyx-orm#235). `PATCH /animals/1`
-            // returned 200 naming angela seconds after `GET /animals/1` returned
-            // `owner.data: null` for the same record -- one HTTP verb apart.
-            const { body, params } = request;
+        const updateHandler = async ({ body, params }, { filter }) => {
             const found = await store.find(model, getId(params));
             if (!found || !isOrmRecord(found))
                 return 404;
@@ -1019,14 +961,7 @@ export default class OrmRequest extends Request {
                     updateRecord(record, relUpdates, { _skipAutoPersist: true });
                 }
             }
-            // No `fields` and no `baseUrl`, both unchanged: `updateHandler` has no
-            // `fieldsMap` in scope, and adding `baseUrl` would put `links` on a
-            // document that has never carried them -- an unrelated behaviour change.
-            // #224 AC6's "emits `data: []` WITH links" is a statement about the READ
-            // surfaces; on these two handlers a filtered relationship and a
-            // genuinely-empty one are both a bare `{ data }`, which is what makes
-            // them indistinguishable here too.
-            return { data: record.toJSON?.({ linkage: createLinkageFilter(request) }) };
+            return { data: record.toJSON?.() };
         };
         const deleteHandler = async ({ params }, { filter }) => {
             // Coerced ONCE. `getId(params)` was evaluated twice here -- once to find
@@ -1310,21 +1245,77 @@ export default class OrmRequest extends Request {
                     return 404;
                 const relatedData = record.__relationships[relationshipName];
                 const baseUrl = getBaseUrl(request);
-                // LINKAGE ONLY. This filter decides which ids the emitted documents may
-                // NAME in their own `relationships.*.data`; it does NOT decide whether
-                // the related records themselves are served -- that is the parent-only
-                // filtering this route has done since #190, and widening it to the
-                // related record is abofs/stonyx-orm#196.
+                // ONE FILTER, TWO JOBS, AND abofs/stonyx-orm#232 IS THE SECOND ONE.
+                //
+                // As LINKAGE (#234) it decides which ids the emitted documents may NAME
+                // in their own `relationships.*.data`. As MEMBERSHIP (this issue) it
+                // decides whether the related record is served here AT ALL -- the
+                // related resource is PRIMARY data on this route, so there is no
+                // linkage-consistency question to answer separately.
+                //
+                // Until #232 this route filtered only the PARENT, so a record its own
+                // model's predicate hides was served in full from another model's
+                // route, at ZERO query parameters. Measured on dev @ 8dda5d6:
+                //
+                //     GET /owners/angela          -> 404
+                //     GET /animals/1/owner        -> 200, owner:angela, full attributes
+                //     GET /traits/2/tag           -> 200, a model NO access class
+                //                                    claims, on a collection that has
+                //                                    no mounted route at all
+                //
+                // ARGUMENT ONE IS THE LIVE REQUEST, NOT A DERIVED ONE. A fabricated
+                // request addressing the RELATED resource was the original design and
+                // it is dropped: #241 removed the shipped fixture's read of argument
+                // one, so a fabricated value changes nothing it could observe, and
+                // test/unit/linkage-verdict-test.ts:484 pins the predicate as receiving
+                // the live request BY IDENTITY. `createLinkageFilter` is also a
+                // published public export (src/index.ts) whose resolution granularity
+                // is per TYPE; supplying a per-RECORD request would mean widening it,
+                // which takes a consumer `access()` from ~2 calls to ~7 on a plain
+                // `GET /animals`. That is a separate, consumer-visible story.
+                //
+                // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
+                // `recordId` is `null` here and the request names a record of a
+                // DIFFERENT model, so a consumer predicate can express a model-level or
+                // a request-level deny for a related resource, but NOT a per-record
+                // one. README.md and docs/usage-patterns.md say so; a ledger assertion
+                // in test/unit/relationship-route-access-test.ts keeps them saying it.
                 const linkage = createLinkageFilter(request);
+                // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED. `isLinkable` is
+                // keyed on the model name; without one there is no predicate to ask,
+                // and an unidentifiable input must never be the permissive path.
+                const isLinkable = (r) => {
+                    const type = r.__model?.__name;
+                    return typeof type === 'string' && type !== '' && linkage(type, r);
+                };
                 let data;
                 if (info.isArray) {
-                    // hasMany - return array
+                    // hasMany - return array, MINUS the members this caller may not see.
+                    // Dropped, never errored: the result is byte-identical to a genuinely
+                    // empty relationship, so this route is not an existence oracle.
                     const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-                    data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
+                    data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
                 }
                 else {
-                    // belongsTo - return single or null
-                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
+                    // belongsTo - return single or null. A DENIED target is 404, the same
+                    // status this route already returns for a denied PARENT and for a
+                    // parent that does not exist, and the same status the related
+                    // record's own route answers.
+                    //
+                    // KNOWN RESIDUAL, stated here because it is the one place a reader
+                    // will look: 404 is distinguishable from a relationship that is
+                    // genuinely EMPTY, which answers 200 with `data: null`. So a caller
+                    // can tell "there is a target you may not see" from "there is no
+                    // target". That asymmetry is inherited -- a denied PARENT has always
+                    // answered 404 while an existing parent with an empty relationship
+                    // answers 200 -- and closing it is a change to the module's whole
+                    // denial spelling, not to this route.
+                    if (!isOrmRecord(relatedData))
+                        data = null;
+                    else if (!isLinkable(relatedData))
+                        return 404;
+                    else
+                        data = relatedData.toJSON?.({ baseUrl, linkage });
                 }
                 return {
                     links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}` },
@@ -1332,28 +1323,6 @@ export default class OrmRequest extends Request {
                 };
             };
             // Relationship linkage route: GET /:id/relationships/{relationship}
-            //
-            // NO `linkage` FILTER HERE, AND IT IS NOT AN OVERSIGHT --
-            // abofs/stonyx-orm#232 OWNS THIS ROUTE. The three sites that carry the
-            // filter (`buildResponse`'s `included`, the related-resource branch
-            // above, and the two write handlers) all call `record.toJSON()`, which is
-            // where the `linkage` option is applied. This branch builds its
-            // `{ type, id }` objects BY HAND and never calls `toJSON` at all, so it
-            // cannot see a filter no matter who passes one.
-            //
-            // It is also a DIFFERENT QUESTION. Everywhere else, linkage is metadata
-            // ABOUT a document. Here the linkage IS the primary data, so dropping an
-            // entry is a MEMBERSHIP decision about what this route serves -- the same
-            // class as abofs/stonyx-orm#233 and #196, not the class #234/#235 close.
-            // That is why it is absent from #224 §2a's seven-site inventory.
-            //
-            // MEASURED, so the next person does not re-derive it: this route answers
-            // `GET /animals/1/relationships/owner` with
-            // `{"type":"owner","id":"angela"}` while `GET /owners/angela` is 404.
-            // Wiring the filter in here takes the suite to 993/2 and turns the
-            // `GET /animals/:id/relationships/owner returns relationship linkage`
-            // test red -- which is #232's own reproduction, not a regression.
-            // Pinned unchanged by `[GUARD] #235 X2` in test/integration/orm-test.ts.
             routes[`/:id/relationships/${dasherizedName}`] = async (request, { filter } = {}) => {
                 const record = await store.find(model, getId(request.params));
                 if (!record)
@@ -1362,17 +1331,35 @@ export default class OrmRequest extends Request {
                     return 404;
                 const relatedData = record.__relationships[relationshipName];
                 const baseUrl = getBaseUrl(request);
+                // THE ONLY ONE OF THE FOUR READ SURFACES THAT DOES NOT GO THROUGH
+                // `toJSON()`. It builds `{ type, id }` BY HAND, which is why #234's
+                // linkage filter never reached it and why this half belongs to
+                // abofs/stonyx-orm#232 rather than to #234: on this route the linkage
+                // IS the primary data of an opt-in request, so filtering it changes the
+                // route's MEMBERSHIP semantics, not the ids named inside somebody
+                // else's document.
+                //
+                // Same filter, same argument-one decision, same residual as
+                // `/:id/{relationship}` above -- read the block there.
+                const linkage = createLinkageFilter(request);
+                const isLinkable = (r) => {
+                    const type = r.__model?.__name;
+                    return typeof type === 'string' && type !== '' && linkage(type, r);
+                };
                 let data;
                 if (info.isArray) {
                     // hasMany - return array of linkage objects
                     const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
                     data = related
                         .filter((r) => Boolean(r.__model))
+                        .filter(isLinkable)
                         .map(r => ({ type: r.__model.__name, id: r.id }));
                 }
                 else {
                     // belongsTo - return single linkage or null
                     if (isOrmRecord(relatedData) && relatedData.__model) {
+                        if (!isLinkable(relatedData))
+                            return 404;
                         data = { type: relatedData.__model.__name, id: relatedData.id };
                     }
                     else {

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.74",
+  "version": "0.3.2-alpha.75",
   "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, LinkageFilter } from './types/orm-types.js';
+import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
 import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 
@@ -465,9 +465,9 @@ function buildResponse(
   data: unknown,
   includeParam: string | undefined,
   recordOrRecords: OrmRecord | OrmRecord[],
-  options: { links?: { [key: string]: string }; baseUrl?: string; linkage?: LinkageFilter } = {}
+  options: { links?: { [key: string]: string }; baseUrl?: string } = {}
 ): JsonApiResponse {
-  const { links, baseUrl, linkage } = options;
+  const { links, baseUrl } = options;
   const response: JsonApiResponse = { data };
 
   // Add top-level links
@@ -482,49 +482,14 @@ function buildResponse(
 
   const includedRecords = collectIncludedRecords(recordOrRecords, includes);
   if (includedRecords.length > 0) {
-    // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
-    // line is one story's and the line above it is another's
-    // (abofs/stonyx-orm#235 and #233 respectively).
-    //
-    //   - WHICH RESOURCES REACH THIS ARRAY is decided by
-    //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
-    //     #233's, and it is deliberately untouched here: a hidden owner is
-    //     still a member of `included` after this change. Pinned green by
-    //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
-    //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
-    //     `relationships.*.data` is LINKAGE -- the same question #234 answers
-    //     for the primary document -- and that is what the `linkage` option
-    //     below decides. Before it, `GET /animals/1?include=owner,owner.pets`
-    //     filtered the primary document's `owner.data` to `null` and then
-    //     handed back nine PERMITTED animals in `included` each naming
-    //     `{"type":"owner","id":"angela"}`. Neither #233 nor #234 closes that.
-    //
-    // THE FILTER IS THE CALLER'S, PASSED IN, NOT BUILT HERE. Both call sites
-    // already hold one for the primary document, and sharing it is what keeps
-    // the per-type verdict cache and the per-(type, id) decision cache alive
-    // across the primary document AND the sideload -- one verdict resolution
-    // per type for the whole response, pinned by `[GUARD] #235 C1`. Building a
-    // fresh filter here would resolve the consumer's `access()` once per
-    // included record instead.
-    //
-    // `linkage` IS OPTIONAL IN THE TYPE AND IS NOT OPTIONAL IN PRACTICE.
-    // Stating it precisely because the opposite claim stood here in an earlier
-    // draft of this change: BOTH of this function's callers supply a filter
-    // (`getCollectionHandler` and `getSingleHandler`, the only two), so the
-    // `undefined` branch has no live caller in this module today. It is
-    // optional so that omitting it degrades to the PRE-#234 document rather
-    // than to a denial -- `Record.toJSON` reads an ABSENT option as "no verdict
-    // was supplied" and emits linkage in full.
-    //
-    // WHAT IT MUST NEVER BE HANDED IS A NON-FUNCTION. `toJSON` does NOT read a
-    // non-function as absent: `Object.prototype.toString.call(linkage)` must be
-    // `'[object Function]'`, and anything else -- `null`, an `AsyncFunction`,
-    // and INCLUDING the primitive `true` -- DENIES every relationship on the
-    // document and logs once. `toJSON({ linkage: true })` emits `null` linkage.
-    // So do not "simplify" this to a boolean, and do not make it default to
-    // `true`: both spellings look like "allow everything" and mean the exact
-    // opposite (abofs/stonyx-orm#224).
-    response.included = includedRecords.map(record => record.toJSON?.({ baseUrl, linkage }));
+    // NO `linkage` ARGUMENT, deliberately, and abofs/stonyx-orm#235 owns adding
+    // one. Until it does, a PERMITTED record here emits the full pre-#234
+    // document: `GET /animals/1?include=owner` filters the primary document's
+    // `owner.data` to `null` and then names `owner:angela` in `included`.
+    // Whether a resource reaches this array at all is a different question
+    // (membership, abofs/stonyx-orm#233) and closing that one does not close
+    // this one.
+    response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
   }
 
   return response;
@@ -735,11 +700,7 @@ export default class OrmRequest extends Request {
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
-        baseUrl,
-        // THE SAME filter object the primary documents above were serialized
-        // with, deliberately: it carries the caches, and rebuilding one here
-        // would re-resolve every type (abofs/stonyx-orm#235).
-        linkage
+        baseUrl
       });
     };
 
@@ -757,29 +718,29 @@ export default class OrmRequest extends Request {
       const baseUrl = getBaseUrl(request);
       const linkage = createLinkageFilter(request);
 
-      // `buildResponse` IS given the filter now (abofs/stonyx-orm#235), and it
-      // is the SAME object the primary document is serialized with -- one
-      // verdict per type for the whole response, sideload included.
+      // `buildResponse` is deliberately NOT given the linkage filter, and the
+      // residual that leaves is NOT the one #233 owns. Two different questions:
+      //
+      //   - WHETHER A RESOURCE APPEARS in `included` at all is MEMBERSHIP ->
+      //     abofs/stonyx-orm#233.
+      //   - What a record already IN `included` may NAME is LINKAGE -- the same
+      //     question #234 answers for the primary document -- and it is
+      //     abofs/stonyx-orm#235, which also owns createHandler/updateHandler.
       //
-      // The boundary that remains, so the next reader does not have to derive
-      // it: this closes what a record already in `included` may NAME. WHETHER a
-      // resource appears in `included` at all is MEMBERSHIP and it is
-      // abofs/stonyx-orm#233's -- a hidden owner is still a member here.
-      // Neither question closes the other.
+      // The residual, stated so the next reader does not have to derive it:
+      // `buildResponse` calls `record.toJSON?.({ baseUrl })` with no `linkage`
+      // argument, so a PERMITTED record in `included` emits the full pre-#234
+      // document. Measured: `GET /animals/1?include=owner` returns
+      // `owner.data: null` on the primary document and `owner:angela` in
+      // `included`. One query parameter deep. Only the PRIMARY document's
+      // linkage is filtered here.
       return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
-        baseUrl,
-        linkage
+        baseUrl
       });
     };
 
-    const createHandler: HandlerFn = async (request, { filter }) => {
-      // BOUND, not destructured (abofs/stonyx-orm#235). `HandlerFn` has always
-      // delivered the request as argument one; this handler simply discarded
-      // the binding, which is why its response document named ids every read
-      // surface withholds. `createLinkageFilter` needs the live request and
-      // there is no signature change involved in giving it one.
-      const { body, query } = request;
+    const createHandler: HandlerFn = async ({ body, query }, { filter }) => {
       const { type, id, attributes, relationships: rels } = (body?.data || {}) as {
         type?: string;
         id?: string | number;
@@ -1034,29 +995,10 @@ export default class OrmRequest extends Request {
         return 403;
       }
 
-      // The filter is built HERE, per invocation, and never hoisted into the
-      // OrmRequest constructor where the other per-mount values live: a verdict
-      // cached across requests answers a second caller with the first caller's
-      // authorization (src/access-verdict.ts says so at the constructor an
-      // implementer would reach for).
-      //
-      // AND IT IS BUILT AFTER `createRecord`, AFTER THE ROLLBACK WINDOW AND
-      // AFTER `isDenied`, so the record is in its final form at the call. The
-      // filter is lazy per type and per (type, id), so it cannot observe a
-      // pre-write state even if it were built earlier.
-      //
-      // `fields` is passed here and NOT in `updateHandler`: the two handlers
-      // are asymmetric on purpose (`updateHandler` has no `fieldsMap` in
-      // scope), and a single copy-pasted wiring would drop it from one of them.
-      return { data: record.toJSON?.({ fields: modelFields, linkage: createLinkageFilter(request) }) };
+      return { data: record.toJSON?.({ fields: modelFields }) };
     };
 
-    const updateHandler: HandlerFn = async (request, { filter }) => {
-      // Bound rather than destructured, for the reason given in
-      // `createHandler` above (abofs/stonyx-orm#235). `PATCH /animals/1`
-      // returned 200 naming angela seconds after `GET /animals/1` returned
-      // `owner.data: null` for the same record -- one HTTP verb apart.
-      const { body, params } = request;
+    const updateHandler: HandlerFn = async ({ body, params }, { filter }) => {
       const found = await store.find(model, getId(params));
       if (!found || !isOrmRecord(found)) return 404;
       // Checked BEFORE any attribute is applied. 404 rather than 403 for the
@@ -1115,14 +1057,7 @@ export default class OrmRequest extends Request {
         }
       }
 
-      // No `fields` and no `baseUrl`, both unchanged: `updateHandler` has no
-      // `fieldsMap` in scope, and adding `baseUrl` would put `links` on a
-      // document that has never carried them -- an unrelated behaviour change.
-      // #224 AC6's "emits `data: []` WITH links" is a statement about the READ
-      // surfaces; on these two handlers a filtered relationship and a
-      // genuinely-empty one are both a bare `{ data }`, which is what makes
-      // them indistinguishable here too.
-      return { data: record.toJSON?.({ linkage: createLinkageFilter(request) }) };
+      return { data: record.toJSON?.() };
     };
 
     const deleteHandler: HandlerFn = async ({ params }, { filter }) => {
@@ -1429,21 +1364,76 @@ export default class OrmRequest extends Request {
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
-        // LINKAGE ONLY. This filter decides which ids the emitted documents may
-        // NAME in their own `relationships.*.data`; it does NOT decide whether
-        // the related records themselves are served -- that is the parent-only
-        // filtering this route has done since #190, and widening it to the
-        // related record is abofs/stonyx-orm#196.
+        // ONE FILTER, TWO JOBS, AND abofs/stonyx-orm#232 IS THE SECOND ONE.
+        //
+        // As LINKAGE (#234) it decides which ids the emitted documents may NAME
+        // in their own `relationships.*.data`. As MEMBERSHIP (this issue) it
+        // decides whether the related record is served here AT ALL -- the
+        // related resource is PRIMARY data on this route, so there is no
+        // linkage-consistency question to answer separately.
+        //
+        // Until #232 this route filtered only the PARENT, so a record its own
+        // model's predicate hides was served in full from another model's
+        // route, at ZERO query parameters. Measured on dev @ 8dda5d6:
+        //
+        //     GET /owners/angela          -> 404
+        //     GET /animals/1/owner        -> 200, owner:angela, full attributes
+        //     GET /traits/2/tag           -> 200, a model NO access class
+        //                                    claims, on a collection that has
+        //                                    no mounted route at all
+        //
+        // ARGUMENT ONE IS THE LIVE REQUEST, NOT A DERIVED ONE. A fabricated
+        // request addressing the RELATED resource was the original design and
+        // it is dropped: #241 removed the shipped fixture's read of argument
+        // one, so a fabricated value changes nothing it could observe, and
+        // test/unit/linkage-verdict-test.ts:484 pins the predicate as receiving
+        // the live request BY IDENTITY. `createLinkageFilter` is also a
+        // published public export (src/index.ts) whose resolution granularity
+        // is per TYPE; supplying a per-RECORD request would mean widening it,
+        // which takes a consumer `access()` from ~2 calls to ~7 on a plain
+        // `GET /animals`. That is a separate, consumer-visible story.
+        //
+        // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
+        // `recordId` is `null` here and the request names a record of a
+        // DIFFERENT model, so a consumer predicate can express a model-level or
+        // a request-level deny for a related resource, but NOT a per-record
+        // one. README.md and docs/usage-patterns.md say so; a ledger assertion
+        // in test/unit/relationship-route-access-test.ts keeps them saying it.
         const linkage = createLinkageFilter(request);
 
+        // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED. `isLinkable` is
+        // keyed on the model name; without one there is no predicate to ask,
+        // and an unidentifiable input must never be the permissive path.
+        const isLinkable = (r: OrmRecord) => {
+          const type = (r as { __model?: { __name?: string } }).__model?.__name;
+
+          return typeof type === 'string' && type !== '' && linkage(type, r);
+        };
+
         let data: unknown;
         if (info.isArray) {
-          // hasMany - return array
+          // hasMany - return array, MINUS the members this caller may not see.
+          // Dropped, never errored: the result is byte-identical to a genuinely
+          // empty relationship, so this route is not an existence oracle.
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-          data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
+          data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
         } else {
-          // belongsTo - return single or null
-          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
+          // belongsTo - return single or null. A DENIED target is 404, the same
+          // status this route already returns for a denied PARENT and for a
+          // parent that does not exist, and the same status the related
+          // record's own route answers.
+          //
+          // KNOWN RESIDUAL, stated here because it is the one place a reader
+          // will look: 404 is distinguishable from a relationship that is
+          // genuinely EMPTY, which answers 200 with `data: null`. So a caller
+          // can tell "there is a target you may not see" from "there is no
+          // target". That asymmetry is inherited -- a denied PARENT has always
+          // answered 404 while an existing parent with an empty relationship
+          // answers 200 -- and closing it is a change to the module's whole
+          // denial spelling, not to this route.
+          if (!isOrmRecord(relatedData)) data = null;
+          else if (!isLinkable(relatedData)) return 404;
+          else data = relatedData.toJSON?.({ baseUrl, linkage });
         }
 
         return {
@@ -1453,28 +1443,6 @@ export default class OrmRequest extends Request {
       };
 
       // Relationship linkage route: GET /:id/relationships/{relationship}
-      //
-      // NO `linkage` FILTER HERE, AND IT IS NOT AN OVERSIGHT --
-      // abofs/stonyx-orm#232 OWNS THIS ROUTE. The three sites that carry the
-      // filter (`buildResponse`'s `included`, the related-resource branch
-      // above, and the two write handlers) all call `record.toJSON()`, which is
-      // where the `linkage` option is applied. This branch builds its
-      // `{ type, id }` objects BY HAND and never calls `toJSON` at all, so it
-      // cannot see a filter no matter who passes one.
-      //
-      // It is also a DIFFERENT QUESTION. Everywhere else, linkage is metadata
-      // ABOUT a document. Here the linkage IS the primary data, so dropping an
-      // entry is a MEMBERSHIP decision about what this route serves -- the same
-      // class as abofs/stonyx-orm#233 and #196, not the class #234/#235 close.
-      // That is why it is absent from #224 §2a's seven-site inventory.
-      //
-      // MEASURED, so the next person does not re-derive it: this route answers
-      // `GET /animals/1/relationships/owner` with
-      // `{"type":"owner","id":"angela"}` while `GET /owners/angela` is 404.
-      // Wiring the filter in here takes the suite to 993/2 and turns the
-      // `GET /animals/:id/relationships/owner returns relationship linkage`
-      // test red -- which is #232's own reproduction, not a regression.
-      // Pinned unchanged by `[GUARD] #235 X2` in test/integration/orm-test.ts.
       routes[`/:id/relationships/${dasherizedName}`] = async (request: OrmRequest$, { filter }: { [key: string]: unknown } = {}) => {
         const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
         if (!record) return 404;
@@ -1483,16 +1451,36 @@ export default class OrmRequest extends Request {
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
+        // THE ONLY ONE OF THE FOUR READ SURFACES THAT DOES NOT GO THROUGH
+        // `toJSON()`. It builds `{ type, id }` BY HAND, which is why #234's
+        // linkage filter never reached it and why this half belongs to
+        // abofs/stonyx-orm#232 rather than to #234: on this route the linkage
+        // IS the primary data of an opt-in request, so filtering it changes the
+        // route's MEMBERSHIP semantics, not the ids named inside somebody
+        // else's document.
+        //
+        // Same filter, same argument-one decision, same residual as
+        // `/:id/{relationship}` above -- read the block there.
+        const linkage = createLinkageFilter(request);
+        const isLinkable = (r: OrmRecord) => {
+          const type = (r as { __model?: { __name?: string } }).__model?.__name;
+
+          return typeof type === 'string' && type !== '' && linkage(type, r);
+        };
+
         let data: unknown;
         if (info.isArray) {
           // hasMany - return array of linkage objects
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
           data = related
             .filter((r): r is OrmRecord & { __model: { __name: string } } => Boolean(r.__model))
+            .filter(isLinkable)
             .map(r => ({ type: r.__model.__name, id: r.id }));
         } else {
           // belongsTo - return single linkage or null
           if (isOrmRecord(relatedData) && relatedData.__model) {
+            if (!isLinkable(relatedData)) return 404;
+
             data = { type: relatedData.__model.__name, id: relatedData.id };
           } else {
             data = null;