@stonyx/orm 0.3.2-alpha.70 → 0.3.2-alpha.71

package/dist/access-verdict.js

@@ -0,0 +1,222 @@
+/**
+ * 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 {
+        access = predicate(request, { model: type, operation: 'read' });
+    }
+    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.
+ */
+export function createLinkageFilter(request) {
+    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/hooks.d.ts

@@ -20,21 +20,7 @@ export interface HookContext {
     state?: Record<string, unknown>;
     /** Previous record state (available in update hooks). */
     oldState?: unknown;
-    /**
-     * Target record ID for single-record operations.
-     *
-     * SET ONLY UNDER `delete`. `_withHooks` assigns this key in the two
-     * `operation === 'delete'` branches and nowhere else, so on `get`, `list`,
-     * `create` and `update` the key is ABSENT -- not `undefined`-valued, absent.
-     * A hook rule written as `ctx.recordId === '<id>'` never fires on an update;
-     * the addressed id is in `ctx.params`. Tracked as abofs/stonyx-orm#242.
-     *
-     * @see AccessContext.recordId in ./types/orm-types.ts -- an identically-named
-     * key on an identically-shaped context object, and NOT interchangeable with
-     * this one: it is present on every route `auth()` classifies, and spells
-     * absence as `null` rather than `undefined`. They differ in coverage on four
-     * of five operations, not only in the absence spelling.
-     */
+    /** Target record ID for single-record operations. */
     recordId?: string | number;
     /** Response data (available in after hooks). */
     response?: unknown;

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

package/dist/orm-request.d.ts

@@ -69,15 +69,6 @@
  * records under `model: 'owner'`, and the context gives no signal of that
  * (abofs/stonyx-orm#196).
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237, AND KEPT FOR THE
- * CONSTRAINT IT STATES RATHER THAN AS A DESCRIPTION OF THE CODE. The context
- * now also carries `recordId` -- the DECODED route-parameter id, see
- * `AccessContext.recordId` in ./types/orm-types.ts -- so the fixture's
- * `/archived` deny IS expressible from the context alone, and the shipped
- * sample no longer reads `request.path` at all. Retiring this wording WITH the
- * measurement that retires it, rather than by deletion, is
- * abofs/stonyx-orm#238.
- *
  * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
  * matching but BEFORE any handler executes (`@stonyx/rest-server`
  * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
@@ -167,11 +158,6 @@
  * `/archived` SUB-PATH rule is still a string match, and abofs/stonyx-orm#228 is
  * a sixth spelling that gets past it.
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: the `/archived` rule is
- * no longer a string match against the request target -- it compares the
- * decoded `recordId` the framework supplies -- and abofs/stonyx-orm#228 is
- * CLOSED. Retirement of this wording: abofs/stonyx-orm#238.
- *
  *   An intermediate revision of the sample read `request.baseUrl` -- the mount
  *   Express ACTUALLY MATCHED. That closed all five variants (no query string,
  *   not mount-relative, unaffected by absolute-form, already carrying the
@@ -187,26 +173,12 @@
  *   does not decode, so `GET /owners/%61rchived` steps past it. See the
  *   normalisation paragraph below and abofs/stonyx-orm#228.
  *
- *   SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237. Variant 3 lived in that
- *   one string comparison, and the comparison is gone: the sample compares the
- *   decoded `recordId`. Left standing rather than edited because the same
- *   "variant 3 survives" wording sits at four sites -- this header, README.md
- *   twice, and test/sample/access/global-access.ts -- three of which SHIP, so
- *   retiring one of four leaves the shipped copies contradicting each other.
- *   Retiring all four WITH their measurement is abofs/stonyx-orm#238.
- *
  * ONE READ OF ARGUMENT ONE SURVIVES, AND IT MUST: `request.path`. It is
  * mount-relative and query-free, and it is for rules that distinguish SUB-PATHS
  * beneath the mount. The context names which model and which verb, NOT which
  * route, so the sample's `/archived` deny cannot be expressed from the context
  * alone and a context-ONLY rewrite would silently turn that deny into an allow.
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: NO read of argument one
- * survives in the shipped sample. `recordId` names WHICH RECORD the route was
- * addressed to, so the `/archived` deny is expressible from the context alone
- * -- and it still must not be dropped; expressible is not optional. Retirement
- * of this wording: abofs/stonyx-orm#238.
- *
  * NORMALISE THE WAY THE ROUTER DOES, AND CASE-FOLDING ALONE IS NOT THAT. The
  * sample lower-cases before comparing, because a matcher stricter than the
  * case-insensitive router can be stepped around. That closes the case gap only.
@@ -216,20 +188,6 @@
  * sample and is tracked as abofs/stonyx-orm#228; the `.toLowerCase()` is not a
  * complete normalisation recipe. Compare record ids at their real case.
  *
- * DO NOT FOLLOW THE PARAGRAPH ABOVE. SUPERSEDED 2026-09-01 BY
- * abofs/stonyx-orm#236/#237, and flagged here rather than merely dated because
- * it is an INSTRUCTION, not a stale observation. `.toLowerCase()` on the access
- * path was measured WRONG IN BOTH DIRECTIONS AT ONCE: with a distinct owner
- * seeded at `ARCHIVED`, `GET /owners/ARCHIVED` was a false DENY on the wrong
- * record and `GET /owners/%41RCHIVED` a false ALLOW on that same record. A
- * record id is a VALUE, not a literal route segment, and express's
- * `case sensitive routing` governs literal segments only. Compare
- * `context.recordId` AS IT ARRIVES: do not case-fold it, do not decode it, do
- * not derive it from `request.path`. `AccessContext.recordId` in
- * ./types/orm-types.ts is the contract and says "Do NOT case-fold it"; the same
- * published tarball ships both files, and THIS paragraph is the one that is
- * wrong. Retiring it WITH its measurement is abofs/stonyx-orm#238.
- *
  * `?? ''` is not a defence. It converts an absent request target into an empty
  * string, which matches no collection, which falls through to the permission
  * array -- a total grant. An input you cannot identify must DENY, and that
@@ -238,12 +196,6 @@
  * argument one. The sample returns `false` for an absent `model` AND for an
  * absent or non-string `request.path`, rather than falling through either way.
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237 as to WHAT is guarded --
- * the principle is unchanged. The sample no longer reads `request.path`, so it
- * returns `false` for an absent `model` AND for an absent `recordId`
- * (`undefined`, the one spelling `auth()` never produces). Retirement of this
- * wording: abofs/stonyx-orm#238.
- *
  * THE REAL FIX IS abofs/stonyx-orm#202: `access()` should receive the model,
  * the operation and the record. Prefer the array shape (`['read']`) or `false`
  * until #202 lands; the function shape is what requires any matching at all.

package/dist/orm-request.js

@@ -69,15 +69,6 @@
  * records under `model: 'owner'`, and the context gives no signal of that
  * (abofs/stonyx-orm#196).
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237, AND KEPT FOR THE
- * CONSTRAINT IT STATES RATHER THAN AS A DESCRIPTION OF THE CODE. The context
- * now also carries `recordId` -- the DECODED route-parameter id, see
- * `AccessContext.recordId` in ./types/orm-types.ts -- so the fixture's
- * `/archived` deny IS expressible from the context alone, and the shipped
- * sample no longer reads `request.path` at all. Retiring this wording WITH the
- * measurement that retires it, rather than by deletion, is
- * abofs/stonyx-orm#238.
- *
  * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
  * matching but BEFORE any handler executes (`@stonyx/rest-server`
  * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
@@ -167,11 +158,6 @@
  * `/archived` SUB-PATH rule is still a string match, and abofs/stonyx-orm#228 is
  * a sixth spelling that gets past it.
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: the `/archived` rule is
- * no longer a string match against the request target -- it compares the
- * decoded `recordId` the framework supplies -- and abofs/stonyx-orm#228 is
- * CLOSED. Retirement of this wording: abofs/stonyx-orm#238.
- *
  *   An intermediate revision of the sample read `request.baseUrl` -- the mount
  *   Express ACTUALLY MATCHED. That closed all five variants (no query string,
  *   not mount-relative, unaffected by absolute-form, already carrying the
@@ -187,26 +173,12 @@
  *   does not decode, so `GET /owners/%61rchived` steps past it. See the
  *   normalisation paragraph below and abofs/stonyx-orm#228.
  *
- *   SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237. Variant 3 lived in that
- *   one string comparison, and the comparison is gone: the sample compares the
- *   decoded `recordId`. Left standing rather than edited because the same
- *   "variant 3 survives" wording sits at four sites -- this header, README.md
- *   twice, and test/sample/access/global-access.ts -- three of which SHIP, so
- *   retiring one of four leaves the shipped copies contradicting each other.
- *   Retiring all four WITH their measurement is abofs/stonyx-orm#238.
- *
  * ONE READ OF ARGUMENT ONE SURVIVES, AND IT MUST: `request.path`. It is
  * mount-relative and query-free, and it is for rules that distinguish SUB-PATHS
  * beneath the mount. The context names which model and which verb, NOT which
  * route, so the sample's `/archived` deny cannot be expressed from the context
  * alone and a context-ONLY rewrite would silently turn that deny into an allow.
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237: NO read of argument one
- * survives in the shipped sample. `recordId` names WHICH RECORD the route was
- * addressed to, so the `/archived` deny is expressible from the context alone
- * -- and it still must not be dropped; expressible is not optional. Retirement
- * of this wording: abofs/stonyx-orm#238.
- *
  * NORMALISE THE WAY THE ROUTER DOES, AND CASE-FOLDING ALONE IS NOT THAT. The
  * sample lower-cases before comparing, because a matcher stricter than the
  * case-insensitive router can be stepped around. That closes the case gap only.
@@ -216,20 +188,6 @@
  * sample and is tracked as abofs/stonyx-orm#228; the `.toLowerCase()` is not a
  * complete normalisation recipe. Compare record ids at their real case.
  *
- * DO NOT FOLLOW THE PARAGRAPH ABOVE. SUPERSEDED 2026-09-01 BY
- * abofs/stonyx-orm#236/#237, and flagged here rather than merely dated because
- * it is an INSTRUCTION, not a stale observation. `.toLowerCase()` on the access
- * path was measured WRONG IN BOTH DIRECTIONS AT ONCE: with a distinct owner
- * seeded at `ARCHIVED`, `GET /owners/ARCHIVED` was a false DENY on the wrong
- * record and `GET /owners/%41RCHIVED` a false ALLOW on that same record. A
- * record id is a VALUE, not a literal route segment, and express's
- * `case sensitive routing` governs literal segments only. Compare
- * `context.recordId` AS IT ARRIVES: do not case-fold it, do not decode it, do
- * not derive it from `request.path`. `AccessContext.recordId` in
- * ./types/orm-types.ts is the contract and says "Do NOT case-fold it"; the same
- * published tarball ships both files, and THIS paragraph is the one that is
- * wrong. Retiring it WITH its measurement is abofs/stonyx-orm#238.
- *
  * `?? ''` is not a defence. It converts an absent request target into an empty
  * string, which matches no collection, which falls through to the permission
  * array -- a total grant. An input you cannot identify must DENY, and that
@@ -238,12 +196,6 @@
  * argument one. The sample returns `false` for an absent `model` AND for an
  * absent or non-string `request.path`, rather than falling through either way.
  *
- * SUPERSEDED 2026-09-01 BY abofs/stonyx-orm#236/#237 as to WHAT is guarded --
- * the principle is unchanged. The sample no longer reads `request.path`, so it
- * returns `false` for an absent `model` AND for an absent `recordId`
- * (`undefined`, the one spelling `auth()` never produces). Retirement of this
- * wording: abofs/stonyx-orm#238.
- *
  * THE REAL FIX IS abofs/stonyx-orm#202: `access()` should receive the model,
  * the operation and the record. Prefer the array shape (`['read']`) or `false`
  * until #202 lands; the function shape is what requires any matching at all.
@@ -267,6 +219,7 @@ import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
+import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 const methodAccessMap = {
     GET: 'read',
     POST: 'create',
@@ -436,6 +389,13 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
         return response;
     const includedRecords = collectIncludedRecords(recordOrRecords, includes);
     if (includedRecords.length > 0) {
+        // NO `linkage` ARGUMENT, deliberately, and abofs/stonyx-orm#235 owns adding
+        // one. Until it does, a PERMITTED record here emits the full pre-#234
+        // document: `GET /animals/1?include=owner` filters the primary document's
+        // `owner.data` to `null` and then names `owner:angela` in `included`.
+        // Whether a resource reaches this array at all is a different question
+        // (membership, abofs/stonyx-orm#233) and closing that one does not close
+        // this one.
         response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
     }
     return response;
@@ -609,7 +569,13 @@ export default class OrmRequest extends Request {
             if (queryFilterPredicate)
                 recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
             const baseUrl = getBaseUrl(request);
-            const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
+            // ONE filter per REQUEST, not one per record: it carries the per-type
+            // verdict cache and the per-(type, id) decision cache, and both are
+            // worthless if it is rebuilt inside the map. Measured on this exact
+            // surface with no `include=`: 48 linkage entries collapse to 7 distinct
+            // (type, id) pairs.
+            const linkage = createLinkageFilter(request);
+            const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl, linkage }));
             return buildResponse(data, request.query?.include, recordsToReturn, {
                 links: { self: `${baseUrl}/${pluralizedModel}` },
                 baseUrl
@@ -627,7 +593,24 @@ export default class OrmRequest extends Request {
             const fieldsMap = parseFields(request.query);
             const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
             const baseUrl = getBaseUrl(request);
-            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
+            const linkage = createLinkageFilter(request);
+            // `buildResponse` is deliberately NOT given the linkage filter, and the
+            // residual that leaves is NOT the one #233 owns. Two different questions:
+            //
+            //   - WHETHER A RESOURCE APPEARS in `included` at all is MEMBERSHIP ->
+            //     abofs/stonyx-orm#233.
+            //   - What a record already IN `included` may NAME is LINKAGE -- the same
+            //     question #234 answers for the primary document -- and it is
+            //     abofs/stonyx-orm#235, which also owns createHandler/updateHandler.
+            //
+            // The residual, stated so the next reader does not have to derive it:
+            // `buildResponse` calls `record.toJSON?.({ baseUrl })` with no `linkage`
+            // argument, so a PERMITTED record in `included` emits the full pre-#234
+            // document. Measured: `GET /animals/1?include=owner` returns
+            // `owner.data: null` on the primary document and `owner:angela` in
+            // `included`. One query parameter deep. Only the PRIMARY document's
+            // linkage is filtered here.
+            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
                 links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
                 baseUrl
             });
@@ -1214,15 +1197,21 @@ export default class OrmRequest extends Request {
                     return 404;
                 const relatedData = record.__relationships[relationshipName];
                 const baseUrl = getBaseUrl(request);
+                // LINKAGE ONLY. This filter decides which ids the emitted documents may
+                // NAME in their own `relationships.*.data`; it does NOT decide whether
+                // the related records themselves are served -- that is the parent-only
+                // filtering this route has done since #190, and widening it to the
+                // related record is abofs/stonyx-orm#196.
+                const linkage = createLinkageFilter(request);
                 let data;
                 if (info.isArray) {
                     // hasMany - return array
                     const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-                    data = related.map(r => r.toJSON?.({ baseUrl }));
+                    data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
                 }
                 else {
                     // belongsTo - return single or null
-                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
+                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
                 }
                 return {
                     links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}` },
@@ -1317,53 +1306,10 @@ export default class OrmRequest extends Request {
         // src/types/orm-types.ts. Nothing is fetched at this point and adding a
         // lookup here would put a store read in the middle of an authorization
         // path. The function return shape below IS the per-record hook.
-        //
-        // -------------------------------------------------------------------------
-        // #236 -- `recordId`, the DECODED route-parameter id, for the same reason.
-        //
-        // WHICH RECORD is the third structural fact the framework already holds and
-        // the consumer was left to re-derive, and re-deriving it failed OPEN. The
-        // documented sample compared `request.path` -- the RAW, undecoded pathname
-        // -- against a literal `/archived`, while the router DECODES `:id`. So
-        // `GET /owners/%61rchived` walked past the deny and was dispatched as the
-        // record `archived`: 200 with the record in full, and DELETE answered 204
-        // with the record destroyed, unauthenticated. Four spellings measured, all
-        // four through; 255 non-canonical spellings of that 8-character id decode
-        // to the same key, so this was never a deny-list of one.
-        //
-        // TWO CONSUMER-SIDE NORMALISATIONS WERE MEASURED WRONG IN OPPOSITE
-        // DIRECTIONS, which is the argument for doing it once, here.
-        // `.toLowerCase()` case-folds a route-parameter VALUE on the axis that
-        // governs literal SEGMENTS: with a distinct owner seeded at `ARCHIVED`,
-        // `GET /owners/ARCHIVED` was a false DENY on the wrong record and
-        // `GET /owners/%41RCHIVED` a false ALLOW on that same one.
-        // `decodeURIComponent(request.path)` decodes THEN splits while the router
-        // splits THEN decodes, so it over-denied `/owners/archived%2fx` -- 403 for
-        // a genuinely distinct record. Failing closed there was luck, not design.
-        //
-        // `getId(request.params)` AND NOT `request.params.id`, for exactly the
-        // reason `operation` is a `methodAccessMap` lookup: it is the SAME single
-        // coercion the store lookup one layer down performs, so the predicate and
-        // the dispatch cannot disagree about which record a request addresses.
-        // The raw string would reintroduce that divergence on hex-shaped ids --
-        // `GET /animals/0x2391` looks up record `9105`.
-        //
-        // NOTHING HERE PARSES THE REQUEST TARGET EITHER. `request.params` is what
-        // the router matched, so a mount prefix, an absolute-form target, a query
-        // string or a case-varied mount cannot move this value -- the same
-        // guarantee `model` carries, by the same means.
-        //
-        // `null` and not `undefined` on a collection route, so the KEY IS ALWAYS
-        // PRESENT -- the rule `operation`'s own docblock already establishes. A
-        // context reaching a predicate WITHOUT the key therefore did not come from
-        // here; it was hand-assembled by a caller resolving the predicate through
-        // `Orm.instance.getAccess()`, and that absence stays deniable only because
-        // `auth()` never produces it.
         // -------------------------------------------------------------------------
         const context = {
             model: this.model,
             operation: methodAccessMap[request.method],
-            recordId: request.params && 'id' in request.params ? getId(request.params) : null,
         };
         let access;
         try {
@@ -1376,26 +1322,23 @@ export default class OrmRequest extends Request {
             log.error?.(`[@stonyx/orm] access() threw for model "${this.model}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
             return 403; // Forbidden
         }
-        if (!access)
-            return 403;
-        if (typeof access === 'function') {
-            state.filter = access;
-            return undefined;
-        }
-        if (access === true)
-            return undefined;
-        // `AccessMethod` declares `string` legal and it fell through every branch
-        // above, returning undefined -- i.e. FULL CRUD, no filter. `return 'read'`
-        // is the natural reading of a type that lists `string` first, and it
-        // granted DELETE. A bare string is one permission, not a grant of all four.
-        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 403;
-        if (!permitted.includes(methodAccessMap[request.method]))
+        // THE READING OF THE RETURN SHAPE LIVES IN ONE PLACE (#234).
+        //
+        // It used to be inline here, and it was the only copy, which was fine while
+        // `auth()` was the only thing that had to ask. It is not any more: the
+        // linkage path has to ask model X's predicate about model X's records while
+        // servicing a request routed to model Y, and a second inline copy of these
+        // six branches would be a second authorization vocabulary -- one that can
+        // drift, and that reviewers would have to notice had drifted. The branch
+        // order in `interpretAccess` is this block, moved, not rewritten.
+        const verdict = interpretAccess(access, methodAccessMap[request.method]);
+        if (!verdict.granted)
             return 403;
+        // The function return shape is the per-record hook, and `state` is the
+        // whole transport for it: @stonyx/rest-server memoises one state object per
+        // request and hands the same one to `auth()` and to the handler.
+        if (verdict.filter)
+            state.filter = verdict.filter;
         return undefined;
     }
 }

package/dist/record.d.ts

@@ -1,7 +1,23 @@
 import type Serializer from './serializer.js';
+import type { LinkageFilter } from './types/orm-types.js';
 interface ToJSONOptions {
     fields?: Set<string>;
     baseUrl?: string;
+    /**
+     * An ALREADY-RESOLVED linkage decision, supplied by a caller that holds the
+     * request (abofs/stonyx-orm#234). Returning `false` for a related record
+     * drops that record's `{ type, id }` from `relationships.*.data`.
+     *
+     * This method APPLIES a verdict; it never RESOLVES one -- see
+     * `src/access-verdict.ts` for the two measured reasons it cannot. ABSENT is
+     * the default and the default is TODAY'S DOCUMENT, unchanged, because
+     * `toJSON` is also the `JSON.stringify` hook and an implicit caller has no
+     * syntactic place to pass this (abofs/stonyx-orm#230).
+     *
+     * ABSENT and UNUSABLE are read differently, and the difference is a security
+     * decision -- see the three-way reading at the call site below.
+     */
+    linkage?: LinkageFilter;
 }
 interface SerializeOptions {
     update?: boolean;