@stonyx/orm 0.3.2-alpha.57 → 0.3.2-alpha.59

package/README.md

@@ -397,7 +397,7 @@ 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. Never an HTTP method name like `'GET'`. `undefined` when the dispatched method has no entry in the framework's method map. |
+| `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:
 
@@ -420,6 +420,49 @@ 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
@@ -459,18 +502,52 @@ request routed to a *different* model:
 import Orm from '@stonyx/orm';
 
 const predicate = Orm.instance.getAccess('animal');
-const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+if (!predicate) return deny;
+
+const verdict = predicate(request, { model: 'animal', operation: 'read' });
 ```
 
-`Orm.instance.getAccess(modelName)` returns the predicate, or `undefined` when
-that model has no access class. The raw map is `Orm.instance.accessFiles`, keyed
-by model name; prefer `getAccess()`.
+**`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).
 
-Passing the context explicitly is what makes the answer **model-correct**. A
-predicate that identifies its collection from the request would otherwise answer
-about the collection the request is *addressed to* while being asked about
-another one — and per the five variants below, it answers wrong in the direction
-that grants access.
+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
 
@@ -607,15 +684,19 @@ sub-paths beneath the mount, as the `/archived` deny above does.
   [#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): `context.model`
-  makes the answer model-correct and `Orm.instance.getAccess(modelName)` makes
-  another model's predicate reachable. **The mechanism exists; the ORM does not
-  yet use it on this path.** The re-parenting write above is still unblocked —
-  that enforcement is
+  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 unblocked. Until they land, do not rely on a filter to keep a
-  record unmodifiable; keep the *writable* collections' predicates as tight as
+  #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()`

package/dist/main.d.ts

