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

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.js

@@ -267,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',
@@ -423,7 +424,7 @@ function normalizeBodyId(id) {
     return coerceId(id);
 }
 function buildResponse(data, includeParam, recordOrRecords, options = {}) {
-    const { links, baseUrl } = options;
+    const { links, baseUrl, linkage } = options;
     const response = { data };
     // Add top-level links
     if (links) {
@@ -436,7 +437,53 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
         return response;
     const includedRecords = collectIncludedRecords(recordOrRecords, includes);
     if (includedRecords.length > 0) {
-        response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
+        // LINKAGE, NOT MEMBERSHIP -- and the distinction is the whole reason this
+        // line is one story's and the line above it is another's
+        // (abofs/stonyx-orm#235 and #233 respectively).
+        //
+        //   - WHICH RESOURCES REACH THIS ARRAY is decided by
+        //     `collectIncludedRecords` on the line above. That is MEMBERSHIP, it is
+        //     #233's, and it is deliberately untouched here: a hidden owner is
+        //     still a member of `included` after this change. Pinned green by
+        //     `[GUARD] #235 X1` so that #235 cannot close #233 incidentally.
+        //   - WHAT A RECORD ALREADY IN THIS ARRAY MAY NAME in its own
+        //     `relationships.*.data` is LINKAGE -- the same question #234 answers
+        //     for the primary document -- and that is what the `linkage` option
+        //     below decides. Before it, `GET /animals/1?include=owner,owner.pets`
+        //     filtered the primary document's `owner.data` to `null` and then
+        //     handed back eight PERMITTED animals in `included` each naming
+        //     `{"type":"owner","id":"angela"}` -- angela's whole `pets` set,
+        //     `[1, 3, 7, 10, 11, 15, 17, 20]`. `included` itself is NINE
+        //     resources there: those eight animals plus the hidden owner, whose
+        //     membership is #233's and not an animal. Neither #233 nor #234
+        //     closes that.
+        //
+        // THE FILTER IS THE CALLER'S, PASSED IN, NOT BUILT HERE. Both call sites
+        // already hold one for the primary document, and sharing it is what keeps
+        // the per-type verdict cache and the per-(type, id) decision cache alive
+        // across the primary document AND the sideload -- one verdict resolution
+        // per type for the whole response, pinned by `[GUARD] #235 C1`. Building a
+        // fresh filter here would resolve the consumer's `access()` once per
+        // included record instead.
+        //
+        // `linkage` IS OPTIONAL IN THE TYPE AND IS NOT OPTIONAL IN PRACTICE.
+        // Stating it precisely because the opposite claim stood here in an earlier
+        // draft of this change: BOTH of this function's callers supply a filter
+        // (`getCollectionHandler` and `getSingleHandler`, the only two), so the
+        // `undefined` branch has no live caller in this module today. It is
+        // optional so that omitting it degrades to the PRE-#234 document rather
+        // than to a denial -- `Record.toJSON` reads an ABSENT option as "no verdict
+        // was supplied" and emits linkage in full.
+        //
+        // WHAT IT MUST NEVER BE HANDED IS A NON-FUNCTION. `toJSON` does NOT read a
+        // non-function as absent: `Object.prototype.toString.call(linkage)` must be
+        // `'[object Function]'`, and anything else -- `null`, an `AsyncFunction`,
+        // and INCLUDING the primitive `true` -- DENIES every relationship on the
+        // document and logs once. `toJSON({ linkage: true })` emits `null` linkage.
+        // So do not "simplify" this to a boolean, and do not make it default to
+        // `true`: both spellings look like "allow everything" and mean the exact
+        // opposite (abofs/stonyx-orm#224).
+        response.included = includedRecords.map(record => record.toJSON?.({ baseUrl, linkage }));
     }
     return response;
 }
@@ -609,10 +656,20 @@ 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
+                baseUrl,
+                // THE SAME filter object the primary documents above were serialized
+                // with, deliberately: it carries the caches, and rebuilding one here
+                // would re-resolve every type (abofs/stonyx-orm#235).
+                linkage
             });
         };
         const getSingleHandler = async (request, { filter }) => {
@@ -627,12 +684,29 @@ 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 given the filter now (abofs/stonyx-orm#235), and it
+            // is the SAME object the primary document is serialized with -- one
+            // verdict per type for the whole response, sideload included.
+            //
+            // The boundary that remains, so the next reader does not have to derive
+            // it: this closes what a record already in `included` may NAME. WHETHER a
+            // resource appears in `included` at all is MEMBERSHIP and it is
+            // abofs/stonyx-orm#233's -- a hidden owner is still a member here.
+            // Neither question closes the other.
+            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
                 links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
-                baseUrl
+                baseUrl,
+                linkage
             });
         };
-        const createHandler = async ({ body, query }, { filter }) => {
+        const createHandler = async (request, { filter }) => {
+            // BOUND, not destructured (abofs/stonyx-orm#235). `HandlerFn` has always
+            // delivered the request as argument one; this handler simply discarded
+            // the binding, which is why its response document named ids every read
+            // surface withholds. `createLinkageFilter` needs the live request and
+            // there is no signature change involved in giving it one.
+            const { body, query } = request;
             const { type, id, attributes, relationships: rels } = (body?.data || {});
             if (!type)
                 return 400; // Bad request
@@ -871,9 +945,28 @@ export default class OrmRequest extends Request {
                 }
                 return 403;
             }
-            return { data: record.toJSON?.({ fields: modelFields }) };
+            // The filter is built HERE, per invocation, and never hoisted into the
+            // OrmRequest constructor where the other per-mount values live: a verdict
+            // cached across requests answers a second caller with the first caller's
+            // authorization (src/access-verdict.ts says so at the constructor an
+            // implementer would reach for).
+            //
+            // AND IT IS BUILT AFTER `createRecord`, AFTER THE ROLLBACK WINDOW AND
+            // AFTER `isDenied`, so the record is in its final form at the call. The
+            // filter is lazy per type and per (type, id), so it cannot observe a
+            // pre-write state even if it were built earlier.
+            //
+            // `fields` is passed here and NOT in `updateHandler`: the two handlers
+            // are asymmetric on purpose (`updateHandler` has no `fieldsMap` in
+            // scope), and a single copy-pasted wiring would drop it from one of them.
+            return { data: record.toJSON?.({ fields: modelFields, linkage: createLinkageFilter(request) }) };
         };
