@stonyx/orm 0.3.2-beta.29 → 0.3.2-beta.290

package/src/orm-request.ts

@@ -7,11 +7,38 @@ import type { HookContext } from './hooks.js';
 import config from 'stonyx/config';
 import type { OrmRecord } from './types/orm-types.js';
 import { isOrmRecord } from './utils.js';
+import normalizeRecordId from './normalize-record-id.js';
 
-interface OrmRequest$ extends Request {
+/**
+ * The request object a consumer's `access()` predicate receives.
+ *
+ * Exported because `recordId` is public API — README's `access()` samples
+ * destructure it — and a public runtime field with an unreachable type asks the
+ * consumer to re-declare something the framework already knows, which is
+ * abofs/stonyx-orm#270's own defect shape one layer over into the type surface.
+ * `HookContext` (src/hooks.ts) is this repo's precedent for exporting the
+ * interface a consumer is handed. Re-exported from the root barrel as
+ * `OrmAccessRequest` (src/index.ts) — NOT as `OrmRequest`, which is already the
+ * default-exported CLASS in this file and means something else. The
+ * `./orm-request` subpath is not in the `exports` map, so the barrel is the
+ * only reachable spelling.
+ */
+export interface OrmRequest$ extends Request {
   protocol?: string;
+  // Express sets this to the path the router was mounted at, e.g. '/api/animals'
+  // when orm.restServer.route is '/api'. Optional because non-Express callers
+  // (unit tests, programmatic handler invocation) do not supply it.
+  baseUrl?: string;
   method: string;
   params: { [key: string]: string };
+  // Attached by auth() before access() runs — abofs/stonyx-orm#270. This is the
+  // value the ORM resolves the record by; `params.id` remains the raw client
+  // text it was parsed from.
+  //
+  // `undefined` is part of the contract, not an absence: it is how a collection
+  // route is told from a record route, and both documented samples branch on
+  // it. Spelled out rather than left to `?:` for that reason.
+  recordId?: string | number | undefined;
   body?: { [key: string]: unknown };
   query?: { [key: string]: string };
   get(header: string): string;
@@ -77,19 +104,49 @@ function getModelRelationships(modelName: string): { [key: string]: Relationship
   return relationships;
 }
 
-// Helper to build base URL from request
-function getBaseUrl(request: OrmRequest$): string {
+/**
+ * Build the absolute base URL that every advertised link hangs off — origin
+ * plus the prefix the ORM's routes are actually mounted at.
+ *
+ * The prefix is derived from the *request*, not from
+ * `config.orm.restServer.route`. Express sets `request.baseUrl` to the real
+ * mountpath registered by `RestServer.mountRoute`, which for this module is
+ * always `<prefix>/<pluralizedModel>` (see setup-rest-server.ts). Stripping the
+ * trailing model segment therefore yields the prefix by construction, and the
+ * link builder cannot drift from the mount registrar the way a second,
+ * independent normalisation of `route` would.
+ *
+ * When `request.baseUrl` is absent or does not end in the model segment the
+ * prefix is empty, which reproduces the previous origin-only behaviour.
+ */
+function getBaseUrl(request: OrmRequest$, pluralizedModel: string): string {
   const protocol = request.protocol || 'http';
   const host = request.get('host');
-  return `${protocol}://${host}`;
+
+  const modelSegment = `/${pluralizedModel}`;
+  const mountPath = request.baseUrl ?? '';
+  const prefix = mountPath.endsWith(modelSegment) ? mountPath.slice(0, -modelSegment.length) : '';
+
+  return `${protocol}://${host}${prefix}`;
 }
 
+// Kept as a name because twelve `getId(...)` call sites read it. It is now a
+// thin delegate: there is exactly ONE normalisation of a URL id in the repo,
+// and it is the exported one a consumer can import.
+//
+// "of a URL id" is the load-bearing qualifier, and it is the same one
+// src/normalize-record-id.ts:18 carries. Three copies of the coercion survive
+// at this head — src/orm-request.ts (the create-response path),
+// src/postgres/postgres-db.ts and src/mysql/mysql-db.ts — but each normalises a
+// RESPONSE id (`response?.data?.id`), not a URL id, and each omits this
+// function's `if (!id) return ''` guard. They are tracked as
+// abofs/stonyx-orm#282 and enumerated by name in AC-5's allowlist
+// (test/integration/readme-sample-test.ts).
+//
+// A second implementation of the URL-id normalisation here is the defect
+// abofs/stonyx-orm#270 exists to remove — see src/normalize-record-id.ts.
 function getId(params: { id?: string; [key: string]: unknown }): string | number {
-  const id = params.id;
-  if (!id) return '';
-  if (isNaN(id as unknown as number)) return id;
-
-  return parseInt(id);
+  return normalizeRecordId(params.id);
 }
 
 function buildResponse(
@@ -278,7 +335,7 @@ export default class OrmRequest extends Request {
       if (accessFilter) recordsToReturn = recordsToReturn.filter(accessFilter as (record: OrmRecord) => boolean);
       if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate as (record: OrmRecord) => boolean);
 
-      const baseUrl = getBaseUrl(request);
+      const baseUrl = getBaseUrl(request, pluralizedModel);
       const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
@@ -294,7 +351,7 @@ export default class OrmRequest extends Request {
       const fieldsMap = parseFields(request.query);
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
-      const baseUrl = getBaseUrl(request);
+      const baseUrl = getBaseUrl(request, pluralizedModel);
       return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
         baseUrl
@@ -376,7 +433,7 @@ export default class OrmRequest extends Request {
     };
 
     const deleteHandler: HandlerFn = ({ params }) => {
-      store.remove(model, getId(params));
+      store.remove(model, getId(params), { _skipAutoPersist: true });
       return 204;
     };
 
@@ -443,9 +500,14 @@ export default class OrmRequest extends Request {
       // Execute main handler
       const response = await handler(request, state);
 
-      // Persist to SQL database for create/update (delete is handled by store.remove auto-persist)
+      // Set context.record for update BEFORE persist so SQL drivers can read it
+      if (operation === 'update' && (response as JsonApiResponse)?.data) {
+        context.record = store.get(this.model, getId(request.params));
+      }
+
+      // Persist to SQL database for all write operations (create/update/delete)
       const sqlDb = Orm.instance.sqlDb;
-      if (sqlDb && (operation === 'create' || operation === 'update')) {
+      if (sqlDb && WRITE_OPERATIONS.has(operation)) {
         await sqlDb.persist(operation, this.model, context, response);
       }
 
@@ -461,8 +523,6 @@ export default class OrmRequest extends Request {
         const responseData = (response as { data: { id: string | number } }).data;
         const recordId = isNaN(responseData.id as unknown as number) ? responseData.id : parseInt(responseData.id as string);
         context.record = store.get(this.model, recordId);
-      } else if (operation === 'update' && (response as JsonApiResponse)?.data) {
-        context.record = store.get(this.model, getId(request.params));
       } else if (operation === 'delete') {
         // For delete, the record may no longer exist, but we have oldState
         context.recordId = getId(request.params);
@@ -499,7 +559,7 @@ export default class OrmRequest extends Request {
         if (!record) return 404;
 
         const relatedData = record.__relationships[relationshipName];
-        const baseUrl = getBaseUrl(request);
+        const baseUrl = getBaseUrl(request, pluralizedModel);
 
         let data: unknown;
         if (info.isArray) {
@@ -523,7 +583,7 @@ export default class OrmRequest extends Request {
         if (!record) return 404;
 
         const relatedData = record.__relationships[relationshipName];
-        const baseUrl = getBaseUrl(request);
+        const baseUrl = getBaseUrl(request, pluralizedModel);
 
         let data: unknown;
         if (info.isArray) {
@@ -572,6 +632,37 @@ export default class OrmRequest extends Request {
   }
 
   auth(request: OrmRequest$, state: { [key: string]: unknown }): number | undefined {
+    // abofs/stonyx-orm#270 — hand the predicate the value the record is
+    // ACTUALLY resolved by, rather than the raw text it was parsed from.
+    //
+    // This is the default path precisely because it requires the consumer to
+    // remember nothing. Exporting `normalizeRecordId` alone would leave the
+    // framework owning resolution while asking every consumer to call one
+    // function, with no signal when they forget — the same silent fail-open,
+    // one step over. The export is the escape hatch for hooks and custom
+    // handlers; this line is the contract.
+    //
+    // `request.params` is deliberately NOT mutated. Twelve `getId(...)` call
+    // sites read it, and `_withHooks` assigns `params: request.params` onto the
+    // hook context, so every consumer hook reads the same object. Changing
+    // `params.id` from string to number underneath them is a silent behaviour
+    // change on paths this issue is not about.
+    //
+    // Synchronous by necessity: @stonyx/rest-server calls auth() without
+    // awaiting it.
+    //
+    // The `undefined` branch is a PRESENCE check, not a second normalisation:
+    // it answers "does this route carry an :id at all", which is how both
+    // documented samples tell a collection request from a record request. It
+    // cannot be folded into normalizeRecordId, because that function must keep
+    // returning '' for a falsy id — `store.get(key, undefined)` returns the
+    // whole model Map rather than a record (abofs/stonyx-orm#167, pinned by
+    // test/unit/store-get-falsy-id-test.ts), so the resolution path depends on
+    // the '' it returns today.
+    const rawId = request.params?.id;
+
+    request.recordId = rawId === undefined ? undefined : normalizeRecordId(rawId);
+
     const access = this.access(request);
 
     if (!access) return 403;

package/src/postgres/column-rules.ts

@@ -0,0 +1,37 @@
+import type { ColumnRule } from '../column-conversion.js';
+
+/**
+ * PostgreSQL's write-path conversion rule (#292).
+ *
+ * JSONB columns must receive a JSON *string*. node-pg's `prepareValue`
+ * (`pg/lib/utils.js`) checks `Array.isArray` before its object fallback, so a
+ * raw array is rendered as a Postgres array literal (`{"1","2","3"}`) rather
+ * than JSON. `[]` becomes `{}`, which is valid JSON, so it lands silently
+ * corrupted with no error.
+ *
+ * Two behaviours this rule must keep:
+ *
+ *  - `typeof value === 'string'` passes through untouched. A JSONB column
+ *    already holding a JSON string (`'{"a":1}'`) must store the object it
+ *    describes; an unconditional `JSON.stringify` would double-encode it.
+ *  - An `undefined` column type is a no-op. `updated_at`, `id` and FK columns
+ *    are added outside the attribute loop and are absent from
+ *    `schema.columns`.
+ *
+ * The `'JSONB'` sentinel is the exact literal emitted by
+ * `src/postgres/type-map.ts`, the only module that produces the values in
+ * `schema.columns`. The two producing functions are `getPgType` and
+ * `getVectorType` (`src/postgres/schema-introspector.ts` writes `columns[key]`
+ * at exactly three sites, all routed through those two); `mysqlTypeToPg` is not
+ * exported and is reachable only from inside `getPgType`.
+ *
+ * One documented gap: `getPgType` returns a consumer transform's declared
+ * `pgType` verbatim, so a consumer writing `pgType: 'jsonb'` puts a value in
+ * `schema.columns` that type-map never authored and this exact-match sentinel
+ * misses. It misses identically on the create path, pre-fix and post-fix --
+ * pre-existing and symmetric, not introduced here.
+ */
+export const postgresJsonRule: ColumnRule = (value, columnType) =>
+  columnType === 'JSONB' && typeof value !== 'string'
+    ? JSON.stringify(value)
+    : value;

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

@@ -8,6 +8,8 @@ import { createRecord } from '../manage-record.js';
 import { confirm } from '@stonyx/utils/prompt';
 import { readFile } from '@stonyx/utils/file';
 import { getPluralName } from '../plural-registry.js';
+import { convertRow } from '../column-conversion.js';
+import { postgresJsonRule } from './column-rules.js';
 import { isDbError } from '../utils.js';
 import config from 'stonyx/config';
 import log from 'stonyx/log';
@@ -61,6 +63,8 @@ interface PostgresDeps {
   confirm: typeof confirm;
   readFile: typeof readFile;
   getPluralName: typeof getPluralName;
+  convertRow: typeof convertRow;
+  postgresJsonRule: typeof postgresJsonRule;
   config: typeof config;
   log: typeof log;
   path: typeof path;
@@ -73,7 +77,8 @@ const defaultDeps: PostgresDeps = {
   introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
   loadLatestSnapshot, detectSchemaDrift,
   buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
-  createRecord, store, confirm, readFile, getPluralName, config, log, path
+  createRecord, store, confirm, readFile, getPluralName, config, log, path,
+  convertRow, postgresJsonRule
 };
 
 export default class PostgresDB {
@@ -90,6 +95,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 +139,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 +168,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 +498,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> {
@@ -503,7 +540,10 @@ export default class PostgresDB {
       delete insertData.id;
     }
 
-    const { sql, values } = this.deps.buildInsert(schema.table, insertData);
+    // Convert the *complete* payload (attributes + id + FKs) in one place (#292).
+    const row = this.deps.convertRow(insertData, schema.columns, this.deps.postgresJsonRule);
+
+    const { sql, values } = this.deps.buildInsert(schema.table, row);
 
     const result = await this.requirePool().query(sql, values);
 
@@ -568,7 +608,12 @@ export default class PostgresDB {
     // PostgreSQL doesn't have ON UPDATE CURRENT_TIMESTAMP -- set updated_at manually
     changedData.updated_at = new Date();
 
-    const { sql, values } = this.deps.buildUpdate(schema.table, id, changedData);
+    // Same conversion, same choke point as the create path (#292). Columns
+    // appended after the attribute loop (FKs, updated_at) are absent from
+    // schema.columns and pass through untouched.
+    const row = this.deps.convertRow(changedData, schema.columns, this.deps.postgresJsonRule);
+
+    const { sql, values } = this.deps.buildUpdate(schema.table, id, row);
     await this.requirePool().query(sql, values);
   }
 
@@ -594,13 +639,11 @@ export default class PostgresDB {
       row.id = data.id;
     }
 
-    // Attribute columns
-    for (const [col, pgType] of Object.entries(schema.columns)) {
+    // Attribute columns. Type conversion is NOT applied here -- it is applied
+    // once to the finished payload by the caller, via convertRow (#292).
+    for (const col of Object.keys(schema.columns)) {
       if (data[col] !== undefined) {
-        // JSONB columns: stringify non-string values for PostgreSQL JSONB storage
-        row[col] = pgType === 'JSONB' && typeof data[col] !== 'string'
-          ? JSON.stringify(data[col])
-          : data[col];
+        row[col] = data[col];
       }
     }
 

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/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);
+          }
+        }
+      }
+    }
   }
 
   /**