@stonyx/orm 0.3.2-alpha.68 → 0.3.2-alpha.69

package/README.md

@@ -350,66 +350,73 @@ Access classes define models and provide custom filtering/authorization logic.
 export default class GlobalAccess {
   models = ['owner', 'animal'];
 
-  access(request, { model, operation }) {
+  access(request, { model, operation, recordId }) {
     // `model` is the model this route was mounted for. It is assigned once, at
     // mount time, and no request can influence it — not a mount prefix, not a
     // query string, not a case-varied path, not an absolute-form request
-    // target. Nothing below parses anything, so variants 1, 2, 4 and 5 are not
-    // constructible against this predicate any more — they are history, not
-    // rules to follow. VARIANT 3 IS THE EXCEPTION AND THE CLAIM IS NARROWER
-    // THAN IT WAS: a matcher stricter than the router can still be stepped
-    // around, because the sub-path rule below is still a string comparison.
-    // Case is handled; percent-encoding is not — abofs/stonyx-orm#228.
+    // target. `recordId` is the record this route was ADDRESSED TO, decoded by
+    // the router and coerced to the key the store lookup uses. Nothing below
+    // parses anything, and since abofs/stonyx-orm#236 nothing below reads
+    // argument one AT ALL. Variants 1, 2, 4 and 5 were already unconstructible;
+    // the sub-path STRING COMPARISON that variant 3 lived in is gone too,
+    // replaced by a comparison against the decoded id. Retiring the "variant 3
+    // survives" wording at the four sites that still carry it — with the
+    // measurement that retires it, rather than by deletion — is
+    // abofs/stonyx-orm#238.
     //
     // `operation` is destructured to name the whole contract at the point of
-    // use. This sample's rules are per-model and per-sub-path rather than
+    // use. This sample's rules are per-model and per-record rather than
     // per-verb, so it does not branch on it; the permission array at the bottom
     // is where the verb is answered.
 
-    // FAIL CLOSED ON ARGUMENT TWO. `model` is absent for any caller that
-    // resolved this predicate without supplying the context, and a request this
-    // function cannot identify DENIES rather than falling through to the CRUD
-    // grant at the bottom. An unidentifiable input must never be the permissive
-    // path. Argument ONE is guarded at its own read, below — this guard does
-    // not cover it.
+    // FAIL CLOSED ON AN UNIDENTIFIABLE MODEL. `model` is absent for any caller
+    // that resolved this predicate without supplying the context, and a request
+    // this function cannot identify DENIES rather than falling through to the
+    // CRUD grant at the bottom. An unidentifiable input must never be the
+    // permissive path.
     if (typeof model !== 'string' || model === '') return false;
 
     if (model === 'owner') {
-      // The context names WHICH MODEL and WHICH VERB — not which route. Six
-      // distinct owner surfaces produce one identical context, so a rule that
-      // depends on the SUB-PATH still needs argument one. `request.path` is
-      // mount-relative and query-free, and it is the one read of the raw
-      // request the README sanctions. false → 403 for the whole request.
+      // FAIL CLOSED ON AN ABSENT `recordId` TOO, AND `undefined` IS THE ONLY
+      // SPELLING OF ABSENT. `auth()` ALWAYS sets the key — `null` on a
+      // collection route, which is addressed to no record — so `undefined`
+      // means the context did not come from `auth()`: it was hand-assembled by
+      // a caller resolving this predicate through the documented
+      // `Orm.instance.getAccess()` path. Letting that through would fall
+      // straight to the per-record filter below, which is a DENY becoming an
+      // ALLOW. This is the same rule the old guard on `request.path` enforced,
+      // moved to the argument this predicate now actually reads.
+      if (recordId === undefined) return false;
+
+      // THE `/archived` DENY, EXPRESSED AGAINST THE DECODED ID. It used to be
+      // `request.path.toLowerCase()` compared against `'/archived'`, and that
+      // was wrong in both directions at once.
       //
-      // THIS DENY CANNOT BE EXPRESSED FROM THE CONTEXT ALONE. Migrating it away
-      // does not remove a rule, it turns a deny into an ALLOW, silently.
+      // TOO PERMISSIVE: express sets `request.path` from the RAW pathname while
+      // the router DECODES `:id`, so `GET /owners/%61rchived` reached the
+      // comparison as `/%61rchived`, walked past the deny and was dispatched as
+      // the record `archived` — 200 with the record in full, and DELETE
+      // answered 204 with the record DESTROYED, unauthenticated. 255
+      // non-canonical spellings of that 8-character id decode to the same key,
+      // so no deny-list of spellings was ever going to close it.
       //
-      // FAIL CLOSED ON ARGUMENT ONE TOO. The guard above covers the context;
-      // this one covers the request, and since #202 they are two different
-      // objects. A caller that resolves this predicate through the documented
-      // `Orm.instance.getAccess()` path and hand-assembles a request can supply
-      // a perfectly valid context with no usable `path` — and
-      // `String(request.path ?? '')` is then `''`, which matches no sub-path
-      // rule and falls straight through to the per-record filter below. That is
-      // a DENY becoming an ALLOW. An input this function cannot identify DENIES,
-      // whichever ARGUMENT it arrived on — which is also why the `?? ''` this
-      // file's header condemns does not appear below.
-      if (typeof request?.path !== 'string' || request.path === '') return false;
-
-      // Lower-cased because the router matched case-insensitively, so a
-      // case-sensitive rule here would be stricter than the router and could be
-      // stepped around.
+      // TOO STRICT: 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`, the `.toLowerCase()` 403'd
+      // `GET /owners/ARCHIVED` — the wrong record — while still admitting
+      // `GET /owners/%41RCHIVED`, the same record encoded.
       //
-      // CASE-FOLDING ALONE IS NOT A SUFFICIENT NORMALISATION, and this line is
-      // not a recipe for one. Express sets `request.path` from the RAW pathname
-      // while the router DECODES `:id`, so `GET /owners/%61rchived` reaches this
-      // comparison as `/%61rchived`, walks past the deny, and is dispatched as
-      // the record `archived` — abofs/stonyx-orm#228. A matcher must normalise
-      // the way the router that dispatched the request does. Record ids are
-      // case-sensitive and must be compared at their real case.
-      const path = request.path.toLowerCase();
-
-      if (path === '/archived' || path.startsWith('/archived/')) return false;
+      // SO DO NOT NORMALISE `recordId`. It is already decoded, exactly ONCE,
+      // which is what a route parameter means: `/owners/%2561rchived` is the
+      // legitimate id `%61rchived`, and decoding until stable would deny it. Do
+      // not case-fold it. Do not rebuild it from `request.path` — decoding the
+      // whole path decodes THEN splits while the router splits THEN decodes,
+      // which over-denies the distinct record at `/owners/archived%2fx`.
+      //
+      // THE DENY IS NOW EXPRESSIBLE FROM THE CONTEXT ALONE, which is exactly
+      // what `recordId` bought — and it still must not be dropped. Deleting it
+      // does not remove a rule loudly, it turns a deny into an ALLOW, silently.
+      if (recordId === 'archived') return false;
 
       // Returning a function plugs it in as a per-record filter, and it is
       // enforced on every surface addressed to one of these records:
@@ -864,50 +871,7 @@ per-record filter. An input you cannot identify must **deny**.
   related record without resolving that model's own access class, so a filter on
   `/owners` does not hide an owner reached through `/animals`. Tracked as
   [#196](https://github.com/abofs/stonyx-orm/issues/196), which covers
-  `include=`, related-resource routes and relationship-linkage routes. This is
-  **membership** — whether the related resource is served at all — and it is a
-  different question from which ids a document may *name*, immediately below.
-- **Relationship linkage is filtered on the four request-bound read surfaces,
-  and only there.** A document's `relationships.*.data` used to publish the id
-  of every related record unconditionally, so a record hidden on every one of
-  its own surfaces was still named inside another model's document — with no
-  `include=`, no relationship route and no query string
-  ([#234](https://github.com/abofs/stonyx-orm/issues/234)). It is now filtered
-  through the related model's own access class on `GET /:models`,
-  `GET /:models/:id` and both `GET /:models/:id/{relationship}` shapes. A
-  filtered-out relationship is **indistinguishable from a genuinely empty one** —
-  an emptied `hasMany` is `data: []` and an emptied `belongsTo` is `data: null`,
-  both **keeping their `links`**, which are built from the serialized record's
-  own id and never from the related one. Nothing errors and no status changes,
-  because throwing here would be an existence oracle *and* would throw out of
-  the enclosing `JSON.stringify`. **Not yet covered:** `included`
-  ([#233](https://github.com/abofs/stonyx-orm/issues/233) owns whether a
-  resource appears there at all), the `POST`/`PATCH` response documents, and
-  `GET /:models/:id/relationships/{relationship}`, whose *primary data* is
-  linkage ([#196](https://github.com/abofs/stonyx-orm/issues/196)).
-- **A bare `toJSON()` still emits unfiltered linkage, and that is deliberate.**
-  `Record.toJSON()` **applies** a verdict; it never **resolves** one. It has no
-  request, and the documented `access()` contract permits a predicate to read
-  one — the sample in this README does, for its sub-path rule — so a filter
-  resolved inside `toJSON()` denies *permitted* records rather than hidden ones
-  (measured: 967 → 964, all three failures over-denials). `toJSON` is also the
-  `JSON.stringify` hook, so `JSON.stringify(record)`, `res.json(record)` and
-  `console.log(JSON.stringify(record))` reach it with a **string** in the
-  options slot and have no syntactic place to pass a verdict. The no-argument
-  call therefore returns the pre-#234 document unchanged. Fail-closed by default
-  is not available either: `Orm.instance.accessFunctions` is `{}` in any process
-  that never ran `setup-rest-server` — a CLI, an SQL-only process, a test — so
-  it would empty every relationship on every document in processes with no REST
-  surface to protect. Closing the residual means moving JSON:API serialization
-  **off** the `toJSON` name, tracked as
-  [#230](https://github.com/abofs/stonyx-orm/issues/230). If you hand a `Record`
-  to an untrusted consumer, serialize it through the REST layer or pass your own
-  resolved `linkage` option.
-- **`format()` and `serialize()` are deliberately not filtered, and must stay
-  that way.** `format()` is the **persistence** path — its output is what
-  `Orm.db.save()` writes to disk — so applying an access filter there would
-  write a truncated database. That is **data loss**, not disclosure prevention.
-  Neither method appears anywhere in the REST response path.
+  `include=`, related-resource routes and relationship-linkage routes.
 - **A before-hook that returns a value short-circuits the request.** On write
   operations addressed to a record the filter is consulted first, so a hook
   cannot answer for a record the caller may not see. On reads it is not, so a

package/dist/orm-request.js

@@ -219,7 +219,6 @@ 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',
@@ -562,13 +561,7 @@ export default class OrmRequest extends Request {
             if (queryFilterPredicate)
                 recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
             const baseUrl = getBaseUrl(request);
-            // 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 }));
+            const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
             return buildResponse(data, request.query?.include, recordsToReturn, {
                 links: { self: `${baseUrl}/${pluralizedModel}` },
                 baseUrl
@@ -586,13 +579,7 @@ export default class OrmRequest extends Request {
             const fieldsMap = parseFields(request.query);
             const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
             const baseUrl = getBaseUrl(request);
-            const linkage = createLinkageFilter(request);
-            // `buildResponse` is deliberately NOT given the linkage filter. It builds
-            // `included`, and WHETHER A RESOURCE APPEARS THERE AT ALL is membership,
-            // which belongs to abofs/stonyx-orm#233 -- see this file's #234 note and
-            // the ownership boundary in that issue. Only the PRIMARY document's
-            // linkage is filtered here.
-            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
+            return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
                 links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
                 baseUrl
             });
@@ -1179,21 +1166,15 @@ 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, linkage }));
+                    data = related.map(r => r.toJSON?.({ baseUrl }));
                 }
                 else {
                     // belongsTo - return single or null
-                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
+                    data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
                 }
                 return {
                     links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}/${dasherizedName}` },
@@ -1288,10 +1269,53 @@ export default class OrmRequest extends Request {
         // src/types/orm-types.ts. Nothing is fetched at this point and adding a
         // lookup here would put a store read in the middle of an authorization
         // path. The function return shape below IS the per-record hook.
+        //
+        // -------------------------------------------------------------------------
+        // #236 -- `recordId`, the DECODED route-parameter id, for the same reason.
+        //
+        // WHICH RECORD is the third structural fact the framework already holds and
+        // the consumer was left to re-derive, and re-deriving it failed OPEN. The
+        // documented sample compared `request.path` -- the RAW, undecoded pathname
+        // -- against a literal `/archived`, while the router DECODES `:id`. So
+        // `GET /owners/%61rchived` walked past the deny and was dispatched as the
+        // record `archived`: 200 with the record in full, and DELETE answered 204
+        // with the record destroyed, unauthenticated. Four spellings measured, all
+        // four through; 255 non-canonical spellings of that 8-character id decode
+        // to the same key, so this was never a deny-list of one.
+        //
+        // TWO CONSUMER-SIDE NORMALISATIONS WERE MEASURED WRONG IN OPPOSITE
+        // DIRECTIONS, which is the argument for doing it once, here.
+        // `.toLowerCase()` case-folds a route-parameter VALUE on the axis that
+        // governs literal SEGMENTS: with a distinct owner seeded at `ARCHIVED`,
+        // `GET /owners/ARCHIVED` was a false DENY on the wrong record and
+        // `GET /owners/%41RCHIVED` a false ALLOW on that same one.
+        // `decodeURIComponent(request.path)` decodes THEN splits while the router
+        // splits THEN decodes, so it over-denied `/owners/archived%2fx` -- 403 for
+        // a genuinely distinct record. Failing closed there was luck, not design.
+        //
+        // `getId(request.params)` AND NOT `request.params.id`, for exactly the
+        // reason `operation` is a `methodAccessMap` lookup: it is the SAME single
+        // coercion the store lookup one layer down performs, so the predicate and
+        // the dispatch cannot disagree about which record a request addresses.
+        // The raw string would reintroduce that divergence on hex-shaped ids --
+        // `GET /animals/0x2391` looks up record `9105`.
+        //
+        // NOTHING HERE PARSES THE REQUEST TARGET EITHER. `request.params` is what
+        // the router matched, so a mount prefix, an absolute-form target, a query
+        // string or a case-varied mount cannot move this value -- the same
+        // guarantee `model` carries, by the same means.
+        //
+        // `null` and not `undefined` on a collection route, so the KEY IS ALWAYS
+        // PRESENT -- the rule `operation`'s own docblock already establishes. A
+        // context reaching a predicate WITHOUT the key therefore did not come from
+        // here; it was hand-assembled by a caller resolving the predicate through
+        // `Orm.instance.getAccess()`, and that absence stays deniable only because
+        // `auth()` never produces it.
         // -------------------------------------------------------------------------
         const context = {
             model: this.model,
             operation: methodAccessMap[request.method],
+            recordId: request.params && 'id' in request.params ? getId(request.params) : null,
         };
         let access;
         try {
@@ -1304,23 +1328,26 @@ 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
         }
-        // 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)
+        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]))
             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

@@ -2,18 +2,6 @@ import type Serializer from './serializer.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).
-     */
-    linkage?: (type: string, record: unknown) => boolean;
 }
 interface SerializeOptions {
     update?: boolean;

package/dist/record.js

@@ -65,13 +65,7 @@ export default class Record {
     toJSON(options = {}) {
         if (!this.__serialized)
             throw new Error('Record must be serialized before being converted to JSON');
-        // 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 { fields, baseUrl } = options;
         const { __data: data } = this;
         const modelName = this.__model.__name;
         const pluralizedModelName = getPluralName(modelName);
@@ -93,20 +87,9 @@ export default class Record {
         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) => !linkage || linkage(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;
+                ? 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;
             // 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,18 +87,9 @@ 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?: (type: string, record: unknown) => boolean;
     }): Record<string, unknown>;
     [key: string]: unknown;
 }
@@ -251,6 +242,72 @@ 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 IS THE ONE KEY THE HOOK VOCABULARY DOES *NOT* DISAGREE WITH.
+     * `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'`. Here they AGREE, and not by coincidence: `_withHooks` sets
+     * `context.recordId = getId(request.params)`, the same single coercion this
+     * key is built from. They differ in ONE way and it is the absence spelling --
+     * `HookContext.recordId` is optional and `undefined` when unset, while this
+     * key is always present and `null` on a collection route. A predicate must
+     * not read `undefined` here as "collection".
+     *
+     * 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.

package/package.json

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

package/src/orm-request.ts

@@ -221,7 +221,6 @@ import config from 'stonyx/config';
 import log from 'stonyx/log';
 import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
 import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
-import { interpretAccess, createLinkageFilter } from './access-verdict.js';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -634,14 +633,7 @@ export default class OrmRequest extends Request {
       if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate as (record: OrmRecord) => boolean);
 
       const baseUrl = getBaseUrl(request);
-
-      // 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 }));
+      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
@@ -661,14 +653,7 @@ export default class OrmRequest extends Request {
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
       const baseUrl = getBaseUrl(request);
-      const linkage = createLinkageFilter(request);
-
-      // `buildResponse` is deliberately NOT given the linkage filter. It builds
-      // `included`, and WHETHER A RESOURCE APPEARS THERE AT ALL is membership,
-      // which belongs to abofs/stonyx-orm#233 -- see this file's #234 note and
-      // the ownership boundary in that issue. Only the PRIMARY document's
-      // linkage is filtered here.
-      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl, linkage }), request.query?.include, record, {
+      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
         baseUrl
       });
@@ -1298,21 +1283,14 @@ export default class OrmRequest extends Request {
         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: unknown;
         if (info.isArray) {
           // hasMany - return array
           const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
-          data = related.map(r => r.toJSON?.({ baseUrl, linkage }));
+          data = related.map(r => r.toJSON?.({ baseUrl }));
         } else {
           // belongsTo - return single or null
-          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl, linkage }) : null;
+          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
         }
 
         return {
@@ -1411,10 +1389,53 @@ export default class OrmRequest extends Request {
     // src/types/orm-types.ts. Nothing is fetched at this point and adding a
     // lookup here would put a store read in the middle of an authorization
     // path. The function return shape below IS the per-record hook.
+    //
+    // -------------------------------------------------------------------------
+    // #236 -- `recordId`, the DECODED route-parameter id, for the same reason.
+    //
+    // WHICH RECORD is the third structural fact the framework already holds and
+    // the consumer was left to re-derive, and re-deriving it failed OPEN. The
+    // documented sample compared `request.path` -- the RAW, undecoded pathname
+    // -- against a literal `/archived`, while the router DECODES `:id`. So
+    // `GET /owners/%61rchived` walked past the deny and was dispatched as the
+    // record `archived`: 200 with the record in full, and DELETE answered 204
+    // with the record destroyed, unauthenticated. Four spellings measured, all
+    // four through; 255 non-canonical spellings of that 8-character id decode
+    // to the same key, so this was never a deny-list of one.
+    //
+    // TWO CONSUMER-SIDE NORMALISATIONS WERE MEASURED WRONG IN OPPOSITE
+    // DIRECTIONS, which is the argument for doing it once, here.
+    // `.toLowerCase()` case-folds a route-parameter VALUE on the axis that
+    // governs literal SEGMENTS: with a distinct owner seeded at `ARCHIVED`,
+    // `GET /owners/ARCHIVED` was a false DENY on the wrong record and
+    // `GET /owners/%41RCHIVED` a false ALLOW on that same one.
+    // `decodeURIComponent(request.path)` decodes THEN splits while the router
+    // splits THEN decodes, so it over-denied `/owners/archived%2fx` -- 403 for
+    // a genuinely distinct record. Failing closed there was luck, not design.
+    //
+    // `getId(request.params)` AND NOT `request.params.id`, for exactly the
+    // reason `operation` is a `methodAccessMap` lookup: it is the SAME single
+    // coercion the store lookup one layer down performs, so the predicate and
+    // the dispatch cannot disagree about which record a request addresses.
+    // The raw string would reintroduce that divergence on hex-shaped ids --
+    // `GET /animals/0x2391` looks up record `9105`.
+    //
+    // NOTHING HERE PARSES THE REQUEST TARGET EITHER. `request.params` is what
+    // the router matched, so a mount prefix, an absolute-form target, a query
+    // string or a case-varied mount cannot move this value -- the same
+    // guarantee `model` carries, by the same means.
+    //
+    // `null` and not `undefined` on a collection route, so the KEY IS ALWAYS
+    // PRESENT -- the rule `operation`'s own docblock already establishes. A
+    // context reaching a predicate WITHOUT the key therefore did not come from
+    // here; it was hand-assembled by a caller resolving the predicate through
+    // `Orm.instance.getAccess()`, and that absence stays deniable only because
+    // `auth()` never produces it.
     // -------------------------------------------------------------------------
     const context: AccessContext = {
       model: this.model,
       operation: methodAccessMap[request.method],
+      recordId: request.params && 'id' in request.params ? getId(request.params) : null,
     };
 
     let access: AccessMethod;
@@ -1429,23 +1450,24 @@ export default class OrmRequest extends Request {
       return 403; // Forbidden
     }
 
-    // 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;
+    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])) return 403;
 
     return undefined;
   }

package/src/record.ts

@@ -7,18 +7,6 @@ import type Serializer from './serializer.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).
-   */
-  linkage?: (type: string, record: unknown) => boolean;
 }
 
 interface SerializeOptions {
@@ -128,13 +116,7 @@ export default class Record {
   toJSON(options: ToJSONOptions = {}): JSONAPIResult {
     if (!this.__serialized) throw new Error('Record must be serialized before being converted to JSON');
 
-    // 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 { fields, baseUrl } = options;
     const { __data: data } = this;
     const modelName = this.__model.__name;
     const pluralizedModelName = getPluralName(modelName);
@@ -156,21 +138,9 @@ export default class Record {
     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) => !linkage || linkage(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;
+        ? childRecord.filter((r: Record) => r?.__model).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
+        : (childRecord && (childRecord as Record).__model) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
 
       // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
       const dasherizedKey = camelCaseToKebabCase(key);

package/src/types/orm-types.ts

@@ -89,15 +89,7 @@ export interface OrmRecord {
   __model?: { __name: string };
   __data: Record<string, unknown> & { id?: string | number; __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?: (type: string, record: unknown) => boolean }): Record<string, unknown>;
+  toJSON?(options?: { fields?: Set<string>; baseUrl?: string }): Record<string, unknown>;
   [key: string]: unknown;
 }
 
@@ -260,6 +252,73 @@ 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 IS THE ONE KEY THE HOOK VOCABULARY DOES *NOT* DISAGREE WITH.
+   * `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'`. Here they AGREE, and not by coincidence: `_withHooks` sets
+   * `context.recordId = getId(request.params)`, the same single coercion this
+   * key is built from. They differ in ONE way and it is the absence spelling --
+   * `HookContext.recordId` is optional and `undefined` when unset, while this
+   * key is always present and `null` on a collection route. A predicate must
+   * not read `undefined` here as "collection".
+   *
+   * 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;
 }
 
 /**

package/dist/access-verdict.d.ts

@@ -1,57 +0,0 @@
-import type { AccessMethod, AccessOperation } 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;
-}
-/**
- * A resolved, request-scoped linkage decision: may `record` of model `type` be
- * NAMED, by id, inside another model's document?
- *
- * Arity is `(type, record)` and not `(type, id)` because the per-record filter
- * the 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, not the input.
- */
-export type LinkageFilter = (type: string, record: unknown) => boolean;
-/**
- * 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 declare function interpretAccess(access: AccessMethod, operation: AccessOperation | undefined): AccessVerdict;
-/**
- * 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}` ``
- * would collapse them and let one model's verdict answer for another record.
- *
- * 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 declare function createLinkageFilter(request: unknown): LinkageFilter;

package/dist/access-verdict.js

@@ -1,185 +0,0 @@
-/**
- * The shared access-verdict primitive (abofs/stonyx-orm#234).
- *
- * ---------------------------------------------------------------------------
- * WHY THIS FILE EXISTS: ONE INTERPRETER, NOT TWO
- * ---------------------------------------------------------------------------
- * A consumer `access()` may return six differently-shaped things -- `false`, a
- * bare permission string, a permission array, `true`, a per-record function, or
- * something the contract does not define at all -- and the reading of each one
- * is a security decision. `auth()` has held that reading inline since #190.
- * Every surface that needs to ask "may this caller see model X's record?" needs
- * the SAME reading, or the second copy becomes an unreviewed second
- * authorization vocabulary that answers differently about the same value.
- *
- * So `interpretAccess` is extracted here and `auth()` now calls it. It is the
- * only place a return shape is classified, and abofs/stonyx-orm#232 and #233
- * rebase onto it rather than re-deriving it.
- *
- * ---------------------------------------------------------------------------
- * WHAT A LINKAGE FILTER IS, AND WHY THE CALLER BUILDS IT
- * ---------------------------------------------------------------------------
- * `Record.toJSON()` APPLIES a verdict; it never RESOLVES one. That is not a
- * style choice, it is forced, and it was measured before it was decided:
- *
- *   INPUT: origin/dev @ c5f7907, unpatched                  -> 967 pass / 0 fail
- *   INPUT: same + fail-closed resolution INSIDE toJSON()    -> 964 pass / 3 fail
- *
- * and all three reds were over-denial of PERMITTED records, not the leak. Two
- * independent reasons:
- *
- *   1. `toJSON()` has no request. The shipped, documented sample reads
- *      `request.path` for its `/archived` sub-path rule -- the one read of
- *      argument one the README sanctions -- and fail-closes when it is absent.
- *      Measured against the live registry:
- *
- *        getAccess('owner')(undefined, { model:'owner',  operation:'read' }) -> false
- *        getAccess('animal')(undefined,{ model:'animal', operation:'read' }) -> [Function]
- *
- *      Same predicate object, two models, two different degradation modes,
- *      chosen by the consumer. Without a request there is no trustworthy
- *      answer to get.
- *
- *   2. `toJSON` is also the `JSON.stringify` hook, so `JSON.stringify({data:
- *      record})` calls `record.toJSON('data')` -- a STRING in the options slot.
- *      An implicit caller has no syntactic place to pass anything
- *      (abofs/stonyx-orm#230). The no-argument document must therefore stay
- *      byte-identical to what shipped, which also rules out fail-closed by
- *      default: `Orm.instance.accessFunctions` is `{}` in any process that
- *      never ran `setup-rest-server` (CLI, SQL-only, unit tests), so a
- *      fail-closed default would empty every relationship on every document in
- *      processes that have no REST surface to protect.
- *
- * The caller -- which still holds the request -- resolves the predicate,
- * interprets it here, caches the answer, and hands `toJSON()` an already-decided
- * `(type, record) => boolean`.
- */
-import Orm from '@stonyx/orm';
-import log from 'stonyx/log';
-const DENIED = Object.freeze({ granted: false });
-const GRANTED = Object.freeze({ granted: true });
-/**
- * Classify one `access()` return value. Extracted verbatim from `auth()`, which
- * now calls this; the branch ORDER is load-bearing and is preserved exactly.
- *
- * `operation` is the verb being authorised. `undefined` -- reachable, because
- * express delivers HEAD to the GET handler and `methodAccessMap` has no entry
- * for it -- falls through `permitted.includes(undefined)` to a denial, which is
- * the same answer `auth()` gave before the extraction.
- */
-export function interpretAccess(access, operation) {
-    if (!access)
-        return DENIED;
-    // The function return shape IS the per-record hook. Grant the request and
-    // carry the predicate; the caller applies it per record.
-    if (typeof access === 'function')
-        return { granted: true, filter: access };
-    if (access === true)
-        return GRANTED;
-    // `AccessMethod` declares `string` legal and it fell through every branch
-    // above. A bare string is ONE permission, not a grant of all four -- reading
-    // it as a full grant is what once let `return 'read'` authorise DELETE.
-    const permitted = typeof access === 'string' ? [access] : access;
-    // Anything that is not a permission array by this point -- an object, a
-    // number, a Symbol -- is a consumer mistake, and the only safe reading of a
-    // shape the contract does not define is a denial. Fail CLOSED.
-    if (!Array.isArray(permitted))
-        return DENIED;
-    if (!permitted.includes(operation))
-        return DENIED;
-    return GRANTED;
-}
-/**
- * Resolve model `type`'s verdict for a read, against the live `request`.
- *
- * Fails closed on both ambiguous inputs:
- *
- *   - `getAccess(type)` -> `undefined`. That is NOT "this model is
- *     unrestricted". `setup-rest-server` catches an access-class load failure,
- *     warns, and publishes whatever PARTIAL map it had, so `undefined` covers
- *     both "no access class claims this model" and "the class that claims it
- *     failed to load" -- and the caller cannot tell them apart. Deny.
- *   - the predicate THROWS. Same reading `auth()` and `isDenied` already use:
- *     a throw is a denial, logged, never a 500 and never a grant.
- *
- * NOTE ON CROSS-MODEL ASKS. The predicate is asked about `type` while the
- * request in hand was dispatched to a DIFFERENT model's route. Since #222 this
- * repo's fixture reads `context.model` and answers correctly; 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). A
- * consequence to expect rather than debug: the fixture's surviving `request.path`
- * read means asking the OWNER predicate on a request dispatched to
- * `GET /animals/archived` returns a bare `false`. That is a whole-request deny
- * bleeding across models -- harmless, because it is the fail-closed direction,
- * and it is treated as "deny this linkage", not as an error.
- */
-function resolveVerdict(request, type) {
-    const predicate = Orm.instance?.getAccess?.(type);
-    if (typeof predicate !== 'function')
-        return DENIED;
-    let access;
-    try {
-        access = predicate(request, { model: type, operation: 'read' });
-    }
-    catch (error) {
-        log.error?.(`[@stonyx/orm] access() threw while resolving linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
-        return DENIED;
-    }
-    return interpretAccess(access, 'read');
-}
-/**
- * Build a request-scoped linkage filter.
- *
- * TWO CACHES, AND BOTH ARE LOAD-BEARING RATHER THAN AN OPTIMISATION:
- *
- *   - one verdict per TYPE. Resolving means CALLING the consumer's `access()`,
- *     which is arbitrary code with arbitrary cost and which the module has
- *     already had to guard for throwing.
- *   - one decision per `(type, id)`. `included` is deduplicated by
- *     `buildResponse`; LINKAGE is not deduplicated at all, so it re-asks once
- *     per record. Measured on a bare `GET /animals` with no `include=`:
- *     48 linkage entries -> 7 distinct `(type, id)` pairs (owner 20, trait 28),
- *     a 6.9x reduction and 41 predicate calls saved.
- *
- * The `(type, id)` cache is a `Map` per type keyed on the RAW id, not on a
- * template-string composite: `Map` compares with SameValueZero, so the numeric
- * id `1` and the string id `'1'` stay distinct, where `` `${type}:${id}` ``
- * would collapse them and let one model's verdict answer for another record.
- *
- * SCOPE IS ONE REQUEST. The filter closes over the request and must not outlive
- * it -- a verdict cached across requests would answer a second caller with the
- * first caller's authorization.
- */
-export function createLinkageFilter(request) {
-    const byType = new Map();
-    return function isLinkable(type, record) {
-        let entry = byType.get(type);
-        if (!entry) {
-            entry = { verdict: resolveVerdict(request, type), decisions: new Map() };
-            byType.set(type, entry);
-        }
-        const { verdict, decisions } = entry;
-        if (!verdict.granted)
-            return false;
-        if (!verdict.filter)
-            return true;
-        const id = record?.id;
-        const cached = decisions.get(id);
-        if (cached !== undefined)
-            return cached;
-        let allowed;
-        try {
-            allowed = Boolean(verdict.filter(record));
-        }
-        catch (error) {
-            // A predicate that throws is a denial -- the same reading `isDenied` uses
-            // one layer down. Logged, because a predicate that throws on every record
-            // empties every relationship and, silently, that is indistinguishable
-            // from a database with no relationships in it.
-            log.error?.(`[@stonyx/orm] access filter threw while filtering linkage for model "${type}" -- denying. ${error instanceof Error ? error.message : String(error)}`);
-            allowed = false;
-        }
-        decisions.set(id, allowed);
-        return allowed;
-    };
-}

package/src/access-verdict.ts

@@ -1,222 +0,0 @@
-/**
- * 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 } 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;
-}
-
-/**
- * A resolved, request-scoped linkage decision: may `record` of model `type` be
- * NAMED, by id, inside another model's document?
- *
- * Arity is `(type, record)` and not `(type, id)` because the per-record filter
- * the 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, not the input.
- */
-export type LinkageFilter = (type: string, 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. The predicate is asked about `type` while the
- * request in hand was dispatched to a DIFFERENT model's route. Since #222 this
- * repo's fixture reads `context.model` and answers correctly; 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). A
- * consequence to expect rather than debug: the fixture's surviving `request.path`
- * read means asking the OWNER predicate on a request dispatched to
- * `GET /animals/archived` returns a bare `false`. That is a whole-request deny
- * bleeding across models -- harmless, because it is the fail-closed direction,
- * and it is treated as "deny this linkage", not as an error.
- */
-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}` ``
- * would collapse them and let one model's verdict answer for another record.
- *
- * 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;
-  };
-}