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

package/README.md

@@ -439,22 +439,11 @@ 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. It is enforced
-      // on every surface addressed to one of these records —
+      // Returning a function plugs it in as a per-record filter, and it is
+      // enforced on every surface addressed to one of these records:
       //   /owners, /owners/:id, /owners/:id/pets, /owners/:id/relationships/pets
-      // — 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.
+      // 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.
       return record => record.id !== 'angela' && record.id !== 'restricted';
     }
 
@@ -463,11 +452,7 @@ 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.
-    // `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;
+    if (model === 'animal') return record => record.owner?.id !== 'restricted';
 
     // Allows full access to all calls that don't match any of the above conditions
     return ['read', 'create', 'update', 'delete'];
@@ -680,11 +665,9 @@ 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 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
+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
 [Known limitations](#known-limitations) and
 [#207](https://github.com/abofs/stonyx-orm/issues/207).
 
@@ -692,42 +675,19 @@ modified: 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}` | 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 |
+| `GET /:models/:id/{relationship}` | `404` — the **addressed** record is filtered, not the related one |
+| `GET /:models/:id/relationships/{relationship}` | `404` — same |
 | `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, 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".
+a record that never existed also returns 404 rather than 204.
 
 `POST` is the one exception and returns **403**, because 404 on a mounted
 collection route is indistinguishable from "model not mounted" — a genuinely
@@ -961,117 +921,59 @@ 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).
-- **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
+- **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
   ([#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`.
 
-  **[#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
@@ -1092,56 +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.** 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,
+  **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.
-  - **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).
+    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
@@ -1235,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**
@@ -1252,31 +1166,6 @@ 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
@@ -1564,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.d.ts

@@ -65,19 +65,9 @@
  * 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 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.
+ * 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).
  *
  * 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