@@ -34,7 +34,25 @@ export default class Orm {
     transforms: Record<string, (value: unknown) => unknown>;
     warnings: Set<string>;
     /**
-     * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+     * 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
@@ -53,10 +71,13 @@ export default class Orm {
      * 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, or when no access configuration
-     * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+     * 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.
      */
-    accessFiles: Record<string, AccessFunction>;
+    accessFunctions: Record<string, AccessFunction>;
     options: OrmOptions;
     sqlDb?: SqlDb;
     db?: OrmDB | SqlDb;
@@ -64,7 +85,8 @@ export default class Orm {
     constructor(options?: OrmOptions);
     init(): Promise<void>;
     /**
-     * Resolve a model's `access` predicate by model name (abofs/stonyx-orm#202).
+     * 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
@@ -73,15 +95,47 @@ export default class Orm {
      *
      * ```js
      * const predicate = Orm.instance.getAccess('animal');
-     * const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+     * if (!predicate) return deny;
+     * const verdict = predicate(request, { model: 'animal', operation: 'read' });
      * ```
      *
-     * Passing the context is not optional in practice. A predicate that
-     * identifies its collection from the request would otherwise answer about the
-     * collection the request is ADDRESSED TO -- owners -- while being asked about
-     * animals, and per #202's thesis it answers wrong in the granting direction.
+     * 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.accessFiles[modelName]` walks the
+     * 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

package/dist/main.js

@@ -39,7 +39,25 @@ export default class Orm {
     transforms = { ...baseTransforms };
     warnings = new Set();
     /**
-     * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+     * 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
@@ -58,10 +76,13 @@ export default class Orm {
      * 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, or when no access configuration
-     * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+     * 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.
      */
-    accessFiles = {};
+    accessFunctions = {};
     options;
     sqlDb;
     db;
@@ -170,7 +191,8 @@ export default class Orm {
         Orm.initialized = true;
     }
     /**
-     * Resolve a model's `access` predicate by model name (abofs/stonyx-orm#202).
+     * 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
@@ -179,15 +201,47 @@ export default class Orm {
      *
      * ```js
      * const predicate = Orm.instance.getAccess('animal');
-     * const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+     * if (!predicate) return deny;
+     * const verdict = predicate(request, { model: 'animal', operation: 'read' });
      * ```
      *
-     * Passing the context is not optional in practice. A predicate that
-     * identifies its collection from the request would otherwise answer about the
-     * collection the request is ADDRESSED TO -- owners -- while being asked about
-     * animals, and per #202's thesis it answers wrong in the granting direction.
+     * 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.accessFiles[modelName]` walks the
+     * 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
@@ -206,9 +260,9 @@ export default class Orm {
      *   note above. Treat it as deny.
      */
     getAccess(modelName) {
-        if (!Object.hasOwn(this.accessFiles, modelName))
+        if (!Object.hasOwn(this.accessFunctions, modelName))
             return undefined;
-        return this.accessFiles[modelName];
+        return this.accessFunctions[modelName];
     }
     async startup() {
         if (this.sqlDb)

package/dist/orm-request.d.ts

@@ -18,12 +18,26 @@
  *
  *   context.operation The operation being authorised. Exactly one of the four
  *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
- *                     there is no second vocabulary, and it is never an HTTP
+ *                     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
@@ -35,6 +49,26 @@
  * 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
@@ -53,9 +87,37 @@
  * an owners route -- use the boot-time registry:
  *
  *     const predicate = Orm.instance.getAccess('animal');
- *     const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
- *
- * Passing the context explicitly is what makes that answer model-CORRECT.
+ *     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()`.

package/dist/orm-request.js

@@ -18,12 +18,26 @@
  *
  *   context.operation The operation being authorised. Exactly one of the four
  *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
- *                     there is no second vocabulary, and it is never an HTTP
+ *                     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
@@ -35,6 +49,26 @@
  * 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
@@ -53,9 +87,37 @@
  * an owners route -- use the boot-time registry:
  *
  *     const predicate = Orm.instance.getAccess('animal');
- *     const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+ *     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.)
  *
- * Passing the context explicitly is what makes that answer model-CORRECT.
+ * 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()`.

package/dist/setup-rest-server.js

@@ -8,7 +8,7 @@ import { dbKey } from './db.js';
 import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
 export default async function (route, accessPath, metaRoute) {
-    const accessFiles = {};
+    const accessFunctions = {};
     try {
         await forEachFileImport(accessPath, (accessClass) => {
             const accessInstance = new accessClass();
@@ -25,9 +25,9 @@ export default async function (route, accessPath, metaRoute) {
                     continue;
                 if (!store.data.has(model))
                     throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
-                if (accessFiles[model])
+                if (accessFunctions[model])
                     throw new Error(`Access for model "${model}" has already been defined by another access class.`);
-                accessFiles[model] = accessInstance.access;
+                accessFunctions[model] = accessInstance.access;
             }
         });
     }
@@ -38,7 +38,7 @@ export default async function (route, accessPath, metaRoute) {
     // -------------------------------------------------------------------------
     // #202 -- the registry has to survive this function.
     //
-    // `accessFiles` used to be a function-local that was discarded at the return
+    // `accessFunctions` used to be a function-local that was discarded at the return
     // below, so the only thing that ever saw it was the mount loop. Each mounted
     // OrmRequest then held its OWN model's predicate and nothing held the map, so
     // at request time there was no route from a model NAME to that model's
@@ -56,12 +56,12 @@ export default async function (route, accessPath, metaRoute) {
     // set of predicates that is actually enforcing. A guard here that skipped the
     // assignment would let the registry go silently missing, which is precisely
     // the failure #202's AC8 exists to catch.
-    Orm.instance.accessFiles = accessFiles;
+    Orm.instance.accessFunctions = accessFunctions;
     await waitForModule('rest-server');
     // Remove "/" prefix and name mount point accordingly
     const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
     // Configure endpoints for models and views with access configuration
-    for (const [model, access] of Object.entries(accessFiles)) {
+    for (const [model, access] of Object.entries(accessFunctions)) {
         const pluralizedModel = getPluralName(model);
         const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
         RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });

package/package.json

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

package/src/main.ts

@@ -71,7 +71,25 @@ export default class Orm {
   warnings: Set<string> = new Set();
 
   /**
-   * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+   * 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
@@ -90,10 +108,13 @@ export default class Orm {
    * 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, or when no access configuration
-   * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+   * 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.
    */
-  accessFiles: Record<string, AccessFunction> = {};
+  accessFunctions: Record<string, AccessFunction> = {};
 
   options!: OrmOptions;
   sqlDb?: SqlDb;
@@ -223,7 +244,8 @@ export default class Orm {
   }
 
   /**
-   * Resolve a model's `access` predicate by model name (abofs/stonyx-orm#202).
+   * 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
@@ -232,15 +254,47 @@ export default class Orm {
    *
    * ```js
    * const predicate = Orm.instance.getAccess('animal');
-   * const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+   * if (!predicate) return deny;
+   * const verdict = predicate(request, { model: 'animal', operation: 'read' });
    * ```
    *
-   * Passing the context is not optional in practice. A predicate that
-   * identifies its collection from the request would otherwise answer about the
-   * collection the request is ADDRESSED TO -- owners -- while being asked about
-   * animals, and per #202's thesis it answers wrong in the granting direction.
+   * 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.accessFiles[modelName]` walks the
+   * 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
@@ -259,9 +313,9 @@ export default class Orm {
    *   note above. Treat it as deny.
    */
   getAccess(modelName: string): AccessFunction | undefined {
-    if (!Object.hasOwn(this.accessFiles, modelName)) return undefined;
+    if (!Object.hasOwn(this.accessFunctions, modelName)) return undefined;
 
-    return this.accessFiles[modelName];
+    return this.accessFunctions[modelName];
   }
 
   async startup(): Promise<void> {

package/src/orm-request.ts

@@ -18,12 +18,26 @@
  *
  *   context.operation The operation being authorised. Exactly one of the four
  *                     verbs `'read'`, `'create'`, `'update'`, `'delete'` --
- *                     there is no second vocabulary, and it is never an HTTP
+ *                     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
@@ -35,6 +49,26 @@
  * 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
@@ -53,9 +87,37 @@
  * an owners route -- use the boot-time registry:
  *
  *     const predicate = Orm.instance.getAccess('animal');
- *     const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
+ *     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.)
  *
- * Passing the context explicitly is what makes that answer model-CORRECT.
+ * 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()`.

package/src/setup-rest-server.ts

@@ -20,7 +20,7 @@ interface AccessInstance {
 }
 
 export default async function(route: string, accessPath: string, metaRoute: boolean): Promise<void> {
-  const accessFiles: Record<string, AccessFunction> = {};
+  const accessFunctions: Record<string, AccessFunction> = {};
 
   try {
     await forEachFileImport(accessPath, (accessClass: unknown) => {
@@ -37,9 +37,9 @@ export default async function(route: string, accessPath: string, metaRoute: bool
       for (const model of models === '*' ? availableModels : models) {
         if (model === dbKey) continue;
         if (!store.data.has(model)) throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
-        if (accessFiles![model]) throw new Error(`Access for model "${model}" has already been defined by another access class.`);
+        if (accessFunctions![model]) throw new Error(`Access for model "${model}" has already been defined by another access class.`);
 
-        accessFiles![model] = accessInstance.access;
+        accessFunctions![model] = accessInstance.access;
       }
     });
   } catch (error) {
@@ -50,7 +50,7 @@ export default async function(route: string, accessPath: string, metaRoute: bool
   // -------------------------------------------------------------------------
   // #202 -- the registry has to survive this function.
   //
-  // `accessFiles` used to be a function-local that was discarded at the return
+  // `accessFunctions` used to be a function-local that was discarded at the return
   // below, so the only thing that ever saw it was the mount loop. Each mounted
   // OrmRequest then held its OWN model's predicate and nothing held the map, so
   // at request time there was no route from a model NAME to that model's
@@ -68,7 +68,7 @@ export default async function(route: string, accessPath: string, metaRoute: bool
   // set of predicates that is actually enforcing. A guard here that skipped the
   // assignment would let the registry go silently missing, which is precisely
   // the failure #202's AC8 exists to catch.
-  Orm.instance.accessFiles = accessFiles;
+  Orm.instance.accessFunctions = accessFunctions;
 
   await waitForModule('rest-server');
 
@@ -76,7 +76,7 @@ export default async function(route: string, accessPath: string, metaRoute: bool
   const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
 
   // Configure endpoints for models and views with access configuration
-  for (const [model, access] of Object.entries(accessFiles!)) {
+  for (const [model, access] of Object.entries(accessFunctions!)) {
     const pluralizedModel = getPluralName(model);
     const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
     RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });