@stonyx/orm 0.3.2-alpha.12 → 0.3.2-alpha.121

package/dist/store.js

@@ -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';
 function isStoreRecord(value) {
     return typeof value === 'object' && value !== null && '__data' in value;
@@ -22,7 +22,7 @@ export default class Store {
         this.data = new Map();
     }
     get(key, id) {
-        if (!id)
+        if (id === undefined)
             return this.data.get(key);
         return this.data.get(key)?.get(id);
     }
@@ -107,13 +107,14 @@ export default class Store {
     set(key, value) {
         this.data.set(key, value);
     }
-    remove(key, id) {
+    remove(key, id, options) {
         // 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) => {
                 Orm.instance.emitPersistError({
                     operation: 'delete',
@@ -127,6 +128,40 @@ export default class Store {
             return this.unloadRecord(key, id);
         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, id, registryId) {
+        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, id, options = {}) {
         const modelStore = this.data.get(model);
         if (!modelStore) {
@@ -149,7 +184,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);
         }
     }
@@ -230,6 +264,31 @@ 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) => {
+                        const entry = e;
+                        return !(entry.sourceModelName === modelName && entry.relationshipId === recordId);
+                    });
+                    if (filtered.length === 0) {
+                        targetIdMap.delete(targetId);
+                    }
+                    else if (filtered.length < entries.length) {
+                        targetIdMap.set(targetId, filtered);
+                    }
+                }
+            }
+        }
     }
     /**
      * Extracts hasMany and non-bidirectional belongsTo children from a record

package/dist/types/orm-types.d.ts

@@ -16,6 +16,7 @@ export interface OrmMysqlConfig {
     connectionLimit?: number;
     migrationsDir?: string;
     migrationsTable?: string;
+    autoMigrate?: boolean;
     [key: string]: unknown;
 }
 export interface OrmPostgresConfig {
@@ -27,6 +28,7 @@ export interface OrmPostgresConfig {
     connectionLimit?: number;
     migrationsDir?: string;
     migrationsTable?: string;
+    autoMigrate?: boolean;
     [key: string]: unknown;
 }
 export interface OrmPaths {
@@ -45,6 +47,7 @@ export interface OrmRestServerConfig {
 export interface OrmDynamoDBConfig {
     region?: string;
     endpoint?: string;
+    tablePrefix?: string;
     [key: string]: unknown;
 }
 export interface OrmSection {

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.12",
+  "version": "0.3.2-alpha.121",
   "description": "",
   "main": "dist/index.js",
   "type": "module",
@@ -61,9 +61,10 @@
   },
   "homepage": "https://github.com/abofs/stonyx-orm#readme",
   "dependencies": {
-    "@stonyx/cron": "0.2.1-beta.66",
-    "@stonyx/events": "0.1.1-beta.49",
-    "stonyx": "0.2.3-beta.66"
+    "@stonyx/cron": "0.2.1-beta.149",
+    "@stonyx/events": "0.1.1-beta.68",
+    "@stonyx/utils": "0.2.3-beta.28",
+    "stonyx": "0.2.3-beta.101"
   },
   "peerDependencies": {
     "@aws-sdk/client-dynamodb": "^3.0.0",
@@ -90,8 +91,7 @@
     }
   },
   "devDependencies": {
-    "@stonyx/rest-server": "0.2.1-beta.67",
-    "@stonyx/utils": "0.2.3-beta.24",
+    "@stonyx/rest-server": "0.2.1-beta.151",
     "@types/node": "^25.6.0",
     "mysql2": "^3.20.0",
     "pg": "^8.20.0",
@@ -103,6 +103,10 @@
   "scripts": {
     "build": "tsc",
     "build:test": "tsc -p tsconfig.test.json",
-    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts'"
+    "test": "pnpm build && NODE_ENV=test node --import tsx/esm --import ./test/setup.ts node_modules/qunit/bin/qunit.js 'test/**/*-test.ts' && ORM_TEST_ROUTE=/ pnpm test:mounted && ORM_TEST_ROUTE=/api pnpm test:mounted && ORM_TEST_ROUTE=api pnpm test:mounted && ORM_TEST_ROUTE=/api/v1 pnpm test:mounted && ORM_TEST_ROUTE=/api/ pnpm test:mounted && pnpm test:readme && pnpm test:reference",
+    "test:mounted": "node --import tsx/esm --import ./test/integration/mounted-route/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/mounted-route/links-mounted.ts' 'test/zz-exit-test.ts'",
+    "test:readme": "pnpm build && node --import tsx/esm --import ./test/integration/readme-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/readme-access/readme-sample.ts' 'test/zz-exit-test.ts'",
+    "test:reference": "pnpm build && node --import tsx/esm --import ./test/integration/reference-access/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/reference-access/reference-sample.ts' 'test/integration/reference-access/record-id-resolution.ts' 'test/zz-exit-test.ts'",
+    "test:dynamodb": "pnpm build && node --import tsx/esm --import ./test/integration/dynamodb/setup.ts node_modules/qunit/bin/qunit.js 'test/integration/dynamodb/**/*-test.ts'"
   }
 }

package/src/column-conversion.ts

@@ -0,0 +1,53 @@
+/**
+ * Shared write-path column conversion (#292).
+ *
+ * This module owns the *iteration* only — the single place where a write
+ * payload is walked column-by-column and each value is handed to the driver's
+ * own conversion rule. The rules themselves are genuinely disjoint per driver
+ * (Postgres stringifies for JSONB; DynamoDB's DocumentClient marshals objects
+ * and arrays natively and must NOT be given stringified values) and therefore
+ * deliberately live with their drivers rather than being merged here.
+ *
+ * The duplicated create/update iteration was the drift vector that produced
+ * #292: `_recordToRow` converted, `_persistUpdate` did not. Routing both
+ * through `convertRow` removes the opportunity for the two to diverge again.
+ */
+
+/**
+ * A driver-supplied per-column conversion rule.
+ *
+ * @param value      the raw value about to be bound into the query
+ * @param columnType the column's declared type from `schema.columns`, or
+ *                   `undefined` when the column is not an attribute column
+ *                   (e.g. `updated_at`, FK columns and `id`, which are added
+ *                   outside the attribute loop). Rules MUST be a no-op for
+ *                   `undefined`.
+ */
+export type ColumnRule = (value: unknown, columnType: string | undefined) => unknown;
+
+/**
+ * Applies `rule` to every column of a complete write payload.
+ *
+ * Call this on the *finished* payload immediately before handing it to the
+ * query builder — not inside a payload-building loop. Columns appended after
+ * such a loop (FKs, `updated_at`) would otherwise bypass conversion, which is
+ * the same class of defect #292 reports.
+ */
+export function convertRow(
+  row: Record<string, unknown>,
+  columns: Record<string, string>,
+  rule: ColumnRule
+): Record<string, unknown> {
+  const converted: Record<string, unknown> = {};
+
+  for (const [col, value] of Object.entries(row)) {
+    // `Object.hasOwn`, not `columns[col]`: a column named `toString` or
+    // `constructor` would otherwise reach the rule with a function as its
+    // "declared type". Inert for the shipped Postgres rule (strict equality
+    // against 'JSONB'), but `ColumnRule` is the extension point other drivers
+    // write against, and the obvious `if (columnType)` rule would invert.
+    converted[col] = rule(value, Object.hasOwn(columns, col) ? columns[col] : undefined);
+  }
+
+  return converted;
+}

package/src/dynamodb/connection.ts

@@ -8,6 +8,7 @@
 export interface DynamoDBConfig {
   region?: string;
   endpoint?: string;
+  tablePrefix?: string;
   [key: string]: unknown;
 }
 