-        const updateHandler = async ({ body, params }, { filter }) => {
+        const updateHandler = async (request, { filter }) => {
+            // Bound rather than destructured, for the reason given in
+            // `createHandler` above (abofs/stonyx-orm#235). `PATCH /animals/1`
+            // returned 200 naming angela seconds after `GET /animals/1` returned
+            // `owner.data: null` for the same record -- one HTTP verb apart.
+            const { body, params } = request;
             const found = await store.find(model, getId(params));
             if (!found || !isOrmRecord(found))
                 return 404;
@@ -930,7 +1023,14 @@ export default class OrmRequest extends Request {
                     updateRecord(record, relUpdates, { _skipAutoPersist: true });
                 }
             }
-            return { data: record.toJSON?.() };
+            // No `fields` and no `baseUrl`, both unchanged: `updateHandler` has no
+            // `fieldsMap` in scope, and adding `baseUrl` would put `links` on a
+            // document that has never carried them -- an unrelated behaviour change.
+            // #224 AC6's "emits `data: []` WITH links" is a statement about the READ
+            // surfaces; on these two handlers a filtered relationship and a
+            // genuinely-empty one are both a bare `{ data }`, which is what makes
+            // them indistinguishable here too.
+            return { data: record.toJSON?.({ linkage: createLinkageFilter(request) }) };
         };
         const deleteHandler = async ({ params }, { filter }) => {
             // Coerced ONCE. `getId(params)` was evaluated twice here -- once to find
@@ -1214,15 +1314,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}` },
@@ -1230,6 +1336,54 @@ export default class OrmRequest extends Request {
                 };
             };
             // Relationship linkage route: GET /:id/relationships/{relationship}
+            //
+            // NO `linkage` FILTER FROM abofs/stonyx-orm#235, AND THAT IS A SCOPE
+            // BOUNDARY RATHER THAN AN OVERSIGHT -- abofs/stonyx-orm#232 OWNS THIS
+            // ROUTE, and PR #247 is IN FLIGHT against it in this same sprint. If you
+            // are reading this after #247 landed, the filtering below is #232's and
+            // this note records why it was never #235's to add.
+            //
+            // The three sites #235 does own -- `buildResponse`'s `included`, and the
+            // two write handlers, `POST /:models` and `PATCH /:models/:id` -- all
+            // reach the filter through `record.toJSON()`, which is where the
+            // `linkage` OPTION is applied.
+            //
+            // The related-resource branch above ALSO passes a `linkage` filter, and
+            // it is NOT one of those three: it is abofs/stonyx-orm#234's code and
+            // predates this change. `git diff 8dda5d6..HEAD -- src/orm-request.ts`
+            // leaves that branch byte-unchanged.
+            //
+            // This branch builds its `{ type, id }` objects BY
+            // HAND and never calls `toJSON` at all, so the `linkage` option cannot
+            // reach it -- whatever this route filters, it has to filter itself, which
+            // is precisely why doing so is a separate change with a separate owner.
+            //
+            // It is also a DIFFERENT QUESTION. Everywhere #235 touches, linkage is
+            // metadata ABOUT a document. Here the linkage IS the primary data, so
+            // dropping an entry is a MEMBERSHIP decision about what this route
+            // serves -- the same class as abofs/stonyx-orm#233 and #196, not the
+            // class #234/#235 close. That is why it is absent from #224 §2a's
+            // seven-site inventory.
+            //
+            // MEASURED, so the next person does not re-derive it. Against this
+            // branch's baseline of 1011/0, wiring `createLinkageFilter` into the
+            // belongsTo branch below takes the suite to 1009/2, reddening
+            // `[GUARD] #235 X2` and the
+            // `GET /animals/:id/relationships/owner returns relationship linkage`
+            // test -- the latter is #232's own reproduction, not a regression.
+            //
+            // THE BASELINE IS QUOTED WITH THE RESULT BECAUSE AN EARLIER REVISION OF
+            // THIS COMMENT SAID 993/2 AND SHIPPED IT. This file lands in consumers'
+            // `node_modules`, so a wrong number here is a wrong number in the
+            // published package. 993+2 = 995 is the DEV baseline, carried over from
+            // a branch on which `[GUARD] #235 X2` does not exist. A pass/fail pair
+            // with no baseline beside it cannot be checked by reading, which is how
+            // it survived three artifacts and a review; the qualitative claim was
+            // right the whole time and only the count was wrong.
+            //
+            // `[GUARD] #235 X2` in test/integration/orm-test.ts pins the OWNERSHIP
+            // BOUNDARY here rather than this route's current answer, so that it
+            // survives #247 landing. Read its comment before changing it.
             routes[`/:id/relationships/${dasherizedName}`] = async (request, { filter } = {}) => {
                 const record = await store.find(model, getId(request.params));
                 if (!record)
@@ -1376,26 +1530,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;
 }
@@ -358,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.157",
+  "version": "0.3.2-beta.159",
   "description": "",
   "main": "dist/index.js",
   "type": "module",