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

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/manage-record.js

@@ -1,7 +1,7 @@
 import Orm, { store } from '@stonyx/orm';
 import OrmRecord from './record.js';
 import { getGlobalRegistry, getPendingRegistry, getPendingBelongsToRegistry, getBelongsToRegistry, getHasManyRegistry } from './relationships.js';
-import { isOrmRecord } from './utils.js';
+import { isOrmRecord, maxNumericId, NO_FREE_ID_ERROR } from './utils.js';
 const defaultOptions = {
     isDbRecord: false,
     serialize: true,
@@ -153,17 +153,58 @@ export function updateRecord(record, rawData, userOptions = {}) {
     }
 }
 /**
- * gets the next available id based on last record entry.
+ * gets the next available id, based on the HIGHEST id present.
  *
  * In MySQL mode with numeric IDs, assigns a temporary pending ID.
  * MySQL's AUTO_INCREMENT provides the real ID after INSERT.
+ *
+ * ---------------------------------------------------------------------------
+ * WAS: `Array.from(storeMap.values()).at(-1).id + 1` — the LAST INSERTED id,
+ * not the maximum (abofs/stonyx-orm#203). The store is a Map, so insertion
+ * order stops being ascending the moment a record is deleted and recreated, a
+ * db.json is written out of order, a directory-mode store is read back in file
+ * order, or a caller POSTs a high id and then a low one. After that, every
+ * server-assigned id is one that is ALREADY TAKEN — and `createRecord`'s
+ * last-entry-wins branch then overwrites that record IN PLACE and answers 200.
+ * No error, no 409, and the store's size does not change. That is the whole
+ * defect, and it is reachable from a create with NO id at all, which is the
+ * most ordinary write a consumer performs.
+ *
+ * Covered by test/unit/assign-record-id-test.ts. Note for anyone changing this
+ * function: before that file existed, the whole suite scored 951/0 both on the
+ * defect and on a naive `Math.max` fix that introduced a second one. A green
+ * suite is not evidence here; those assertions are.
+ * ---------------------------------------------------------------------------
  */
 function assignRecordId(modelName, rawData) {
-    if (rawData.id)
+    // PRESENCE, not truthiness. `0` is a legal value for an `attr('number')` id,
+    // and `if (rawData.id) return` silently reassigned it, handing the caller back
+    // a different record than the one it named (#203).
+    //
+    // `''` is deliberately NOT honoured here and this is not an oversight: it is
+    // the one string that means "no id". `parseInt('')` is `NaN`, a record CAN be
+    // held under the key `NaN`, and orm-request.ts's body-id normalisation relies
+    // on `''` staying absent — otherwise `POST {"id":""}` answers 409 against a
+    // record it never named.
+    //
+    // WHAT WIDENING THIS TO `!== undefined` ACTUALLY DOES, measured rather than
+    // asserted: `{id: ''}` early-returns, `parseInt('')` NaNs it, and the record
+    // lands on the store's `NaN` slot and OVERWRITES whatever is there — #203's
+    // own defect class. It does NOT turn access-filter-enforcement-test.ts
+    // assertion 44 red; an earlier revision of this comment claimed it did, which
+    // converted an unknown into a false assurance. AC6's BOUNDARY assertions are
+    // what catch it, and they only do so because they seed the `NaN` slot first.
+    if (rawData.id || rawData.id === 0)
         return;
     // In SQL mode with numeric IDs, defer to database auto-increment.
     // Use unique negative integers — they survive the number transform (parseInt preserves negatives)
     // and avoid NaN store-key collisions that string pending IDs caused.
+    //
+    // This early return is ABOVE the max computation on purpose: a pending
+    // negative must never be a candidate for, or be perturbed by, the max path.
+    // Pinned directly (AC5.3) rather than by asserting the max is unaffected —
+    // that assertion could not have failed, because nothing negative ever reaches
+    // the code below.
     if (Orm.instance?.sqlDb && !isStringIdModel(modelName)) {
         rawData.id = -(++pendingIdCounter);
         rawData.__pendingSqlId = true;
@@ -173,13 +214,197 @@ function assignRecordId(modelName, rawData) {
     if (!storeMap)
         throw new Error(`Cannot assign record ID: model "${modelName}" not found in store`);
     const modelStore = Array.from(storeMap.values()).filter(isOrmRecord);
-    const lastRecord = modelStore.at(-1);
-    rawData.id = lastRecord ? lastRecord.id + 1 : 1;
+    // ONE COPY of the max-numeric-id reduce, in src/utils.ts. There were three
+    // (here, StandaloneDB.create, and the #203 test helper) and `docs/
+    // improvements.md`'s WET Code category prescribes the extraction. What that
+    // helper must NOT be is `Math.max(...ids)`; the reason is measured and it is
+    // documented at the helper rather than duplicated here. Pinned by AC2.
+    const maxId = maxNumericId(modelStore);
+    // THE OCCUPANCY CHECK RUNS ON THE LANDING KEY, NOT ON THE RAW CANDIDATE, and
+    // the difference is a silent data loss rather than a nicety.
+    //
+    // `createRecord` looks the record up under `rawData.id` (:50) but WRITES it
+    // under `record.id` (:69) — the value after the model's declared id transform
+    // has run inside `serialize`. When the transform is not the identity those two
+    // differ, so a guard written as `storeMap.has(rawData.id)` checks a key the
+    // record will never occupy, misses an occupied slot and overwrites it —
+    // measured on an `uppercase`-id model: the guard checks `owner-1`, the record
+    // lands under `OWNER-1`, store size unchanged, no error. That is
+    // abofs/stonyx-orm#205's lookup-key/landing-key divergence reappearing inside
+    // #203's own fix, which is why AC4 exists and why `rawData.id` is set to the
+    // LANDING key below.
+    //
+    // THE SCOPE OF THAT CLAIM, stated rather than implied. Setting `rawData.id` to
+    // the landing key makes :50 and :69 agree for every IDEMPOTENT id transform —
+    // `number`, `float`, `string`, `passthrough`, `uppercase`, `trim`. It does NOT
+    // make them agree for `date` or `timestamp`: `transforms.date` returns a NEW
+    // object every call and a `Map` keys by identity, so `storeMap.has(landingKey)`
+    // is always `false` there and the occupancy check is vacuous. `dev` is broken
+    // for those types too — this is not a regression — but no comment here may
+    // claim a property it was not measured to have (#212 § AC5).
+    //
+    // Resolved ONCE, outside the walk: `getIdType` instantiates the model class,
+    // so resolving it per candidate would put a model construction on every
+    // iteration of a loop that exists to walk past occupied slots.
+    const toStoreKey = storeKeyDeriver(modelName);
+    // DOES THIS MODEL FILE ITS RECORDS UNDER STRING KEYS? Decided by RUNNING the
+    // model's own id transform once, not by matching a type NAME against a list:
+    // `Orm.instance.transforms` (main.ts:70) is a public, MUTABLE instance
+    // property, so any enumeration of "the string-ish types" written here would be
+    // wrong the moment a consumer registers one.
+    const stringKeyed = typeof toStoreKey(maxId + 1) === 'string';
+    // THE CANDIDATE FOR A STRING-KEYED MODEL IS NOT A BARE NUMBER, and this is
+    // abofs/stonyx-orm#209 — which is REOPENED — not aesthetics.
+    //
+    // `orm-request.ts`'s `coerceId` (:322) resolves a NUMERIC-LOOKING string to a
+    // NUMBER on every id-bearing surface, while a model declaring
+    // `id = attr('string')` files under the STRING key. So a server-assigned `'1'`
+    // produces a record that is created and then NOT ADDRESSABLE. Measured over
+    // the route, owner store `{'1': ...}`:
+    //
+    //   GET    /owners/1       -> 404      (the record exists)
+    //   DELETE /owners/1       -> 404
+    //   GET    /owners/owner-1 -> 200
+    //
+    // and `_withHooks` (:1185) hands an after-`create` hook
+    // `context.record === undefined` for the same reason. `dev` assigned `'bob1'`,
+    // which is not numeric-looking, so `dev` has neither problem: a bare-number
+    // candidate would move #209 from "a caller supplied a numeric-looking id" onto
+    // the DEFAULT path for every server-assigned create on every string-id model.
+    // Prefixing with the model name keeps #209's population exactly as narrow as
+    // it already was, without touching the one shared coercion or the assertion
+    // that pins #209 open. Pinned by AC3.
+    const toCandidate = stringKeyed
+        ? (value) => `${modelName}-${value}`
+        : (value) => value;
+    // `maxId + 1` is the id AC1 pins: strictly greater than every numeric key
+    // present. IT IS NOT ALWAYS AVAILABLE, and that gap was a live denial of
+    // service. Float64 has no integer successor at or above 2^53, so
+    // `maxId + 1 === maxId` for every `maxId >= 9007199254740992` and `+ 1` inside
+    // the walk is a NO-OP there. One record filed under that key — which an
+    // unauthenticated `POST {"id":9007199254740992}` puts there, and which reaches
+    // even a filter-protected collection through has-many.ts:65 (#207), a channel
+    // GATE 0 does not cover — made the walk unable to advance, so it exhausted its
+    // budget and threw on EVERY subsequent server-assigned create, permanently,
+    // until that record was deleted. Measured over the route: 200, then 500 for
+    // every no-id create. `dev` answers 200.
+    //
+    // So a store holding one adversarial record must not disable its collection.
+    // When "above the max" is not a usable strategy the walk RESTARTS FROM 1: the
+    // store holds at most `size` keys, so one of `1 .. size + 1` is always free
+    // under an injective id transform. Pinned by AC7.
+    const start = maxId + 1;
+    let landingKey = firstFreeKey(storeMap, toStoreKey, toCandidate, start);
+    // THE RESTART, and it is the whole of the ceiling fix. Killing mutation:
+    // delete this block -> AC7 goes red (the route answers 409 instead of the
+    // created resource).
+    if (landingKey === NO_FREE_KEY && start !== 1) {
+        landingKey = firstFreeKey(storeMap, toStoreKey, toCandidate, 1);
+    }
+    if (landingKey === NO_FREE_KEY) {
+        // Reachable only with a NON-INJECTIVE id transform — see `firstFreeKey`.
+        // `createHandler` matches this message and answers 409 rather than letting it
+        // reach express's default handler, which serialises a stack trace with
+        // absolute install paths outside NODE_ENV=production (the hazard
+        // orm-request.ts:553-558 exists to name). Pinned by AC8.
+        throw new Error(`${NO_FREE_ID_ERROR} for model "${modelName}"`);
+    }
+    rawData.id = landingKey;
 }
-function isStringIdModel(modelName) {
-    const modelClass = Orm.instance.getRecordClasses(modelName).modelClass;
+// Returned instead of a key so that "no key" cannot be confused with a transform
+// that legitimately produced `undefined` or `null`.
+const NO_FREE_KEY = Symbol('no free store key');
+/**
+ * The first store key at or above `start` that no record occupies, walking
+ * candidate ids upward, or `NO_FREE_KEY` if the walk cannot reach one.
+ */
+function firstFreeKey(storeMap, toStoreKey, toCandidate, start) {
+    let candidate = start;
+    let landingKey = toStoreKey(toCandidate(candidate));
+    let attempts = 0;
+    while (storeMap.has(landingKey)) {
+        // THE BOUND IS EXACTLY TIGHT, not conservative: this walk tries
+        // `storeMap.size + 1` DISTINCT candidates against at most `storeMap.size`
+        // occupied keys, so under an injective `toStoreKey` it provably cannot fire.
+        // Under a non-injective one it provably terminates — and that is a reachable
+        // consumer state rather than a hypothesis: `transforms.boolean`
+        // (transforms.ts:4) collapses every candidate onto `true`/`false`, and
+        // `Orm.instance.transforms` (main.ts:70) is public and MUTABLE, so a consumer
+        // can register an arbitrary non-injective transform and name it as an id
+        // type. Without this, a no-id create spins forever inside a synchronous store
+        // walk and pins a worker, which is worse than either collision policy. Its
+        // EXISTENCE and its THRESHOLD are both pinned by AC8: deleting it makes AC8
+        // HANG rather than fail, and weakening it to fire on the first collision
+        // makes AC8.1 red.
+        if (++attempts > storeMap.size)
+            return NO_FREE_KEY;
+        // NOTE FOR ANYONE ADDING A SECOND EXIT HERE. A `candidate + 1 === candidate`
+        // float-saturation check was written, measured, and REMOVED: with the
+        // restart-from-1 above in place, deleting the saturation check leaves the
+        // whole suite green, because the budget reaches the same `NO_FREE_KEY` one
+        // pass later and the restart still answers. An unkillable guard in a change
+        // whose deliverable is falsifiable coverage is exactly what this story exists
+        // to stop shipping. `+ 1` being a no-op at 2^53 costs `size` extra `Map.has`
+        // calls on that one path and changes no outcome.
+        candidate += 1;
+        landingKey = toStoreKey(toCandidate(candidate));
+    }
+    return landingKey;
+}
+/**
+ * Returns the derivation that maps an id VALUE to the store KEY a record
+ * carrying it will actually be filed under — the model's declared id transform,
+ * the same one `serialize` runs at createRecord:68 before the `.set` at :69.
+ */
+function storeKeyDeriver(modelName) {
+    const idType = getIdType(modelName);
+    const transform = idType ? Orm.instance?.transforms?.[idType] : undefined;
+    // SURVIVOR, RETAINED, with its reachability condition stated rather than left
+    // silent — `docs/project-structure.md` § "unkillable code reads as coverage and
+    // is not" is the standing rule and it applies outside orm-request.ts too.
+    //
+    // No mutation in this repo can kill this branch, and that is STRUCTURAL rather
+    // than an untested gap: `Model` declares `id = attr('number')` (model.ts:15) so
+    // every registered model has an id type; `ModelProperty` refuses a type with no
+    // registered transform (model-property.ts:4) so a declared type always
+    // resolves; and `getIdType` can therefore only return `undefined` when
+    // `getRecordClasses` yields no `modelClass` — in which case `createRecord`
+    // throws at :62 a few lines later regardless, so no record is ever filed
+    // through this branch.
+    //
+    // BECOMES REACHABLE if a model can be declared without an `id` property, if a
+    // store map can exist for a model with no registered class, or if
+    // `createRecord` stops constructing the model class. Kept rather than deleted
+    // because the alternative on that path is a `transform is not a function`
+    // TypeError, and because identity is exactly what `createRecord` would file
+    // under when no transform exists — the two agree, which is the property AC4 is
+    // about.
+    if (typeof transform !== 'function')
+        return value => value;
+    return value => {
+        try {
+            return transform(value);
+        }
+        catch {
+            // `uppercase` and `trim` (transforms.ts:11-12) call a string method on the
+            // value directly, so a NUMERIC candidate throws `value?.toUpperCase is not
+            // a function`. On `dev` they never saw one — `lastRecord.id + 1` on a
+            // string id is a string — so feeding them a number here would regress a
+            // legal, registered id type into an uncaught 500. The retry feeds the
+            // string form, which is the shape an id actually arrives in off a JSON body
+            // or a URL param. A transform that throws on BOTH shapes still propagates.
+            // Pinned by AC9.
+            return transform(String(value));
+        }
+    };
+}
+function getIdType(modelName) {
+    const modelClass = Orm.instance?.getRecordClasses(modelName).modelClass;
     if (!modelClass)
-        return false;
+        return undefined;
     const model = new modelClass(modelName);
-    return model.id?.type === 'string';
+    return model.id?.type;
+}
+function isStringIdModel(modelName) {
+    return getIdType(modelName) === 'string';
 }

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;