@stonyx/orm 0.3.2-alpha.75 → 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';
     }
 
@@ -669,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).
 
@@ -679,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
@@ -933,9 +969,11 @@ per-record filter. An input you cannot identify must **deny**.
   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
+  `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.
 
@@ -946,12 +984,29 @@ per-record filter. An input you cannot identify must **deny**.
   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.
+  **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`
@@ -981,10 +1036,15 @@ per-record filter. An input you cannot identify must **deny**.
   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
+  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
@@ -1003,6 +1063,15 @@ per-record filter. An input you cannot identify must **deny**.
   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
@@ -1023,8 +1092,9 @@ per-record filter. An input you cannot identify must **deny**.
   *permitted* related record, which is recorded in the release notes as a
   breaking change.
 
-  **Not yet covered, and each one still publishes ids the surfaces above
-  withhold:**
+  **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**
@@ -1044,6 +1114,26 @@ per-record filter. An input you cannot identify must **deny**.
     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
@@ -1162,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

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

package/dist/orm-request.js

@@ -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
@@ -1266,13 +1276,25 @@ export default class OrmRequest extends Request {
                 // 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.
+                // one, so a fabricated value changes nothing it could observe.
+                // `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.
+                //
+                // GUARDED BY OWN-PROPERTY IDENTITY, NOT BY THE #234 AC13 PIN. That pin
+                // (test/unit/linkage-verdict-test.ts, `strictEqual(seen[0].request,
+                // READ_REQUEST)`) calls `createLinkageFilter` DIRECTLY, so it pins the
+                // function's pass-through and constrains no call site -- an earlier
+                // revision of this comment cited it for this decision and was wrong.
+                // `Object.create(request)` here measured 1015 / 0 with nothing red.
+                // test/integration/orm-test.ts, `#232 AC9`, now asserts that the object
+                // the predicate is handed OWNS `params` (`Object.hasOwn`) and has
+                // nothing request-shaped behind it on the prototype chain. A derived
+                // request inherits `params` -- so it satisfies every value assertion
+                // there -- and reds on those two. Measured: with the derived request in
+                // place, 1014 / 1, and that one is this guard.
                 //
                 // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
                 // `recordId` is `null` here and the request names a record of a
@@ -1297,23 +1319,36 @@ export default class OrmRequest extends Request {
                     data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
                 }
                 else {
-                    // 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.
+                    // belongsTo - return single or null. A DENIED target is `data: null`,
+                    // BYTE-IDENTICAL to a relationship that is genuinely empty, for the
+                    // same reason the hasMany branch above drops rather than errors: this
+                    // route must not be an existence oracle for the RELATED record.
+                    //
+                    // THE OTHER SPELLING WAS 404 AND IT WAS MEASURED AS A DISCLOSURE.
+                    // Unauthenticated, zero query parameters, one request each, on `tag`
+                    // -- the model with no route mounted at all, which is exactly what
+                    // #240 AC5 exists to protect:
+                    //
+                    //     GET /traits/1/tag  [ABSENT]  -> 200  application/json  len 68
+                    //     GET /traits/2/tag  [DENIED]  -> 404  text/plain        len  9
                     //
-                    // 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.
+                    // and `GET /traits/1` and `GET /traits/2` both report
+                    // `relationships.tag = {"data":null}` byte-identical modulo the id,
+                    // because #234 closed THAT oracle deliberately. A 404 here would let
+                    // a caller ask which of those two nulls was a denial. Under
+                    // `data: null` the pair closes completely: 200/200, same
+                    // content-type, same content-length, bodies identical modulo the
+                    // parent id the caller put in the URL. It opens nothing -- `links`
+                    // are entirely parent-derived, there is no `meta` and no counts.
+                    //
+                    // This is also what README.md's module-wide rule already demanded:
+                    // every status on a record route must be identical for filtered-out
+                    // and does-not-exist. The route now CONFORMS to that rule rather than
+                    // carving an exception out of it.
                     if (!isOrmRecord(relatedData))
                         data = null;
                     else if (!isLinkable(relatedData))
-                        return 404;
+                        data = null;
                     else
                         data = relatedData.toJSON?.({ baseUrl, linkage });
                 }
@@ -1331,13 +1366,21 @@ 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.
+                // THE ONE READ SURFACE 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.
+                //
+                // DELIBERATELY NOT STATED AS A COUNT. README.md's Consumer Contracts
+                // section enumerates the surfaces on which the framework resolves a
+                // verdict and hands it to `toJSON()`, and that enumeration GROWS --
+                // abofs/stonyx-orm#235 adds the two write handlers and the `included`
+                // records. This route is not on that list under any count, because it
+                // never calls `toJSON()`: whatever it filters, it filters here. A
+                // number written into this comment would be false the next time that
+                // list changes, and the README already carries the enumeration.
                 //
                 // Same filter, same argument-one decision, same residual as
                 // `/:id/{relationship}` above -- read the block there.
@@ -1356,10 +1399,10 @@ export default class OrmRequest extends Request {
                         .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;
+                    // belongsTo - return single linkage or null. A DENIED target is
+                    // `data: null`, indistinguishable from a genuinely empty one -- see
+                    // the measured oracle in the `/:id/{relationship}` block above.
+                    if (isOrmRecord(relatedData) && relatedData.__model && isLinkable(relatedData)) {
                         data = { type: relatedData.__model.__name, id: relatedData.id };
                     }
                     else {

package/dist/types/orm-types.d.ts

@@ -340,10 +340,36 @@ export interface AccessContext {
      * repaired here. A predicate must not read `undefined` here as "collection",
      * and nothing in this contract makes it safe to read the two keys as one key.
      *
-     * IT NAMES WHICH RECORD, NOT WHICH SURFACE. `GET /owners/gina`,
-     * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` all
-     * carry `recordId: 'gina'`; the related-resource gap is abofs/stonyx-orm#196
-     * and is untouched by this key.
+     * IT NAMES WHICH RECORD OF THE MODEL BEING ASKED ABOUT, NOT WHICH SURFACE,
+     * AND THE ANSWER DEPENDS ON WHICH MODEL IS BEING ASKED ABOUT.
+     *
+     * For the ask about the ROUTE'S OWN model, all three of `GET /owners/gina`,
+     * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` carry
+     * `recordId: 'gina'` -- `auth()` reads it off `request.params`.
+     *
+     * FOR THE ASK ABOUT A RELATED MODEL, IT IS `null`, AND THAT IS A LIMIT ON
+     * WHAT A PREDICATE CAN EXPRESS (abofs/stonyx-orm#232). The two relationship
+     * route families resolve the RELATED model's own predicate -- `animal` on
+     * `GET /owners/gina/pets`, `owner` on `GET /animals/4/owner` -- and that ask
+     * carries `recordId: null` while `request.params` names a record of a
+     * DIFFERENT model. So a predicate answering about a related model gets the
+     * model name, the operation and the request, and CANNOT branch on which
+     * related record it is being asked about.
+     *
+     * The rule, so it is not re-derived wrong: `recordId` may name a record only
+     * where the route addresses exactly one record OF THE MODEL BEING ASKED
+     * ABOUT. A `hasMany` related-resource route returns many records of one type
+     * and the verdict is resolved ONCE PER TYPE, before any record is examined --
+     * seeding it from a record would let the first one decide for all of them.
+     *
+     * What still works, and what does not, is pinned as behaviour by `#232 AC10`
+     * in test/integration/orm-test.ts and stated for consumers in README.md:
+     * model-level denies work, request-level denies work, and the per-record
+     * FILTER shape works because `access()` may return a function and that
+     * function receives the whole record. Branching on identity BEFORE returning
+     * does not.
+     *
+     * `?include=` is a separate surface and is abofs/stonyx-orm#233 / #235.
      */
     recordId: string | number | null;
 }

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.75",
+  "version": "0.3.2-alpha.77",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/orm-request.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
@@ -1385,13 +1395,25 @@ export default class OrmRequest extends Request {
         // 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.
+        // one, so a fabricated value changes nothing it could observe.
+        // `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.
+        //
+        // GUARDED BY OWN-PROPERTY IDENTITY, NOT BY THE #234 AC13 PIN. That pin
+        // (test/unit/linkage-verdict-test.ts, `strictEqual(seen[0].request,
+        // READ_REQUEST)`) calls `createLinkageFilter` DIRECTLY, so it pins the
+        // function's pass-through and constrains no call site -- an earlier
+        // revision of this comment cited it for this decision and was wrong.
+        // `Object.create(request)` here measured 1015 / 0 with nothing red.
+        // test/integration/orm-test.ts, `#232 AC9`, now asserts that the object
+        // the predicate is handed OWNS `params` (`Object.hasOwn`) and has
+        // nothing request-shaped behind it on the prototype chain. A derived
+        // request inherits `params` -- so it satisfies every value assertion
+        // there -- and reds on those two. Measured: with the derived request in
+        // place, 1014 / 1, and that one is this guard.
         //
         // THE RESIDUAL THAT FOLLOWS FROM THAT IS DISCLOSED, NOT PAPERED OVER.
         // `recordId` is `null` here and the request names a record of a
@@ -1418,21 +1440,34 @@ export default class OrmRequest extends Request {
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
           data = related.filter(isLinkable).map(r => r.toJSON?.({ baseUrl, linkage }));
         } else {
-          // 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.
+          // belongsTo - return single or null. A DENIED target is `data: null`,
+          // BYTE-IDENTICAL to a relationship that is genuinely empty, for the
+          // same reason the hasMany branch above drops rather than errors: this
+          // route must not be an existence oracle for the RELATED record.
+          //
+          // THE OTHER SPELLING WAS 404 AND IT WAS MEASURED AS A DISCLOSURE.
+          // Unauthenticated, zero query parameters, one request each, on `tag`
+          // -- the model with no route mounted at all, which is exactly what
+          // #240 AC5 exists to protect:
+          //
+          //     GET /traits/1/tag  [ABSENT]  -> 200  application/json  len 68
+          //     GET /traits/2/tag  [DENIED]  -> 404  text/plain        len  9
           //
-          // 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.
+          // and `GET /traits/1` and `GET /traits/2` both report
+          // `relationships.tag = {"data":null}` byte-identical modulo the id,
+          // because #234 closed THAT oracle deliberately. A 404 here would let
+          // a caller ask which of those two nulls was a denial. Under
+          // `data: null` the pair closes completely: 200/200, same
+          // content-type, same content-length, bodies identical modulo the
+          // parent id the caller put in the URL. It opens nothing -- `links`
+          // are entirely parent-derived, there is no `meta` and no counts.
+          //
+          // This is also what README.md's module-wide rule already demanded:
+          // every status on a record route must be identical for filtered-out
+          // and does-not-exist. The route now CONFORMS to that rule rather than
+          // carving an exception out of it.
           if (!isOrmRecord(relatedData)) data = null;
-          else if (!isLinkable(relatedData)) return 404;
+          else if (!isLinkable(relatedData)) data = null;
           else data = relatedData.toJSON?.({ baseUrl, linkage });
         }
 
@@ -1451,13 +1486,21 @@ 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.
+        // THE ONE READ SURFACE 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.
+        //
+        // DELIBERATELY NOT STATED AS A COUNT. README.md's Consumer Contracts
+        // section enumerates the surfaces on which the framework resolves a
+        // verdict and hands it to `toJSON()`, and that enumeration GROWS --
+        // abofs/stonyx-orm#235 adds the two write handlers and the `included`
+        // records. This route is not on that list under any count, because it
+        // never calls `toJSON()`: whatever it filters, it filters here. A
+        // number written into this comment would be false the next time that
+        // list changes, and the README already carries the enumeration.
         //
         // Same filter, same argument-one decision, same residual as
         // `/:id/{relationship}` above -- read the block there.
@@ -1477,10 +1520,10 @@ export default class OrmRequest extends Request {
             .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;
-
+          // belongsTo - return single linkage or null. A DENIED target is
+          // `data: null`, indistinguishable from a genuinely empty one -- see
+          // the measured oracle in the `/:id/{relationship}` block above.
+          if (isOrmRecord(relatedData) && relatedData.__model && isLinkable(relatedData)) {
             data = { type: relatedData.__model.__name, id: relatedData.id };
           } else {
             data = null;

package/src/types/orm-types.ts

@@ -350,10 +350,36 @@ export interface AccessContext {
    * repaired here. A predicate must not read `undefined` here as "collection",
    * and nothing in this contract makes it safe to read the two keys as one key.
    *
-   * IT NAMES WHICH RECORD, NOT WHICH SURFACE. `GET /owners/gina`,
-   * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` all
-   * carry `recordId: 'gina'`; the related-resource gap is abofs/stonyx-orm#196
-   * and is untouched by this key.
+   * IT NAMES WHICH RECORD OF THE MODEL BEING ASKED ABOUT, NOT WHICH SURFACE,
+   * AND THE ANSWER DEPENDS ON WHICH MODEL IS BEING ASKED ABOUT.
+   *
+   * For the ask about the ROUTE'S OWN model, all three of `GET /owners/gina`,
+   * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` carry
+   * `recordId: 'gina'` -- `auth()` reads it off `request.params`.
+   *
+   * FOR THE ASK ABOUT A RELATED MODEL, IT IS `null`, AND THAT IS A LIMIT ON
+   * WHAT A PREDICATE CAN EXPRESS (abofs/stonyx-orm#232). The two relationship
+   * route families resolve the RELATED model's own predicate -- `animal` on
+   * `GET /owners/gina/pets`, `owner` on `GET /animals/4/owner` -- and that ask
+   * carries `recordId: null` while `request.params` names a record of a
+   * DIFFERENT model. So a predicate answering about a related model gets the
+   * model name, the operation and the request, and CANNOT branch on which
+   * related record it is being asked about.
+   *
+   * The rule, so it is not re-derived wrong: `recordId` may name a record only
+   * where the route addresses exactly one record OF THE MODEL BEING ASKED
+   * ABOUT. A `hasMany` related-resource route returns many records of one type
+   * and the verdict is resolved ONCE PER TYPE, before any record is examined --
+   * seeding it from a record would let the first one decide for all of them.
+   *
+   * What still works, and what does not, is pinned as behaviour by `#232 AC10`
+   * in test/integration/orm-test.ts and stated for consumers in README.md:
+   * model-level denies work, request-level denies work, and the per-record
+   * FILTER shape works because `access()` may return a function and that
+   * function receives the whole record. Branching on identity BEFORE returning
+   * does not.
+   *
+   * `?include=` is a separate surface and is abofs/stonyx-orm#233 / #235.
    */
   recordId: string | number | null;
 }