@stonyx/orm 0.3.2-alpha.11 → 0.3.2-alpha.111

package/README.md

@@ -40,6 +40,12 @@ All properties prefixed with `__` (`__data`, `__relationships`, `__model`, `__se
 npm install @stonyx/orm
 ````
 
+That is the whole install for an ORM-only app. The database drivers and
+`@stonyx/rest-server` are **optional peer dependencies**: a default install does
+not put them on disk, and none of them is loaded unless your configuration asks
+for it. Add only the ones you actually use — see
+[Optional peer dependencies](#optional-peer-dependencies).
+
 ## Usage example
 
 This module is part of the **Stonyx framework**. To use it, first configure the `restServer` key in your `environment.js` file:
@@ -98,20 +104,29 @@ export default {
       connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
       migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
       migrationsTable: '__migrations',
+      autoMigrate: AUTO_MIGRATE === 'true' ? true : AUTO_MIGRATE === 'false' ? false : undefined,
     } : undefined,
     dynamodb: DYNAMODB_REGION ? {
-      region: DYNAMODB_REGION ?? 'us-east-1',
+      region: DYNAMODB_REGION,
       endpoint: DYNAMODB_ENDPOINT,          // optional, for DynamoDB Local
       tablePrefix: DYNAMODB_TABLE_PREFIX,   // optional table name prefix
     } : undefined,
     restServer: {
-      enabled: ORM_USE_REST_SERVER ?? 'true',
+      // 'true' requires @stonyx/rest-server to be installed — see
+      // "Optional peer dependencies" below.
+      enabled: ORM_USE_REST_SERVER ?? 'false',
       route: ORM_REST_ROUTE ?? '/'
     }
   }
 };
 ```
 
+> **`route` and JSON:API `links`.** Generated endpoints are mounted under `route`, and every
+> `links.self` / `links.related` the ORM emits is an absolute URL that includes it. With
+> `ORM_REST_ROUTE='/api'` the animal collection is served at `/api/animals` and advertises
+> `http://host/api/animals`, so published links are followable as-is — do not prepend the
+> mount yourself.
+
 Then run the application via the Stonyx CLI, which auto-initializes all modules including the ORM:
 
 ```bash
@@ -120,6 +135,46 @@ stonyx serve
 
 For further framework instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
 
+## Optional peer dependencies
+
+`@stonyx/orm` boots with **none** of its optional peers installed. Each one is
+imported lazily, and only when your configuration selects it:
+
+| Configuration | Package you must install |
+|---|---|
+| `orm.restServer.enabled: 'true'` | `@stonyx/rest-server` |
+| `orm.postgres` or `orm.timescale` | `pg` |
+| `orm.mysql` | `mysql2` |
+| `orm.dynamodb` | `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
+
+If a configuration key selects one that is not on disk, the failure surfaces
+from `Orm.init()` while the framework boots:
+
+```
+Cannot find package '@stonyx/rest-server' imported from .../@stonyx/orm/dist/orm-request.js
+```
+
+**ORM-only, no REST server.** This is the shape the `environment.js` above is
+written for: keep `orm.restServer.enabled` at `'false'` and install nothing
+beyond `@stonyx/orm`. Models, relationships, serializers, transforms and hooks
+work unchanged; only the generated REST routes are absent.
+
+> **The module's own default is the other way round.** The `config/environment.js`
+> that ships inside `@stonyx/orm` defaults `restServer.enabled` to `'true'`, so
+> an app that omits the `restServer` key *entirely* gets REST switched on and
+> needs `@stonyx/rest-server` installed. Set the key explicitly, whichever way
+> you want it.
+
+**Turning REST on.**
+
+```bash
+npm install @stonyx/rest-server
+ORM_USE_REST_SERVER=true stonyx serve
+```
+
+See [REST Server Integration](#rest-server-integration) for access classes and
+route configuration.
+
 ## Models
 
 Define a model with attributes and relationships:
@@ -311,16 +366,127 @@ await setupRestServer('/', './access');
 Access classes define models and provide custom filtering/authorization logic:
 
 ```js
-export default class GlobalAccess {
-  models = ['owner', 'animal'];
+export default class OwnerAccess {
+  models = ['owner'];
 
   access(request) {
-    if (request.url.endsWith('/owner/angela')) return false;
+    // `access` runs after route matching, so `request.params` is populated and
+    // `id` has already been URL-decoded. Authorize on it, never on a URL.
+    const { id } = request.params;
+
+    // `id` is still raw client text. Normalise it the way the record lookup
+    // does, or your predicate and the lookup disagree — see "Numeric ids" below.
+    // No radix on parseInt: that is deliberate, and it must stay that way.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+
+    // Returning false explicitly denies access to this record
+    if (recordId === 'angela') return false;
+
+    // No `id` means the collection route. Returning a function plugs it in to
+    // the response object as a filter. NOTE: a function return authorizes the
+    // request outright — the operations list below is not consulted — so this
+    // branch permits POST /owners as well as reads.
+    if (recordId === undefined) return record => record.id !== 'angela';
+
+    // Returning a list of operations allows full access to everything else
     return ['read', 'create', 'update', 'delete'];
   }
 }
 ```
 
+**Do not authorize on the request URL.** `request.url` is rewritten relative to
+the mount point, so inside the REST server it is `/angela`, not `/owners/angela`
+— a suffix comparison against it never matches and the request falls through to
+whatever the method returns next. `request.originalUrl` keeps the full path but
+is still the raw text the client sent, so it varies with query strings
+(`/owners?x=1`), trailing slashes (`/owners/angela/`), casing (`/OwNeRs/angela`)
+and percent-encoding (`/owners/%61ngela`). Each of those is a plain address-bar
+request. Which of them reach your handler at all depends on how the REST server
+configures Express route matching — that is a deployment detail you should not
+be building an authorization decision on top of. `request.params.id` is
+identical for every spelling that does reach you.
+
+**One access class per model when the rules are model-specific.** `access()`
+receives only the request, and the request does not carry the model name
+directly — `request.baseUrl` is the *mount text as the client spelled it*
+(`/OWNERS`), so it must be case-normalised before it is compared, and it is
+still the mount rather than the model. Deriving a model from it means every
+unrecognised spelling falls through to whatever your method returns next, so
+prefer one class per model. A class may still list several models in `models`
+when they share one rule.
+
+**Numeric ids: normalise before you compare.** `request.params.id` is raw text
+from the client. When it looks numeric the ORM coerces it — `isNaN(id) ? id :
+parseInt(id)` — *before* it resolves the record, so `7`, `007`, `7.0`, `7.9`,
+`7e0`, `0x7`, `+7`, `%207` (a leading space), `%097` (a tab) and `7%0A` (a
+trailing newline) all address record `7`, while a `===` against the raw text
+matches only the one spelling you wrote down. Every other spelling falls through
+to whatever your method returns next — which, in the shape above, is a full CRUD
+grant. All of them are plain address-bar requests.
+
+Two details are load-bearing. `parseInt` is called with **no radix**, so `0x7`
+is `7` and not `0`; writing `parseInt(id, 10)` in your predicate re-opens the
+hex spelling. And the coercion applies only when the id looks numeric, so a
+model with string ids (like `owner` above) is unaffected — which is exactly why
+this is easy to miss. Normalise the same way the lookup does:
+
+```javascript
+export default class AnimalAccess {
+  models = ['animal'];
+
+  access(request) {
+    const { id } = request.params;
+
+    // Agrees with the lookup for every spelling of 7 above. Compare the
+    // coerced value, which for a numeric-id model is a number, not a string.
+    const recordId = id === undefined ? undefined : (isNaN(id) ? id : parseInt(id));
+
+    if (recordId === 7) return false;
+
+    if (recordId === undefined) return record => record.id !== 7;
+
+    return ['read', 'create', 'update', 'delete'];
+  }
+}
+```
+
+Both samples above are extracted from this file and executed verbatim against a
+live server on every CI run — see
+[`test/integration/readme-access/`](https://github.com/abofs/stonyx-orm/tree/dev/test/integration/readme-access).
+`DELETE /owners/angela` is asserted to be refused with the record intact, and
+every spelling named above is measured individually, the numeric ones over a raw
+socket. Nothing in this section is prose that was never run.
+
+### Upgrading: behaviour changes
+
+**Advertised `links.self` / `links.related` now carry the REST mount route.**
+Consumer-visible for any deployment where `orm.restServer.route` is not the
+default `'/'`.
+
+Measured on this repo's mounted-route harness at `ORM_REST_ROUTE='/api'`, resource
+`links.self` in the response to `GET /api/animals/1`:
+
+| | published `links.self` | fetching that URL |
+|---|---|---|
+| before | `http://host/animals/1` | **404** |
+| after | `http://host/api/animals/1` | **200** |
+
+The ORM previously built links from the request origin alone, so at any non-default
+mount every URL it advertised pointed at a route that did not exist
+(abofs/stonyx-orm#254). Links are now built from the path the routes are actually
+mounted at, and are followable verbatim.
+
+**⚠️ Breaking if you carry a prepending workaround.** The usual workaround for #254
+was for the client to prepend the mount to every link the ORM published. That now
+double-prefixes: prepending `/api` to the new `http://host/api/animals/1` yields
+`http://host/api/api/animals/1`, measured **404**. Remove the prepending. There is no
+configuration flag that restores the old link shape.
+
+**Unaffected.** Deployments on the default `ORM_REST_ROUTE='/'` see byte-identical
+output — the prefix is empty, and this is pinned by a byte-identity test against a
+golden fixture captured *before* the fix. Response structure, field names and the
+public API are unchanged; only the URL value inside `links` changes.
+
 ### Include Parameter (Sideloading Relationships)
 
 The ORM supports JSON API-compliant relationship sideloading via the `include` query parameter. This reduces the need for multiple API requests by embedding related records in a single response.
@@ -798,7 +964,9 @@ test('validation hook rejects negative age', async () => {
 
 ## Project Structure
 
-For a full architectural reference, see [project-structure.md](project-structure.md).
+For a full architectural reference, see
+[docs/project-structure.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/project-structure.md).
+That file is repo-only — it is not in the published tarball, so the link is absolute.
 
 ## License
 

package/dist/dynamodb/connection.d.ts

@@ -7,15 +7,18 @@
 export interface DynamoDBConfig {
     region?: string;
     endpoint?: string;
+    tablePrefix?: string;
     [key: string]: unknown;
 }
 export type DocumentClient = {
     send(command: unknown): Promise<unknown>;
 };
-export type DocumentClientConstructor = new (options: {
-    client: unknown;
-}) => DocumentClient;
-export type DynamoDBClientConstructor = new (options: unknown) => unknown;
+export type DynamoDBClientConstructor = new (options: unknown) => {
+    config: unknown;
+};
+export type DocumentClientFromFn = {
+    from(client: unknown): DocumentClient;
+};
 /**
  * Create a DynamoDBDocumentClient from the given config.
  * Uses dynamic import so @aws-sdk/* are optional peer deps.

package/dist/dynamodb/connection.js

@@ -9,15 +9,15 @@
  * Uses dynamic import so @aws-sdk/* are optional peer deps.
  */
 export async function createDocumentClient(dbConfig) {
-    const { DynamoDB } = await import('@aws-sdk/client-dynamodb');
-    const { DynamoDBDocument } = await import('@aws-sdk/lib-dynamodb');
+    const { DynamoDBClient } = await import('@aws-sdk/client-dynamodb');
+    const { DynamoDBDocumentClient } = await import('@aws-sdk/lib-dynamodb');
     const clientOptions = {};
     if (dbConfig.region)
         clientOptions.region = dbConfig.region;
     if (dbConfig.endpoint)
         clientOptions.endpoint = dbConfig.endpoint;
-    const rawClient = new DynamoDB(clientOptions);
-    return new DynamoDBDocument({ client: rawClient });
+    const rawClient = new DynamoDBClient(clientOptions);
+    return DynamoDBDocumentClient.from(rawClient);
 }
 /**
  * Nullify the document client reference (DynamoDB connections are HTTP-based

package/dist/dynamodb/dynamodb-db.d.ts

@@ -91,6 +91,7 @@ export default class DynamoDBDB {
     private _gsiRegistry;
     constructor(deps?: Partial<DynamoDBDeps>);
     private requireClient;
+    private _resolveTableName;
     /** Resolve Orm singleton — falls back to real import in production. */
     private _getOrm;
     init(): Promise<void>;
@@ -100,6 +101,16 @@ export default class DynamoDBDB {
      */
     startup(): Promise<void>;
     shutdown(): Promise<void>;
+    /**
+     * DynamoDB does NOT use write serialization (#156).
+     *
+     * Unlike MySQL/PostgreSQL, DynamoDB has no server-side foreign key
+     * constraints and no multi-row transactions in standard single-item
+     * operations (PutItem, UpdateItem, DeleteItem). Each operation is
+     * atomic at the item level and cannot deadlock against other items.
+     * Concurrent fire-and-forget writes therefore cannot produce the
+     * cross-row lock contention that causes InnoDB/PG deadlocks.
+     */
     persist(operation: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void>;
     findRecord(modelName: string, id: unknown): Promise<OrmRecord | undefined>;
     findAll(modelName: string, conditions?: Record<string, unknown>): Promise<OrmRecord[]>;

package/dist/dynamodb/dynamodb-db.js

@@ -33,6 +33,23 @@ function generateUlid() {
     }
     return id;
 }
+/**
+ * Generates a monotonically unique numeric ID for DynamoDB tables with numeric keys.
+ * Uses timestamp-based generation with a sub-millisecond counter to ensure uniqueness.
+ */
+let _numericIdCounter = 0;
+let _numericIdLastMs = 0;
+function generateNumericId() {
+    const now = Date.now();
+    if (now === _numericIdLastMs) {
+        _numericIdCounter++;
+    }
+    else {
+        _numericIdLastMs = now;
+        _numericIdCounter = 0;
+    }
+    return now * 1000 + _numericIdCounter;
+}
 // ---------------------------------------------------------------------------
 // SDK Command factories (injectable for testing without real AWS SDK)
 // ---------------------------------------------------------------------------
@@ -93,6 +110,9 @@ export default class DynamoDBDB {
             throw new Error('DynamoDBDB client not initialized — call init() first');
         return this.client;
     }
+    _resolveTableName(modelName) {
+        return (this.dbConfig.tablePrefix ?? '') + sanitizeTableName(this.deps.getPluralName(modelName));
+    }
     /** Resolve Orm singleton — falls back to real import in production. */
     async _getOrm() {
         if (this.deps._importOrm)
@@ -124,7 +144,7 @@ export default class DynamoDBDB {
             clientOptions.endpoint = this.dbConfig.endpoint;
         const rawClient = new DynamoDBClient(clientOptions);
         for (const [modelName, schema] of Object.entries(schemas)) {
-            const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+            const tableName = this._resolveTableName(modelName);
             const gsis = this._buildGsiDefinitions(modelName, schema);
             try {
                 const desc = await rawClient.send(new DescribeTableCommand({ TableName: tableName }));
@@ -171,6 +191,16 @@ export default class DynamoDBDB {
     // -------------------------------------------------------------------------
     // SqlDb contract — persist
     // -------------------------------------------------------------------------
+    /**
+     * DynamoDB does NOT use write serialization (#156).
+     *
+     * Unlike MySQL/PostgreSQL, DynamoDB has no server-side foreign key
+     * constraints and no multi-row transactions in standard single-item
+     * operations (PutItem, UpdateItem, DeleteItem). Each operation is
+     * atomic at the item level and cannot deadlock against other items.
+     * Concurrent fire-and-forget writes therefore cannot produce the
+     * cross-row lock contention that causes InnoDB/PG deadlocks.
+     */
     async persist(operation, modelName, context, response) {
         const OrmModule = await this._getOrm();
         if (OrmModule.default?.instance?.isView?.(modelName))
@@ -192,7 +222,7 @@ export default class DynamoDBDB {
         const schema = schemas[modelName];
         if (!schema)
             return undefined;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const { GetCommand } = await this.deps.loadDocClientCommands();
         const params = this.deps.buildGetItem(tableName, { id });
         try {
@@ -220,7 +250,7 @@ export default class DynamoDBDB {
         const schema = schemas[modelName];
         if (!schema)
             return [];
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         try {
             let items;
             if (!conditions || Object.keys(conditions).length === 0) {
@@ -275,7 +305,7 @@ export default class DynamoDBDB {
                 continue;
             }
             const schema = schemas[modelName];
-            const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+            const tableName = this._resolveTableName(modelName);
             try {
                 const items = await this._paginatedScan(tableName);
                 for (const item of items) {
@@ -308,11 +338,12 @@ export default class DynamoDBDB {
         if (!record)
             return;
         const isPendingId = context.rawData?.__pendingSqlId === true;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
-        // For numeric-ID models with a pending ID, generate a ULID
+        const tableName = this._resolveTableName(modelName);
+        // For models with a pending ID, generate a unique replacement ID
         let finalId = record.id;
         if (isPendingId) {
-            finalId = generateUlid();
+            const keyType = this.deps.getDynamoKeyType(schema.idType);
+            finalId = keyType === 'N' ? generateNumericId() : generateUlid();
         }
         const item = this._recordToItem(record, schema, context.rawData);
         item.id = finalId;
@@ -340,7 +371,7 @@ export default class DynamoDBDB {
         const record = context.record;
         if (!record)
             return;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const id = record.id;
         const oldState = context.oldState || {};
         const currentData = record.__data;
@@ -348,7 +379,11 @@ export default class DynamoDBDB {
         const changedData = {};
         for (const col of Object.keys(schema.columns)) {
             if (currentData[col] !== oldState[col]) {
-                changedData[col] = currentData[col] ?? null;
+                const value = currentData[col] ?? null;
+                // Date objects must be serialized to ISO-8601 strings for DynamoDB 'S' storage
+                changedData[col] = (value instanceof Date)
+                    ? value.toISOString()
+                    : value;
             }
         }
         // FK changes
@@ -376,7 +411,7 @@ export default class DynamoDBDB {
         const id = context.recordId;
         if (id == null)
             return;
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const { DeleteCommand } = await this.deps.loadDocClientCommands();
         const params = this.deps.buildDeleteItem(tableName, { id });
         await this.requireClient().send(new DeleteCommand(params));
@@ -422,7 +457,7 @@ export default class DynamoDBDB {
     _buildGsiRegistry() {
         const schemas = this.deps.introspectModels();
         for (const [modelName, schema] of Object.entries(schemas)) {
-            const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+            const tableName = this._resolveTableName(modelName);
             const modelGsis = new Map();
             for (const fkCol of Object.keys(schema.foreignKeys)) {
                 const gsiName = `${tableName}-${fkCol}-index`;
@@ -471,7 +506,7 @@ export default class DynamoDBDB {
         });
     }
     _buildGsiDefinitions(modelName, schema) {
-        const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+        const tableName = this._resolveTableName(modelName);
         const gsis = [];
         for (const fkCol of Object.keys(schema.foreignKeys)) {
             const gsiName = `${tableName}-${fkCol}-index`;
@@ -515,8 +550,13 @@ export default class DynamoDBDB {
         if (data.id !== undefined)
             item.id = data.id;
         for (const col of Object.keys(schema.columns)) {
-            if (data[col] !== undefined)
-                item[col] = data[col];
+            if (data[col] !== undefined) {
+                const value = data[col];
+                // Date objects must be serialized to ISO-8601 strings for DynamoDB 'S' storage
+                item[col] = (value instanceof Date)
+                    ? value.toISOString()
+                    : value;
+            }
         }
         for (const fkCol of Object.keys(schema.foreignKeys)) {
             const relName = fkCol.replace(/_id$/, '');

package/dist/dynamodb/operation-builder.js

@@ -64,19 +64,22 @@ export function buildScan(tableName, conditions, exclusiveStartKey) {
     if (exclusiveStartKey)
         params.ExclusiveStartKey = exclusiveStartKey;
     if (conditions && Object.keys(conditions).length > 0) {
-        const names = {};
-        const values = {};
-        const clauses = [];
-        for (const [attr, val] of Object.entries(conditions)) {
-            const nameAlias = `#${attr}`;
-            const valAlias = `:${attr}`;
-            names[nameAlias] = attr;
-            values[valAlias] = val;
-            clauses.push(`${nameAlias} = ${valAlias}`);
+        const validEntries = Object.entries(conditions).filter(([, val]) => val !== undefined && val !== null);
+        if (validEntries.length > 0) {
+            const names = {};
+            const values = {};
+            const clauses = [];
+            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;
         }
-        params.FilterExpression = clauses.join(' AND ');
-        params.ExpressionAttributeNames = names;
-        params.ExpressionAttributeValues = values;
     }
     return params;
 }
@@ -86,10 +89,14 @@ export function buildScan(tableName, conditions, exclusiveStartKey) {
  * as equality expressions joined by AND.
  */
 export function buildQuery(tableName, indexName, keyConditions, exclusiveStartKey) {
+    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 = {};
     const values = {};
     const clauses = [];
-    for (const [attr, val] of Object.entries(keyConditions)) {
+    for (const [attr, val] of validEntries) {
         const nameAlias = `#${attr}`;
         const valAlias = `:${attr}`;
         names[nameAlias] = attr;

package/dist/main.js

@@ -19,7 +19,6 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
-import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -131,6 +130,25 @@ export default class Orm {
             promises.push(db.init());
         }
         if (restServer.enabled === 'true') {
+            // MUST stay dynamic. setup-rest-server.js names the optional
+            // '@stonyx/rest-server' peer in its own static graph — directly, and
+            // through orm-request.ts / meta-request.ts, which import `Request` at
+            // module scope because they extend it (correctly: an `extends` base
+            // class cannot be awaited). Node links a module's entire static graph
+            // before evaluating any of it, so a static import here puts that
+            // specifier on the entry graph and `import('@stonyx/orm')` throws
+            // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
+            // optional peer.
+            //
+            // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
+            // modules carry no static peer specifier that survives to `dist/`
+            // (postgres-db.ts:15 and mysql-db.ts:17 are `import type`, erased by
+            // tsc), so the `await import()` there is not what isolates pg / mysql2 /
+            // @aws-sdk — that happens one layer down, in src/*/connection.ts (and
+            // src/dynamodb/dynamodb-db.ts).
+            // setup-rest-server.js is the only dist module whose laziness is
+            // load-bearing for peer resolution. (#280)
+            const { default: setupRestServer } = await import('./setup-rest-server.js');
             promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
         }
         // Wire up memory resolver so store.find() can check model memory flags

package/dist/manage-record.js

@@ -52,13 +52,34 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
             relationship.push(record);
         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);
     const pendingBelongsTo = Array.isArray(pendingBelongsToRaw) ? pendingBelongsToRaw : undefined;
     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
             sourceRecord.__relationships[relationshipKey] = record;
@@ -72,7 +93,7 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
                 }
             }
             // 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);
             }
@@ -83,14 +104,24 @@ export function createRecord(modelName, rawData = {}, userOptions = {}) {
     // 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) => {
+        orm.sqlDb.persist('create', modelName, { rawData }, response)
+            .catch((err) => {
             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;

package/dist/mysql/connection.d.ts

@@ -8,6 +8,7 @@ interface MysqlConfig {
     connectionLimit?: number;
     migrationsTable?: string;
     migrationsDir?: string;
+    autoMigrate?: boolean;
 }
 export declare function getPool(mysqlConfig: MysqlConfig): Promise<Pool>;
 export declare function closePool(): Promise<void>;

package/dist/mysql/mysql-db.d.ts

@@ -61,6 +61,14 @@ export default class MysqlDB {
     deps: MysqlDBDeps;
     pool: Pool | null;
     mysqlConfig: MysqlConfig;
+    /**
+     * Promise-chain mutex for write serialization (#156).
+     * All persist() calls chain through this single queue so concurrent
+     * fire-and-forget writes never produce parallel InnoDB transactions
+     * on FK-linked rows (which cause deadlocks).
+     * Reads are NOT affected — only persist() serializes.
+     */
+    private _writeQueue;
     constructor(deps?: Partial<MysqlDBDeps>);
     private requirePool;
     init(): Promise<void>;