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

package/dist/orm-request.js

@@ -69,6 +69,15 @@
  * 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
@@ -158,6 +167,11 @@
  * `/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
@@ -173,12 +187,26 @@
  *   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.
@@ -188,6 +216,20 @@
  * 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
@@ -196,6 +238,12 @@
  * 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.
@@ -219,6 +267,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',
@@ -388,6 +437,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;
@@ -561,7 +617,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
@@ -579,7 +641,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
             });
@@ -1166,15 +1245,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}` },
@@ -1269,10 +1354,53 @@ 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 {
@@ -1285,26 +1413,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;

package/dist/record.js

@@ -1,7 +1,26 @@
 import { store } from '@stonyx/orm';
+import log from 'stonyx/log';
 import { getComputedProperties } from "./serializer.js";
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
 import { getPluralName } from './plural-registry.js';
+/**
+ * Name a non-boolean `linkage` return for the one log line that reports it.
+ *
+ * A thenable is called out BY NAME because it is the shape a consumer produces
+ * by accident -- an `async` resolver, or one that returns the promise of an
+ * authorization lookup -- and the one whose truthiness silently GRANTED every
+ * relationship before the ANSWER was checked (abofs/stonyx-orm#234).
+ */
+function describeNonVerdict(verdict) {
+    if (verdict === null)
+        return 'null';
+    if (Array.isArray(verdict))
+        return 'an array';
+    if ((typeof verdict === 'object' || typeof verdict === 'function')
+        && typeof verdict.then === 'function')
+        return 'a Promise (or other thenable)';
+    return `a value of type ${typeof verdict}`;
+}
 export default class Record {
     /** @private */
     __data = {};
@@ -65,7 +84,13 @@ export default class Record {
     toJSON(options = {}) {
         if (!this.__serialized)
             throw new Error('Record must be serialized before being converted to JSON');
-        const { fields, baseUrl } = options;
+        // DESTRUCTURED FROM A VALUE THAT IS NOT ALWAYS AN OBJECT. `toJSON` is the
+        // ECMAScript serialization hook, so `JSON.stringify({ data: record })`
+        // arrives here as `toJSON('data')` -- a STRING in the options slot.
+        // Destructuring a string yields `undefined` for every key, which is exactly
+        // the no-argument default, so the implicit path keeps working and keeps
+        // emitting today's document (abofs/stonyx-orm#230).
+        const { fields, baseUrl, linkage } = options;
         const { __data: data } = this;
         const modelName = this.__model.__name;
         const pluralizedModelName = getPluralName(modelName);
@@ -84,12 +109,133 @@ export default class Record {
                 continue;
             attributes[key] = getter.call(this);
         }
+        // `linkage` is a PUBLIC option -- it is on `OrmRecord.toJSON`
+        // (src/types/orm-types.ts) and the README tells consumers to pass one -- so
+        // it arrives from outside this package, may be ANY value, and whatever it
+        // is, it gets INVOKED here. That makes this the trust boundary, and it was
+        // the LAX side of one: the internal `createLinkageFilter` coerces and
+        // try/catches the consumer predicate it wraps, while this -- the site that
+        // consumes the PUBLIC option -- did neither.
+        //
+        // THREE QUESTIONS. Every wrong answer below was measured, on a two-
+        // relationship record, emitting the full pre-#234 document or throwing out
+        // of `JSON.stringify`.
+        //
+        //   1. IS IT SUPPLIED? ABSENT (`undefined`) means no verdict was supplied:
+        //      emit today's document. Load-bearing and asserted (AC5/AC5b) --
+        //      `toJSON` is also the `JSON.stringify` hook, so the implicit caller
+        //      arrives as `toJSON('data')`, a STRING, which destructures to
+        //      `undefined` here (abofs/stonyx-orm#230).
+        //
+        //   2. IS ITS SHAPE USABLE? `[object Function]` only, because
+        //      `typeof x === 'function'` is NOT the question "can this answer a
+        //      synchronous boolean".
+        //
+        //      A NON-FUNCTION denies. Reading it as absent is what `!linkage ||`
+        //      did, and a resolver returning `null` because it could not resolve a
+        //      session is the natural shape of that value and the fail-closed
+        //      INTENT -- measured, `toJSON({ linkage: null })` emitted the full
+        //      pre-#234 linkage with no signal, byte-identical to unpatched dev.
+        //
+        //      AN `AsyncFunction`, `GeneratorFunction` or `AsyncGeneratorFunction`
+        //      denies for that SAME reason, one branch over -- and a `typeof`-only
+        //      check left the whole defect standing there. `async (type, r) =>
+        //      false` returns a PROMISE, a promise is TRUTHY, so every relationship
+        //      was emitted in full with ZERO log, again byte-identical to unpatched
+        //      dev. An awaited authorization lookup is at least as natural a
+        //      resolver as a nullish one -- the README's own Consumer Contracts
+        //      section points consumers at queue payloads and websocket frames,
+        //      where lookups are routinely awaited -- and it landed on the GRANT
+        //      side of the same branch the `null` reading closed.
+        //
+        //   3. IS ITS ANSWER A VERDICT? It must BE a boolean, not merely coerce to
+        //      one. `Boolean(...)` -- the coercion `createLinkageFilter` applies to
+        //      a consumer `access()` predicate, whose truthy contract predates this
+        //      option and is deliberately NOT changed -- is not enough here, and
+        //      was measured not to be: with `Boolean(...)` plus a try/catch in
+        //      place, `async () => false`, `function* () {}`,
+        //      `() => Promise.resolve(false)`, `() => ({})` and `() => 'no'` ALL
+        //      still emitted the full pre-#234 linkage with no log, because
+        //      truthiness is what they already had. A non-boolean is a resolver
+        //      that did not answer, and the only safe reading of a non-answer is a
+        //      denial.
+        //
+        // AND IT NEVER THROWS -- which is now true rather than only written down.
+        // A throw here escapes the enclosing `JSON.stringify` and takes
+        // `console.log` and `Orm.db.save()`'s neighbours with it, a far worse
+        // failure mode than a status. `class Klass {}`, `Klass.bind(null)` and any
+        // predicate that dereferences something undefined were all measured raising
+        // out of the `stringify`; all three are caught and denied.
+        //
+        // Logged once per DOCUMENT, not once per relationship key or per related
+        // record: an emptied relationship is deliberately indistinguishable from a
+        // genuinely empty one on the wire, so the log is the ONLY signal a consumer
+        // whose resolver quietly returned `null`, or a promise, will ever get.
+        const linkageSupplied = linkage !== undefined;
+        // Read the tag DEFENSIVELY. `Object.prototype.toString` consults
+        // `Symbol.toStringTag`, so a Proxy with a throwing `get` trap would throw
+        // out of the validation whose entire job is that nothing throws.
+        let linkageShape = 'a non-function';
+        if (typeof linkage === 'function') {
+            try {
+                linkageShape = Object.prototype.toString.call(linkage);
+            }
+            catch {
+                linkageShape = '[object Unreadable]';
+            }
+        }
+        const linkageUsable = linkageShape === '[object Function]';
+        let linkageReported = false;
+        const denyAllLinkage = (reason) => {
+            if (linkageReported)
+                return;
+            linkageReported = true;
+            log.error?.(`[@stonyx/orm] toJSON() received an unusable \`linkage\` option -- ${reason}, so ALL relationship linkage on this \`${modelName}\` document is denied.`);
+        };
+        if (linkageSupplied && !linkageUsable) {
+            denyAllLinkage(typeof linkage !== 'function'
+                ? `it is of type ${linkage === null ? 'null' : typeof linkage} and it must be a function`
+                : `it is ${linkageShape} and it must be a SYNCHRONOUS function -- \`toJSON\` is the \`JSON.stringify\` hook and cannot await a verdict`);
+        }
+        const linkageVerdict = !linkageSupplied
+            ? undefined
+            : linkageUsable ? linkage : () => false;
+        // Applied per related record, alongside the existing `__model` liveness
+        // check, and producing exactly the shapes that check already produces: a
+        // dropped hasMany member leaves `data: []`, a dropped belongsTo leaves
+        // `data: null`. Both already ship -- a genuinely-empty hasMany emits
+        // `data: []` with links, and a cleaned belongsTo emits `data: null` -- so a
+        // filtered relationship is BYTE-IDENTICAL to an empty one and there is no
+        // new wire shape and no oracle.
+        const isLinkable = (r) => {
+            if (!linkageVerdict)
+                return true;
+            try {
+                const verdict = linkageVerdict(r.__model.__name, r);
+                if (typeof verdict === 'boolean')
+                    return verdict;
+                denyAllLinkage(`it answered with ${describeNonVerdict(verdict)} rather than a boolean`);
+            }
+            catch (error) {
+                // Building the report is itself a throw site -- `throw Symbol('x')`
+                // makes `String(error)` throw, and a getter on `.message` can throw --
+                // and a throw from the reporter would escape the catch that exists so
+                // that nothing escapes.
+                let detail = 'a value that could not be described';
+                try {
+                    detail = error instanceof Error ? error.message : String(error);
+                }
+                catch { /* keep the fallback -- the denial matters, the text does not */ }
+                denyAllLinkage(`it threw (${detail})`);
+            }
+            return false;
+        };
         for (const [key, childRecord] of Object.entries(this.__relationships)) {
             if (fields && !fields.has(key))
                 continue;
             const relationshipData = Array.isArray(childRecord)
-                ? childRecord.filter((r) => r?.__model).map((r) => ({ type: r.__model.__name, id: r.id }))
-                : (childRecord && childRecord.__model) ? { type: childRecord.__model.__name, id: childRecord.id } : null;
+                ? childRecord.filter((r) => r?.__model).filter(isLinkable).map((r) => ({ type: r.__model.__name, id: r.id }))
+                : (childRecord && childRecord.__model && isLinkable(childRecord)) ? { type: childRecord.__model.__name, id: childRecord.id } : null;
             // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
             const dasherizedKey = camelCaseToKebabCase(key);
             relationships[dasherizedKey] = { data: relationshipData };

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

@@ -87,9 +87,18 @@ export interface OrmRecord {
         __pendingSqlId?: boolean;
     };
     __relationships: Record<string, unknown>;
+    /**
+     * `linkage` is an ALREADY-RESOLVED decision supplied by a caller that holds
+     * the request (abofs/stonyx-orm#234): return `false` for a related record and
+     * its `{ type, id }` is dropped from `relationships.*.data`. Omitting it is
+     * the default, and the default is the pre-#234 document unchanged -- this
+     * method is also the `JSON.stringify` hook, so an implicit caller has no
+     * syntactic place to pass it (abofs/stonyx-orm#230).
+     */
     toJSON?(options?: {
         fields?: Set<string>;
         baseUrl?: string;
+        linkage?: LinkageFilter;
     }): Record<string, unknown>;
     [key: string]: unknown;
 }
@@ -242,6 +251,101 @@ export interface AccessContext {
      * from one that classified the request and found nothing.
      */
     operation: AccessOperation | undefined;
+    /**
+     * The record this route was addressed to, as the store key -- or `null` on a
+     * collection route, which is addressed to no record (abofs/stonyx-orm#236).
+     *
+     * IT IS ALREADY DECODED, AND THAT IS THE WHOLE POINT. Express decodes route
+     * PARAMETERS while leaving `request.path` raw, so a consumer comparing
+     * `request.path` against a literal compares an undecoded string against a
+     * decoded dispatch. `GET /owners/%61rchived` reached such a comparison as
+     * `/%61rchived`, walked past a `/archived` deny, and was dispatched as the
+     * record `archived` -- 200 with the record in full, and `DELETE` destroyed
+     * it, unauthenticated. 255 non-canonical spellings of an 8-character id
+     * decode to the same key, so a deny-list of spellings is the wrong shape.
+     *
+     * SO DO NOT NORMALISE THIS, AND DO NOT NORMALISE ANYTHING ELSE INSTEAD:
+     *
+     * - Do NOT decode it. Express decodes exactly ONCE, which is what a route
+     *   parameter means. `GET /owners/%2561rchived` is the legitimate id
+     *   `%61rchived`, not a second-order spelling of `archived`; a predicate that
+     *   decoded until stable would deny a record it was never asked about.
+     * - Do NOT case-fold it. A record id is a VALUE, not a literal route segment,
+     *   and express's `case sensitive routing` governs literal segments only.
+     *   With a distinct owner seeded at `ARCHIVED`, `.toLowerCase()` was measured
+     *   wrong in BOTH directions at once: `GET /owners/ARCHIVED` 403 (a false
+     *   deny, on the wrong record) and `GET /owners/%41RCHIVED` 200 (a false
+     *   allow, on that same record).
+     * - Do NOT derive it from `request.path` or the request target. Decoding the
+     *   whole path decodes THEN splits, while the router splits THEN decodes, so
+     *   `/owners/archived%2fx` -- a genuinely distinct record whose id is
+     *   `archived/x` -- was measured over-denied 403.
+     *
+     * IT IS `getId(request.params)`, BYTE FOR BYTE -- the same single coercion
+     * the store lookup uses, exactly as `operation` is the same `methodAccessMap`
+     * lookup the permission-array branch uses. The predicate and the dispatch
+     * therefore cannot disagree about which record a request addresses. Handing
+     * over the raw `request.params.id` instead would reintroduce that divergence
+     * on hex-shaped ids: `GET /animals/0x2391` looks up record `9105`.
+     *
+     * It inherits abofs/stonyx-orm#209 along with that coercion -- on a model
+     * declaring `id = attr('string')`, `'9107'` arrives here as the number
+     * `9107`. That is consistency WITH THE LOOKUP, which is the property this key
+     * exists to buy; it is not a defect to repair here.
+     *
+     * `null`, not `undefined`, on a collection route -- and the KEY IS ALWAYS
+     * PRESENT, the same rule `operation` states above. `auth()` always sets it,
+     * so a context arriving WITHOUT the key did not come from `auth()`: it was
+     * hand-assembled by a caller resolving the predicate through
+     * `Orm.instance.getAccess()`. That absence stays a distinguishable, deniable
+     * signal only because the framework never produces it.
+     *
+     * IT DISAGREES WITH THE HOOK VOCABULARY, AND NOT ONLY ON THE ABSENCE
+     * SPELLING. `HookContext.recordId` (`src/hooks.ts`) is an identically-named
+     * key on an identically-shaped context object, which is the exact
+     * configuration that makes `operation` fail-open shaped -- a hook sees
+     * `'get'` where `access()` sees `'read'`. An earlier revision of THIS
+     * docblock asserted the opposite ("here they AGREE... they differ in ONE way
+     * and it is the absence spelling"). That was measured false, in the fail-open
+     * direction, and it is corrected here rather than deleted.
+     *
+     * MEASURED over the live dispatch, before-hooks registered for all five
+     * operations on one model:
+     *
+     *     before:list    key ABSENT      ('recordId' in context === false)
+     *     before:get     key ABSENT      params={"id":"visible1"}
+     *     before:create  key ABSENT
+     *     before:update  key ABSENT      params={"id":"visible2"}
+     *     before:delete  recordId="visible3"
+     *     after:delete   recordId="visible3"
+     *
+     * `_withHooks` assigns `context.recordId` at exactly TWO sites in
+     * `src/orm-request.ts`, and BOTH sit inside an `operation === 'delete'`
+     * branch. So the two keys differ in COVERAGE, on four of five operations: on
+     * a hook context the key is absent for get, list, create and update, while
+     * this key is present on every route `auth()` classifies. The absence
+     * spelling is the smaller half of the difference, not the whole of it.
+     *
+     * AND THAT INVERTS THE ARGUMENT ABOVE WHEN IT IS READ ACROSS THE TWO. Here,
+     * a missing `recordId` means "did not come from `auth()`" and is deniable.
+     * On a hook context it means "this is a get / list / create / update" -- an
+     * ordinary request. A consumer who writes the hook-side half of the same
+     * rule --
+     *
+     *     beforeHook('update', 'owner', ctx => ctx.recordId === 'archived' ? 403 : undefined)
+     *
+     * -- gets a deny that NEVER FIRES: measured, `PATCH /owners/visible2` -> 200,
+     * with `ctx.recordId === undefined` while the addressed record sits in
+     * `ctx.params`. The hook side is abofs/stonyx-orm#242 and is deliberately not
+     * repaired here. A predicate must not read `undefined` here as "collection",
+     * and nothing in this contract makes it safe to read the two keys as one key.
+     *
+     * IT NAMES WHICH RECORD, NOT WHICH SURFACE. `GET /owners/gina`,
+     * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` all
+     * carry `recordId: 'gina'`; the related-resource gap is abofs/stonyx-orm#196
+     * and is untouched by this key.
+     */
+    recordId: string | number | null;
 }
 /**
  * A consumer `access()` predicate.
@@ -263,3 +367,21 @@ export interface AccessContext {
  * context gets `TS2554: Expected 2 arguments, but got 1`.
  */
 export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;
+/**
+ * A resolved, request-scoped linkage decision: may `record` of model `type` be
+ * NAMED, by id, inside another model's document (abofs/stonyx-orm#234)?
+ *
+ * Arity is `(type, record)` and not `(type, id)` because the per-record filter
+ * a consumer returns is handed the RECORD -- this repo's own fixture reads
+ * `record.owner?.id`, not just `record.id`. The `(type, id)` pair is the CACHE
+ * key inside `createLinkageFilter`, not the input.
+ *
+ * DECLARED HERE, with the rest of the access vocabulary, and imported by every
+ * site that names it. It had three structurally-identical hand-written copies
+ * (`access-verdict.ts`, `record.ts`, `OrmRecord.toJSON` below) bridged to each
+ * other by nothing, so a drift in nullability or a widening of `type` would
+ * have landed on one and not the others -- which is the same "second,
+ * unreviewed vocabulary" failure `src/access-verdict.ts` exists to prevent, one
+ * level up in the type system.
+ */
+export type LinkageFilter = (type: string, record: unknown) => boolean;

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-beta.156",
+  "version": "0.3.2-beta.158",
   "description": "",
   "main": "dist/index.js",
   "type": "module",