@stonyx/orm 0.3.2-alpha.87 → 0.3.2-alpha.89

package/README.md

@@ -985,10 +985,13 @@ per-record filter. An input you cannot identify must **deny**.
   "indistinguishable" as a property of the response — it is a property of the
   relationship member alone. The other channels in the same class are
   [#245](https://github.com/abofs/stonyx-orm/issues/245) (computed attributes,
-  which is the one measured above),
-  [#233](https://github.com/abofs/stonyx-orm/issues/233) (`included`
-  membership) and [#246](https://github.com/abofs/stonyx-orm/issues/246) (the
-  absence of `attributes.<fk>` on a `POST` response), all open. **Audit your
+  which is the one measured above) and
+  [#246](https://github.com/abofs/stonyx-orm/issues/246) (the
+  `attributes.<fk>` echo of an unresolved `belongsTo` target) — **both still
+  open**. `included` membership was the third,
+  [#233](https://github.com/abofs/stonyx-orm/issues/233), and it is **closed**:
+  a related record its own model's access class rejects is dropped at the
+  traversal's push site and is no longer a member. **Audit your
   computed properties before you treat a dropped member as unobservable.** 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
@@ -1046,24 +1049,35 @@ per-record filter. An input you cannot identify must **deny**.
   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
+- **`?include=` records are filtered on both questions now, and so are the
+  relationship routes.** *Re-specified twice, each time by the story that
+  falsified it, and recorded here rather than deleted. The original said all
+  three surfaces were unfiltered.
+  [#232](https://github.com/abofs/stonyx-orm/issues/232) made two of them
+  filtered and the bullet became "**`?include=` records are still not
+  filtered — the relationship routes now are**", with the body "**`?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`."
+  [#233](https://github.com/abofs/stonyx-orm/issues/233) falsified that half
+  too.* `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
+  class (see the bullet above). **`?include=owner` now resolves it as well**,
+  at the traversal's push site, so a filter on `/owners` *does* hide an owner
+  reached through `?include=` on `/animals`: measured on this branch,
+  `GET /animals/1?include=owner` answers `200` with **no `included` array at
+  all**, where before it served the hidden owner's full document.
+  There were **two** questions here and they were owned separately — #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.
+  (linkage). **Both have now landed, and neither closed the other** — they are
+  still answered by different mechanisms at different sites, and a resource can
+  legitimately be a member while its own linkage is filtered. Membership —
+  whether the related resource is served at all — remains 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
@@ -1117,6 +1131,59 @@ per-record filter. An input you cannot identify must **deny**.
   `404` on the `belongsTo` shape and did contradict this paragraph; that is
   measured and closed in the #232 bullet above.
 
+  **[#233](https://github.com/abofs/stonyx-orm/issues/233) owns whether a
+  related resource appears in `included` at all, and that question is now
+  answered too.** #235 filters what a record *already in* `included` may
+  **name**; #233 decides **membership**. They remain different questions
+  answered by different mechanisms and neither closes the other — a resource
+  can legitimately be a member while its own linkage is filtered. A related
+  resource is judged by **its own** model's access class at the traversal's
+  push site, so a record that class's **per-record filter** rejects is not a
+  member, and **the
+  subtree beneath it is never traversed**: dropping a parent *after* descending
+  through it would publish that parent's exact child set. Measured on
+  `dev @ c106cf9`, `GET /animals/1?include=owner,owner.pets` returned nine
+  resources — the hidden owner plus her eight animals
+  `[1, 3, 7, 10, 11, 15, 17, 20]`, which *is* her `pets` array, reconstructed
+  for a caller who is `404` on the parent. It now returns no `included` array
+  at all. A model **no access class claims** (`getAccess()` → `undefined`) is
+  denied on this path too, so a collection the consumer never exposed is not
+  reachable as a sideloaded resource either. **Drop, never error:** a pruned
+  sideload is byte-identical to a genuinely empty one — same `200`, the same
+  top-level keys, no `included` member on either, no `errors` — so its absence
+  carries no signal about whether the record exists.
+
+  **Read "per-record filter" literally — it is not "everything the
+  record-addressed route refuses", and the difference is measurable.** The
+  linkage ask carries `recordId: null`, so a deny expressed as a
+  request-scoped `return false` cannot fire on this path at all. The shipped
+  sample expresses the `archived` owner's deny that way, and measured
+  unauthenticated on this branch — byte-identically on `dev @ b23cfec`, so this
+  is not a regression this change introduces —
+  `GET /owners/archived` is `403` while `GET /animals/9500?include=owner`
+  answers `200` with her full document. That is
+  [#243](https://github.com/abofs/stonyx-orm/issues/243)'s mechanism, and #243
+  records it on `GET /owners` only; it reaches `included` membership and the
+  `#232` related-resource route the same way. **#233 does not close it, and a
+  consumer who needs `?include=` to honour a per-record deny must express that
+  deny as a filter.**
+
+  **And read "carries no signal" as a property of the `included` member, the
+  same way [Known limitations](#known-limitations) already asks you to read
+  "indistinguishable" — not as a property of the whole response.** The prune is
+  unobservable in `included`; the *rest* of the document is a separate
+  question, and the same computed-and-serialized-attribute channels recorded
+  above still apply to it. Measured counter-example on this very fixture pair:
+  `GET /traits/2?include=tag` prunes the unclaimed `tag` from `included` and
+  still serves `attributes.tag: "never-mounted"`, while `GET /traits/1` has no
+  `tag` key at all — an existence oracle in `attributes`, from
+  `src/serializer.ts` echoing the raw foreign key of a `belongsTo` target that
+  did not resolve. That is
+  [#246](https://github.com/abofs/stonyx-orm/issues/246)'s mechanism reached on
+  a **read**, with [#248](https://github.com/abofs/stonyx-orm/issues/248) as
+  its precondition — **audit your attributes before you treat a pruned
+  sideload as unobservable.**
+
   **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
@@ -1157,14 +1224,6 @@ per-record filter. An input you cannot identify must **deny**.
     [#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
-    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
@@ -1720,20 +1779,41 @@ GET /animals/1
 2. Recursively traverses relationships depth-first
 3. Deduplication still by type+id (no duplicates in included array)
 4. Gracefully handles null/missing relationships at any depth
-5. Each included record gets full `toJSON()` representation
+5. Each related record is judged by **its own** model's access class at the
+   push site before it is added, so a denied record neither enters `included`
+   nor becomes a parent at the next depth
+   ([#233](https://github.com/abofs/stonyx-orm/issues/233)) — see the
+   Limitations below for what "denied" does and does not cover
+6. Each included record gets full `toJSON()` representation, with its
+   **linkage filtered** by the same verdict object the primary document was
+   serialized with ([#235](https://github.com/abofs/stonyx-orm/issues/235))
 
 #### 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
+- **`included` is access-filtered on both of the two questions.** *Re-specified
+  by [#233](https://github.com/abofs/stonyx-orm/issues/233). The sentence this
+  replaces said membership "is still unfiltered (#233): a record that is 404 on
+  its own routes is still served as an `included` resource, attributes and
+  all."* 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).
+  appears in `included` **at all** is *membership*, and #233 filters it: a
+  related resource is judged by **its own** model's access class at the
+  traversal's push site, so a record that class's **per-record filter** rejects
+  is not a member, and the subtree beneath it is never traversed.
+- **Membership is filtered by the per-record filter, not by everything a
+  record-addressed route refuses.** A deny expressed as a request-scoped
+  `return false` — the shape the shipped sample uses for the `archived`
+  owner — is **not** expressible on this path, because the linkage ask carries
+  `recordId: null`. Measured on this branch and byte-identically on `dev`:
+  `GET /owners/archived` is `403` while `GET /animals/9500?include=owner`
+  serves her document in full. That is
+  [#243](https://github.com/abofs/stonyx-orm/issues/243)'s mechanism, not
+  #233's, and it reaches every linkage surface rather than only `GET /owners`.
+  Express a per-record deny as a **filter** if you need `?include=` to honour
+  it. See [Consumer Contracts](#consumer-contracts).
 
 ## Lifecycle Hooks
 

package/dist/orm-request.d.ts

@@ -76,8 +76,18 @@
  * 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.
+ * that limit.
+ *
+ * AND THE `?include=` HALF IS NOW OUT OF DATE TOO, CORRECTED THE SAME WAY. It
+ * read: "`?include=` is still unfiltered and is abofs/stonyx-orm#233 / #235."
+ * Both have landed. #235 filters what a record already in `included` may NAME,
+ * and #233 filters MEMBERSHIP at the traversal's push site -- see
+ * `traverseIncludePath` below. The ask is the same shape as the
+ * related-resource one and carries the same limit: `recordId` is `null`, so a
+ * deny expressible only as a request-scoped `return false` -- which is how the
+ * shipped sample spells `/archived` -- still cannot fire on this path. That
+ * residual is abofs/stonyx-orm#243's, not #233's, and it is measured
+ * byte-identical on `dev`.
  *
  * 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

@@ -76,8 +76,18 @@
  * 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.
+ * that limit.
+ *
+ * AND THE `?include=` HALF IS NOW OUT OF DATE TOO, CORRECTED THE SAME WAY. It
+ * read: "`?include=` is still unfiltered and is abofs/stonyx-orm#233 / #235."
+ * Both have landed. #235 filters what a record already in `included` may NAME,
+ * and #233 filters MEMBERSHIP at the traversal's push site -- see
+ * `traverseIncludePath` below. The ask is the same shape as the
+ * related-resource one and carries the same limit: `recordId` is `null`, so a
+ * deny expressible only as a request-scoped `return false` -- which is how the
+ * shipped sample spells `/archived` -- still cannot fire on this path. That
+ * residual is abofs/stonyx-orm#243's, not #233's, and it is measured
+ * byte-identical on `dev`.
  *
  * 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
@@ -445,17 +455,27 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
     const includes = parseInclude(includeParam);
     if (includes.length === 0)
         return response;
-    const includedRecords = collectIncludedRecords(recordOrRecords, includes);
+    // THE SAME FILTER OBJECT DECIDES MEMBERSHIP AND LINKAGE, AND IT IS PASSED TO
+    // BOTH (abofs/stonyx-orm#233). It carries #234's per-type verdict cache and
+    // per-(type, id) decision cache, so the traversal below and the `toJSON`
+    // calls beneath it share one resolution of the consumer's `access()` per
+    // type for the whole response. Building a second filter here would double
+    // every predicate call and, worse, could answer the two questions
+    // differently about the same record.
+    const includedRecords = collectIncludedRecords(recordOrRecords, includes, linkage);
     if (includedRecords.length > 0) {
         // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
         // line is one story's and the line above it is another's
         // (abofs/stonyx-orm#235 and #233 respectively).
         //
         //   - WHICH RESOURCES REACH THIS ARRAY is decided by
-        //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
-        //     #233's, and it is deliberately untouched here: a hidden owner is
-        //     still a member of `included` after this change. Pinned green by
-        //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
+        //     `collectIncludedRecords` on the line above. That is MEMBERSHIP and
+        //     it is #233's. As of #233 that call is given the SAME `linkage`
+        //     filter, so a hidden owner is no longer a member: she is dropped at
+        //     the push site and her subtree is never traversed. Pinned by
+        //     `[DEFECT] #233 AC2` and `[DEFECT] #233 AC4`; the re-specification of
+        //     `[GUARD] #235 X1`, which pinned the PRE-#233 answer here, is in that
+        //     same test.
         //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
         //     `relationships.*.data` is LINKAGE -- the same question #234 answers
         //     for the primary document -- and that is what the `linkage` option
@@ -498,9 +518,45 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
     return response;
 }
 /**
- * Recursively traverse an include path and collect related records
+ * Recursively traverse an include path and collect related records.
+ *
+ * ---------------------------------------------------------------------------
+ * THE `linkage` FILTER DECIDES MEMBERSHIP HERE (abofs/stonyx-orm#233)
+ * ---------------------------------------------------------------------------
+ * A resource reaches `included` because some record NAMED it, and until #233
+ * being named was the whole test. That made `?include=` a restoration of every
+ * record the read surfaces withhold: `GET /owners/angela` is 404 and
+ * `GET /animals/1?include=owner` returned her document in full, attributes and
+ * all. Measured on dev @ 8dda5d6, over the live router.
+ *
+ * FILTERED AT THE PUSH SITE, AND THE SITE MATTERS. The obvious alternative --
+ * let the traversal run and filter `collectIncludedRecords`' RETURN value --
+ * closes the membership half and leaves the worse half open: dropping a parent
+ * AFTER traversing through it publishes that parent's exact child set. On this
+ * repo's own fixture `GET /animals/1?include=owner,owner.pets` names angela's
+ * eight animals `[1, 3, 7, 10, 11, 15, 17, 20]`, which IS her `pets` array,
+ * reconstructed from a resource the caller may not read. So a denied record is
+ * `continue`d before it is pushed to `included` AND before it is pushed to
+ * `nextRecords`, which is what prunes the subtree.
+ *
+ * A DENIED RECORD IS DELIBERATELY NOT ADDED TO `seen`. `seen` is the
+ * deduplicator for records that DID enter `included`; putting a denial in it
+ * would conflate "already emitted" with "withheld", and the `else if` branch
+ * below would then push a denied record into `nextRecords` for deeper
+ * traversal -- re-opening the prune this function just closed. Re-asking is
+ * free: #234's filter caches per `(type, id)`, so the second ask is a `Map`
+ * hit and not a call into the consumer's `access()`.
+ *
+ * ABSENT FILTER MEANS PRE-#233 BEHAVIOUR, NOT A DENIAL. `linkage` is optional
+ * for the same reason it is optional on `buildResponse` and on
+ * `Record.toJSON`: an absent option means "no verdict was supplied", and the
+ * honest degradation is the document that shipped before, not an empty one.
+ * Both of `buildResponse`'s callers -- `getCollectionHandler` and
+ * `getSingleHandler`, the only two -- supply it, which is pinned by
+ * `[GUARD] #233 AC8`. What must never arrive here is a non-function; the
+ * guard below is the fail-closed reading of one.
  */
-function traverseIncludePath(currentRecords, includePath, depth, seen, included) {
+function traverseIncludePath(currentRecords, includePath, depth, seen, included, linkage) {
     if (depth >= includePath.length)
         return; // Reached end of path
     const relationshipName = includePath[depth];
@@ -524,6 +580,19 @@ function traverseIncludePath(currentRecords, includePath, depth, seen, included)
                 continue;
             const type = relatedRecord.__model.__name;
             const id = relatedRecord.id;
+            // MEMBERSHIP AND PRUNE, abofs/stonyx-orm#233. `continue` skips BOTH
+            // pushes below -- the record does not enter `included` and it does not
+            // become a parent at the next depth.
+            //
+            // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED, the same reading
+            // #232's `isLinkable` uses on the relationship routes: `type` is the key
+            // the verdict is resolved under, so a missing or empty one means there
+            // is no predicate to ask and no way to ask it. Denying is the only safe
+            // answer, and it is only reachable while a filter is in force -- with no
+            // filter this whole check is skipped and the pre-#233 document is
+            // emitted unchanged.
+            if (linkage && !(typeof type === 'string' && type !== '' && linkage(type, relatedRecord)))
+                continue;
             // Initialize Set for this type if needed
             let seenIds = seen.get(type);
             if (!seenIds) {
@@ -544,10 +613,10 @@ function traverseIncludePath(currentRecords, includePath, depth, seen, included)
     }
     // If there are more segments in the path, recursively process
     if (depth < includePath.length - 1 && nextRecords.length > 0) {
-        traverseIncludePath(nextRecords, includePath, depth + 1, seen, included);
+        traverseIncludePath(nextRecords, includePath, depth + 1, seen, included, linkage);
     }
 }
-function collectIncludedRecords(data, includes) {
+function collectIncludedRecords(data, includes, linkage) {
     if (!includes || includes.length === 0)
         return [];
     if (!data)
@@ -558,7 +627,7 @@ function collectIncludedRecords(data, includes) {
     const records = Array.isArray(data) ? data : [data];
     // Process each include path
     for (const includePath of includes) {
-        traverseIncludePath(records, includePath, 0, seen, included);
+        traverseIncludePath(records, includePath, 0, seen, included, linkage);
     }
     return included;
 }
@@ -699,11 +768,17 @@ export default class OrmRequest extends Request {
             // is the SAME object the primary document is serialized with -- one
             // verdict per type for the whole response, sideload included.
             //
-            // The boundary that remains, so the next reader does not have to derive
-            // it: this closes what a record already in `included` may NAME. WHETHER a
+            // The boundary, so the next reader does not have to derive it: this
+            // closes what a record already in `included` may NAME. WHETHER a
             // resource appears in `included` at all is MEMBERSHIP and it is
-            // abofs/stonyx-orm#233's -- a hidden owner is still a member here.
-            // Neither question closes the other.
+            // abofs/stonyx-orm#233's. THAT IS NOW CLOSED TOO, and the same `linkage`
+            // object closes it: `buildResponse` hands this filter to
+            // `collectIncludedRecords`, which denies at the push site. Corrected
+            // rather than deleted -- this comment read "a hidden owner is still a
+            // member here", which is the sentence the identical copy in
+            // `buildResponse` carried and which #233 falsified in both places. They
+            // are still two questions and neither closes the other: a record can be
+            // a member while its own linkage is filtered.
             return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
                 links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
                 baseUrl,

package/package.json

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

package/src/orm-request.ts

@@ -76,8 +76,18 @@
  * 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.
+ * that limit.
+ *
+ * AND THE `?include=` HALF IS NOW OUT OF DATE TOO, CORRECTED THE SAME WAY. It
+ * read: "`?include=` is still unfiltered and is abofs/stonyx-orm#233 / #235."
+ * Both have landed. #235 filters what a record already in `included` may NAME,
+ * and #233 filters MEMBERSHIP at the traversal's push site -- see
+ * `traverseIncludePath` below. The ask is the same shape as the
+ * related-resource one and carries the same limit: `recordId` is `null`, so a
+ * deny expressible only as a request-scoped `return false` -- which is how the
+ * shipped sample spells `/archived` -- still cannot fire on this path. That
+ * residual is abofs/stonyx-orm#243's, not #233's, and it is measured
+ * byte-identical on `dev`.
  *
  * 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
@@ -490,17 +500,27 @@ function buildResponse(
   const includes = parseInclude(includeParam);
   if (includes.length === 0) return response;
 
-  const includedRecords = collectIncludedRecords(recordOrRecords, includes);
+  // THE SAME FILTER OBJECT DECIDES MEMBERSHIP AND LINKAGE, AND IT IS PASSED TO
+  // BOTH (abofs/stonyx-orm#233). It carries #234's per-type verdict cache and
+  // per-(type, id) decision cache, so the traversal below and the `toJSON`
+  // calls beneath it share one resolution of the consumer's `access()` per
+  // type for the whole response. Building a second filter here would double
+  // every predicate call and, worse, could answer the two questions
+  // differently about the same record.
+  const includedRecords = collectIncludedRecords(recordOrRecords, includes, linkage);
   if (includedRecords.length > 0) {
     // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
     // line is one story's and the line above it is another's
     // (abofs/stonyx-orm#235 and #233 respectively).
     //
     //   - WHICH RESOURCES REACH THIS ARRAY is decided by
-    //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
-    //     #233's, and it is deliberately untouched here: a hidden owner is
-    //     still a member of `included` after this change. Pinned green by
-    //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
+    //     `collectIncludedRecords` on the line above. That is MEMBERSHIP and
+    //     it is #233's. As of #233 that call is given the SAME `linkage`
+    //     filter, so a hidden owner is no longer a member: she is dropped at
+    //     the push site and her subtree is never traversed. Pinned by
+    //     `[DEFECT] #233 AC2` and `[DEFECT] #233 AC4`; the re-specification of
+    //     `[GUARD] #235 X1`, which pinned the PRE-#233 answer here, is in that
+    //     same test.
     //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
     //     `relationships.*.data` is LINKAGE -- the same question #234 answers
     //     for the primary document -- and that is what the `linkage` option
@@ -545,14 +565,51 @@ function buildResponse(
 }
 
 /**
- * Recursively traverse an include path and collect related records
+ * Recursively traverse an include path and collect related records.
+ *
+ * ---------------------------------------------------------------------------
+ * THE `linkage` FILTER DECIDES MEMBERSHIP HERE (abofs/stonyx-orm#233)
+ * ---------------------------------------------------------------------------
+ * A resource reaches `included` because some record NAMED it, and until #233
+ * being named was the whole test. That made `?include=` a restoration of every
+ * record the read surfaces withhold: `GET /owners/angela` is 404 and
+ * `GET /animals/1?include=owner` returned her document in full, attributes and
+ * all. Measured on dev @ 8dda5d6, over the live router.
+ *
+ * FILTERED AT THE PUSH SITE, AND THE SITE MATTERS. The obvious alternative --
+ * let the traversal run and filter `collectIncludedRecords`' RETURN value --
+ * closes the membership half and leaves the worse half open: dropping a parent
+ * AFTER traversing through it publishes that parent's exact child set. On this
+ * repo's own fixture `GET /animals/1?include=owner,owner.pets` names angela's
+ * eight animals `[1, 3, 7, 10, 11, 15, 17, 20]`, which IS her `pets` array,
+ * reconstructed from a resource the caller may not read. So a denied record is
+ * `continue`d before it is pushed to `included` AND before it is pushed to
+ * `nextRecords`, which is what prunes the subtree.
+ *
+ * A DENIED RECORD IS DELIBERATELY NOT ADDED TO `seen`. `seen` is the
+ * deduplicator for records that DID enter `included`; putting a denial in it
+ * would conflate "already emitted" with "withheld", and the `else if` branch
+ * below would then push a denied record into `nextRecords` for deeper
+ * traversal -- re-opening the prune this function just closed. Re-asking is
+ * free: #234's filter caches per `(type, id)`, so the second ask is a `Map`
+ * hit and not a call into the consumer's `access()`.
+ *
+ * ABSENT FILTER MEANS PRE-#233 BEHAVIOUR, NOT A DENIAL. `linkage` is optional
+ * for the same reason it is optional on `buildResponse` and on
+ * `Record.toJSON`: an absent option means "no verdict was supplied", and the
+ * honest degradation is the document that shipped before, not an empty one.
+ * Both of `buildResponse`'s callers -- `getCollectionHandler` and
+ * `getSingleHandler`, the only two -- supply it, which is pinned by
+ * `[GUARD] #233 AC8`. What must never arrive here is a non-function; the
+ * guard below is the fail-closed reading of one.
  */
 function traverseIncludePath(
   currentRecords: OrmRecord[],
   includePath: string[],
   depth: number,
   seen: Map<string, Set<string | number>>,
-  included: OrmRecord[]
+  included: OrmRecord[],
+  linkage?: LinkageFilter
 ): void {
   if (depth >= includePath.length) return; // Reached end of path
 
@@ -578,6 +635,19 @@ function traverseIncludePath(
       const type = relatedRecord.__model.__name;
       const id = relatedRecord.id as string | number;
 
+      // MEMBERSHIP AND PRUNE, abofs/stonyx-orm#233. `continue` skips BOTH
+      // pushes below -- the record does not enter `included` and it does not
+      // become a parent at the next depth.
+      //
+      // FAIL CLOSED ON A RECORD WHOSE TYPE CANNOT BE NAMED, the same reading
+      // #232's `isLinkable` uses on the relationship routes: `type` is the key
+      // the verdict is resolved under, so a missing or empty one means there
+      // is no predicate to ask and no way to ask it. Denying is the only safe
+      // answer, and it is only reachable while a filter is in force -- with no
+      // filter this whole check is skipped and the pre-#233 document is
+      // emitted unchanged.
+      if (linkage && !(typeof type === 'string' && type !== '' && linkage(type, relatedRecord))) continue;
+
       // Initialize Set for this type if needed
       let seenIds = seen.get(type);
       if (!seenIds) {
@@ -599,11 +669,15 @@ function traverseIncludePath(
 
   // If there are more segments in the path, recursively process
   if (depth < includePath.length - 1 && nextRecords.length > 0) {
-    traverseIncludePath(nextRecords, includePath, depth + 1, seen, included);
+    traverseIncludePath(nextRecords, includePath, depth + 1, seen, included, linkage);
   }
 }
 
-function collectIncludedRecords(data: OrmRecord | OrmRecord[], includes: string[][]): OrmRecord[] {
+function collectIncludedRecords(
+  data: OrmRecord | OrmRecord[],
+  includes: string[][],
+  linkage?: LinkageFilter
+): OrmRecord[] {
   if (!includes || includes.length === 0) return [];
   if (!data) return [];
 
@@ -615,7 +689,7 @@ function collectIncludedRecords(data: OrmRecord | OrmRecord[], includes: string[
 
   // Process each include path
   for (const includePath of includes) {
-    traverseIncludePath(records, includePath, 0, seen, included);
+    traverseIncludePath(records, includePath, 0, seen, included, linkage);
   }
 
   return included;
@@ -775,11 +849,17 @@ export default class OrmRequest extends Request {
       // is the SAME object the primary document is serialized with -- one
       // verdict per type for the whole response, sideload included.
       //
-      // The boundary that remains, so the next reader does not have to derive
-      // it: this closes what a record already in `included` may NAME. WHETHER a
+      // The boundary, so the next reader does not have to derive it: this
+      // closes what a record already in `included` may NAME. WHETHER a
       // resource appears in `included` at all is MEMBERSHIP and it is
-      // abofs/stonyx-orm#233's -- a hidden owner is still a member here.
-      // Neither question closes the other.
+      // abofs/stonyx-orm#233's. THAT IS NOW CLOSED TOO, and the same `linkage`
+      // object closes it: `buildResponse` hands this filter to
+      // `collectIncludedRecords`, which denies at the push site. Corrected
+      // rather than deleted -- this comment read "a hidden owner is still a
+      // member here", which is the sentence the identical copy in
+      // `buildResponse` carried and which #233 falsified in both places. They
+      // are still two questions and neither closes the other: a record can be
+      // a member while its own linkage is filtered.
       return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
         baseUrl,