@stonyx/orm 0.3.2-beta.157 → 0.3.2-beta.158

package/README.md

@@ -927,7 +927,97 @@ per-record filter. An input you cannot identify must **deny**.
   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.
+  `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 the four request-bound read surfaces,
+  and only there.** A document's `relationships.*.data` used to publish the id
+  of every related record unconditionally, so a record hidden on every one of
+  its own surfaces was still named inside another model's document — with no
+  `include=`, no relationship route and no query string
+  ([#234](https://github.com/abofs/stonyx-orm/issues/234)). The ORM now resolves
+  the **related** model's own access class on `GET /:models`, `GET /:models/:id`
+  and both `GET /:models/:id/{relationship}` shapes, and asks it
+  `{ model: <related>, operation: 'read' }`. An unresolvable class
+  (`getAccess()` → `undefined`) and a predicate that throws both **deny**. A
+  filtered-out relationship is **indistinguishable from a genuinely empty one** —
+  an emptied `hasMany` is `data: []` and an emptied `belongsTo` is `data: null`,
+  both **keeping their `links`**, which are built from the serialized record's
+  own id and never from the related one. Nothing errors and no status changes,
+  because throwing here would be an existence oracle *and* would throw out of
+  the enclosing `JSON.stringify`.
+
+  **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
+  [Passing the context makes a model-correct answer *possible*](#passing-the-context-makes-a-model-correct-answer-possible)
+  above. A **single-argument predicate remains the default in every consumer
+  tree**, it identifies its collection from the request, and asked about
+  `owner` on a request dispatched to `/animals` it answers about **animals**.
+  Measured against this repo's own fixture with an arity-1 predicate registered
+  for `owner`: `GET /owners` correctly returns `["gina","michael","bob"]` while
+  `GET /animals/1` returns `owner.data {"type":"owner","id":"angela"}` — the
+  #234 defect, on the #234 surface, after the #234 fix. This is not a
+  regression (the id was published unconditionally before), it cannot be fixed
+  from this side, and the signal that surfaces such a predicate is
+  [#221](https://github.com/abofs/stonyx-orm/issues/221) /
+  [#213](https://github.com/abofs/stonyx-orm/issues/213). **Migrate your
+  predicates to read the context before relying on this filter.** A migrated,
+  context-reading predicate degrades the other way — it can over-deny a
+  *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:**
+
+  - **`included`** — [#235](https://github.com/abofs/stonyx-orm/issues/235). A
+    permitted record sideloaded by `?include=` emits its **own**
+    `relationships.*.data` unfiltered, so `GET /animals/1?include=owner,owner.pets`
+    returns `owner.data: null` on the primary document and then names angela in
+    `included`, along with eight permitted animals that each name
+    `{"type":"owner","id":"angela"}`. Separately,
+    [#233](https://github.com/abofs/stonyx-orm/issues/233) owns whether a
+    resource appears in `included` **at all** — that is membership, a different
+    question, and following it will not lead you to this residual.
+  - **The `POST`/`PATCH` response documents** —
+    [#235](https://github.com/abofs/stonyx-orm/issues/235). `createHandler` and
+    `updateHandler` destructure the request rather than binding it, so wiring
+    them needs a signature change rather than an argument. Until then **one HTTP
+    verb defeats the filter on the same record**: measured, `GET /animals/1`
+    returns `owner.data: null` and `PATCH /animals/1` returns **200 naming
+    angela**, seconds apart, with no query string and no relationship route. Any
+    caller who can read a record can also write it and be handed the id the read
+    withheld.
+  - **`GET /:models/:id/relationships/{relationship}`**, whose *primary data* is
+    linkage, so filtering it is a **membership** decision —
+    [#232](https://github.com/abofs/stonyx-orm/issues/232), the filed child of
+    [#196](https://github.com/abofs/stonyx-orm/issues/196).
+- **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
+  one — the sample in this README does, for its sub-path rule — so a filter
+  resolved inside `toJSON()` denies *permitted* records rather than hidden ones
+  (measured: 967 → 964, all three failures over-denials). `toJSON` is also the
+  `JSON.stringify` hook, so `JSON.stringify(record)`, `res.json(record)` and
+  `console.log(JSON.stringify(record))` reach it with a **string** in the
+  options slot and have no syntactic place to pass a verdict. The no-argument
+  call therefore returns the pre-#234 document unchanged. Fail-closed by default
+  is not available either: `Orm.instance.accessFunctions` is `{}` in any process
+  that never ran `setup-rest-server` — a CLI, an SQL-only process, a test — so
+  it would empty every relationship on every document in processes with no REST
+  surface to protect. Closing the residual means moving JSON:API serialization
+  **off** the `toJSON` name, tracked as
+  [#230](https://github.com/abofs/stonyx-orm/issues/230). If you hand a `Record`
+  to an untrusted consumer, serialize it through the REST layer, or resolve a
+  verdict with the **exported** `createLinkageFilter(request)` and pass it as
+  the `linkage` option — do not write your own reading of `access()`. This is a
+  consumer obligation with no signal when it lapses; it is stated once, in full,
+  under [Consumer Contracts](#consumer-contracts) below.
+- **`format()` and `serialize()` are deliberately not filtered, and must stay
+  that way.** `format()` is the **persistence** path — its output is what
+  `Orm.db.save()` writes to disk — so applying an access filter there would
+  write a truncated database. That is **data loss**, not disclosure prevention.
+  Neither method appears anywhere in the REST response path.
 - **A before-hook that returns a value short-circuits the request.** On write
   operations addressed to a record the filter is consulted first, so a hook
   cannot answer for a record the caller may not see. On reads it is not, so a
@@ -986,6 +1076,110 @@ per-record filter. An input you cannot identify must **deny**.
   back, and without the guard a denied `403` would delete a record the request
   did not create.
 
+### Consumer Contracts
+
+Obligations this package **cannot enforce**, where nothing fails, warns or
+changes shape when a consumer omits them. One place, findable, per
+`quality.md` rule 2 — if you are relying on `@stonyx/orm` for access control,
+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)`,
+`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**
+([#234](https://github.com/abofs/stonyx-orm/issues/234)). That default is
+deliberate and cannot be inverted; the reasons are in
+[Known limitations](#known-limitations) above.
+
+**There is no signal when you omit it.** `linkage` is optional, absent is the
+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".
+
+Do this:
+
+```js
+import { createLinkageFilter } from '@stonyx/orm';
+
+// `request` is the live request the caller was authorised against. The verdict
+// is REQUEST-SCOPED: build one per request and never cache it across requests,
+// or a second caller is answered with the first caller's authorization.
+const linkage = createLinkageFilter(request);
+
+res.json({ data: record.toJSON({ baseUrl, linkage }) });
+```
+
+Not this:
+
+```js
+// A second, unreviewed reading of access(). It will drift from the one in
+// src/access-verdict.ts, and it will drift in consumer code where no reviewer
+// of this repository will ever see it.
+const linkage = (type, r) => Orm.instance.getAccess(type)?.(request)?.(r) ?? true;
+```
+
+**`createLinkageFilter` requires a live request, and there is no safe call
+without one.** `request` is the only authorization input the filter has — it is
+handed straight to your `access()` predicates, and a predicate that does not
+*read* it cannot fail closed when it is missing. Passing `undefined`, `null` or
+any non-object therefore denies **all** linkage and logs, once, at construction.
+Measured before that guard existed, `createLinkageFilter(undefined)` granted
+four of the five models in this repository's own fixture, silently.
+
+**This is the catch for the request-less contexts named above.** In a queue
+consumer or a websocket handler there is no live request, so there is nothing to
+authorize against and nothing this package can resolve for you. Either carry the
+originating request through to the point of serialization, or publish no linkage
+at all — `record.toJSON({ linkage: () => false })` emits the document with every
+relationship empty. A stand-in is **not** a substitute: `{}` is an object
+and passes the guard, and any predicate that ignores its request will grant.
+
+**`linkage` itself is validated, and an unusable value DENIES.** `undefined`
+means "no verdict supplied" and emits today's document. Anything else must be a
+**synchronous function that answers with a boolean**. Each of the following
+drops **all** linkage on that document and logs once:
+
+- **A non-function** — `null`, `0`, `false`, `''`, `true`, a string, an object.
+  `null` is the natural return of a resolver that could not resolve a session:
+  it used to be read as "absent" and emit the full document silently.
+- **An `async` function, a generator function, or any predicate that returns a
+  promise or thenable.** `toJSON` is the `JSON.stringify` hook and cannot await
+  a verdict, and **an `async` resolver returns a promise, a promise is
+  truthy**, so every related id was published, silently, exactly as if this fix
+  were not here. If your
+  authorization lookup is asynchronous, `await` it *before* you serialize and
+  close over the result.
+- **Any answer that is not a boolean** — `{}`, `'no'`, `1`, `undefined`. A
+  non-boolean is a resolver that did not answer, and a truthy one granted.
+- **A predicate that throws**, including a `class` passed by mistake. It is
+  caught and denied; it used to escape the enclosing `JSON.stringify` and take
+  the rest of that serialization down with it.
+
+#### A predicate that ignores `context.model` makes cross-model resolution GRANT
+
+The linkage filter above asks the **related** model's access class the
+model-correct question, but only a predicate that *reads*
+[`context.model`](#the-access-context-second-argument) can give a model-correct
+answer. A single-argument predicate identifies its collection from the request
+and therefore answers about the collection the request was *addressed to* —
+which is the direction that **grants**. Measured, and worked through in
+[Known limitations](#known-limitations). There is no boot-time warning yet
+([#221](https://github.com/abofs/stonyx-orm/issues/221)). **Migrate your
+predicates to the two-argument contract.**
+
+#### `format()` and `serialize()` are never filtered, by design
+
+They are the persistence path. Do not hand their output to an untrusted
+consumer, and do not add a filter to them — `Orm.db.save()` writes `format()`
+output to disk, so filtering there is data loss rather than disclosure
+prevention.
+
 ### Breaking changes
 
 These land in the next published build. There is no changelog or release-notes channel yet
@@ -1195,6 +1389,13 @@ 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).
 
 ## Lifecycle Hooks
 

package/dist/access-verdict.d.ts

@@ -0,0 +1,85 @@
+import type { AccessMethod, AccessOperation, LinkageFilter } from './types/orm-types.js';
+/**
+ * The classified reading of one `access()` return value.
+ *
+ * `granted: false` is a total denial. `granted: true` with no `filter` is an
+ * unconditional grant. `granted: true` WITH a filter means "grant, subject to
+ * this per-record predicate" -- the function return shape, which is the
+ * per-record hook `AccessContext` deliberately does not provide.
+ */
+export interface AccessVerdict {
+    granted: boolean;
+    filter?: (record: unknown) => boolean;
+}
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export declare function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict;
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite. `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay DISTINCT, where `` `${type}:${id}` `` --
+ * or a bare `String(id)` -- collapses them onto one entry and answers the second
+ * record with the first record's verdict.
+ *
+ * WHAT THAT DOES AND DOES NOT PROTECT. It cannot cross MODELS. `decisions` is
+ * already partitioned per type by `byType`, so a composite key inside a per-type
+ * map is one-to-one with the raw one and no owner's verdict could ever answer
+ * for an animal -- the claim that once stood here. The real exposure is narrower
+ * and entirely WITHIN one model: two records of the same type whose ids differ
+ * only by JavaScript type, which a per-record predicate may legitimately answer
+ * differently about (an id read off a JSON body is a string; the same id
+ * assigned by the server is a number). Pinned by unit assertion, because this
+ * fixture cannot produce the collision on its own -- `owner` ids are strings and
+ * `animal` ids are numbers.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ *
+ * A REQUEST IS REQUIRED, AND ITS ABSENCE IS CHECKED HERE RATHER THAN DELEGATED.
+ * This function is EXPORTED (src/index.ts), and the README's Consumer Contracts
+ * section points consumers at exactly the contexts that have no live request --
+ * a queue payload, a websocket frame, a custom route. Without one there is no
+ * caller to authorise against, and this file's header already says so: the
+ * shipped sample reads `request.path` and fail-closes when it is absent, so
+ * `getAccess('owner')(undefined, ...)` is `false`, while
+ * `getAccess('animal')(undefined, ...)` returns a per-record predicate and
+ * GRANTS. Measured on this repo's own fixture before this guard existed:
+ *
+ *   createLinkageFilter(undefined | null | {} | 'x' | 0)
+ *     -> owner=false animal=TRUE trait=TRUE category=TRUE phone-number=TRUE
+ *
+ * Four of five claimed models granted, with no log, because whether an absent
+ * request fails closed was left ENTIRELY to consumer predicates -- and a
+ * predicate that ignores its request cannot fail closed on one that is missing.
+ * A nullish or primitive `request` therefore denies every model outright and
+ * says so once, at construction, so the signal exists even for a caller that
+ * goes on to serialize nothing.
+ *
+ * WHAT THIS CANNOT CHECK: `{}` is an object and passes. There is no request
+ * contract this module owns -- `auth()` reads `.method`, the shipped sample
+ * reads `.path`, a consumer's reads whatever it likes -- so anything past
+ * "is it an object" would be this module inventing a shape for someone else's
+ * framework. The residual is documented in the README under Consumer Contracts.
+ */
+export declare function createLinkageFilter(request: unknown): LinkageFilter;

