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

package/dist/record.js

@@ -1,4 +1,5 @@
 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';
@@ -65,7 +66,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 +91,59 @@ 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 and may be ANY value. Three
+        // readings, and the difference between the second and the third is a
+        // security decision:
+        //
+        //   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 FUNCTION. Apply it per related record.
+        //
+        //   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.
+        //
+        // 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.
+        const linkageSupplied = linkage !== undefined;
+        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.`);
+        }
         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).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,101 +251,6 @@ 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.
@@ -358,3 +272,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-alpha.70",
+  "version": "0.3.2-alpha.71",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/access-verdict.ts

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

package/src/hooks.ts

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

package/src/index.ts

@@ -28,6 +28,15 @@ 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'; // access() contract (#202)
+export type { LinkageFilter } from './types/orm-types.js'; // linkage verdict contract (#234)
+// 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