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

package/README.md

@@ -1061,12 +1061,42 @@ Not this:
 const linkage = (type, r) => Orm.instance.getAccess(type)?.(request)?.(r) ?? true;
 ```
 
-**`linkage` is validated, and an unusable value DENIES.** `undefined` means "no
-verdict supplied" and emits today's document. Any other non-function — `null`,
-`0`, `false`, `''`, `true`, a string, an object — drops **all** linkage on that
-document and logs. This matters because `null` is the natural return of a
-resolver that could not resolve a session: it used to be read as "absent" and
-emit the full document silently.
+**`createLinkageFilter` requires a live request, and there is no safe call
+without one.** `request` is the only authorization input the filter has — it is
+handed straight to your `access()` predicates, and a predicate that does not
+*read* it cannot fail closed when it is missing. Passing `undefined`, `null` or
+any non-object therefore denies **all** linkage and logs, once, at construction.
+Measured before that guard existed, `createLinkageFilter(undefined)` granted
+four of the five models in this repository's own fixture, silently.
+
+**This is the catch for the request-less contexts named above.** In a queue
+consumer or a websocket handler there is no live request, so there is nothing to
+authorize against and nothing this package can resolve for you. Either carry the
+originating request through to the point of serialization, or publish no linkage
+at all — `record.toJSON({ linkage: () => false })` emits the document with every
+relationship empty. A stand-in is **not** a substitute: `{}` is an object
+and passes the guard, and any predicate that ignores its request will grant.
+
+**`linkage` itself is validated, and an unusable value DENIES.** `undefined`
+means "no verdict supplied" and emits today's document. Anything else must be a
+**synchronous function that answers with a boolean**. Each of the following
+drops **all** linkage on that document and logs once:
+
+- **A non-function** — `null`, `0`, `false`, `''`, `true`, a string, an object.
+  `null` is the natural return of a resolver that could not resolve a session:
+  it used to be read as "absent" and emit the full document silently.
+- **An `async` function, a generator function, or any predicate that returns a
+  promise or thenable.** `toJSON` is the `JSON.stringify` hook and cannot await
+  a verdict, and **an `async` resolver returns a promise, a promise is
+  truthy**, so every related id was published, silently, exactly as if this fix
+  were not here. If your
+  authorization lookup is asynchronous, `await` it *before* you serialize and
+  close over the result.
+- **Any answer that is not a boolean** — `{}`, `'no'`, `1`, `undefined`. A
+  non-boolean is a resolver that did not answer, and a truthy one granted.
+- **A predicate that throws**, including a `class` passed by mistake. It is
+  caught and denied; it used to escape the enclosing `JSON.stringify` and take
+  the rest of that serialization down with it.
 
 #### A predicate that ignores `context.model` makes cross-model resolution GRANT
 

package/dist/access-verdict.d.ts

@@ -55,5 +55,31 @@ export declare function interpretAccess(access: AccessMethod, operation: AccessO
  * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
  * it -- a verdict cached across requests would answer a second caller with the
  * first caller's authorization.
+ *
+ * A REQUEST IS REQUIRED, AND ITS ABSENCE IS CHECKED HERE RATHER THAN DELEGATED.
+ * This function is EXPORTED (src/index.ts), and the README's Consumer Contracts
+ * section points consumers at exactly the contexts that have no live request --
+ * a queue payload, a websocket frame, a custom route. Without one there is no
+ * caller to authorise against, and this file's header already says so: the
+ * shipped sample reads `request.path` and fail-closes when it is absent, so
+ * `getAccess('owner')(undefined, ...)` is `false`, while
+ * `getAccess('animal')(undefined, ...)` returns a per-record predicate and
+ * GRANTS. Measured on this repo's own fixture before this guard existed:
+ *
+ *   createLinkageFilter(undefined | null | {} | 'x' | 0)
+ *     -> owner=false animal=TRUE trait=TRUE category=TRUE phone-number=TRUE
+ *
+ * Four of five claimed models granted, with no log, because whether an absent
+ * request fails closed was left ENTIRELY to consumer predicates -- and a
+ * predicate that ignores its request cannot fail closed on one that is missing.
+ * A nullish or primitive `request` therefore denies every model outright and
+ * says so once, at construction, so the signal exists even for a caller that
+ * goes on to serialize nothing.
+ *
+ * WHAT THIS CANNOT CHECK: `{}` is an object and passes. There is no request
+ * contract this module owns -- `auth()` reads `.method`, the shipped sample
+ * reads `.path`, a consumer's reads whatever it likes -- so anything past
+ * "is it an object" would be this module inventing a shape for someone else's
+ * framework. The residual is documented in the README under Consumer Contracts.
  */
 export declare function createLinkageFilter(request: unknown): LinkageFilter;

package/dist/access-verdict.js

@@ -186,8 +186,40 @@ function resolveVerdict(request, type) {
  * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
  * it -- a verdict cached across requests would answer a second caller with the
  * first caller's authorization.
+ *
+ * A REQUEST IS REQUIRED, AND ITS ABSENCE IS CHECKED HERE RATHER THAN DELEGATED.
+ * This function is EXPORTED (src/index.ts), and the README's Consumer Contracts
+ * section points consumers at exactly the contexts that have no live request --
+ * a queue payload, a websocket frame, a custom route. Without one there is no
+ * caller to authorise against, and this file's header already says so: the
+ * shipped sample reads `request.path` and fail-closes when it is absent, so
+ * `getAccess('owner')(undefined, ...)` is `false`, while
+ * `getAccess('animal')(undefined, ...)` returns a per-record predicate and
+ * GRANTS. Measured on this repo's own fixture before this guard existed:
+ *
+ *   createLinkageFilter(undefined | null | {} | 'x' | 0)
+ *     -> owner=false animal=TRUE trait=TRUE category=TRUE phone-number=TRUE
+ *
+ * Four of five claimed models granted, with no log, because whether an absent
+ * request fails closed was left ENTIRELY to consumer predicates -- and a
+ * predicate that ignores its request cannot fail closed on one that is missing.
+ * A nullish or primitive `request` therefore denies every model outright and
+ * says so once, at construction, so the signal exists even for a caller that
+ * goes on to serialize nothing.
+ *
+ * WHAT THIS CANNOT CHECK: `{}` is an object and passes. There is no request
+ * contract this module owns -- `auth()` reads `.method`, the shipped sample
+ * reads `.path`, a consumer's reads whatever it likes -- so anything past
+ * "is it an object" would be this module inventing a shape for someone else's
+ * framework. The residual is documented in the README under Consumer Contracts.
  */
 export function createLinkageFilter(request) {
+    if (typeof request !== 'object' || request === null) {
+        log.error?.(`[@stonyx/orm] createLinkageFilter() was called with no request (received ${request === null ? 'null' : typeof request}) -- there is no caller to authorise against, so ALL relationship linkage it is asked about is denied.`);
+        return function isLinkable(_type, _record) {
+            return false;
+        };
+    }
     const byType = new Map();
     return function isLinkable(type, record) {
         let entry = byType.get(type);

package/dist/record.js

@@ -3,6 +3,24 @@ 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 = {};
@@ -93,54 +111,128 @@ export default class Record {
         }
         // `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 and may be ANY value. Three
