@stonyx/orm 0.3.2-alpha.6 → 0.3.2-alpha.60

package/src/postgres/connection.ts

@@ -8,6 +8,7 @@ interface PgConfig {
   password: string;
   database: string;
   connectionLimit: number;
+  [key: string]: unknown;
 }
 
 let pool: PgPool | null = null;
@@ -20,15 +21,18 @@ export async function getPool(pgConfig: PgConfig, extensions: string[] = ['vecto
 
   const { default: pg } = await import('pg');
 
+  const { host, port, user, password, database, connectionLimit, migrationsDir, migrationsTable, autoMigrate, ...poolOpts } = pgConfig;
+
   pool = new pg.Pool({
-    host: pgConfig.host,
-    port: pgConfig.port,
-    user: pgConfig.user,
-    password: pgConfig.password,
-    database: pgConfig.database,
-    max: pgConfig.connectionLimit,
+    host,
+    port,
+    user,
+    password,
+    database,
+    max: connectionLimit,
     idleTimeoutMillis: 30000,
     connectionTimeoutMillis: 10000,
+    ...poolOpts,
   });
 
   // Enable requested PostgreSQL extensions

package/src/postgres/postgres-db.ts

@@ -90,6 +90,15 @@ export default class PostgresDB {
   pool!: Pool | null;
   pgConfig!: Record<string, unknown>;
 
+  /**
+   * Promise-chain mutex for write serialization (#156).
+   * All persist() calls chain through this single queue so concurrent
+   * fire-and-forget writes never produce parallel transactions
+   * on FK-linked rows (which cause deadlocks).
+   * Reads are NOT affected — only persist() serializes.
+   */
+  private _writeQueue: Promise<void> = Promise.resolve();
+
   constructor(deps: Partial<PostgresDeps> = {}) {
     const Ctor = this.constructor as typeof PostgresDB;
     if (Ctor.instance) return Ctor.instance;
@@ -125,7 +134,15 @@ export default class PostgresDB {
     if (pending.length > 0) {
       this.deps.log.db?.(`${pending.length} pending migration(s) found.`);
 
-      const shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      let shouldApply: boolean;
+      if (this.pgConfig.autoMigrate === true) {
+        shouldApply = true;
+      } else if (this.pgConfig.autoMigrate === false) {
+        shouldApply = false;
+        this.deps.log.warn?.(`autoMigrate is false — skipping ${pending.length} pending migration(s).`);
+      } else {
+        shouldApply = await this.deps.confirm(`${pending.length} pending migration(s) found. Apply now?`);
+      }
 
       if (shouldApply) {
         for (const filename of pending) {
@@ -146,9 +163,17 @@ export default class PostgresDB {
       const modelCount = Object.keys(schemas).length;
 
       if (modelCount > 0) {
-        const shouldGenerate = await this.deps.confirm(
-          `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
-        );
+        let shouldGenerate: boolean;
+        if (this.pgConfig.autoMigrate === true) {
+          shouldGenerate = true;
+        } else if (this.pgConfig.autoMigrate === false) {
+          shouldGenerate = false;
+          this.deps.log.warn?.(`autoMigrate is false — skipping initial migration generation for ${modelCount} model(s).`);
+        } else {
+          shouldGenerate = await this.deps.confirm(
+            `No migrations found but ${modelCount} model(s) detected. Generate and apply initial migration?`
+          );
+        }
 
         if (shouldGenerate) {
           const { generateMigration } = await import('./migration-generator.js');
@@ -468,14 +493,21 @@ export default class PostgresDB {
     const Orm = (await import('@stonyx/orm')).default;
     if ((Orm.instance as { isView?: (name: string) => boolean })?.isView?.(modelName)) return;
 
-    switch (operation) {
-      case 'create':
-        return this._persistCreate(modelName, context, response);
-      case 'update':
-        return this._persistUpdate(modelName, context, response);
-      case 'delete':
-        return this._persistDelete(modelName, context);
-    }
+    const work = async () => {
+      switch (operation) {
+        case 'create':
+          return this._persistCreate(modelName, context, response);
+        case 'update':
+          return this._persistUpdate(modelName, context, response);
+        case 'delete':
+          return this._persistDelete(modelName, context);
+      }
+    };
+
+    // Chain through the write queue — .then(work, work) ensures the queue
+    // advances even when a previous persist rejects (#156).
+    this._writeQueue = this._writeQueue.then(work, work);
+    return this._writeQueue;
   }
 
   private async _persistCreate(modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {

package/src/record.ts

@@ -87,12 +87,15 @@ export default class Record {
 
     for (const [key, childRecord] of Object.entries(this.__relationships)) {
       if (Array.isArray(childRecord)) {
+        // Filter out cleaned records (those with no __model)
+        const live = childRecord.filter((r: Record) => r?.__model);
+
         // Deduplicate by record ID — keep last occurrence (latest data wins)
         const seen = new Set<unknown>();
         const unique: Record[] = [];
 
-        for (let i = childRecord.length - 1; i >= 0; i--) {
-          const r = childRecord[i] as Record;
+        for (let i = live.length - 1; i >= 0; i--) {
+          const r = live[i] as Record;
           if (!seen.has(r.id)) {
             seen.add(r.id);
             unique.push(r);
@@ -102,7 +105,7 @@ export default class Record {
         unique.reverse();
         records[key] = unique.map((r: Record) => r.serialize());
       } else {
-        records[key] = (childRecord as Record)?.serialize() ?? null;
+        records[key] = (childRecord as Record)?.__model ? (childRecord as Record).serialize() : null;
       }
     }
 
@@ -136,8 +139,8 @@ export default class Record {
       if (fields && !fields.has(key)) continue;
 
       const relationshipData = Array.isArray(childRecord)
-        ? childRecord.map((r: Record) => ({ type: r.__model.__name, id: r.id }))
-        : childRecord ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
+        ? childRecord.filter((r: Record) => r?.__model).map((r: Record) => ({ type: r.__model.__name, id: r.id }))
+        : (childRecord && (childRecord as Record).__model) ? { type: (childRecord as Record).__model.__name, id: (childRecord as Record).id } : null;
 
       // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
       const dasherizedKey = camelCaseToKebabCase(key);

package/src/relationships.ts

@@ -51,4 +51,4 @@ export function getPendingBelongsToRegistry(): PendingBelongsToMap {
   return relationships.get('pendingBelongsTo') as PendingBelongsToMap;
 }
 
-export const TYPES: string[] = ['global', 'hasMany', 'belongsTo', 'pending'];
+export const TYPES: string[] = ['global', 'hasMany', 'belongsTo', 'pending', 'pendingBelongsTo'];

package/src/serializer.ts

@@ -94,8 +94,45 @@ export default class Serializer {
         const handlerOptions = { ...options, _relationshipKey: key };
         const childRecord = handler(record, data, handlerOptions);
 
-        rec[key] = childRecord;
-        relatedRecords[key] = childRecord;
+        // hasMany relationships use a getter so format()/toJSON() always read
+        // the live registry array instead of a stale snapshot captured at
+        // serialization time.  This is critical when child records are created
+        // in a later async frame — the belongsTo inverse wiring pushes into
+        // the shared registry array, and the getter ensures the parent sees it.
+        const isHasMany = (handler as { __relationshipType?: string }).__relationshipType === 'hasMany';
+
+        if (isHasMany) {
+          // `childRecord` IS the shared registry array — define a getter that
+          // always dereferences through the same array reference.
+          const registryArray = childRecord as unknown[];
+          Object.defineProperty(rec, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => registryArray,
+            set(v: unknown) { relatedRecords[key] = v; }
+          });
+          Object.defineProperty(relatedRecords, key, {
+            enumerable: true,
+            configurable: true,
+            get: () => registryArray,
+            set(v: unknown) { Object.defineProperty(relatedRecords, key, { value: v, writable: true, enumerable: true, configurable: true }); }
+          });
+        } else {
+          rec[key] = childRecord;
+          relatedRecords[key] = childRecord;
+
+          // Preserve the raw FK value in __data when the belongsTo handler
+          // couldn't resolve the target (e.g., memory:false model not loaded).
+          // This allows adapters to read the FK from __data as a fallback
+          // when __relationships[key] is null.  Only store when `data` is a
+          // truthy non-object — i.e., a raw FK string/number that the handler
+          // attempted but failed to resolve.  When `data` is null/undefined
+          // (optional empty relationship) we intentionally skip to preserve
+          // the existing behavior of not populating __data for empty FKs.
+          if (childRecord === null && data && typeof data !== 'object') {
+            parsedData[key] = data;
+          }
+        }
 
         continue;
       }

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/store.ts

@@ -1,5 +1,5 @@
 import Orm, { relationships } from '@stonyx/orm';
-import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry } from './relationships.js';
+import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry, getPendingBelongsToRegistry } from './relationships.js';
 import ViewResolver from './view-resolver.js';
 
 interface UnloadOptions {
@@ -64,7 +64,7 @@ export default class Store {
   get(key: string): Map<number | string, unknown> | undefined;
   get(key: string, id: number | string): unknown;
   get(key: string, id?: number | string): Map<number | string, unknown> | unknown | undefined {
-    if (!id) return this.data.get(key);
+    if (id === undefined) return this.data.get(key);
 
     return this.data.get(key)?.get(id);
   }
@@ -170,14 +170,15 @@ export default class Store {
     this.data.set(key, value);
   }
 
-  remove(key: string, id?: number | string): void {
+  remove(key: string, id?: number | string, options?: { _skipAutoPersist?: boolean }): void {
     // Guard: read-only views cannot have records removed
     if (Orm.instance?.isView?.(key)) {
       throw new Error(`Cannot remove records from read-only view '${key}'`);
     }
 
-    // Auto-persist delete to SQL
-    if (id && Orm.instance?.sqlDb) {
+    // Auto-persist delete to SQL (fire-and-forget) — skipped when the
+    // request path handles persist itself to avoid double-delete.
+    if (id && Orm.instance?.sqlDb && !options?._skipAutoPersist) {
       Orm.instance.sqlDb.persist('delete', key, { recordId: id }, {}).catch((err: unknown) => {
         Orm.instance.emitPersistError({
           operation: 'delete',
@@ -193,6 +194,44 @@ export default class Store {
     this.unloadAllRecords(key);
   }
 
+  /**
+   * Evict a record from the store with full relationship registry cleanup.
+   * The caller retains its reference to the returned record, which is the
+   * contract memory:false post-persist eviction relies on.
+   *
+   * @param registryId - The ID used when the record's relationships were
+   *   registered. For SQL models with pending IDs, this is the original
+   *   negative pending ID (before the adapter re-keyed to the real DB ID).
+   */
+  evictRecord(modelName: string, id: unknown, registryId?: unknown): void {
+    const modelStore = this.data.get(modelName);
+    if (!modelStore) return;
+
+    if (typeof id !== 'string' && typeof id !== 'number') return;
+    const raw = modelStore.get(id);
+    if (!raw || !isStoreRecord(raw)) return;
+
+    const visited = new Set([`${modelName}:${id}`]);
+
+    // Remove from hasMany arrays and nullify belongsTo references using current ID
+    // (the adapter updates record.id, so value-based matches need the current ID)
+    this._removeFromHasManyArrays(modelName, id, visited);
+    this._nullifyBelongsToReferences(modelName, id, visited);
+
+    // Clean up relationship registry entries using the registry key
+    // (belongsTo/hasMany registries were keyed by the ID at registration time,
+    // which may differ from the current ID if SQL persist re-keyed the record)
+    const cleanupId = registryId ?? id;
+    this._cleanupRelationshipRegistries(modelName, cleanupId);
+
+    // If registryId differs from id, also clean with current id as safety net
+    if (registryId !== undefined && registryId !== id) {
+      this._cleanupRelationshipRegistries(modelName, id);
+    }
+
+    modelStore.delete(id);
+  }
+
   unloadRecord(model: string, id: unknown, options: UnloadOptions = {}): void {
     const modelStore = this.data.get(model);
 
@@ -219,7 +258,6 @@ export default class Store {
       this._removeFromHasManyArrays(modelName, recordId, visited);
       this._nullifyBelongsToReferences(modelName, recordId, visited);
       this._cleanupRelationshipRegistries(modelName, recordId);
-      recordToUnload.clean();
 
       this.data.get(modelName)?.delete(recordId as string | number);
     }
@@ -308,6 +346,30 @@ export default class Store {
 
     const pendingMap = getPendingRegistry().get(modelName);
     if (pendingMap) pendingMap.delete(recordId);
+
+    // Clean pendingBelongsTo entries in both directions
+    const pendingBelongsToMap = getPendingBelongsToRegistry();
+    if (pendingBelongsToMap) {
+      // Direction 1: evicted record was the TARGET others were waiting for
+      const targetEntries = pendingBelongsToMap.get(modelName);
+      if (targetEntries) targetEntries.delete(recordId);
+
+      // Direction 2: evicted record was the SOURCE with unresolved forward-references
+      for (const [, targetIdMap] of pendingBelongsToMap) {
+        for (const [targetId, entries] of targetIdMap) {
+          if (!Array.isArray(entries)) continue;
+          const filtered = entries.filter((e: unknown) => {
+            const entry = e as { sourceModelName?: string; relationshipId?: unknown };
+            return !(entry.sourceModelName === modelName && entry.relationshipId === recordId);
+          });
+          if (filtered.length === 0) {
+            targetIdMap.delete(targetId);
+          } else if (filtered.length < entries.length) {
+            targetIdMap.set(targetId, filtered);
+          }
+        }
+      }
+    }
   }
 
   /**

package/src/types/orm-types.ts

@@ -18,6 +18,7 @@ export interface OrmMysqlConfig {
   connectionLimit?: number;
   migrationsDir?: string;
   migrationsTable?: string;
+  autoMigrate?: boolean;
   [key: string]: unknown;
 }
 
@@ -30,6 +31,7 @@ export interface OrmPostgresConfig {
   connectionLimit?: number;
   migrationsDir?: string;
   migrationsTable?: string;
+  autoMigrate?: boolean;
   [key: string]: unknown;
 }
 
@@ -48,6 +50,13 @@ export interface OrmRestServerConfig {
   metaRoute: boolean;
 }
 
+export interface OrmDynamoDBConfig {
+  region?: string;
+  endpoint?: string;
+  tablePrefix?: string;
+  [key: string]: unknown;
+}
+
 export interface OrmSection {
   db: OrmDbConfig;
   paths: OrmPaths;
@@ -55,6 +64,9 @@ export interface OrmSection {
   mysql?: OrmMysqlConfig;
   postgres?: OrmPostgresConfig;
   timescale?: OrmPostgresConfig;
+  dynamodb?: OrmDynamoDBConfig;
+  logColor?: string;
+  logMethod?: string;
   [key: string]: unknown;
 }
 
@@ -156,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/types/stonyx.d.ts

@@ -5,7 +5,13 @@ declare module 'stonyx/config' {
 }
 
 declare module 'stonyx/log' {
-  const log: Record<string, ((...args: unknown[]) => void) | undefined>;
+  interface Log {
+    db(message: string): void;
+    error(message: string, ...args: unknown[]): void;
+    defineType(type: string, setting: string, options?: Record<string, unknown> | null): void;
+    [key: string]: ((...args: unknown[]) => void) | undefined;
+  }
+  const log: Log;
   export default log;
 }