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

package/src/orm-request.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
@@ -66,8 +184,8 @@ import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
-import type { OrmRecord } from './types/orm-types.js';
-import { isOrmRecord } from './utils.js';
+import type { OrmRecord, AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js';
+import { isOrmRecord, NO_FREE_ID_ERROR } from './utils.js';
 
 interface OrmRequest$ extends Request {
   protocol?: string;
@@ -94,10 +212,9 @@ interface JsonApiResponse {
   included?: unknown[];
 }
 
-type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
 type HandlerFn = (request: OrmRequest$, state: { [key: string]: unknown }) => unknown | Promise<unknown>;
 
-const methodAccessMap: { [key: string]: string } = {
+const methodAccessMap: { [key: string]: AccessOperation } = {
   GET: 'read',
   POST: 'create',
   DELETE: 'delete',
@@ -455,10 +572,10 @@ function isDenied(filter: unknown, record: unknown): boolean {
 
 export default class OrmRequest extends Request {
   model: string;
-  access: (request: unknown) => AccessMethod;
+  access: AccessFunction;
   handlers: { [key: string]: { [key: string]: HandlerFn } };
 
-  constructor({ model, access }: { model: string; access: (request: unknown) => AccessMethod }) {
+  constructor({ model, access }: { model: string; access: AccessFunction }) {
     super(...arguments as unknown as unknown[]);
 
     this.model = model;
@@ -645,7 +762,41 @@ export default class OrmRequest extends Request {
       // only O(1) signal that distinguishes an insert from an overwrite.
       const slotsBefore = store.get(model)?.size ?? 0;
 
-      const created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
+      // THE ONE `createRecord` FAILURE THIS ROUTE ANSWERS RATHER THAN
+      // PROPAGATES, and it is narrow on purpose.
+      //
+      // `assignRecordId` throws when it cannot derive a free store key for a
+      // server-assigned id. Unguarded that rejection is auto-forwarded -- there
+      // is no catch here, none in @stonyx/rest-server's dispatcher
+      // (dist/request.js:41-70), and express 5 hands it to its default error
+      // handler, which serialises the STACK, with absolute install paths and the
+      // internal module graph, to an unauthenticated caller outside
+      // NODE_ENV=production. That is the hazard :553-558 already names in this
+      // file, and every sibling refusal in this handler returns an integer
+      // status instead. So this one returns 409, matching the client-duplicate
+      // refusal at :713: the caller asked for a record and the collection has no
+      // id to give it.
+      //
+      // MATCHED ON THE SHARED PREFIX, not on a literal, and NOT by catching
+      // everything: `createRecord` also throws for "ORM is not ready", a
+      // read-only view and an unregistered model store, and turning any of those
+      // into a 409 would report a configuration fault as a conflict. Anything
+      // else is re-thrown unchanged.
+      let created;
+
+      try {
+        created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false, _skipAutoPersist: true });
+      } catch (error) {
+        if (!(error instanceof Error) || !error.message.startsWith(NO_FREE_ID_ERROR)) throw error;
+
+        // Not silently. A collection that can no longer assign an id is a
+        // configuration fault (a non-injective id transform), and a bare 409
+        // with no diagnostic is indistinguishable from an ordinary duplicate.
+        log.error?.(`[@stonyx/orm] ${error.message}`);
+
+        return 409; // Conflict
+      }
+
       const record = isOrmRecord(created) ? created : null;
       if (!record) return 500;
 
@@ -670,11 +821,32 @@ export default class OrmRequest extends Request {
         //
         // Both conditions are required and neither implies the other:
         //   createdNewSlot -- the store grew, so this request inserted rather
-        //                     than overwrote. Guards `assignRecordId` picking an
-        //                     id that is already taken (it returns
-        //                     last-INSERTED + 1, not max + 1, so a store whose
-        //                     insertion order is not ascending collides) -- see
-        //                     abofs/stonyx-orm#203.
+        //                     than overwrote. SURVIVOR AS OF #203, AND THAT IS
+        //                     WHAT THIS NOTE IS FOR. It used to be killable:
+        //                     `assignRecordId` returned last-INSERTED + 1, so a
+        //                     server-assigned id could land on an occupied slot,
+        //                     `createRecord` updated in place, and removing this
+        //                     half turned access-filter-enforcement-test.ts
+        //                     assertion 31 red. #203 closed that: the
+        //                     server-assigned path now walks past occupied keys,
+        //                     so no create reaching here can overwrite. Measured
+        //                     -- delete `createdNewSlot &&` below: `dev` gives
+        //                     55 pass / 1 fail with assertion 31 RED, this tree
+        //                     gives 56 pass / 0 fail, GREEN.
+        //                     KEPT ANYWAY, AND NOT FOR THE OLD REASON. Without
+        //                     it a denied create becomes `store.remove` on a key
+        //                     the caller may have influenced, which :815-820
+        //                     records as having been an unauthenticated deletion
+        //                     primitive across the whole id space. BECOMES
+        //                     KILLABLE AGAIN the moment any caller-supplied id
+        //                     can reach `createRecord` from this handler --
+        //                     which is exactly what has-many.ts:65 and
+        //                     belongs-to.ts:45 already do for ANOTHER model's
+        //                     store (abofs/stonyx-orm#207), and what a third
+        //                     un-stripped id channel would do for this one
+        //                     (#204). Do not delete it on the strength of #203
+        //                     being closed; that is the reasoning :862-867 warns
+        //                     about, one level up.
         //   identity       -- the slot still holds the object we just created,
         //                     so nothing between createRecord and here replaced
         //                     it. Deleting this half SURVIVES the suite, and it
@@ -1155,9 +1327,42 @@ export default class OrmRequest extends Request {
     // answers 500 -- and the documented sample itself can throw
     // (`request.originalUrl.split(...)` when originalUrl is absent), so the
     // failure mode is reachable by following the docs.
+    // -------------------------------------------------------------------------
+    // #202 -- hand the consumer the STRUCTURAL facts, not just the transport.
+    //
+    // Both members are already in hand here. `model` is `this.model`, the name
+    // setup-rest-server mounted this route for; `operation` is the SAME
+    // `methodAccessMap` lookup the permission-array branch at the bottom of
+    // this method performs, so the predicate form and the array form cannot
+    // answer differently about the same request.
+    //
+    // NEITHER IS DERIVED FROM THE REQUEST TARGET, and that is the whole point.
+    // Deriving `model` here from `request.baseUrl` (or from the mounted route
+    // name, or from `getPluralName(this.model)`) would move all five fail-open
+    // variants listed in this file's header OUT of the consumer and INTO the
+    // framework, where every consumer inherits them at once. `this.model` is
+    // assigned once at mount time and no request can influence it.
+    //
+    // `operation` is left UNDEFINED for a method with no entry in
+    // `methodAccessMap`, rather than defaulted. Express delivers HEAD to the
+    // GET handler, so an unmapped method really does reach this line; a
+    // `?? 'read'` here would hand the consumer a fabricated authorisation fact
+    // and turn an unclassified request into an authorised one. Undefined is
+    // the honest answer.
+    //
+    // `record` is deliberately absent -- see `AccessContext` in
+    // src/types/orm-types.ts. Nothing is fetched at this point and adding a
+    // lookup here would put a store read in the middle of an authorization
+    // path. The function return shape below IS the per-record hook.
+    // -------------------------------------------------------------------------
+    const context: AccessContext = {
+      model: this.model,
+      operation: methodAccessMap[request.method],
+    };
+
     let access: AccessMethod;
     try {
-      access = this.access(request);
+      access = this.access(request, context);
     } catch (error) {
       // Same reasoning as `isDenied`: fail closed, but say so. An `access()`
       // that throws denies EVERY request to the collection, and a silent 403

package/src/setup-rest-server.ts

@@ -1,5 +1,5 @@
 import { waitForModule } from 'stonyx';
-import { store } from '@stonyx/orm';
+import Orm, { store } from '@stonyx/orm';
 import OrmRequest from './orm-request.js';
 import MetaRequest from './meta-request.js';
 import RestServer from '@stonyx/rest-server';
@@ -7,14 +7,20 @@ import { forEachFileImport } from '@stonyx/utils/file';
 import { dbKey } from './db.js';
 import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
+import type { AccessFunction } from './types/orm-types.js';
 
 interface AccessInstance {
   models: string[] | '*';
-  access: (request: unknown) => unknown;
+  /**
+   * The consumer predicate. Called as `access(request, { model, operation })`
+   * -- the second argument is additive (abofs/stonyx-orm#202), so a predicate
+   * declared with a single parameter is still valid and still works.
+   */
+  access: AccessFunction;
 }
 
 export default async function(route: string, accessPath: string, metaRoute: boolean): Promise<void> {
-  const accessFiles: Record<string, (request: unknown) => unknown> = {};
+  const accessFunctions: Record<string, AccessFunction> = {};
 
   try {
     await forEachFileImport(accessPath, (accessClass: unknown) => {
@@ -31,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) {
@@ -41,13 +47,60 @@ export default async function(route: string, accessPath: string, metaRoute: bool
     log.warn?.('You must define a valid access configuration file in order to access ORM generated REST endpoints.');
   }
 
+  // -------------------------------------------------------------------------
+  // #202 -- the registry has to survive this function.
+  //
+  // `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
+  // predicate -- which is what abofs/stonyx-orm#196 and #207 need in order to
+  // ask model X's predicate about a request routed to model Y.
+  //
+  // Published BEFORE `await waitForModule('rest-server')`, deliberately: that
+  // await is the ONLY yield point in this function, and the rest-server module
+  // may already be listening by the time it reports ready, so an assignment
+  // after it would leave a window in which a route is live and the registry is
+  // not.
+  //
+  // It is NOT before the mount loop for that reason, and the comment here used
+  // to say it was. `RestServer.mountRoute` is fully synchronous -- construct,
+  // registerCalls(), api.use() -- and nothing between the loop and this
+  // function's closing brace yields, so the event loop cannot deliver a request
+  // in there and the window that clause described cannot open. Measured:
+  // moving this assignment to the last statement of the function leaves the
+  // suite at 951 pass / 0 fail. Being ahead of the mount loop is free and
+  // harmless; it is not what makes the ordering correct.
+  //
+  // Assigned unconditionally, including when the try above failed and the map
+  // is empty or partial: the mount loop below is driven by this exact object,
+  // so at the moment of assignment whatever is reachable through
+  // `Orm.instance` is the same set of predicates that is about to enforce.
+  // A guard such as `if (Object.keys(accessFunctions).length)` would let the
+  // registry go silently missing on a total load failure, and a later consumer
+  // would read `undefined` from `getAccess` and have to distinguish "no access
+  // class" from "the registry was never published" -- which it cannot. That is
+  // the reasoning, and it is REASONING, not something this suite tests: the
+  // guarded variant is also 951 pass / 0 fail, AC8 included, because every boot
+  // in this suite loads a non-empty access map so the guard never fires. AC8
+  // demonstrably cannot catch it. Catching it needs a boot with
+  // `orm.paths.access` pointed at an empty directory, which this suite has no
+  // harness for.
+  //
+  // One further limit on "by construction": the mount loop passes `access` BY
+  // VALUE into each OrmRequest, so the enforcing set is a snapshot taken here,
+  // while `getAccess` reads the map live. The two are the same set at boot and
+  // stay the same set only for as long as nobody writes to the public field.
+  // The equality is a boot-time fact, not an invariant.
+  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/src/standalone-db.ts

@@ -8,6 +8,10 @@
 
 import fs from 'fs/promises';
 import path from 'path';
+// `./utils.js` pulls in `@stonyx/utils/string` and nothing else -- no ORM
+// bootstrap, no `@stonyx/orm` index, no side effects -- so the "no framework
+// dependencies" property above still holds.
+import { maxNumericId } from './utils.js';
 
 interface StandaloneDBOptions {
   dbPath?: string;
@@ -131,12 +135,19 @@ export default class StandaloneDB {
     const records = await this.readCollection(collection);
 
     if (!data.id) {
-      const maxId = records.reduce((max, r) => {
-        const rid = typeof r.id === 'number' ? r.id : 0;
-        return rid > max ? rid : max;
-      }, 0);
-
-      data.id = maxId + 1;
+      // SHARED WITH `assignRecordId` (src/manage-record.ts), which is the other
+      // place this repo picks a server-assigned id. It was a second copy of the
+      // reduce, and nothing here pointed at it — a maintainer editing this
+      // method could not discover the other existed. See `maxNumericId` for why
+      // it is not `Math.max` (abofs/stonyx-orm#203).
+      //
+      // THE TWO ARE NOT THE SAME FUNCTION beyond this line, deliberately.
+      // `StandaloneDB` has no model, id-type or transform concept, so `maxId + 1`
+      // IS its store key; `assignRecordId` has to map the candidate through the
+      // model's declared id transform first, and then walk past occupied keys.
+      // Transplanting this method's remaining logic into the ORM reproduces
+      // #203's landing-key defect exactly — which is what AC4 pins.
+      data.id = maxNumericId(records) + 1;
     }
 
     // Check for duplicate id

package/src/types/orm-types.ts

@@ -168,3 +168,109 @@ export interface SnapshotEntry {
   source?: string;
   viewQuery?: string;
 }
+
+/**
+ * The shapes a consumer `access()` predicate may return.
+ *
+ * - `false` (or any falsy value) -- deny, 403.
+ * - `true` -- allow, with no per-record filter.
+ * - a permission string or array of them, drawn from the same four verbs as
+ *   {@link AccessContext.operation}. A BARE STRING IS ONE PERMISSION, not a
+ *   grant of all four.
+ * - a `(record) => boolean` predicate -- allow, and filter every record the
+ *   request touches through it.
+ *
+ * Anything else fails CLOSED. See `src/orm-request.ts` `auth()`.
+ */
+export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+
+/**
+ * The closed vocabulary `AccessContext.operation` is drawn from
+ * (abofs/stonyx-orm#202).
+ *
+ * A literal union rather than `string`, so the guarantee the prose makes is the
+ * one the compiler enforces: a consumer who writes `operation === 'GET'` or
+ * `operation === 'get'` -- the hook vocabulary, see below -- gets a compile
+ * error instead of a comparison that never matches. A predicate that stops
+ * matching falls through to the permission array, so the misreading is
+ * fail-open shaped.
+ *
+ * In-repo precedent: `PersistErrorDetail.operation` in `src/main.ts`.
+ */
+export type AccessOperation = 'read' | 'create' | 'update' | 'delete';
+
+/**
+ * The structural facts about the request being authorised, handed to a consumer
+ * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
+ *
+ * These are the facts the framework already holds at authorisation time. Before
+ * #202 a consumer had to reconstruct both of them by string-matching a URL, and
+ * five independent fail-open variants of that reconstruction were found in one
+ * three-line documented example -- each one wrong in the direction that GRANTS
+ * access. Read these instead; there is nothing to parse and no variant to miss.
+ *
+ * `record` is deliberately NOT a member. `auth()` runs after route matching but
+ * before any handler executes (`@stonyx/rest-server` `src/request.ts:58-60`),
+ * so nothing has been fetched yet -- carrying a record here would force a
+ * pre-fetch on every request. It is also unnecessary: the `(record) => boolean`
+ * return shape of {@link AccessMethod} already IS the per-record hook, applied
+ * by the handlers. Auth-time and record-time are separate decision points.
+ */
+export interface AccessContext {
+  /**
+   * The model this route was mounted for, e.g. `'owner'` or `'phone-number'`.
+   *
+   * Model names are kebab-case, as declared under `config.orm.paths.model` and
+   * keyed in the store -- NOT the pluralised, mount-prefixed route name. It is
+   * read from the `OrmRequest` instance and is never derived from the request
+   * target, so a mount prefix, a case-varied path, a query string or an
+   * absolute-form request-target cannot change it.
+   */
+  model: string;
+
+  /**
+   * The operation being authorised. Exactly one of the four {@link
+   * AccessOperation} verbs, or `undefined`. These are exactly the values of
+   * `methodAccessMap` in `src/orm-request.ts`, which is also what the
+   * permission-array return shape is matched against -- so the two forms cannot
+   * disagree.
+   *
+   * NOT the hook vocabulary. `HookContext.operation` (`src/hooks.ts`) 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'`. "No second vocabulary" is a
+   * statement about the ACCESS path only.
+   *
+   * `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.
+   *
+   * The KEY is required even though the value may be undefined: `auth()` always
+   * sets it, and a context that simply omitted it would be indistinguishable
+   * from one that classified the request and found nothing.
+   */
+  operation: AccessOperation | undefined;
+}
+
+/**
+ * A consumer `access()` predicate.
+ *
+ * The second argument is ADDITIVE: JavaScript ignores extra arguments, so every
+ * pre-#202 single-argument predicate keeps working untouched. Changing the
+ * FIRST argument instead would have been the breaking form, and a predicate
+ * that can no longer identify its collection falls through to a full CRUD
+ * grant -- so the "safer" breaking change would have converted every unmigrated
+ * predicate into a fail-open.
+ *
+ * `context` is nonetheless REQUIRED in the type, and that costs back-compat
+ * nothing. TypeScript already lets a fewer-parameter implementation satisfy a
+ * more-parameter signature, so an arity-1 predicate assigns to this type
+ * cleanly -- measured under `--strict`. What the `?` bought was the opposite of
+ * safety: it silently permitted `getAccess('animal')?.(request)` at the CALL
+ * site, i.e. exactly the omission {@link AccessContext} exists to prevent, and
+ * that call gets the model-wrong answer. Required, a caller that drops the
+ * context gets `TS2554: Expected 2 arguments, but got 1`.
+ */
+export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;

package/src/types/stonyx-rest-server.d.ts

@@ -5,7 +5,20 @@ declare module '@stonyx/rest-server' {
 
   interface RouteOptions {
     name: string;
-    options?: { model: string; access: (request: unknown) => unknown } | Record<string, unknown>;
+    /**
+     * `access` is the two-argument post-#202 shape. This is the THIRD place the
+     * contract is declared (`AccessInstance.access` in
+     * `src/setup-rest-server.ts` and `OrmRequest.access` in
+     * `src/orm-request.ts` are the other two) and it is the one `mountRoute` is
+     * actually called through, at `src/setup-rest-server.ts`. It kept the
+     * pre-#202 single-argument signature after the other two migrated; the
+     * union with `Record<string, unknown>` meant nothing broke, which is
+     * exactly why it would have drifted silently.
+     *
+     * Spelled structurally rather than as `AccessFunction`: an ambient
+     * `declare module` block cannot carry an `import type`.
+     */
+    options?: { model: string; access: (request: unknown, context: { model: string; operation: string | undefined }) => unknown } | Record<string, unknown>;
   }
 
   export default class RestServer {

package/src/utils.ts

@@ -20,3 +20,53 @@ export function pluralize(word: string): string {
 
   return basePluralize(word);
 }
+
+/**
+ * The highest NUMERIC id held by a set of records, or `0` when there is none.
+ *
+ * ONE COPY, and the duplication it replaces is the reason it lives here. Three
+ * near-identical reduces existed at once: `assignRecordId` (server-assigned id
+ * selection), `StandaloneDB.create` (src/standalone-db.ts) and the #203 test
+ * helper. `docs/improvements.md`'s standing WET Code category prescribes
+ * exactly this remedy -- extract into the module that already acts as the
+ * shared utility -- and `assignRecordId` already imported `isOrmRecord` from
+ * here.
+ *
+ * NON-NUMBERS ARE SKIPPED RATHER THAN COERCED TO `0`, AND THAT IS STYLISTIC.
+ * `StandaloneDB`'s shape mapped them to `0`, which can never beat a seed of
+ * `0`. Measured over eleven input classes (`[]`, `1`, `NaN`, `'5'`, `'abc'`,
+ * `-3`, `0`, `null`, `undefined`, `Infinity`, and mixed arrays) the two shapes
+ * produce IDENTICAL output on every one. In particular `typeof NaN` is
+ * `'number'`, so NEITHER shape coerces `NaN` -- both reject it on `NaN > max`,
+ * which is `false`. An earlier revision of this code asserted that the skip was
+ * what made the `NaN` case work; it is not, the comparison is, and that claim
+ * has been removed rather than left standing.
+ *
+ * WHAT IS LOAD-BEARING is that this is not `Math.max(...ids)`. `Math.max`
+ * returns `NaN` if any operand is `NaN`, and a record CAN be held under the key
+ * `NaN` -- so the obvious fix assigns `NaN`, lands on that slot and overwrites
+ * it, which is abofs/stonyx-orm#203 in a new disguise. Pinned by
+ * test/unit/assign-record-id-test.ts AC2; before that file existed the whole
+ * suite scored 951/0 under exactly that fix.
+ */
+export function maxNumericId(records: { id?: unknown }[]): number {
+  return records.reduce((max: number, record) => {
+    const { id } = record;
+
+    return typeof id === 'number' && id > max ? id : max;
+  }, 0);
+}
+
+/**
+ * The message prefix `assignRecordId` throws with when no free id can be
+ * derived for a model, and the ONE string `createHandler` matches on to answer
+ * `409` instead of letting the rejection reach express's default handler.
+ *
+ * It lives here rather than in either file because both need it and neither
+ * should own a copy: a literal in two places is how the two id coercions in
+ * orm-request.ts drifted apart (see `coerceId`). The repo has no error codes
+ * and no custom error classes -- 24 bare `throw new Error` sites across `src/`
+ * -- so a shared prefix is the narrowest way to make ONE failure distinguishable
+ * without inventing an error taxonomy this codebase does not use.
+ */
+export const NO_FREE_ID_ERROR = 'Cannot assign record ID: no free id available';