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

package/src/dynamodb/operation-builder.ts

@@ -0,0 +1,202 @@
+/**
+ * DynamoDB operation parameter builders.
+ *
+ * Each function returns a plain-object "params" bag that can be passed
+ * directly to the corresponding DocumentClient command
+ * (PutCommand, GetCommand, UpdateCommand, DeleteCommand, ScanCommand, QueryCommand).
+ *
+ * All functions are pure — no SDK imports here; the caller wraps params
+ * in the appropriate Command class.
+ */
+
+export interface PutItemParams {
+  TableName: string;
+  Item: Record<string, unknown>;
+  ConditionExpression?: string;
+}
+
+export interface GetItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface UpdateItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+  UpdateExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ReturnValues: string;
+}
+
+export interface DeleteItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface ScanParams {
+  TableName: string;
+  FilterExpression?: string;
+  ExpressionAttributeNames?: Record<string, string>;
+  ExpressionAttributeValues?: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+export interface QueryParams {
+  TableName: string;
+  IndexName: string;
+  KeyConditionExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+/**
+ * PutItem — optionally with a condition expression.
+ *
+ * Pass conditionExpression = 'attribute_not_exists(id)' to enforce uniqueness.
+ */
+export function buildPutItem(
+  tableName: string,
+  item: Record<string, unknown>,
+  conditionExpression?: string,
+): PutItemParams {
+  const params: PutItemParams = { TableName: tableName, Item: item };
+  if (conditionExpression) params.ConditionExpression = conditionExpression;
+  return params;
+}
+
+/**
+ * GetItem by primary key.
+ */
+export function buildGetItem(
+  tableName: string,
+  key: Record<string, unknown>,
+): GetItemParams {
+  return { TableName: tableName, Key: key };
+}
+
+/**
+ * UpdateItem with a SET expression built from the `updates` object.
+ * Only the supplied attributes are updated (diff-based call site).
+ */
+export function buildUpdateItem(
+  tableName: string,
+  key: Record<string, unknown>,
+  updates: Record<string, unknown>,
+): UpdateItemParams {
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const setClauses: string[] = [];
+
+  for (const [attr, val] of Object.entries(updates)) {
+    const nameAlias = `#${attr}`;
+    const valAlias = `:${attr}`;
+    names[nameAlias] = attr;
+    values[valAlias] = val;
+    setClauses.push(`${nameAlias} = ${valAlias}`);
+  }
+
+  return {
+    TableName: tableName,
+    Key: key,
+    UpdateExpression: `SET ${setClauses.join(', ')}`,
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values,
+    ReturnValues: 'NONE',
+  };
+}
+
+/**
+ * DeleteItem by primary key.
+ */
+export function buildDeleteItem(
+  tableName: string,
+  key: Record<string, unknown>,
+): DeleteItemParams {
+  return { TableName: tableName, Key: key };
+}
+
+/**
+ * ScanCommand params.
+ * If conditions are supplied they are rendered as a FilterExpression using AND.
+ */
+export function buildScan(
+  tableName: string,
+  conditions?: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): ScanParams {
+  const params: ScanParams = { TableName: tableName };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  if (conditions && Object.keys(conditions).length > 0) {
+    const validEntries = Object.entries(conditions).filter(
+      ([, val]) => val !== undefined && val !== null,
+    );
+
+    if (validEntries.length > 0) {
+      const names: Record<string, string> = {};
+      const values: Record<string, unknown> = {};
+      const clauses: string[] = [];
+
+      for (const [attr, val] of validEntries) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        clauses.push(`${nameAlias} = ${valAlias}`);
+      }
+
+      params.FilterExpression = clauses.join(' AND ');
+      params.ExpressionAttributeNames = names;
+      params.ExpressionAttributeValues = values;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * QueryCommand params for a GSI.
+ * keyConditions must be in the form { attrName: value } and will be rendered
+ * as equality expressions joined by AND.
+ */
+export function buildQuery(
+  tableName: string,
+  indexName: string,
+  keyConditions: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): QueryParams {
+  const validEntries = Object.entries(keyConditions).filter(
+    ([, val]) => val !== undefined && val !== null,
+  );
+
+  if (validEntries.length === 0) {
+    throw new Error('buildQuery: all keyCondition values are undefined/null');
+  }
+
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const clauses: string[] = [];
+
+  for (const [attr, val] of validEntries) {
+    const nameAlias = `#${attr}`;
+    const valAlias = `:${attr}`;
+    names[nameAlias] = attr;
+    values[valAlias] = val;
+    clauses.push(`${nameAlias} = ${valAlias}`);
+  }
+
+  const params: QueryParams = {
+    TableName: tableName,
+    IndexName: indexName,
+    KeyConditionExpression: clauses.join(' AND '),
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values,
+  };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  return params;
+}

package/src/dynamodb/type-map.ts

@@ -0,0 +1,54 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+
+export type DynamoScalarType = 'S' | 'N' | 'BOOL';
+
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+const typeMap: Record<string, DynamoScalarType> = {
+  string: 'S',
+  number: 'N',
+  float: 'N',
+  boolean: 'BOOL',
+  date: 'S',
+  timestamp: 'N',
+  passthrough: 'S',
+  trim: 'S',
+  uppercase: 'S',
+  ceil: 'N',
+  floor: 'N',
+  round: 'N',
+};
+
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export function getDynamoType(attrType: string): DynamoScalarType {
+  return typeMap[attrType] ?? 'S';
+}
+
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export function getDynamoKeyType(attrType: string): 'S' | 'N' {
+  const t = getDynamoType(attrType);
+  return t === 'N' ? 'N' : 'S';
+}
+
+export default typeMap;

package/src/index.ts

@@ -27,6 +27,7 @@ import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
+export type { AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js'; // access() contract (#202)
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers

package/src/main.ts

@@ -25,6 +25,7 @@ import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
 import { setup } from '@stonyx/events';
+import type { AccessFunction } from './types/orm-types.js';
 
 interface OrmOptions {
   dbType?: string;
@@ -68,6 +69,53 @@ export default class Orm {
   views: Record<string, unknown> = {};
   transforms: Record<string, (value: unknown) => unknown> = { ...baseTransforms };
   warnings: Set<string> = 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: Record<string, AccessFunction> = {};
+
   options!: OrmOptions;
   sqlDb?: SqlDb;
   db?: OrmDB | SqlDb;
@@ -90,6 +138,11 @@ export default class Orm {
   }
 
   async init(): Promise<void> {
+    // Self-register so log.db works even when @stonyx/orm is in the
+    // consumer's `dependencies` (stonyx loader only merges devDependencies).
+    const { logColor = 'white', logMethod = 'db' } = config.orm;
+    log.defineType(logMethod, logColor);
+
     const { paths, restServer } = config.orm;
 
     const promises: Promise<unknown>[] = ['Model', 'Serializer', 'Transform'].map(type => {
@@ -159,6 +212,11 @@ export default class Orm {
       this.sqlDb = new MysqlDB() as SqlDb;
       this.db = this.sqlDb;
       promises.push(this.sqlDb.init());
+    } else if (config.orm.dynamodb) {
+      const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+      this.sqlDb = new DynamoDBDB() as SqlDb;
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
     } else if (this.options.dbType !== 'none') {
       const db = new DB();
       this.db = db;
@@ -185,6 +243,81 @@ export default class Orm {
     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: string): AccessFunction | undefined {
+    if (!Object.hasOwn(this.accessFunctions, modelName)) return undefined;
+
+    return this.accessFunctions[modelName];
+  }
+
   async startup(): Promise<void> {
     if (this.sqlDb) await this.sqlDb.startup();
   }

package/src/manage-record.ts

@@ -79,6 +79,28 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
     pendingHasMany.splice(0);
   }
 
+  // FK-based inverse hasMany wiring — when a child record is created with a
+  // foreign-key field (e.g. `owner: 'owner-1'` on an animal), find any parent
+  // whose hasMany registry targets this model and push the child into the
+  // parent's shared array.  This covers edge cases where the child is created
+  // in a separate async frame without a belongsTo handler firing.
+  const hasManyReg = getHasManyRegistry();
+  if (hasManyReg) {
+    for (const [parentModelName, targetMap] of hasManyReg) {
+      const childArrayMap = targetMap.get(modelName);
+      if (!childArrayMap) continue;
+
+      // Check if rawData contains a FK field matching the parent model name
+      const fkValue = rawData[parentModelName];
+      if (fkValue === undefined || fkValue === null) continue;
+
+      const parentArray = childArrayMap.get(fkValue);
+      if (parentArray && !parentArray.includes(record)) {
+        parentArray.push(record);
+      }
+    }
+  }
+
   // Fulfill pending belongsTo relationships
   const pendingBelongsToQueue = getPendingBelongsToRegistry();
   const pendingBelongsToRaw = pendingBelongsToQueue.get(modelName)?.get(record.id);
@@ -86,7 +108,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
 
   if (pendingBelongsTo) {
     const belongsToReg = getBelongsToRegistry();
-    const hasManyReg = getHasManyRegistry();
+    const pendingHasManyReg = getHasManyRegistry();
 
     for (const { sourceRecord, sourceModelName, relationshipKey, relationshipId } of pendingBelongsTo) {
       // Update the belongsTo relationship on the source record
@@ -103,7 +125,7 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
       }
 
       // Wire inverse hasMany if it exists
-      const inverseHasMany = hasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
+      const inverseHasMany = pendingHasManyReg.get(modelName)?.get(sourceModelName)?.get(record.id);
 
       if (inverseHasMany && !inverseHasMany.includes(sourceRecord)) {
         inverseHasMany.push(sourceRecord);
@@ -117,15 +139,25 @@ export function createRecord(modelName: string, rawData: { [key: string]: unknow
   // Auto-persist to SQL — skip for DB loads (isDbRecord) and relationship resolution (_relationshipKey)
   const shouldPersist = orm?.sqlDb && !options.isDbRecord && !userOptions._relationshipKey && !options._skipAutoPersist;
   if (shouldPersist) {
+    // Capture ID before persist — SQL adapters re-key pending IDs to real DB IDs,
+    // but relationship registries were keyed with this original ID
+    const registryId = record.id;
     const response = { data: { id: record.id } };
-    orm!.sqlDb!.persist('create', modelName, { rawData }, response).catch((err: unknown) => {
-      orm!.emitPersistError({
-        operation: 'create',
-        modelName,
-        recordId: record.id,
-        error: err instanceof Error ? err : new Error(String(err)),
+    orm!.sqlDb!.persist('create', modelName, { rawData }, response)
+      .catch((err: unknown) => {
+        orm!.emitPersistError({
+          operation: 'create',
+          modelName,
+          recordId: record.id,
+          error: err instanceof Error ? err : new Error(String(err)),
+        });
+      })
+      .finally(() => {
+        // Evict non-memory records after persist to prevent unbounded heap growth (stonyx#81)
+        if (store._memoryResolver && !store._memoryResolver(modelName)) {
+          store.evictRecord(modelName, record.id, registryId);
+        }
       });
-    });
   }
 
   return record;
@@ -163,17 +195,52 @@ export function updateRecord(record: OrmRecord, rawData: unknown, userOptions: C
 }
 
 /**
- * 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: string, rawData: { [key: string]: unknown }): void {
-  if (rawData.id) return;
+  // 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. Pinned by test/unit/assign-record-id-test.ts (AC6's
+  // BOUNDARY assertions) and by access-filter-enforcement-test.ts assertion 44.
+  // Widening this to `!== undefined` breaks both.
+  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;
@@ -183,15 +250,85 @@ function assignRecordId(modelName: string, rawData: { [key: string]: unknown }):
   const storeMap = store.get(modelName);
   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 as number) + 1 : 1;
+
+  // The shape of src/standalone-db.ts:134-137, and it is chosen over
+  // `Math.max(...ids)` for a reason that is measurable rather than stylistic:
+  // a store CAN hold a record under the key `NaN` (`{id: '   '}` is truthy, so
+  // it survives the guard above and NaNs in the number transform — that is the
+  // state access-filter-enforcement-test.ts assertion 44 constructs). `Math.max`
+  // returns `NaN` if any operand is `NaN`, so it would assign `NaN`, land on
+  // that slot and overwrite it — exactly the defect being fixed, in a new
+  // disguise. This reduce cannot: non-numbers are skipped, and `NaN > max` is
+  // `false`. Pinned by AC2.
+  const maxId = modelStore.reduce((max: number, record) => {
+    const recordId = record.id as unknown;
+
+    return typeof recordId === 'number' && recordId > max ? recordId : max;
+  }, 0);
+
+  // 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`. On a string-id model those two differ: the
+  // number `1` is looked up, the record lands under the string `'1'`. A guard
+  // written as `storeMap.has(rawData.id)` therefore checks a key the record will
+  // never occupy, misses an occupied slot and overwrites it — measured: owner
+  // '1' age 55 -> 9, 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: it makes :50 and :69 agree by construction.
+  //
+  // Termination: with an injective id transform at most `storeMap.size`
+  // candidates can be occupied. A NON-injective id type would otherwise spin
+  // forever, so the loop is bounded and exits with a defined error the route can
+  // report instead of hanging the request.
+  //
+  // Resolved ONCE, outside the loop: `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);
+
+  let candidate = maxId + 1;
+  let landingKey = toStoreKey(candidate);
+  let attempts = 0;
+
+  while (storeMap.has(landingKey)) {
+    if (++attempts > storeMap.size) {
+      throw new Error(`Cannot assign record ID: no free id available for model "${modelName}"`);
+    }
+
+    candidate += 1;
+    landingKey = toStoreKey(candidate);
+  }
+
+  rawData.id = landingKey;
 }
 
-function isStringIdModel(modelName: string): boolean {
-  const modelClass = Orm.instance.getRecordClasses(modelName).modelClass as (new (name: string) => { [key: string]: unknown }) | undefined;
-  if (!modelClass) return false;
+/**
+ * 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: string): (value: number) => number | string {
+  const idType = getIdType(modelName);
+  const transform = idType ? Orm.instance?.transforms?.[idType] : undefined;
+
+  if (typeof transform !== 'function') return value => value;
+
+  return value => transform(value) as number | string;
+}
+
+function getIdType(modelName: string): string | undefined {
+  const modelClass = Orm.instance?.getRecordClasses(modelName).modelClass as (new (name: string) => { [key: string]: unknown }) | undefined;
+  if (!modelClass) return undefined;
 
   const model = new modelClass(modelName);
 
-  return (model.id as { type?: string } | undefined)?.type === 'string';
+  return (model.id as { type?: string } | undefined)?.type;
+}
+
+function isStringIdModel(modelName: string): boolean {
+  return getIdType(modelName) === 'string';
 }

package/src/mysql/connection.ts

@@ -9,6 +9,7 @@ interface MysqlConfig {
   connectionLimit?: number;
   migrationsTable?: string;
   migrationsDir?: string;
+  autoMigrate?: boolean;
 }
 
 let pool: Pool | null = null;