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

package/README.md

@@ -439,11 +439,22 @@ export default class GlobalAccess {
       // does not remove a rule loudly, it turns a deny into an ALLOW, silently.
       if (recordId === 'archived') return false;
 
-      // Returning a function plugs it in as a per-record filter, and it is
-      // enforced on every surface addressed to one of these records:
+      // Returning a function plugs it in as a per-record filter. It is enforced
+      // on every surface addressed to one of these records —
       //   /owners, /owners/:id, /owners/:id/pets, /owners/:id/relationships/pets
-      // A rejected record is 404 on record routes — the same status as a record
-      // that does not exist — so the filter is not an existence oracle.
+      // — AND, since #232, on every surface that reaches one of these records
+      // as the RELATED resource of another model:
+      //   /animals/:id/owner, /animals/:id/relationships/owner
+      // Both readings are the same rule: an owner this predicate rejects is
+      // withheld wherever she is reachable, not only on /owners.
+      //
+      // NOTHING HERE IS AN EXISTENCE ORACLE, AND THE SPELLING DIFFERS BY WHOSE
+      // RECORD IS BEING REJECTED. A rejected ADDRESSED record is 404 — the same
+      // status as a record that does not exist. A rejected RELATED record is
+      // `data: null` at 200 — byte-identical to a relationship that is
+      // genuinely empty, because on those routes 404 is already the answer for
+      // a PARENT that does not exist. In both cases "rejected" and "not there"
+      // are the same answer, which is the property that matters.
       return record => record.id !== 'angela' && record.id !== 'restricted';
     }
 
@@ -452,7 +463,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'];
@@ -665,9 +680,11 @@ A `throw` inside `access()` is a **denial**, not a 500.
 A function return value is a **per-record predicate**, and it is enforced on
 every endpoint that is addressed to a record — not only on the collection.
 
