@stonyx/orm 0.3.2-beta.33 → 0.3.2-beta.330

package/dist/postgres/postgres-db.js

@@ -2,23 +2,41 @@ import { getPool, closePool } from './connection.js';
 import { ensureMigrationsTable, getAppliedMigrations, getMigrationFiles, applyMigration, parseMigrationFile } from './migration-runner.js';
 import { introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot } from './schema-introspector.js';
 import { loadLatestSnapshot, detectSchemaDrift } from './migration-generator.js';
-import { buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch } from './query-builder.js';
+import { buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch } from './query-builder.js';
 import { store } from '@stonyx/orm';
 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';
 import path from 'path';
+const POSTGRES_MAX_BIND_PARAMETERS = 65535;
+const DEFAULT_WRITE_BATCH_SIZE = 500;
+const DEFAULT_WRITE_QUEUE_LIMIT = 10000;
+export class WriteQueueFullError extends Error {
+    constructor(limit) {
+        super(`PostgresDB write queue is full (${limit} queued writes, writeQueueLimit); the write was rejected`);
+        this.name = 'WriteQueueFullError';
+    }
+}
+export class WriteQueueClosedError extends Error {
+    constructor() {
+        super('PostgresDB is shutting down; the write was rejected');
+        this.name = 'WriteQueueClosedError';
+    }
+}
 const defaultDeps = {
     getPool, closePool, ensureMigrationsTable, getAppliedMigrations,
     getMigrationFiles, applyMigration, parseMigrationFile,
     introspectModels, introspectViews, getTopologicalOrder, schemasToSnapshot,
     loadLatestSnapshot, detectSchemaDrift,
-    buildInsert, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
-    createRecord, store, confirm, readFile, getPluralName, config, log, path
+    buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect, buildVectorSearch, buildHybridSearch,
+    createRecord, store, confirm, readFile, getPluralName, config, log, path, process,
+    convertRow, postgresJsonRule
 };
 export default class PostgresDB {
     /** PostgreSQL extensions to enable on pool init. Subclasses can override. */
@@ -30,6 +48,12 @@ export default class PostgresDB {
     deps;
     pool;
     pgConfig;
+    persistResolvesAfterWrite = true;
+    _queuedWrites = [];
+    _inFlightWrites = new Set();
+    _drainingWrites = null;
+    _acceptingWrites = true;
+    _exitReport = null;
     constructor(deps = {}) {
         const Ctor = this.constructor;
         if (Ctor.instance)
@@ -48,6 +72,17 @@ export default class PostgresDB {
         this.pool = await this.deps.getPool(this.pgConfig, this.constructor.extensions);
         await this.deps.ensureMigrationsTable(this.pool, this.pgConfig.migrationsTable);
         await this.loadMemoryRecords();
+        this._acceptingWrites = true;
+        this._registerExitReport();
+    }
+    get writeBatchSize() {
+        return Number(this.pgConfig?.writeBatchSize) || DEFAULT_WRITE_BATCH_SIZE;
+    }
+    get writeQueueLimit() {
+        return Number(this.pgConfig?.writeQueueLimit) || DEFAULT_WRITE_QUEUE_LIMIT;
+    }
+    get pendingWriteCount() {
+        return this._inFlightWrites.size + this._queuedWrites.length;
     }
     async startup() {
         const migrationsPath = this.deps.path.resolve(this.deps.config.rootPath, this.pgConfig.migrationsDir);
@@ -57,7 +92,17 @@ export default class PostgresDB {
         const pending = files.filter(f => !applied.includes(f));
         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;
+            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) {
                     const content = await this.deps.readFile(this.deps.path.join(migrationsPath, filename));
@@ -76,7 +121,17 @@ export default class PostgresDB {
             const schemas = this.deps.introspectModels();
             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;
+                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');
                     const result = await generateMigration('initial_setup');
@@ -104,9 +159,35 @@ export default class PostgresDB {
         }
     }
     async shutdown() {
+        this._acceptingWrites = false;
+        while (this._drainingWrites)
+            await this._drainingWrites;
+        this._unregisterExitReport();
         await this.deps.closePool();
         this.pool = null;
     }
+    _registerExitReport() {
+        if (this._exitReport)
+            return;
+        this._exitReport = () => this._reportUnpersistedWrites();
+        this.deps.process.once('exit', this._exitReport);
+    }
+    _unregisterExitReport() {
+        if (!this._exitReport)
+            return;
+        this.deps.process.removeListener('exit', this._exitReport);
+        this._exitReport = null;
+    }
+    _reportUnpersistedWrites() {
+        const lostWrites = [...this._inFlightWrites, ...this._queuedWrites];
+        if (lostWrites.length === 0)
+            return;
+        const lostByModel = new Map();
+        for (const { modelName } of lostWrites)
+            lostByModel.set(modelName, (lostByModel.get(modelName) ?? 0) + 1);
+        const breakdown = [...lostByModel].map(([modelName, count]) => `${modelName}: ${count}`).join(', ');
+        this.deps.log.error?.(`[PostgresDB] Process exiting with ${lostWrites.length} queued write(s) not persisted; they are lost (${breakdown})`);
+    }
     async save() {
         // No-op: PostgreSQL persists data immediately via persist()
     }
@@ -352,55 +433,171 @@ export default class PostgresDB {
         return rawData;
     }
     async persist(operation, modelName, context, response) {
-        // Views are read-only -- no-op for all write operations
         const Orm = (await import('@stonyx/orm')).default;
         if (Orm.instance?.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);
-        }
+        if (!this._acceptingWrites)
+            throw new WriteQueueClosedError();
+        if (this._queuedWrites.length >= this.writeQueueLimit)
+            throw new WriteQueueFullError(this.writeQueueLimit);
+        return new Promise((resolve, reject) => {
+            const write = {
+                operation, modelName, context, response,
+                resolve: () => {
+                    this._inFlightWrites.delete(write);
+                    resolve();
+                },
+                reject: (error) => {
+                    this._inFlightWrites.delete(write);
+                    reject(error);
+                },
+            };
+            this._queuedWrites.push(write);
+            this._drainWritesInBackground();
+        });
     }
-    async _persistCreate(modelName, context, response) {
-        const schemas = this.deps.introspectModels();
-        const schema = schemas[modelName];
-        if (!schema)
+    _drainWritesInBackground() {
+        if (this._drainingWrites)
             return;
+        this._drainingWrites = this._drainQueuedWrites().finally(() => {
+            this._drainingWrites = null;
+        });
+    }
+    async _drainQueuedWrites() {
+        while (this._queuedWrites.length > 0) {
+            const writes = this._takeNextWriteGroup();
+            writes.forEach(write => this._inFlightWrites.add(write));
+            try {
+                await this._executeWriteGroup(writes);
+            }
+            catch (error) {
+                writes.filter(write => this._inFlightWrites.has(write)).forEach(write => write.reject(error));
+            }
+        }
+    }
+    _takeNextWriteGroup() {
+        const [first] = this._queuedWrites;
+        let groupSize = 1;
+        if (first.operation === 'create') {
+            while (groupSize < this.writeBatchSize
+                && groupSize < this._queuedWrites.length
+                && this._queuedWrites[groupSize].operation === 'create'
+                && this._queuedWrites[groupSize].modelName === first.modelName)
+                groupSize++;
+        }
+        return this._queuedWrites.splice(0, groupSize);
+    }
+    async _executeWriteGroup(writes) {
+        const [first] = writes;
+        if (first.operation === 'create')
+            return this._persistCreates(first.modelName, writes);
+        try {
+            if (first.operation === 'update')
+                await this._persistUpdate(first.modelName, first.context, first.response);
+            if (first.operation === 'delete')
+                await this._persistDelete(first.modelName, first.context);
+            first.resolve();
+        }
+        catch (error) {
+            first.reject(error);
+        }
+    }
+    async _persistCreates(modelName, writes) {
+        const schema = this.deps.introspectModels()[modelName];
+        const prepared = [];
+        for (const write of writes) {
+            try {
+                const create = schema ? this._prepareCreate(modelName, schema, write) : null;
+                if (create)
+                    prepared.push(create);
+                else
+                    write.resolve();
+            }
+            catch (error) {
+                write.reject(error);
+            }
+        }
+        for (const chunk of this._chunkWithinBindParameterLimit(prepared)) {
+            await this._insertCreates(schema, chunk);
+        }
+    }
+    _prepareCreate(modelName, schema, write) {
+        const { context, response } = write;
         const recordId = response?.data?.id;
         const storeRef = this.deps.store;
         const record = recordId != null ? storeRef.get(modelName, isNaN(recordId) ? recordId : parseInt(recordId)) : null;
         if (!record)
-            return;
+            return null;
         const insertData = this._recordToRow(record, schema, context.rawData);
-        // For auto-increment models, remove the pending ID.
-        // Check context.rawData (not record.__data) because __pendingSqlId is not a model
-        // attribute and gets lost during serialization.
         const isPendingId = context.rawData?.__pendingSqlId === true;
-        if (isPendingId) {
+        if (isPendingId)
             delete insertData.id;
+        const row = this.deps.convertRow(insertData, schema.columns, this.deps.postgresJsonRule);
+        return { write, modelName, record, row, isPendingId };
+    }
+    _chunkWithinBindParameterLimit(prepared) {
+        const chunks = [];
+        let chunk = [];
+        let chunkColumns = new Set();
+        for (const create of prepared) {
+            const columnsWithCreate = new Set([...chunkColumns, ...Object.keys(create.row)]);
+            if (chunk.length > 0 && (chunk.length + 1) * columnsWithCreate.size > POSTGRES_MAX_BIND_PARAMETERS) {
+                chunks.push(chunk);
+                chunk = [];
+                chunkColumns = new Set(Object.keys(create.row));
+            }
+            else {
+                chunkColumns = columnsWithCreate;
+            }
+            chunk.push(create);
+        }
+        if (chunk.length > 0)
+            chunks.push(chunk);
+        return chunks;
+    }
+    async _insertCreates(schema, creates) {
+        if (creates.length === 1)
+            return this._insertCreatesOneByOne(schema, creates);
+        let result;
+        try {
+            const { sql, values } = this.deps.buildInsertMany(schema.table, creates.map(({ row }) => row));
+            result = await this.requirePool().query(sql, values);
+        }
+        catch {
+            return this._insertCreatesOneByOne(schema, creates);
         }
-        const { sql, values } = this.deps.buildInsert(schema.table, insertData);
-        const result = await this.requirePool().query(sql, values);
-        // Re-key the record in the store if PostgreSQL generated the ID (via RETURNING)
-        if (isPendingId && result.rows.length > 0) {
-            const pendingId = record.id;
-            const realId = result.rows[0].id;
-            const modelStore = this.deps.store.get(modelName);
-            modelStore.delete(pendingId);
-            record.__data.id = realId;
-            record.id = realId;
-            modelStore.set(realId, record);
-            // Update the response data with the real ID
-            if (response?.data) {
-                response.data.id = realId;
+        creates.forEach((create, index) => {
+            this._adoptGeneratedId(create, result.rows[index]);
+            create.write.resolve();
+        });
+    }
+    async _insertCreatesOneByOne(schema, creates) {
+        for (const create of creates) {
+            try {
+                const { sql, values } = this.deps.buildInsert(schema.table, create.row);
+                const result = await this.requirePool().query(sql, values);
+                this._adoptGeneratedId(create, result.rows[0]);
+                create.write.resolve();
+            }
+            catch (error) {
+                create.write.reject(error);
             }
-            delete record.__data.__pendingSqlId;
         }
     }
+    _adoptGeneratedId({ modelName, record, isPendingId, write }, returnedRow) {
+        if (!isPendingId || !returnedRow)
+            return;
+        const pendingId = record.id;
+        const realId = returnedRow.id;
+        const modelStore = this.deps.store.get(modelName);
+        modelStore.delete(pendingId);
+        record.__data.id = realId;
+        record.id = realId;
+        modelStore.set(realId, record);
+        if (write.response?.data)
+            write.response.data.id = realId;
+        delete record.__data.__pendingSqlId;
+    }
     async _persistUpdate(modelName, context, _response) {
         const schemas = this.deps.introspectModels();
         const schema = schemas[modelName];
@@ -435,7 +632,11 @@ export default class PostgresDB {
             return;
         // 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);
     }
     async _persistDelete(modelName, context) {
@@ -456,13 +657,11 @@ export default class PostgresDB {
         if (data.id !== undefined) {
             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];
             }
         }
         // FK columns from relationships

package/dist/postgres/query-builder.d.ts

@@ -12,6 +12,7 @@ interface HybridSearchOptions {
 }
 export declare function validateIdentifier(name: string, context?: string): string;
 export declare function buildInsert(table: string, data: Record<string, unknown>): QueryResult;
+export declare function buildInsertMany(table: string, rows: Record<string, unknown>[]): QueryResult;
 export declare function buildUpdate(table: string, id: unknown, data: Record<string, unknown>): QueryResult;
 export declare function buildDelete(table: string, id: unknown): QueryResult;
 export declare function buildSelect(table: string, conditions?: Record<string, unknown>): QueryResult;

package/dist/postgres/query-builder.js

@@ -14,6 +14,23 @@ export function buildInsert(table, data) {
     const sql = `INSERT INTO "${table}" (${keys.map(k => `"${k}"`).join(', ')}) VALUES (${placeholders.join(', ')}) RETURNING "id"`;
     return { sql, values };
 }
+export function buildInsertMany(table, rows) {
+    validateIdentifier(table, 'table name');
+    const columns = [...new Set(rows.flatMap(row => Object.keys(row)))];
+    columns.forEach(column => validateIdentifier(column, 'column name'));
+    const values = [];
+    const tuples = rows.map(row => {
+        const cells = columns.map(column => {
+            if (!Object.hasOwn(row, column))
+                return 'DEFAULT';
+            values.push(row[column]);
+            return `$${values.length}`;
+        });
+        return `(${cells.join(', ')})`;
+    });
+    const sql = `INSERT INTO "${table}" (${columns.map(column => `"${column}"`).join(', ')}) VALUES ${tuples.join(', ')} RETURNING "id"`;
+    return { sql, values };
+}
 export function buildUpdate(table, id, data) {
     validateIdentifier(table, 'table name');
     const keys = Object.keys(data);

package/dist/record.js

@@ -40,11 +40,13 @@ export default class Record {
         const records = {};
         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) => r?.__model);
                 // Deduplicate by record ID — keep last occurrence (latest data wins)
                 const seen = new Set();
                 const unique = [];
-                for (let i = childRecord.length - 1; i >= 0; i--) {
-                    const r = childRecord[i];
+                for (let i = live.length - 1; i >= 0; i--) {
+                    const r = live[i];
                     if (!seen.has(r.id)) {
                         seen.add(r.id);
                         unique.push(r);
@@ -54,7 +56,7 @@ export default class Record {
                 records[key] = unique.map((r) => r.serialize());
             }
             else {
-                records[key] = childRecord?.serialize() ?? null;
+                records[key] = childRecord?.__model ? childRecord.serialize() : null;
             }
         }
         return { ...data, ...records };
@@ -86,8 +88,8 @@ export default class Record {
             if (fields && !fields.has(key))
                 continue;
             const relationshipData = Array.isArray(childRecord)
-                ? childRecord.map((r) => ({ type: r.__model.__name, id: r.id }))
-                : childRecord ? { type: childRecord.__model.__name, id: childRecord.id } : null;
+                ? childRecord.filter((r) => r?.__model).map((r) => ({ type: r.__model.__name, id: r.id }))
+                : (childRecord && childRecord.__model) ? { type: childRecord.__model.__name, id: childRecord.id } : null;
             // Dasherize the key for URL paths (e.g., accessLinks -> access-links)
             const dasherizedKey = camelCaseToKebabCase(key);
             relationships[dasherizedKey] = { data: relationshipData };

package/dist/relationships.js

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

package/dist/serializer.js

@@ -79,8 +79,44 @@ export default class Serializer {
                 // Pass relationship key name to handler for pending fulfillment
                 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.__relationshipType === 'hasMany';
+                if (isHasMany) {
+                    // `childRecord` IS the shared registry array — define a getter that
+                    // always dereferences through the same array reference.
+                    const registryArray = childRecord;
+                    Object.defineProperty(rec, key, {
+                        enumerable: true,
+                        configurable: true,
+                        get: () => registryArray,
+                        set(v) { relatedRecords[key] = v; }
+                    });
+                    Object.defineProperty(relatedRecords, key, {
+                        enumerable: true,
+                        configurable: true,
+                        get: () => registryArray,
+                        set(v) { 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;
             }
             // Aggregate property handling — use the rawData value, not the aggregate descriptor

package/dist/store.d.ts

@@ -45,7 +45,19 @@ export default class Store {
      */
     private _isMemoryModel;
     set(key: string, value: Map<number | string, unknown>): void;
-    remove(key: string, id?: number | string): void;
+    remove(key: string, id?: number | string, options?: {
+        _skipAutoPersist?: boolean;
+    }): void;
+    /**
+     * 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;
     unloadRecord(model: string, id: unknown, options?: UnloadOptions): void;
     unloadAllRecords(model: string, options?: UnloadOptions): void;
     private _removeFromHasManyArrays;

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/timescale/query-builder.d.ts

@@ -1,4 +1,4 @@
-export { validateIdentifier, buildInsert, buildUpdate, buildDelete, buildSelect } from '../postgres/query-builder.js';
+export { validateIdentifier, buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect } from '../postgres/query-builder.js';
 export declare function validateInterval(interval: string, context?: string): string;
 export declare function validateAggregate(expr: string, context?: string): string;
 interface QueryResult {

package/dist/timescale/query-builder.js

@@ -1,5 +1,4 @@
-// Re-export all base PostgreSQL query builders
-export { validateIdentifier, buildInsert, buildUpdate, buildDelete, buildSelect } from '../postgres/query-builder.js';
+export { validateIdentifier, buildInsert, buildInsertMany, buildUpdate, buildDelete, buildSelect } from '../postgres/query-builder.js';
 import { validateIdentifier } from '../postgres/query-builder.js';
 const SAFE_INTERVAL = /^\d+\s+(microsecond|millisecond|second|minute|hour|day|week|month|year)s?$/i;
 export function validateInterval(interval, context = 'interval') {