-        // readings, and the difference between the second and the third is a
-        // security decision:
+        // 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".
         //
-        //   ABSENT (`undefined`). 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).
+        //      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.
         //
-        //   A FUNCTION. Apply it per related record.
+        //      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.
         //
-        //   ANYTHING ELSE -- `null`, `0`, `false`, `''`, `true`, a string, an
-        //   object. DENY, and say so. Neither of the two obvious alternatives is
-        //   available. 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. Reading it as a function
-        //   raises `TypeError: linkage is not a function` out of the enclosing
-        //   `JSON.stringify` -- measured on `true`, `'x'` and `{}` -- which is
-        //   exactly the outcome the comment below promises cannot happen.
+        //   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 silently returned `null` will ever get.
+        // 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
-            : typeof linkage === 'function' ? linkage : () => false;
-        if (linkageSupplied && typeof linkage !== 'function') {
-            log.error?.(`[@stonyx/orm] toJSON() received a \`linkage\` option of type ${linkage === null ? 'null' : typeof linkage} -- it must be a function, so ALL relationship linkage on this \`${modelName}\` document is denied.`);
-        }
+            : 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;
-            // The linkage decision is applied HERE, alongside the existing
-            // `__model` liveness check, and it produces 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. It never throws: a throw here escapes the enclosing
-            // `JSON.stringify` and takes `console.log` and `Orm.db.save()`'s
-            // neighbours with it, which is a far worse failure mode than a status.
-            const isLinkable = (r) => !linkageVerdict || linkageVerdict(r.__model.__name, r);
             const relationshipData = Array.isArray(childRecord)
                 ? 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;

package/package.json

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

package/src/access-verdict.ts