@@ -17,27 +18,27 @@ 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.
  */
 export async function createDocumentClient(dbConfig: DynamoDBConfig): Promise<DocumentClient> {
-  const { DynamoDB } = await import('@aws-sdk/client-dynamodb' as string) as {
-    DynamoDB: DynamoDBClientConstructor;
+  const { DynamoDBClient } = await import('@aws-sdk/client-dynamodb' as string) as {
+    DynamoDBClient: DynamoDBClientConstructor;
   };
-  const { DynamoDBDocument } = await import('@aws-sdk/lib-dynamodb' as string) as {
-    DynamoDBDocument: DocumentClientConstructor;
+  const { DynamoDBDocumentClient } = await import('@aws-sdk/lib-dynamodb' as string) as {
+    DynamoDBDocumentClient: DocumentClientFromFn;
   };
 
   const clientOptions: Record<string, unknown> = {};
   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);
 }
 
 /**

package/src/dynamodb/dynamodb-db.ts

@@ -50,6 +50,24 @@ function generateUlid(): string {
   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(): number {
+  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)
 // ---------------------------------------------------------------------------
@@ -199,6 +217,10 @@ export default class DynamoDBDB {
     return this.client;
   }
 
+  private _resolveTableName(modelName: string): string {
+    return (this.dbConfig.tablePrefix ?? '') + sanitizeTableName(this.deps.getPluralName(modelName));
+  }
+
   /** Resolve Orm singleton — falls back to real import in production. */
   private async _getOrm(): Promise<OrmModule> {
     if (this.deps._importOrm) return this.deps._importOrm();
@@ -235,7 +257,7 @@ export default class DynamoDBDB {
     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 {
@@ -297,6 +319,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: string, modelName: string, context: PersistContext, response: PersistResponse): Promise<void> {
     const OrmModule = await this._getOrm();
     if (OrmModule.default?.instance?.isView?.(modelName)) return;
@@ -320,7 +352,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 });
@@ -354,7 +386,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: Record<string, unknown>[];
@@ -421,7 +453,7 @@ export default class DynamoDBDB {
       }
 
       const schema = schemas[modelName];
-      const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+      const tableName = this._resolveTableName(modelName);
 
       try {
         const items = await this._paginatedScan(tableName);
@@ -457,12 +489,13 @@ export default class DynamoDBDB {
     if (!record) return;
 
     const isPendingId = context.rawData?.__pendingSqlId === true;
-    const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+    const tableName = this._resolveTableName(modelName);
 
-    // For numeric-ID models with a pending ID, generate a ULID
+    // For models with a pending ID, generate a unique replacement ID
     let finalId: unknown = 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);
@@ -494,7 +527,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;
@@ -504,7 +537,11 @@ export default class DynamoDBDB {
 
     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;
       }
     }
 
@@ -535,7 +572,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));
@@ -597,7 +634,7 @@ export default class DynamoDBDB {
     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<string, string>();
 
       for (const fkCol of Object.keys(schema.foreignKeys)) {
@@ -659,7 +696,7 @@ export default class DynamoDBDB {
   }
 
   private _buildGsiDefinitions(modelName: string, schema: ModelSchema): unknown[] {
-    const tableName = sanitizeTableName(this.deps.getPluralName(modelName));
+    const tableName = this._resolveTableName(modelName);
     const gsis: unknown[] = [];
 
     for (const fkCol of Object.keys(schema.foreignKeys)) {
@@ -720,7 +757,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)) {

package/src/dynamodb/operation-builder.ts

@@ -131,21 +131,27 @@ export function buildScan(
   if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
 
   if (conditions && Object.keys(conditions).length > 0) {
-    const names: Record<string, string> = {};
-    const values: Record<string, unknown> = {};
-    const clauses: string[] = [];
-
-    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: 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;
     }
-
-    params.FilterExpression = clauses.join(' AND ');
-    params.ExpressionAttributeNames = names;
-    params.ExpressionAttributeValues = values;
   }
 
   return params;
@@ -162,11 +168,19 @@ export function buildQuery(
   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 Object.entries(keyConditions)) {
+  for (const [attr, val] of validEntries) {
     const nameAlias = `#${attr}`;
     const valAlias = `:${attr}`;
     names[nameAlias] = attr;

package/src/index.ts

@@ -30,6 +30,8 @@ export type { PersistErrorDetail } from './main.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers
+export { default as normalizeRecordId } from './normalize-record-id.js'; // canonical URL-id -> record-id resolution (#270)
+export type { OrmRequest$ as OrmAccessRequest } from './orm-request.js'; // the request access() is handed, incl. recordId (#270)
 export { beforeHook, afterHook, clearHook, clearAllHooks } from './hooks.js'; // middleware hooks
 
 // Store API:

package/src/main.ts

@@ -20,7 +20,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';
@@ -177,6 +176,25 @@ export default class Orm {
     }
 
     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));
     }
 

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;

package/src/mysql/connection.ts

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