-It is evaluated against the record the route is *addressed to*, **on that model
-only**. It is not a guarantee that a hidden record cannot be reached or modified:
-a write to a *different* collection can still re-parent one. See
+It is evaluated against the record the route is *addressed to*. On the two
+relationship route families it is **also** evaluated against the **related**
+record, by that record's *own* model's predicate — see the two `{relationship}`
+rows below. It is not a guarantee that a hidden record cannot be reached or
+modified: a write to a *different* collection can still re-parent one. See
 [Known limitations](#known-limitations) and
 [#207](https://github.com/abofs/stonyx-orm/issues/207).
 
@@ -675,19 +692,42 @@ a write to a *different* collection can still re-parent one. See
 |---|---|
 | `GET /:models` | omitted from the collection |
 | `GET /:models/:id` | `404` |
-| `GET /:models/:id/{relationship}` | `404` — the **addressed** record is filtered, not the related one |
-| `GET /:models/:id/relationships/{relationship}` | `404` — same |
+| `GET /:models/:id/{relationship}` | the **addressed** record → `404`. The **related** record → `200` with `data: null` for a `belongsTo`, or dropped from the array for a `hasMany` |
+| `GET /:models/:id/relationships/{relationship}` | same, on the linkage objects |
 | `PATCH /:models/:id` | `404`, no attribute is applied |
 | `DELETE /:models/:id` | `404`, the record is not removed and no SQL `DELETE` is issued |
 | `POST /:models` | `403`, and a record **this request inserted** is rolled back — see [Known limitations](#known-limitations) for why the rollback is conditional |
 
+**A withheld related record is not an error, and that is the same rule.** The
+addressed record is filtered with `404` and the related one with `data: null`
+because in both cases the answer must be **identical to the answer for a record
+that does not exist**. A `belongsTo` whose target is genuinely absent already
+answers `200 {"data": null}`; a `hasMany` with no members already answers `200`
+with an empty array. Withholding therefore has to be spelled the same way, or
+the route becomes an existence oracle for a record on a collection the caller
+may have no access to at all. Measured before this was closed — unauthenticated,
+zero query parameters, one request each:
+
+```
+GET /traits/1/tag   [target absent]  ->  200  application/json  68 bytes
+GET /traits/2/tag   [target denied]  ->  404  text/plain         9 bytes
+```
+
+`tag` is a model with **no route mounted at all**, so those two requests were the
+only way to ask about it — and they answered differently. Both now answer
+`200 {"data": null}`.
+
 **Denied record-level requests return 404, not 403.** This is deliberate and it
 is the property most easily "improved" away. 403 would confirm that the record
 exists to a caller who is not allowed to know that, which turns the filter into
 an existence oracle: `404` means "no such record", `403` means "there is one and
 it is not yours". Every status on a record route must therefore be identical for
 "filtered out" and "does not exist" — including `DELETE`, which is why deleting
-a record that never existed also returns 404 rather than 204.
+a record that never existed also returns 404 rather than 204, and including the
+**related** record on the two relationship families, which is why a denied
+`belongsTo` target is `200 {"data": null}` rather than `404`: on that route
+`404` is the answer for a parent that does not exist, so it is `data: null`, and
+not the status, that carries "no target you may see".
 
 `POST` is the one exception and returns **403**, because 404 on a mounted
 collection route is indistinguishable from "model not mounted" — a genuinely
@@ -921,59 +961,117 @@ 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 **`200` with
+  `data: null`**, byte-identical to a target that is genuinely absent, for the
+  same reason. Nothing on either family errors and no status changes — the
+  status on these routes belongs to the **parent**, and `data` carries the
+  answer about the related record. 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.
+
+  **The `belongsTo` shape is not an existence oracle, and it was measured
+  rather than reasoned about.** An earlier revision of this fix answered `404`
+  for a denied target, which made it distinguishable from a target that is
+  genuinely absent. Unauthenticated, zero query parameters, one request each, on
+  `tag` — a model with **no route mounted at all**:
+
+  ```
+  GET /traits/1/tag   [target absent]  ->  200  application/json  68 bytes
+  GET /traits/2/tag   [target denied]  ->  404  text/plain         9 bytes
+  ```
+
+  `GET /traits/1` and `GET /traits/2` report `relationships.tag = {"data":null}`
+  byte-identical modulo the id, because
+  [#234](https://github.com/abofs/stonyx-orm/issues/234) closed that oracle
+  deliberately — so this route was the one remaining way to ask which of those
+  two nulls was a denial. Under `data: null` both requests answer `200`, same
+  content-type, same content-length, same bytes modulo the parent id the caller
+  put in the URL. It discloses nothing further: `links` on these routes are
+  derived entirely from the parent and the relationship name, there is no `meta`
+  and there are no counts. This also brings the two families back into line with
+  the module-wide rule under [Filter functions](#filter-functions) — *every
+  status on a record route must be identical for "filtered out" and "does not
+  exist"* — which the `404` spelling was an exception to.
+
+  **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`.
+  There are **two** open questions here and they are owned separately —
+  [#233](https://github.com/abofs/stonyx-orm/issues/233), the remaining child of
+  [#196](https://github.com/abofs/stonyx-orm/issues/196), owns whether a
+  resource enters `included` **at all** (membership), and
+  [#235](https://github.com/abofs/stonyx-orm/issues/235) owns the
+  `relationships.*.data` emitted **inside** a record that is already there
+  (linkage). Neither closes the other, and following only #233 will not lead you
+  to the second. Membership — whether the related resource is served at all — 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
-  (`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
+  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`.
 
+  **[#232](https://github.com/abofs/stonyx-orm/issues/232) holds to the same
+  spelling on the routes where that linkage is the *primary* data.** A denied
+  member is dropped from the `hasMany` array and a denied `belongsTo` target is
+  `data: null`, at `200`, `links` intact — so the claim above is true of both
+  `GET /:models/:id/{relationship}` shapes as *routes* and not only as linkage
+  emitted inside somebody else's document. An earlier revision of #232 answered
+  `404` on the `belongsTo` shape and did contradict this paragraph; that is
+  measured and closed in the #232 bullet above.
+
   **That resolves the right class; it does not guarantee a model-correct
   answer, and the failure direction is not the safe one.** Only a predicate that
   *reads* `context.model` can answer about the model it was asked about — see
@@ -994,45 +1092,56 @@ 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 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.**
+  **Not yet covered.** The first two still publish ids the surfaces above
+  withhold; the third is struck through because it **is** covered now, and is
+  kept for the reason given under it:
+
+  - **`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
-    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.** 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.
+    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.
+  - **A computed property can republish a hidden related record's id into
+    `attributes`** — [#245](https://github.com/abofs/stonyx-orm/issues/245).
+    `Record.toJSON()` runs consumer computed properties and writes their return
+    values straight into `attributes` with no verdict applied. A computed
+    property is ordinary consumer code with `this` bound to the record, so it
+    can read any resolved relationship and emit the id this list's surfaces
+    withheld — through a channel that filters `relationships.*.data` and never
+    sees it. The shipped sample's `animal.tag` getter does exactly that. **This
+    is reachable on `dev` once this pull request merges**, because
+    [#240](https://github.com/abofs/stonyx-orm/issues/240) fixture 1 puts a
+    hidden child (animal 18) under a **permitted** parent for the first time.
+  - **The absence of `attributes.<fk>` on a `POST` response proves a hidden
+    record exists** — [#246](https://github.com/abofs/stonyx-orm/issues/246).
+    `createHandler` copies each supplied relationship's raw id into
+    `attributes`; when the related record resolves, the value is consumed and
+    does not appear, and when it does not resolve, it survives. The oracle runs
+    in the negative space, so nothing this list's surfaces withhold is
+    *published* — the **absence** is the signal. Pre-existing, and it does not
+    compose with the two relationship families above: they emit no `attributes`
+    for a related record at all.
+  - ~~**`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
@@ -1126,29 +1235,11 @@ read all of these.
 
 #### `Record.toJSON()` does not filter relationship linkage unless you pass a verdict
 
-**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)`,
+**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)`,
 `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**
@@ -1161,6 +1252,31 @@ default, the default is the unfiltered document, and a filtered relationship is
 byte-identical to a genuinely empty one — so nothing on the wire distinguishes
 "filtered" from "forgotten".
 
+**And `linkage` cannot reach a document you build by hand.** It is an *option to
+`toJSON()`*, so it filters only what goes through `toJSON()`. The ORM's own
+`GET /:models/:id/relationships/{relationship}` route is the worked example: its
+primary data *is* linkage, it assembles `{ type, id }` directly rather than
+serializing a record, and it therefore resolves and applies the verdict itself
+([#232](https://github.com/abofs/stonyx-orm/issues/232)). If you assemble
+linkage the same way anywhere — a custom relationship route, a projection, a
+hand-built document — **passing `linkage` to `toJSON()` does nothing for it and
+nothing warns**. Build the filter and consult it before you emit an id:
+
+```js
+const linkage = createLinkageFilter(request);
+
+if (related && linkage(related.__model.__name, related)) {
+  data = { type: related.__model.__name, id: related.id };
+} else {
+  data = null; // withheld and genuinely-empty must be the SAME answer
+}
+```
+
+The `else` branch is the part that is easy to get wrong. Answering `404`, `403`
+or an `errors` member for the withheld case makes the route an **existence
+oracle** — see [Filter functions](#filter-functions) for the rule and for the
+measurement that closed it on this route.
+
 Do this:
 
 ```js
@@ -1448,15 +1564,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.d.ts

@@ -65,9 +65,19 @@
  * warning below sanctions. This repo's own fixture has such a rule: its
  * `/archived` deny cannot be expressed from the context alone, and a predicate
  * migrated to context-only would silently drop it, turning a deny into an
- * allow. The related-resource and `?include=` surfaces serve ANOTHER model's
- * records under `model: 'owner'`, and the context gives no signal of that
- * (abofs/stonyx-orm#196).
+ * allow.
+ *
+ * THE RELATED-RESOURCE HALF OF THAT SENTENCE IS NOW OUT OF DATE AND IS
+ * CORRECTED HERE RATHER THAN DELETED. Both relationship route families resolve
+ * the RELATED model's own access class and ask it
+ * `{ model: <related>, operation: 'read', recordId: null }`
+ * (abofs/stonyx-orm#232), so those surfaces no longer serve another model's
+ * records under `model: 'owner'` unexamined. What the context still gives no
+ * signal of is WHICH related record is being asked about -- `recordId` is
+ * `null` there and `request.params` names a record of a different model. See
+ * `AccessContext.recordId` in ./types/orm-types.ts for the full statement of
+ * that limit. `?include=` is still unfiltered and is abofs/stonyx-orm#233 /
+ * #235.
  *
  * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237, AND KEPT FOR THE
  * CONSTRAINT IT STATES RATHER THAN AS A DESCRIPTION OF THE CODE. The context