@@ -206,8 +206,42 @@ function resolveVerdict(request: unknown, type: string): AccessVerdict {
  * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
  * it -- a verdict cached across requests would answer a second caller with the
  * first caller's authorization.
+ *
+ * A REQUEST IS REQUIRED, AND ITS ABSENCE IS CHECKED HERE RATHER THAN DELEGATED.
+ * This function is EXPORTED (src/index.ts), and the README's Consumer Contracts
+ * section points consumers at exactly the contexts that have no live request --
+ * a queue payload, a websocket frame, a custom route. Without one there is no
+ * caller to authorise against, and this file's header already says so: the
+ * shipped sample reads `request.path` and fail-closes when it is absent, so
+ * `getAccess('owner')(undefined, ...)` is `false`, while
+ * `getAccess('animal')(undefined, ...)` returns a per-record predicate and
+ * GRANTS. Measured on this repo's own fixture before this guard existed:
+ *
+ *   createLinkageFilter(undefined | null | {} | 'x' | 0)
+ *     -> owner=false animal=TRUE trait=TRUE category=TRUE phone-number=TRUE
+ *
+ * Four of five claimed models granted, with no log, because whether an absent
+ * request fails closed was left ENTIRELY to consumer predicates -- and a
+ * predicate that ignores its request cannot fail closed on one that is missing.
+ * A nullish or primitive `request` therefore denies every model outright and
+ * says so once, at construction, so the signal exists even for a caller that
+ * goes on to serialize nothing.
+ *
+ * WHAT THIS CANNOT CHECK: `{}` is an object and passes. There is no request
+ * contract this module owns -- `auth()` reads `.method`, the shipped sample
+ * reads `.path`, a consumer's reads whatever it likes -- so anything past
+ * "is it an object" would be this module inventing a shape for someone else's
+ * framework. The residual is documented in the README under Consumer Contracts.
  */
 export function createLinkageFilter(request: unknown): LinkageFilter {
+  if (typeof request !== 'object' || request === null) {
+    log.error?.(`[@stonyx/orm] createLinkageFilter() was called with no request (received ${request === null ? 'null' : typeof request}) -- there is no caller to authorise against, so ALL relationship linkage it is asked about is denied.`);
+
+    return function isLinkable(_type: string, _record: unknown): boolean {
+      return false;
+    };
+  }
+
   const byType = new Map<string, { verdict: AccessVerdict; decisions: Map<unknown, boolean> }>();
 
   return function isLinkable(type: string, record: unknown): boolean {

package/src/record.ts

@@ -55,6 +55,25 @@ interface JSONAPIResult {
   links?: { self: string };
 }
 
+
+/**
+ * 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: unknown): string {
+  if (verdict === null) return 'null';
+  if (Array.isArray(verdict)) return 'an array';
+
+  if ((typeof verdict === 'object' || typeof verdict === 'function')
+    && typeof (verdict as { then?: unknown }).then === 'function') return 'a Promise (or other thenable)';
+
+  return `a value of type ${typeof verdict}`;
+}
+
 export default class Record {
   /** @private */
   __data: { [key: string]: unknown } = {};
@@ -160,57 +179,138 @@ export default class Record {
 
     // `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 and may be ANY value. Three
-    // readings, and the difference between the second and the third is a
-    // security decision:
+    // 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".
     //
-    //   ABSENT (`undefined`). 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).
+    //      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.
     //
-    //   A FUNCTION. Apply it per related record.
+    //      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.
     //
-    //   ANYTHING ELSE -- `null`, `0`, `false`, `''`, `true`, a string, an
-    //   object. DENY, and say so. Neither of the two obvious alternatives is
-    //   available. 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. Reading it as a function
-    //   raises `TypeError: linkage is not a function` out of the enclosing
-    //   `JSON.stringify` -- measured on `true`, `'x'` and `{}` -- which is
-    //   exactly the outcome the comment below promises cannot happen.
+    //   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 silently returned `null` will ever get.
+    // 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: string) => {
+      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: LinkageFilter | undefined = !linkageSupplied
       ? undefined
-      : typeof linkage === 'function' ? linkage : () => false;
+      : linkageUsable ? linkage as LinkageFilter : () => 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: Record): boolean => {
+      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})`);
+      }
 
-    if (linkageSupplied && typeof linkage !== 'function') {
-      log.error?.(`[@stonyx/orm] toJSON() received a \`linkage\` option of type ${linkage === null ? 'null' : typeof linkage} -- it must be a function, so ALL relationship linkage on this \`${modelName}\` document is denied.`);
-    }
+      return false;
+    };
 
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (fields && !fields.has(key)) continue;
 
-      // The linkage decision is applied HERE, alongside the existing
-      // `__model` liveness check, and it produces 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. It never throws: a throw here escapes the enclosing
-      // `JSON.stringify` and takes `console.log` and `Orm.db.save()`'s
-      // neighbours with it, which is a far worse failure mode than a status.
-      const isLinkable = (r: Record) => !linkageVerdict || linkageVerdict(r.__model.__name, r);
-
       const relationshipData = Array.isArray(childRecord)
         ? childRecord.filter((r: Record) => r?.__model).filter(isLinkable).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
         : (childRecord && (childRecord as Record).__model && isLinkable(childRecord as Record)) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;