@stonyx/orm 0.3.2-beta.153 → 0.3.2-beta.154

package/README.md

@@ -381,6 +381,174 @@ export default class GlobalAccess {
 }
 ```
 
+
+### The access context (second argument)
+
+`access()` is called with **two** arguments:
+
+```js
+access(request, { model, operation })
+```
+
+The second is the **access context** — the structural facts about the request,
+which the framework already holds at authorization time. Read these instead of
+parsing anything.
+
+| Key | Value |
+|---|---|
+| `model` | The model this route was mounted for, as a **model name**: kebab-case, exactly as declared under `config.orm.paths.model` and keyed in the store — `'owner'`, `'animal'`, `'phone-number'`. **Not** the pluralized, dasherized, mount-prefixed *route* name. |
+| `operation` | One of **`'read'`, `'create'`, `'update'`, `'delete'`** — and no second vocabulary *on this path*. Never an HTTP method name like `'GET'`, and **not** the hook vocabulary either (see [below](#operation-is-not-the-hook-operation)). `undefined` when the dispatched method has no entry in the framework's method map. |
+
+So a predicate can be written without reference to any URL:
+
+```js
+export default class OwnerAccess {
+  models = ['owner'];
+
+  access(request, { model, operation }) {
+    if (model === 'owner' && operation === 'read') {
+      return record => record.id !== 'angela';
+    }
+
+    return ['read'];
+  }
+}
+```
+
+There is no string to parse, no variant to miss, and no way to fail open through
+a URL shape nobody anticipated. `model` is fixed 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.
+
+#### What the context does not tell you: which surface
+
+It names **which model and which verb**, not **which route**. Measured over the
+live router, six surfaces produce one identical context:
+
+```
+GET /owners                          { model: 'owner', operation: 'read' }
+GET /owners/gina                     { model: 'owner', operation: 'read' }
+GET /owners/gina/pets                { model: 'owner', operation: 'read' }
+GET /owners/gina/relationships/pets  { model: 'owner', operation: 'read' }
+GET /owners/archived                 { model: 'owner', operation: 'read' }
+GET /owners/gina?include=pets        { model: 'owner', operation: 'read' }
+```
+
+So a rule that depends on the **sub-path** still needs `request.path` —
+mount-relative and query-free, and the one read of argument one that
+[Identifying the collection](#identifying-the-collection) sanctions. The sample
+access class shipped with this repo has such a rule: its `/archived` deny
+**cannot be expressed from the context alone**, and a predicate migrated to
+context-only would silently drop it — a deny becoming an allow.
+
+Note also that the related-resource and `?include=` surfaces serve *another
+model's* records under `model: 'owner'`, and the context gives a predicate no
+signal that it is authorizing a related-resource route. That is
+[#196](https://github.com/abofs/stonyx-orm/issues/196).
+
+#### `operation` is not the hook `operation`
+
+This module exposes a **second** `operation` vocabulary, on an identically-named
+key of an identically-shaped context object:
+[hook contexts](#hook-context-object) carry `list` / `get` / `create` /
+`update` / `delete`. The access vocabulary collapses `list` and `get` into
+`'read'`, so for one `GET /animals/1` a hook sees `'get'` while `access()` sees
+`'read'` — and a predicate cannot distinguish a collection read from a
+record read.
+
+"No second vocabulary" above is a statement about the **access path**, where
+both the context and the permission array come from one method map. It is not a
+statement about the module. Writing `operation === 'get'` in a predicate never
+matches, and a predicate that stops matching falls through to the permission
+array — so the misreading is fail-open shaped. In TypeScript the exported
+`AccessOperation` union makes it a compile error.
+
+The four `operation` values are the same four strings the permission-array
+return shape is written in (`['read', 'create', 'update', 'delete']`), because
+both come from one method map inside the framework. The two forms cannot
+disagree about the same request.
+
+**`operation` is `undefined`, never defaulted, for an unmapped method.** Express
+delivers `HEAD` to the `GET` handler, so this is reachable. It is deliberately
+not defaulted to `'read'`: a fabricated operation would turn an unclassified
+request into an authorized one. Treat `undefined` as *not classified* and deny.
+
+**The second argument is additive.** JavaScript ignores extra arguments, so an
+existing `access(request)` predicate keeps working exactly as it did. Nothing
+needs to be migrated to keep running — but note that argument **one** is still
+the raw request, so the warning in
+[Identifying the collection](#identifying-the-collection) still applies to any
+predicate that reads it.
+
+#### `record` is not in the context
+
+Deliberately, and it is not an oversight. `auth()` runs after route matching but
+**before any handler executes**, so nothing has been fetched yet. Supplying a
+record would force a pre-fetch on every request — a second store hit, a new
+failure mode, and an ordering change in the middle of an authorization path.
+
+It is also unnecessary: the **function** return shape already *is* the
+per-record hook. Return `(record) => boolean` and the handlers apply it to every
+record the request touches. Auth-time and record-time are separate decision
+points, and the contract keeps them separate.
+
+#### Reaching another model's predicate
+
+The model → predicate map is published on the ORM instance at boot, before any
+route is mounted, so a predicate can be resolved by model name and asked about a
+request routed to a *different* model:
+
+```js
+import Orm from '@stonyx/orm';
+
+const predicate = Orm.instance.getAccess('animal');
+if (!predicate) return deny;
+
+const verdict = predicate(request, { model: 'animal', operation: 'read' });
+```
+
+**`undefined` means no predicate could be resolved — not that the model is
+unrestricted. Treat it as deny.** It covers a model with no access class *and* a
+model whose access class failed to **load**: a load failure is caught and warned
+about, and the partial map is published anyway, so a missing key is not evidence
+of an unrestricted model. This is the same rule as `operation === undefined`
+above, and for the same reason.
+
+The raw map is `Orm.instance.accessFunctions`, keyed by model name; prefer
+`getAccess()` — it is guarded against inherited `Object.prototype` members and a
+direct index is not. Note that it maps a model name to the predicate of the
+access *class* that claims it, which may claim many models: against this repo's
+sample, `getAccess('owner') === getAccess('animal')`.
+
+#### Passing the context makes a model-correct answer *possible*
+
+It does not make the answer model-correct on its own. **The resolved predicate
+has to read the context.** Measured against the access class shipped with this
+repo, on a request Express dispatched to `GET /owners/angela`, asked about
+**animals**:
+
+```
+getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+  ->  record => record.id !== 'angela' && record.id !== 'restricted'
+```
+
+That is the **owners** filter, and it returns `true` for animal 21 — the record
+hidden on every animal surface. Under a mount that predicate recognizes neither
+way it is worse still: it falls through to
+`['read', 'create', 'update', 'delete']`, a full CRUD grant.
+
+Either way the context was supplied and the answer is not the animal answer, and
+it is wrong in the direction that **grants**. That predicate is single-argument
+and identifies its collection from the request, so it answered about the
+collection the request is *addressed to* while being asked about another one.
+Every predicate in this repo, and in every consumer tree, is single-argument on
+the day this ships, and a caller has no supported way to tell which kind it
+resolved. The boot-time arity warning that would surface it is
+[#213](https://github.com/abofs/stonyx-orm/issues/213).
+
+So: pass the context, and do not treat a resolved predicate's answer as
+model-specific until that predicate has been migrated to read it.
+
 ### Return values
 
 | `access()` returns | Effect |
@@ -512,14 +680,24 @@ sub-paths beneath the mount, as the `/archived` deny above does.
   one collection is writable and another is filtered on a field the first can
   set. Blocking it requires checking animal 21 against the **animal** model's
   predicate while servicing an **owners** route — cross-model access resolution,
-  which the current contract cannot express: `access()` never receives the model
-  structurally ([#202](https://github.com/abofs/stonyx-orm/issues/202)) and
-  `setup-rest-server.ts` discards the model→predicate map at boot
-  ([#196](https://github.com/abofs/stonyx-orm/issues/196)). Tracked as
-  [#207](https://github.com/abofs/stonyx-orm/issues/207), blocked on that chain
-  (#202 → #196 → #207). Until it lands, do not rely on a filter to keep a record
-  unmodifiable; keep the *writable* collections' predicates as tight as the
-  hidden ones.
+  which the contract could not express before
+  [#202](https://github.com/abofs/stonyx-orm/issues/202): `access()` never
+  received the model structurally and `setup-rest-server.ts` discarded the
+  model→predicate map at boot. **#202 has landed and both halves now exist** —
+  see [The access context](#the-access-context-second-argument):
+  `Orm.instance.getAccess(modelName)` makes another model's predicate
+  **reachable**, and `context.model` makes a **model-correct answer possible** —
+  possible, not guaranteed: the resolved predicate has to read the context, and
+  every predicate in tree is still single-argument
+  ([#213](https://github.com/abofs/stonyx-orm/issues/213)), so today it answers
+  about the collection the request is addressed to. **The mechanism exists; the
+  ORM does not yet use it on this path.** The re-parenting write above is still
+  **not refused** — that enforcement is
+  [#196](https://github.com/abofs/stonyx-orm/issues/196) and
+  [#207](https://github.com/abofs/stonyx-orm/issues/207), which were blocked on
+  #202 and are now free to proceed. Until they land, do not rely on a filter to
+  keep a record unmodifiable; keep the *writable* collections' predicates as tight as
+  the hidden ones.
 - **Authorization by identifying the collection is a consumer-side
   reconstruction of information the framework already holds.** `access()`
   receives a transport artifact and is asked to work out which model, which

package/dist/index.d.ts

@@ -9,6 +9,7 @@ import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
+export type { AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
 export { Model, View, Serializer };
 export { attr, belongsTo, hasMany, createRecord, updateRecord };
 export { count, avg, sum, min, max };

package/dist/main.d.ts

@@ -1,4 +1,5 @@
 import Store from './store.js';
+import type { AccessFunction } from './types/orm-types.js';
 interface OrmOptions {
     dbType?: string;
 }
@@ -32,12 +33,127 @@ export default class Orm {
     views: Record<string, unknown>;
     transforms: Record<string, (value: unknown) => unknown>;
     warnings: Set<string>;
+    /**
+     * Model name -> the `access` predicate of the access class that CLAIMS that
+     * model (abofs/stonyx-orm#202).
+     *
+     * Not "that model's own predicate". One access class may claim many models
+     * -- `GlobalAccess` in this repo's fixtures declares five, and `models = '*'`
+     * claims every model in the store -- and it declares ONE `access` method, so
+     * the same function object is registered under every one of those keys.
+     * `getAccess('owner') === getAccess('animal')` is `true` there. The
+     * one-to-one guarantee below is key -> function, never function -> model,
+     * and a caller must not read a resolved predicate as being animal-specific.
+     * What makes the ANSWER model-specific is the context the caller passes and
+     * the predicate actually reading it -- see {@link Orm#getAccess}.
+     *
+     * NAMED FOR WHAT IT HOLDS. It was `accessFiles` through review, inherited
+     * from the function-local in `setup-rest-server.ts` where the values came
+     * straight out of `forEachFileImport` and "files" was defensible. The values
+     * are `AccessFunction`s, and the sibling public registries on this class
+     * (`models`, `serializers`, `views`, `transforms`) are all plural nouns of
+     * the thing held. Renamed here because #202 is the last moment it is free.
+     *
+     * Populated by `setup-rest-server.ts` at boot, from the access classes under
+     * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+     * and reachable before the first request can be served. The mapping is
+     * one-to-one by construction: setup-rest-server throws if two access classes
+     * claim the same model.
+     *
+     * Keys are model names as declared and stored (kebab-case, e.g.
+     * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+     *
+     * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+     * setup-rest-server that was discarded when that function returned, so at
+     * request time there was no way to get from a model name to that model's
+     * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+     * That made cross-model authorization -- asking model X's predicate about a
+     * request routed to model Y -- inexpressible, which is the capability
+     * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+     *
+     * Empty when the REST server is disabled, and PARTIAL when one access file
+     * failed to load (`setup-rest-server.ts` catches, warns and assigns whatever
+     * it had). So a missing key does NOT mean the model has no access class.
+     * Prefer {@link Orm#getAccess} over indexing this directly -- it is guarded
+     * against the prototype chain and this is not.
+     */
+    accessFunctions: Record<string, AccessFunction>;
     options: OrmOptions;
     sqlDb?: SqlDb;
     db?: OrmDB | SqlDb;
     private _persistErrorHandler;
     constructor(options?: OrmOptions);
     init(): Promise<void>;
+    /**
+     * Resolve the `access` predicate registered for a model name
+     * (abofs/stonyx-orm#202).
+     *
+     * This is the supported way to reach another model's predicate while
+     * servicing a request routed to a different model. Call it with the model
+     * name and invoke the result with the live request and an explicit context
+     * naming THAT model:
+     *
+     * ```js
+     * const predicate = Orm.instance.getAccess('animal');
+     * if (!predicate) return deny;
+     * const verdict = predicate(request, { model: 'animal', operation: 'read' });
+     * ```
+     *
+     * WHAT IT RESOLVES. The predicate of the access CLASS that claims the model,
+     * which is not necessarily specific to it: one class may claim many models
+     * and declares one `access` method, so
+     * `getAccess('owner') === getAccess('animal')` is `true` against this repo's
+     * fixture. See {@link Orm#accessFunctions}.
+     *
+     * `undefined` means NO PREDICATE COULD BE RESOLVED for that name. That
+     * includes a model whose access class failed to LOAD -- `setup-rest-server`
+     * catches, warns and publishes the partial map -- so it is not the same claim
+     * as "this model is unrestricted". Treat it as DENY, the same way
+     * `AccessContext.operation === undefined` is treated.
+     *
+     * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not, on
+     * its own, make the answer model-correct: the resolved predicate has to READ
+     * the context. Measured against this repo's shipped access class on a request
+     * express dispatched to `GET /owners/angela`, asked about ANIMALS:
+     *
+     * ```
+     * getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+     *   ->  record => record.id !== 'angela' && record.id !== 'restricted'
+     * ```
+     *
+     * The OWNERS filter, which returns `true` for animal 21 -- the record hidden
+     * on every animal surface. Under a mount that predicate recognises neither
+     * way it falls through to `['read', 'create', 'update', 'delete']`, a full
+     * CRUD grant. Either way: context supplied, answer not the animal answer,
+     * wrong in the GRANTING direction, because that predicate is arity-1 and
+     * identifies its collection from the request. AC9 asserts the first case on a
+     * live dispatch.
+     *
+     * Every predicate in this repo and in every consumer tree is arity-1 today,
+     * and there is no supported way for the caller to tell which kind it got; the
+     * boot-time arity warning that would surface it is abofs/stonyx-orm#213. Pass
+     * the context, and do not treat a resolved predicate's answer as
+     * model-specific until that predicate reads it.
+     *
+     * OWN PROPERTIES ONLY. A bare `this.accessFunctions[modelName]` walks the
+     * prototype chain, so `getAccess('constructor')` resolved `Object` and
+     * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+     * callable, and the documented `predicate?.(request, ctx)` pattern then
+     * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+     * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+     * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+     * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+     * which would have made a one-field body an authorization bypass. Guarded
+     * here at the read point rather than by constructing the map with a null
+     * prototype, because the field is public and reassignable and the guard has
+     * to hold whatever object it is holding.
+     *
+     * @param modelName - Model name as declared and stored (kebab-case).
+     * @returns The predicate, or `undefined` when no predicate could be resolved
+     *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+     *   note above. Treat it as deny.
+     */
+    getAccess(modelName: string): AccessFunction | undefined;
     startup(): Promise<void>;
     shutdown(): Promise<void>;
     static get db(): OrmDB | SqlDb;

package/dist/main.js

@@ -38,6 +38,51 @@ export default class Orm {
     views = {};
     transforms = { ...baseTransforms };
     warnings = new Set();
+    /**
+     * Model name -> the `access` predicate of the access class that CLAIMS that
+     * model (abofs/stonyx-orm#202).
+     *
+     * Not "that model's own predicate". One access class may claim many models
+     * -- `GlobalAccess` in this repo's fixtures declares five, and `models = '*'`
+     * claims every model in the store -- and it declares ONE `access` method, so
+     * the same function object is registered under every one of those keys.
+     * `getAccess('owner') === getAccess('animal')` is `true` there. The
+     * one-to-one guarantee below is key -> function, never function -> model,
+     * and a caller must not read a resolved predicate as being animal-specific.
+     * What makes the ANSWER model-specific is the context the caller passes and
+     * the predicate actually reading it -- see {@link Orm#getAccess}.
+     *
+     * NAMED FOR WHAT IT HOLDS. It was `accessFiles` through review, inherited
+     * from the function-local in `setup-rest-server.ts` where the values came
+     * straight out of `forEachFileImport` and "files" was defensible. The values
+     * are `AccessFunction`s, and the sibling public registries on this class
+     * (`models`, `serializers`, `views`, `transforms`) are all plural nouns of
+     * the thing held. Renamed here because #202 is the last moment it is free.
+     *
+     * Populated by `setup-rest-server.ts` at boot, from the access classes under
+     * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+     * and reachable before the first request can be served. The mapping is
+     * one-to-one by construction: setup-rest-server throws if two access classes
+     * claim the same model.
+     *
+     * Keys are model names as declared and stored (kebab-case, e.g.
+     * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+     *
+     * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+     * setup-rest-server that was discarded when that function returned, so at
+     * request time there was no way to get from a model name to that model's
+     * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+     * That made cross-model authorization -- asking model X's predicate about a
+     * request routed to model Y -- inexpressible, which is the capability
+     * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+     *
+     * Empty when the REST server is disabled, and PARTIAL when one access file
+     * failed to load (`setup-rest-server.ts` catches, warns and assigns whatever
+     * it had). So a missing key does NOT mean the model has no access class.
+     * Prefer {@link Orm#getAccess} over indexing this directly -- it is guarded
+     * against the prototype chain and this is not.
+     */
+    accessFunctions = {};
     options;
     sqlDb;
     db;
@@ -145,6 +190,80 @@ export default class Orm {
         Orm.ready = await Promise.all(promises);
         Orm.initialized = true;
     }
+    /**
+     * Resolve the `access` predicate registered for a model name
+     * (abofs/stonyx-orm#202).
+     *
+     * This is the supported way to reach another model's predicate while
+     * servicing a request routed to a different model. Call it with the model
+     * name and invoke the result with the live request and an explicit context
+     * naming THAT model:
+     *
+     * ```js
+     * const predicate = Orm.instance.getAccess('animal');
+     * if (!predicate) return deny;
+     * const verdict = predicate(request, { model: 'animal', operation: 'read' });
+     * ```
+     *
+     * WHAT IT RESOLVES. The predicate of the access CLASS that claims the model,
+     * which is not necessarily specific to it: one class may claim many models
+     * and declares one `access` method, so
+     * `getAccess('owner') === getAccess('animal')` is `true` against this repo's
+     * fixture. See {@link Orm#accessFunctions}.
+     *
+     * `undefined` means NO PREDICATE COULD BE RESOLVED for that name. That
+     * includes a model whose access class failed to LOAD -- `setup-rest-server`
+     * catches, warns and publishes the partial map -- so it is not the same claim
+     * as "this model is unrestricted". Treat it as DENY, the same way
+     * `AccessContext.operation === undefined` is treated.
+     *
+     * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not, on
+     * its own, make the answer model-correct: the resolved predicate has to READ
+     * the context. Measured against this repo's shipped access class on a request
+     * express dispatched to `GET /owners/angela`, asked about ANIMALS:
+     *
+     * ```
+     * getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+     *   ->  record => record.id !== 'angela' && record.id !== 'restricted'
+     * ```
+     *
+     * The OWNERS filter, which returns `true` for animal 21 -- the record hidden
+     * on every animal surface. Under a mount that predicate recognises neither
+     * way it falls through to `['read', 'create', 'update', 'delete']`, a full
+     * CRUD grant. Either way: context supplied, answer not the animal answer,
+     * wrong in the GRANTING direction, because that predicate is arity-1 and
+     * identifies its collection from the request. AC9 asserts the first case on a
+     * live dispatch.
+     *
+     * Every predicate in this repo and in every consumer tree is arity-1 today,
+     * and there is no supported way for the caller to tell which kind it got; the
+     * boot-time arity warning that would surface it is abofs/stonyx-orm#213. Pass
+     * the context, and do not treat a resolved predicate's answer as
+     * model-specific until that predicate reads it.
+     *
+     * OWN PROPERTIES ONLY. A bare `this.accessFunctions[modelName]` walks the
+     * prototype chain, so `getAccess('constructor')` resolved `Object` and
+     * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+     * callable, and the documented `predicate?.(request, ctx)` pattern then
+     * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+     * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+     * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+     * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+     * which would have made a one-field body an authorization bypass. Guarded
+     * here at the read point rather than by constructing the map with a null
+     * prototype, because the field is public and reassignable and the guard has
+     * to hold whatever object it is holding.
+     *
+     * @param modelName - Model name as declared and stored (kebab-case).
+     * @returns The predicate, or `undefined` when no predicate could be resolved
+     *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+     *   note above. Treat it as deny.
+     */
+    getAccess(modelName) {
+        if (!Object.hasOwn(this.accessFunctions, modelName))
+            return undefined;
+        return this.accessFunctions[modelName];
+    }
     async startup() {
         if (this.sqlDb)
             await this.sqlDb.startup();

package/dist/orm-request.d.ts

@@ -2,6 +2,124 @@
  * REST request handling and access enforcement for @stonyx/orm.
  *
  * ---------------------------------------------------------------------------
+ * THE `access()` CONTRACT: `access(request, { model, operation })`
+ * ---------------------------------------------------------------------------
+ * `auth()` calls your predicate with TWO arguments. The second is the access
+ * CONTEXT -- the structural facts about the request, which the framework
+ * already holds and which you should read INSTEAD of parsing anything:
+ *
+ *   context.model     The model this route was mounted for, as a model name:
+ *                     kebab-case, exactly as declared under
+ *                     `config.orm.paths.model` and keyed in the store --
+ *                     `'owner'`, `'animal'`, `'phone-number'`. NOT the
+ *                     pluralised, dasherized, mount-prefixed ROUTE name. It is
+ *                     read from the OrmRequest instance, fixed at mount time,
+ *                     and no request can influence it.
+ *
+ *   context.operation The operation being authorised. Exactly one of the four
+ *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
+ *                     no second vocabulary ON THIS PATH, and never an HTTP
+ *                     method name like `'GET'`. These are the same four
+ *                     strings the permission-array return shape is written in
+ *                     (`['read', 'create']`), because both come from the one
+ *                     `methodAccessMap` below.
+ *
+ *                     NOT the hook vocabulary. `HookContext.operation`
+ *                     (`src/hooks.ts`, documented under "Hook Context Object"
+ *                     in the README) carries `'list' | 'get' | 'create' |
+ *                     'update' | 'delete'` on an identically-named key of an
+ *                     identically-shaped context object, and the access
+ *                     vocabulary collapses `list` and `get` into `'read'`. For
+ *                     one `GET /animals/1` a hook sees `'get'` and `access()`
+ *                     sees `'read'`, so a predicate cannot tell a collection
+ *                     read from a record read. `AccessOperation` makes
+ *                     `operation === 'get'` a compile error for a TypeScript
+ *                     consumer, because a predicate that stops matching falls
+ *                     through to the permission array -- the misreading is
+ *                     fail-open shaped.
+ *
+ *                     `undefined` when the dispatched method has no entry in
+ *                     that map. Express delivers `HEAD` to the `GET` handler,
+ *                     so this is reachable. It is left undefined rather than
+ *                     defaulted on purpose -- a fabricated `'read'` would turn
+ *                     an unclassified request into an authorised one. Treat
+ *                     `undefined` as "not classified" and deny.
+ *
+ * So a consumer writes `if (model === 'owner' && operation === 'read')`. There
+ * is no string to parse, no variant to miss, and no way to fail open through a
+ * URL shape nobody anticipated.
+ *
+ * WHAT THE CONTEXT DOES NOT TELL YOU: WHICH SURFACE. It names the model and
+ * the verb, not the route. Measured over the live router, six surfaces produce
+ * one identical context:
+ *
+ *     GET /owners                          { model: 'owner', operation: 'read' }
+ *     GET /owners/gina                     { model: 'owner', operation: 'read' }
+ *     GET /owners/gina/pets                { model: 'owner', operation: 'read' }
+ *     GET /owners/gina/relationships/pets  { model: 'owner', operation: 'read' }
+ *     GET /owners/archived                 { model: 'owner', operation: 'read' }
+ *     GET /owners/gina?include=pets        { model: 'owner', operation: 'read' }
+ *
+ * So a rule that depends on the SUB-PATH still needs `request.path` -- which is
+ * mount-relative and query-free, and is the one read of argument one the
+ * warning below sanctions. This repo's own fixture has such a rule: its
+ * `/archived` deny cannot be expressed from the context alone, and a predicate
+ * migrated to context-only would silently drop it, turning a deny into an
+ * allow. The related-resource and `?include=` surfaces serve ANOTHER model's
+ * records under `model: 'owner'`, and the context gives no signal of that
+ * (abofs/stonyx-orm#196).
+ *
+ * `record` IS NOT IN THIS CONTEXT, deliberately. `auth()` runs after route
+ * matching but BEFORE any handler executes (`@stonyx/rest-server`
+ * `src/request.ts:58-60`), so nothing has been fetched yet -- supplying a
+ * record would force a pre-fetch on every request, a second store hit and an
+ * ordering change in the middle of an authorization path. It is also
+ * unnecessary: the FUNCTION return shape already is the per-record hook. Return
+ * `(record) => boolean` and the handlers apply it to every record the request
+ * touches. Auth-time and record-time are separate decision points.
+ *
+ * THE SECOND ARGUMENT IS ADDITIVE. JavaScript ignores extra arguments, so an
+ * existing `access(request)` predicate keeps working exactly as before. The
+ * warning immediately below is therefore still live: `request` is still
+ * argument ONE, and reading it is still how predicates fail open.
+ *
+ * To reach ANOTHER model's predicate -- e.g. to check an animal while servicing
+ * an owners route -- use the boot-time registry:
+ *
+ *     const predicate = Orm.instance.getAccess('animal');
+ *     if (!predicate) return deny;
+ *     const verdict = predicate(request, { model: 'animal', operation: 'read' });
+ *
+ * `undefined` means NO PREDICATE COULD BE RESOLVED for that name -- which
+ * includes the case where the model has an access class that failed to load,
+ * because `setup-rest-server.ts` catches a load failure, warns, and publishes
+ * whatever partial map it had. It does NOT mean the model is unrestricted.
+ * Treat it as DENY, the same way `operation === undefined` is treated above.
+ *
+ * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not make
+ * the answer model-correct on its own -- the resolved predicate has to READ it.
+ * Measured against this repo's own shipped access class, on a request express
+ * dispatched to `GET /owners/angela`, asked about ANIMALS:
+ *
+ *     getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+ *       ->  record => record.id !== 'angela' && record.id !== 'restricted'
+ *
+ * That is the OWNERS filter, and it returns `true` for animal 21 -- the record
+ * hidden on every animal surface. Under a mount that predicate recognises
+ * neither way it is worse: it falls through to
+ * `['read', 'create', 'update', 'delete']`, a full CRUD grant. Either way the
+ * context was supplied and the answer is not the animal answer, and it is wrong
+ * in the GRANTING direction, because that predicate is arity-1 and identifies
+ * its collection from the request. (The first of these is asserted on a live
+ * dispatch by AC9 in test/integration/orm-test.ts.)
+ *
+ * Every predicate in this repo and in every consumer tree is arity-1 on the day
+ * this ships, and the caller has no supported way to tell which kind it got --
+ * the boot-time arity warning that would surface it is abofs/stonyx-orm#213.
+ * So: pass the context, and do not treat a resolved predicate's answer as
+ * model-specific until that predicate has been migrated to read the context.
+ *
+ * ---------------------------------------------------------------------------
  * DO NOT RECONSTRUCT THE REQUEST PATH INSIDE `access()`.
  * ---------------------------------------------------------------------------
  * `auth()` below hands your `access(request)` a raw transport artifact and asks
@@ -59,6 +177,7 @@
  * See `### Known limitations` in README.
  */
 import { Request } from '@stonyx/rest-server';
+import type { AccessFunction } from './types/orm-types.js';
 interface OrmRequest$ extends Request {
     protocol?: string;
     method: string;
@@ -73,13 +192,12 @@ interface OrmRequest$ extends Request {
     };
     get(header: string): string;
 }
-type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
 type HandlerFn = (request: OrmRequest$, state: {
     [key: string]: unknown;
 }) => unknown | Promise<unknown>;
 export default class OrmRequest extends Request {
     model: string;
-    access: (request: unknown) => AccessMethod;
+    access: AccessFunction;
     handlers: {
         [key: string]: {
             [key: string]: HandlerFn;
@@ -87,7 +205,7 @@ export default class OrmRequest extends Request {
     };
     constructor({ model, access }: {
         model: string;
-        access: (request: unknown) => AccessMethod;
+        access: AccessFunction;
     });
     private _withHooks;
     private _generateRelationshipRoutes;