package/dist/access-verdict.js

@@ -0,0 +1,284 @@
+/**
+ * The shared access-verdict primitive (abofs/stonyx-orm#234).
+ *
+ * ---------------------------------------------------------------------------
+ * WHY THIS FILE EXISTS: ONE INTERPRETER, NOT TWO
+ * ---------------------------------------------------------------------------
+ * A consumer `access()` may return six differently-shaped things -- `false`, a
+ * bare permission string, a permission array, `true`, a per-record function, or
+ * something the contract does not define at all -- and the reading of each one
+ * is a security decision. `auth()` has held that reading inline since #190.
+ * Every surface that needs to ask "may this caller see model X's record?" needs
+ * the SAME reading, or the second copy becomes an unreviewed second
+ * authorization vocabulary that answers differently about the same value.
+ *
+ * So `interpretAccess` is extracted here and `auth()` now calls it. It is the
+ * only place a return shape is classified, and abofs/stonyx-orm#232 and #233
+ * rebase onto it rather than re-deriving it.
+ *
+ * ---------------------------------------------------------------------------
+ * WHAT A LINKAGE FILTER IS, AND WHY THE CALLER BUILDS IT
+ * ---------------------------------------------------------------------------
+ * `Record.toJSON()` APPLIES a verdict; it never RESOLVES one. That is not a
+ * style choice, it is forced, and it was measured before it was decided:
+ *
+ *   INPUT: origin/dev @ c5f7907, unpatched                  -> 967 pass / 0 fail
+ *   INPUT: same + fail-closed resolution INSIDE toJSON()    -> 964 pass / 3 fail
+ *
+ * and all three reds were over-denial of PERMITTED records, not the leak. Two
+ * independent reasons:
+ *
+ *   1. `toJSON()` has no request. The shipped, documented sample reads
+ *      `request.path` for its `/archived` sub-path rule -- the one read of
+ *      argument one the README sanctions -- and fail-closes when it is absent.
+ *      Measured against the live registry:
+ *
+ *        getAccess('owner')(undefined, { model:'owner',  operation:'read' }) -> false
+ *        getAccess('animal')(undefined,{ model:'animal', operation:'read' }) -> [Function]
+ *
+ *      Same predicate object, two models, two different degradation modes,
+ *      chosen by the consumer. Without a request there is no trustworthy
+ *      answer to get.
+ *
+ *   2. `toJSON` is also the `JSON.stringify` hook, so `JSON.stringify({data:
+ *      record})` calls `record.toJSON('data')` -- a STRING in the options slot.
+ *      An implicit caller has no syntactic place to pass anything
+ *      (abofs/stonyx-orm#230). The no-argument document must therefore stay
+ *      byte-identical to what shipped, which also rules out fail-closed by
+ *      default: `Orm.instance.accessFunctions` is `{}` in any process that
+ *      never ran `setup-rest-server` (CLI, SQL-only, unit tests), so a
+ *      fail-closed default would empty every relationship on every document in
+ *      processes that have no REST surface to protect.
+ *
+ * The caller -- which still holds the request -- resolves the predicate,
+ * interprets it here, caches the answer, and hands `toJSON()` an already-decided
+ * `(type, record) => boolean`.
+ */
+import Orm from '@stonyx/orm';
+import log from 'stonyx/log';
+const DENIED = Object.freeze({ granted: false });
+const GRANTED = Object.freeze({ granted: true });
+/**
+ * Classify one `access()` return value. Extracted verbatim from `auth()`, which
+ * now calls this; the branch ORDER is load-bearing and is preserved exactly.
+ *
+ * `operation` is the verb being authorised. `undefined` -- reachable, because
+ * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
+ * for it -- falls through `permitted.includes(undefined)` to a denial, which is
+ * the same answer `auth()` gave before the extraction.
+ */
+export function interpretAccess(access, operation) {
+    if (!access)
+        return DENIED;
+    // The function return shape IS the per-record hook. Grant the request and
+    // carry the predicate; the caller applies it per record.
+    if (typeof access === 'function')
+        return { granted: true, filter: access };
+    if (access === true)
+        return GRANTED;
+    // `AccessMethod` declares `string` legal and it fell through every branch
+    // above. A bare string is ONE permission, not a grant of all four -- reading
+    // it as a full grant is what once let `return 'read'` authorise DELETE.
+    const permitted = typeof access === 'string' ? [access] : access;
+    // Anything that is not a permission array by this point -- an object, a
+    // number, a Symbol -- is a consumer mistake, and the only safe reading of a
+    // shape the contract does not define is a denial. Fail CLOSED.
+    if (!Array.isArray(permitted))
+        return DENIED;
+    if (!permitted.includes(operation))
+        return DENIED;
+    return GRANTED;
+}
+/**
+ * Resolve model `type`'s verdict for a read, against the live `request`.
+ *
+ * Fails closed on both ambiguous inputs:
+ *
+ *   - `getAccess(type)` -> `undefined`. That is NOT "this model is
+ *     unrestricted". `setup-rest-server` catches an access-class load failure,
+ *     warns, and publishes whatever PARTIAL map it had, so `undefined` covers
+ *     both "no access class claims this model" and "the class that claims it
+ *     failed to load" -- and the caller cannot tell them apart. Deny.
+ *   - the predicate THROWS. Same reading `auth()` and `isDenied` already use:
+ *     a throw is a denial, logged, never a 500 and never a grant.
+ *
+ * NOTE ON CROSS-MODEL ASKS -- READ THIS BEFORE REBASING #232 OR #233 ONTO IT.
+ * The predicate is asked about `type` while the request in hand was dispatched
+ * to a DIFFERENT model's route. This function makes another model's class
+ * REACHABLE and asks it the model-correct question (`{ model: type }`); whether
+ * the ANSWER is model-correct is the CONSUMER's, because only a predicate that
+ * READS `context.model` can give one. Since #222 this repo's fixture does. A
+ * consumer's arity-1 predicate does not, and there is no supported way to tell
+ * which kind was resolved (the boot-time arity warning is
+ * abofs/stonyx-orm#213/#221, unshipped).
+ *
+ * BOTH DEGRADATION DIRECTIONS ARE REACHABLE, AND THE SECOND ONE GRANTS. This is
+ * measured, not reasoned:
+ *
+ *   - CLOSED. The migrated fixture's surviving `request.path` read means asking
+ *     the OWNER predicate on a request dispatched to `GET /animals/archived`
+ *     returns a bare `false` -- a whole-request deny bleeding across models,
+ *     treated here as "deny this linkage", not as an error. That over-denies a
+ *     PERMITTED record.
+ *   - OPEN. An arity-1 predicate -- the shape `setup-rest-server.ts:15-18`
+ *     still declares valid and the README calls the default in every consumer
+ *     tree -- identifies its collection from the request, so asked about
+ *     `owner` on a request dispatched to `/animals` it answers about ANIMALS.
+ *     Measured against this repo's own fixture with `reg.owner` replaced by an
+ *     arity-1 predicate that hides angela on `/owners`:
+ *
+ *       GET /owners     -> ["gina","michael","bob"]   angela hidden, correctly
+ *       GET /animals    -> owners named: [angela, ...]              LEAK
+ *       GET /animals/1  -> owner.data {"type":"owner","id":"angela"}
+ *
+ *     That is byte-for-byte the abofs/stonyx-orm#234 defect, on the surface
+ *     #234 was filed for, AFTER this fix. It is not a regression -- dev
+ *     published the same id unconditionally -- and this file cannot close it,
+ *     because the arity signal is #213/#221. Do NOT write, here or anywhere
+ *     else, that the cross-model ask degrades closed. The standing rule this
+ *     paragraph is held to is in docs/project-structure.md.
+ */
+function resolveVerdict(request, type) {
+    const predicate = Orm.instance?.getAccess?.(type);
+    if (typeof predicate !== 'function')
+        return DENIED;
+    let access;
+    try {
+        // `recordId: null`, AND NOT `request.params.id`. THE TEMPTING WRONG ANSWER
+        // IS RIGHT THERE, so this is pinned by assertion as well as by comment --
+        // test/unit/linkage-verdict-test.ts, `#234 + #241 -- recordId is null`.
+        //
+        // `AccessContext.recordId` (src/types/orm-types.ts, abofs/stonyx-orm#236 /
+        // #241) means "the record THIS ROUTE WAS ADDRESSED TO, as the store key of
+        // the model being authorised", and `null` means "addressed to no record".
+        // The id sitting on the request in hand names the PRIMARY record, which
+        // belongs to a DIFFERENT model -- `GET /owners/gina` carries
+        // `params.id === 'gina'`, and the ask being made HERE is about `animal` or
+        // `trait`. Filling this in from the request would hand the related model's
+        // predicate an id belonging to another model, which is byte-for-byte the
+        // cross-model confusion abofs/stonyx-orm#202 introduced this context to
+        // eliminate: the predicate would compare an owner's id against its own
+        // records and answer a question nobody asked. There is no record of THIS
+        // model addressed by this request, so `null` is the honest value -- the
+        // same spelling `auth()` uses for a collection route.
+        //
+        // NOR ANY RECORD'S OWN ID, WHICH IS THE SECOND-MOST TEMPTING ANSWER. This
+        // verdict is resolved ONCE PER TYPE and cached in `byType` below, before
+        // any record has been looked at; there is no per-record `AccessContext`
+        // built anywhere on this path. Seeding it from the first record of a type
+        // would let that record's identity answer for every later record of the
+        // same type -- the same "one record's verdict answers for another" defect
+        // the `decisions` raw-key argument below exists to prevent, just one level
+        // coarser. And it is unnecessary: `AccessContext` deliberately carries no
+        // `record` because auth-time and record-time are separate decision points,
+        // and the per-record point already receives the WHOLE record, id included,
+        // through `verdict.filter(record)`. A predicate that wants a record's id
+        // has the contract's own channel for it.
+        access = predicate(request, { model: type, operation: 'read', recordId: null });
+    }
+    catch (error) {
+        log.error?.(`[@stonyx/orm] access() threw while resolving linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+        return DENIED;
+    }
+    return interpretAccess(access, 'read');
+}
+/**
+ * Build a request-scoped linkage filter.
+ *
+ * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
+ *
+ *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
+ *     which is arbitrary code with arbitrary cost and which the module has
+ *     already had to guard for throwing.
+ *   - one decision per `(type, id)`. `included` is deduplicated by
+ *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
+ *     per record. Measured on a bare `GET /animals` with no `include=`:
+ *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
+ *     a 6.9x reduction and 41 predicate calls saved.
+ *
+ * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
+ * template-string composite. `Map` compares with SameValueZero, so the numeric
+ * id `1` and the string id `'1'` stay DISTINCT, where `` `${type}:${id}` `` --
+ * or a bare `String(id)` -- collapses them onto one entry and answers the second
+ * record with the first record's verdict.
+ *
+ * WHAT THAT DOES AND DOES NOT PROTECT. It cannot cross MODELS. `decisions` is
+ * already partitioned per type by `byType`, so a composite key inside a per-type
+ * map is one-to-one with the raw one and no owner's verdict could ever answer
+ * for an animal -- the claim that once stood here. The real exposure is narrower
+ * and entirely WITHIN one model: two records of the same type whose ids differ
+ * only by JavaScript type, which a per-record predicate may legitimately answer
+ * differently about (an id read off a JSON body is a string; the same id
+ * assigned by the server is a number). Pinned by unit assertion, because this
+ * fixture cannot produce the collision on its own -- `owner` ids are strings and
+ * `animal` ids are numbers.
+ *
+ * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
+ * it -- a verdict cached across requests would answer a second caller with the
+ * first caller's authorization.
+ *
+ * A REQUEST IS REQUIRED, AND ITS ABSENCE IS CHECKED HERE RATHER THAN DELEGATED.
+ * This function is EXPORTED (src/index.ts), and the README's Consumer Contracts
+ * section points consumers at exactly the contexts that have no live request --
+ * a queue payload, a websocket frame, a custom route. Without one there is no
+ * caller to authorise against, and this file's header already says so: the
+ * shipped sample reads `request.path` and fail-closes when it is absent, so
+ * `getAccess('owner')(undefined, ...)` is `false`, while
+ * `getAccess('animal')(undefined, ...)` returns a per-record predicate and
+ * GRANTS. Measured on this repo's own fixture before this guard existed:
+ *
+ *   createLinkageFilter(undefined | null | {} | 'x' | 0)
+ *     -> owner=false animal=TRUE trait=TRUE category=TRUE phone-number=TRUE
+ *
+ * Four of five claimed models granted, with no log, because whether an absent
+ * request fails closed was left ENTIRELY to consumer predicates -- and a
+ * predicate that ignores its request cannot fail closed on one that is missing.
+ * A nullish or primitive `request` therefore denies every model outright and
+ * says so once, at construction, so the signal exists even for a caller that
+ * goes on to serialize nothing.
+ *
+ * WHAT THIS CANNOT CHECK: `{}` is an object and passes. There is no request
+ * contract this module owns -- `auth()` reads `.method`, the shipped sample
+ * reads `.path`, a consumer's reads whatever it likes -- so anything past
+ * "is it an object" would be this module inventing a shape for someone else's
+ * framework. The residual is documented in the README under Consumer Contracts.
+ */
+export function createLinkageFilter(request) {
+    if (typeof request !== 'object' || request === null) {
+        log.error?.(`[@stonyx/orm] createLinkageFilter() was called with no request (received ${request === null ? 'null' : typeof request}) -- there is no caller to authorise against, so ALL relationship linkage it is asked about is denied.`);
+        return function isLinkable(_type, _record) {
+            return false;
+        };
+    }
+    const byType = new Map();
+    return function isLinkable(type, record) {
+        let entry = byType.get(type);
+        if (!entry) {
+            entry = { verdict: resolveVerdict(request, type), decisions: new Map() };
+            byType.set(type, entry);
+        }
+        const { verdict, decisions } = entry;
+        if (!verdict.granted)
+            return false;
+        if (!verdict.filter)
+            return true;
+        const id = record?.id;
+        const cached = decisions.get(id);
+        if (cached !== undefined)
+            return cached;
+        let allowed;
+        try {
+            allowed = Boolean(verdict.filter(record));
+        }
+        catch (error) {
+            // A predicate that throws is a denial -- the same reading `isDenied` uses
+            // one layer down. Logged, because a predicate that throws on every record
+            // empties every relationship and, silently, that is indistinguishable
+            // from a database with no relationships in it.
+            log.error?.(`[@stonyx/orm] access filter threw while filtering linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
+            allowed = false;
+        }
+        decisions.set(id, allowed);
+        return allowed;
+    };
+}

package/dist/index.d.ts

@@ -10,6 +10,8 @@ export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
 export type { AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
+export type { LinkageFilter } from './types/orm-types.js';
+export { createLinkageFilter } from './access-verdict.js';
 export { Model, View, Serializer };
 export { attr, belongsTo, hasMany, createRecord, updateRecord };
 export { count, avg, sum, min, max };

package/dist/index.js

@@ -23,6 +23,14 @@ import { createRecord, updateRecord } from './manage-record.js';
 import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
+// The request-scoped linkage-verdict factory (#234). PUBLIC on purpose: the
+// README tells a consumer serializing a `Record` outside the REST layer to pass
+// their own resolved `linkage` option, and without an exported factory the only
+// way to follow that advice is to write a SECOND reading of `access()` in
+// consumer code -- the exact "unreviewed second authorization vocabulary" that
+// src/access-verdict.ts exists to prevent, reproduced where no reviewer sees it
+// drift. Give them the one interpreter instead of an invitation to fork it.
+export { createLinkageFilter } from './access-verdict.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers