@spine-event-engine/storage-postgres 2.0.0-snapshot.23 → 2.0.0-snapshot.25

package/dist/postgres/record-storage.js

@@ -12,13 +12,12 @@
  * the License.
  */
 import { fromBinary, ScalarType, toBinary } from "@bufbuild/protobuf";
+import { defaultStringifierRegistry, StringifierRegistry } from "@spine-event-engine/core";
+import { ColumnMappings, defaultQueryCandidateLimit, RecordQuery, RecordStorage, } from "@spine-event-engine/storage";
 import { createHash } from "node:crypto";
-import { StringifierRegistry } from "@spine-event-engine/core";
-import { ColumnMappings, defaultQueryCandidateLimit, RecordStorage, } from "@spine-event-engine/storage";
 import { PostgresColumnMapping } from "./column-mapping.js";
-import { PostgresStorageDataError, PostgresStorageOperationError, PostgresTransactionErrors, PostgresClientDisposal, PostgresRollbackErrors, } from "./errors.js";
+import { PostgresStorageDataError, PostgresStorageOperationError, PostgresClientDisposal, } from "./errors.js";
 import { PostgresIdColumn } from "./id-column.js";
-import { PostgresTableInitializer } from "./table-initializer.js";
 const maximumNormalizedPlanBinds = 1_000;
 /**
  * Stores one record family in one qualified PostgreSQL table.
@@ -27,35 +26,50 @@ const maximumNormalizedPlanBinds = 1_000;
  * @typeParam R The stored Protobuf record type.
  */
 export class PostgresRecordStorage extends RecordStorage {
-    table;
+    tableNameValue;
+    onSchema;
     lifecycle;
     onClose;
+    create;
     /**
-     * Reports that compare-and-set uses PostgreSQL transaction coordination.
+     * Reports that compare-and-set uses a conditional SQL mutation.
      */
     atomicCompareAndSet = true;
     #idColumn;
     #columns;
-    #initializer;
+    #binding;
+    #table;
     /**
      * Creates a PostgreSQL record-family handle.
      *
      * @param context Identifies the storage boundary for this handle.
      * @param spec Defines the record type, ID type, and declared columns.
-     * @param table Supplies the resolved physical table layout.
+     * @param tableNameValue Supplies the locally resolved physical table name.
+     * @param onSchema Builds the physical layout after schema resolution.
      * @param lifecycle Acquires clients for the selected database and schema.
      * @param onClose Removes this handle from the factory's live set.
      * @param create Optionally supplies custom create-table SQL.
      * @param stringifiers Converts message IDs and columns reversibly.
      */
-    constructor(context, spec, table, lifecycle, onClose, create, stringifiers = new StringifierRegistry()) {
+    constructor(context, spec, tableNameValue, onSchema, lifecycle, onClose, create, stringifiers = defaultStringifierRegistry) {
         super(context, spec);
-        this.table = table;
+        this.tableNameValue = tableNameValue;
+        this.onSchema = onSchema;
         this.lifecycle = lifecycle;
         this.onClose = onClose;
+        this.create = create;
         this.#idColumn = new PostgresIdColumn(spec.idType, stringifiers);
         this.#columns = new PostgresColumnMapping(stringifiers);
-        this.#initializer = new PostgresTableInitializer(lifecycle, table.schema, table, create);
+    }
+    /**
+     * Returns the bound layout after preparation.
+     *
+     * @returns The resolved physical layout.
+     */
+    get table() {
+        if (this.#table === undefined)
+            throw new Error("PostgreSQL record table is not bound.");
+        return this.#table;
     }
     /**
      * Returns the resolved physical table name.
@@ -63,15 +77,47 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns The physical table name without its schema.
      */
     get tableName() {
-        return this.table.tableName;
+        return this.tableNameValue;
     }
     /**
-     * Prepares this table before an external coordinator transaction.
+     * Prepares this table before a record operation.
      *
      * @returns A promise that resolves after compatible initialization.
      */
     prepare() {
-        return this.#initializer.prepare();
+        return this.admit(() => this.prepareInternal());
+    }
+    /**
+     * Prepares an already admitted operation, including after the factory fence.
+     *
+     * @returns Completion after table preparation.
+     */
+    prepareInternal() {
+        return this.lifecycle.track(Promise.resolve().then(() => this.prepareBound()));
+    }
+    /**
+     * Binds the destination and prepares its physical table.
+     *
+     * @returns Completion after physical table preparation.
+     */
+    async prepareBound() {
+        this.#binding ??= this.bind().catch((error) => {
+            this.#binding = undefined;
+            throw error;
+        });
+        await this.#binding;
+        const create = this.create;
+        await this.lifecycle.prepare(this.table, create === undefined ? undefined : () => create(this.table));
+    }
+    /**
+     * Resolves the database before constructing the schema-bound initializer.
+     *
+     * @returns Completion after the initializer is available.
+     */
+    async bind() {
+        await this.lifecycle.resolve();
+        const table = this.onSchema(this.lifecycle.schema);
+        this.#table = table;
     }
     /**
      * Opens package-local bounded history operations for this record family.
@@ -85,15 +131,12 @@ export class PostgresRecordStorage extends RecordStorage {
             transaction: (work) => this.transaction(work),
             using: (work) => this.using(work),
             read: (client, id, lock) => this.readOn(client, id, lock === "for-update"),
-            assertImmutable: (client, record) => this.assertImmutableOn(client, record),
             appendImmutable: (client, record) => this.appendImmutableOn(client, record),
             write: (client, record) => this.writeOn(client, record),
-            delete: (client, id) => this.deleteOn(client, id),
             query: (client, sql, values) => this.historyEntries(client, sql, values),
             column: (name, value) => this.historyColumn(name, value),
             table: () => this.qualified(),
             lock: (domain, ...identity) => this.historyKey(domain, identity),
-            lockRecord: (id) => this.casKey(id),
         };
     }
     /**
@@ -105,18 +148,104 @@ export class PostgresRecordStorage extends RecordStorage {
         super.close();
         this.onClose();
     }
+    /**
+     * Registers a complete public operation before invoking record callbacks.
+     *
+     * @typeParam T The operation result.
+     * @param work Performs the public record operation.
+     * @returns The complete admitted outcome.
+     */
+    admit(work) {
+        if (!this.isOpen() || !this.lifecycle.publicOpen())
+            return Promise.reject(new Error("PostgreSQL record storage is closed."));
+        const { promise, resolve, reject } = Promise.withResolvers();
+        void this.lifecycle.track(promise);
+        try {
+            void work().then(resolve, reject);
+        }
+        catch (error) {
+            reject(error);
+        }
+        return promise;
+    }
+    /**
+     * Deletes one public record under the factory admission fence.
+     * @inheritdoc
+     */
+    delete(id) {
+        return this.admit(() => super.delete(id));
+    }
+    /**
+     * Reads one public record under the factory admission fence.
+     * @inheritdoc
+     */
+    read(id) {
+        return this.admit(() => super.read(id));
+    }
+    /**
+     * Indexes public records under the factory admission fence.
+     * @inheritdoc
+     */
+    index(query = {}) {
+        return this.admit(() => super.index(query));
+    }
+    /**
+     * Queries public records under the factory admission fence.
+     * @inheritdoc
+     */
+    query(query = {}) {
+        return this.admit(() => super.query(query));
+    }
+    /**
+     * Queries public record entries under the factory admission fence.
+     * @inheritdoc
+     */
+    queryEntries(query = {}) {
+        return this.admit(() => super.queryEntries(query));
+    }
+    /**
+     * Queries a normalized plan under the factory admission fence.
+     * @inheritdoc
+     */
+    queryPlan(plan) {
+        return this.admit(async () => (await super.queryPlanEntries(plan)).map((entry) => entry.record));
+    }
+    /**
+     * Queries normalized entries under the factory admission fence.
+     * @inheritdoc
+     */
+    queryPlanEntries(plan) {
+        return this.admit(() => super.queryPlanEntries(plan));
+    }
+    /**
+     * Writes a public record under the factory admission fence.
+     * @inheritdoc
+     */
+    write(record) {
+        return this.admit(() => super.write(record));
+    }
+    /**
+     * Compares and sets a public record under the factory admission fence.
+     * @inheritdoc
+     */
+    compareAndSet(id, expected, next) {
+        return this.admit(() => super.compareAndSet(id, expected, next));
+    }
+    /**
+     * Writes a public batch under the factory admission fence.
+     * @inheritdoc
+     */
+    writeAll(records) {
+        return this.admit(() => super.writeAll(records));
+    }
     /**
      * Writes an immutable record or confirms an identical existing payload.
      *
      * @param record Provides the immutable record to store.
      * @returns A promise that resolves when the payload is stored or confirmed.
      */
-    async writeImmutable(record) {
-        const id = this.recordSpec.idValueIn(record);
-        await this.transaction(async (client) => {
-            await this.lockSlot(client, id);
-            await this.appendImmutableOn(client, record, true);
-        }).catch((error) => {
+    writeImmutable(record) {
+        return this.admit(() => this.using((client) => this.appendImmutableOn(client, record))).catch((error) => {
             throw operationError(error);
         });
     }
@@ -127,7 +256,7 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns A promise that rejects when the stored payload differs.
      */
     async assertImmutable(record) {
-        const existing = await this.read(this.recordSpec.idValueIn(record));
+        const existing = await this.admit(() => super.read(this.recordSpec.idValueIn(record)));
         if (existing === undefined || this.same(existing, record))
             return;
         throw new PostgresStorageOperationError("PostgreSQL immutable record collides.");
@@ -139,7 +268,7 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns Whether a stored record was deleted.
      */
     async deleteRecord(id) {
-        return this.transaction(async (client) => this.deleteOn(client, id)).catch((error) => {
+        return this.using(async (client) => this.deleteOn(client, id)).catch((error) => {
             throw operationError(error);
         });
     }
@@ -161,8 +290,7 @@ export class PostgresRecordStorage extends RecordStorage {
     async queryRecordEntries(query) {
         if (query.ids?.length === 0)
             return [];
-        const compiled = this.recordQuery(query);
-        return this.using((client) => this.entries(client, compiled));
+        return this.using((client) => this.entries(client, this.recordQuery(query)));
     }
     /**
      * Returns complete normalized-plan pushdown capabilities.
@@ -182,52 +310,54 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns The decoded records admitted by the plan.
      */
     async queryPlanRecordEntries(plan) {
-        const compiled = this.planQuery(plan);
-        return this.using((client) => this.entries(client, compiled));
+        this.validatePlan(plan);
+        return this.using((client) => this.entries(client, this.planQuery(plan)));
+    }
+    /**
+     * Checks plan columns and bind count before connecting to PostgreSQL.
+     *
+     * @param plan The normalized query definition.
+     */
+    validatePlan(plan) {
+        for (const item of plan.order ?? [])
+            this.column(item.column);
+        const visit = (predicate) => {
+            if (predicate.kind === "comparison")
+                this.column(predicate.column);
+            if (predicate.kind === "all" || predicate.kind === "either")
+                for (const child of predicate.predicates)
+                    visit(child);
+        };
+        if (plan.predicate !== undefined)
+            visit(plan.predicate);
+        if (!plan.exhaustive && this.predicateBindCount(plan.predicate) >= maximumNormalizedPlanBinds)
+            throw new PostgresStorageOperationError("PostgreSQL normalized query exceeds the 1000-parameter bind budget.");
     }
     /**
-     * Compares and atomically applies one mutation with bounded retry.
+     * Compares and conditionally mutates one row with a raw-byte SQL guard.
      *
-     * @param id Identifies the record guarded by the transaction advisory lock.
+     * @param id Identifies the record slot.
      * @param expected Specifies the current materialized record required to write.
      * @param next Specifies the replacement record, or absence for deletion.
      * @returns Whether the current stored payload matched the expected payload.
      */
     async compareAndSetRecord(id, expected, next) {
-        for (let attempt = 0; attempt !== 2; attempt += 1) {
-            try {
-                return await this.casOnce(id, expected, next);
-            }
-            catch (error) {
-                if (attempt === 0 && retryable(error))
-                    continue;
-                throw operationError(error);
-            }
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const result = await this.using((client) => this.casOnce(client, id, expected, next));
+            if (result !== undefined)
+                return result;
         }
-        throw new PostgresStorageOperationError("PostgreSQL record operation failed.");
+        throw new PostgresStorageOperationError("PostgreSQL record compare-and-set contention exceeded.");
     }
     /**
-     * Writes all supplied materialized records in source order and one transaction.
+     * Writes all supplied materialized records independently in source order.
      *
      * @param records Provides the materialized records to write.
-     * @returns A promise that resolves after the transaction commits.
+     * @returns A promise that resolves after all writes complete.
      */
     async writeAllRecords(records) {
-        for (let attempt = 0; attempt < 2; attempt += 1) {
-            try {
-                await this.transaction(async (client) => {
-                    await this.lockSlots(client, records.map((record) => this.recordSpec.idValueIn(record.record)));
-                    for (const record of records)
-                        await this.writeOn(client, record.record, undefined, true);
-                });
-                return;
-            }
-            catch (error) {
-                if (attempt === 0 && PostgresTransactionErrors.retryable(error))
-                    continue;
-                throw operationError(error);
-            }
-        }
+        for (const record of records)
+            await this.writeRecord(record);
     }
     /**
      * Writes one materialized record.
@@ -236,61 +366,77 @@ export class PostgresRecordStorage extends RecordStorage {
      * @returns A promise that resolves after PostgreSQL applies the upsert.
      */
     writeRecord(record) {
-        return this.transaction((client) => this.writeOn(client, record.record)).catch((error) => {
+        return this.using((client) => this.writeOn(client, record.record)).catch((error) => {
             throw operationError(error);
         });
     }
     /**
-     * Applies one compare-and-set attempt inside a transaction.
+     * Applies one compare-and-set attempt using a conditional statement.
      *
+     * @param client Provides the operation client.
      * @param id Identifies the guarded record.
      * @param expected Supplies the required current materialization.
      * @param next Supplies the replacement or requests deletion when absent.
-     * @returns Whether the current record matched the expected record.
-     */
-    async casOnce(id, expected, next) {
-        return this.transaction(async (client) => {
-            await this.lockSlot(client, id);
-            const current = await this.readOn(client, id, true);
-            if (!this.same(current, expected?.record))
-                return false;
-            if (next === undefined)
-                await this.deleteOn(client, id, true);
-            else
-                await this.writeOn(client, next.record, id, true);
+     * @returns Whether the current record matched, or undefined after a guard miss.
+     */
+    async casOnce(client, id, expected, next) {
+        const raw = await this.rawOn(client, id);
+        const current = raw === undefined ? undefined : this.decode(raw);
+        if (!this.same(current, expected?.record))
+            return false;
+        if (next === undefined) {
+            if (raw === undefined)
+                return true;
+            const deleted = await client.query(`DELETE FROM ${this.qualified()} WHERE "ID" = $1 AND "bytes" = $2`, [this.id(id), raw]);
+            return deleted.rowCount === 1 ? true : undefined;
+        }
+        if (this.same(current, next.record))
             return true;
-        });
+        if (raw === undefined) {
+            const inserted = await client.query(`${this.insertSql()} ON CONFLICT ("ID") DO NOTHING`, this.values(next.record, id));
+            return inserted.rowCount === 1 ? true : undefined;
+        }
+        const changed = await client.query(this.casUpdateSql(), [
+            this.id(id),
+            raw,
+            ...this.values(next.record, id).slice(1),
+        ]);
+        return changed.rowCount === 1 ? true : undefined;
     }
     /**
-     * Executes work in one transaction and always releases its client.
-     *
-     * @typeParam T The value returned by the transaction work.
-     * @param work Performs the transaction work.
-     * @returns The value returned by the work after a successful commit.
+     * Reads the exact bytes used as a conditional-mutation guard.
+     * @param client Provides the operation client.
+     * @param id Identifies the row.
+     * @returns Stored bytes, if present.
      */
-    async transaction(work) {
-        await this.prepare();
-        const client = await this.lifecycle.acquire();
-        let discard;
+    async rawOn(client, id) {
+        const result = await client.query(`SELECT "bytes" FROM ${this.qualified()} WHERE "ID" = $1`, [this.id(id)]);
+        return result.rows[0] === undefined ? undefined : bytes(result.rows[0].bytes);
+    }
+    /**
+     * Decodes one stored record with the provider's data-error boundary.
+     * @param raw Supplies exact stored bytes.
+     * @returns Decoded Protobuf record.
+     */
+    decode(raw) {
         try {
-            await client.query("BEGIN");
-            const result = await work(client);
-            await client.query("COMMIT");
-            return result;
+            return fromBinary(this.recordSpec.recordType, raw);
         }
         catch (error) {
-            try {
-                await client.query("ROLLBACK");
-            }
-            catch {
-                discard = PostgresRollbackErrors.discard(error);
-            }
-            throw error;
-        }
-        finally {
-            client.release(discard);
+            throw new PostgresStorageDataError("Stored PostgreSQL record data is invalid.", {
+                cause: error,
+            });
         }
     }
+    /**
+     * Builds a conditional update that changes bytes and materialized columns together.
+     * @returns Parameterized update SQL.
+     */
+    casUpdateSql() {
+        const names = ["bytes", ...this.recordSpec.columns.map(({ name }) => name)];
+        const assignments = names.map((name, index) => `${quote(name)} = $${String(index + 3)}`);
+        return `UPDATE ${this.qualified()} SET ${assignments.join(", ")} WHERE "ID" = $1 AND "bytes" = $2`;
+    }
     /**
      * Executes work with one prepared and automatically released client.
      *
@@ -298,8 +444,18 @@ export class PostgresRecordStorage extends RecordStorage {
      * @param work Performs the client work.
      * @returns The value returned by the work.
      */
-    async using(work) {
-        await this.prepare();
+    using(work) {
+        return this.lifecycle.track(this.usePrepared(work));
+    }
+    /**
+     * Executes one prepared record operation on a released client.
+     *
+     * @typeParam T The operation result.
+     * @param work Performs the client operation.
+     * @returns The operation result.
+     */
+    async usePrepared(work) {
+        await this.prepareInternal();
         const client = await this.lifecycle.acquire();
         let discard = false;
         try {
@@ -310,19 +466,77 @@ export class PostgresRecordStorage extends RecordStorage {
             throw operationError(error);
         }
         finally {
-            client.release(discard ? new Error("PostgreSQL client discarded after lock cleanup failure.") : undefined);
+            client.release(discard ? new Error("PostgreSQL client discarded after provider failure.") : undefined);
         }
     }
+    /**
+     * Executes Agent-scoped record work under one PostgreSQL transaction.
+     *
+     * @typeParam T Result of the transaction work.
+     * @param work Operations to run on the acquired client.
+     * @returns Result after commit.
+     */
+    transaction(work) {
+        return this.lifecycle.track(this.transactionPrepared(work));
+    }
+    /**
+     * Executes one prepared Agent transaction on a released client.
+     *
+     * @typeParam T The transaction result.
+     * @param work Performs work on the transaction client.
+     * @returns The committed result.
+     */
+    async transactionPrepared(work) {
+        await this.prepareInternal();
+        const client = await this.lifecycle.acquire();
+        let releaseFailure;
+        try {
+            await client.query("BEGIN");
+            const result = await work(client);
+            await client.query("COMMIT");
+            return result;
+        }
+        catch (error) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch {
+                releaseFailure = new Error("PostgreSQL Agent transaction rollback failed.");
+            }
+            throw error;
+        }
+        finally {
+            client.release(releaseFailure);
+        }
+    }
+    /**
+     * Calculates a stable Agent advisory key in this database and schema.
+     *
+     * @param domain Lock namespace within the provider.
+     * @param identity Components of the lock identity.
+     * @returns Stable advisory lock key.
+     */
+    historyKey(domain, identity) {
+        return createHash("sha256")
+            .update(`spine-postgres-${domain}\0`)
+            .update(this.lifecycle.databaseName)
+            .update("\0")
+            .update(this.lifecycle.schema)
+            .update("\0")
+            .update(identity.join("\0"))
+            .digest()
+            .readBigInt64BE();
+    }
     /**
      * Reads and decodes one record on the supplied client.
      *
      * @param client Provides the active client.
      * @param id Identifies the record.
-     * @param lock Whether to lock the selected row for update.
+     * @param locked Whether to lock the selected row in the Agent transaction.
      * @returns The decoded record, when present.
      */
-    async readOn(client, id, lock = false) {
-        const result = await client.query(`SELECT "bytes" FROM ${this.qualified()} WHERE "ID" = $1${lock ? " FOR UPDATE" : ""}`, [this.id(id)]);
+    async readOn(client, id, locked = false) {
+        const result = await client.query(`SELECT "bytes" FROM ${this.qualified()} WHERE "ID" = $1${locked ? " FOR UPDATE" : ""}`, [this.id(id)]);
         if (result.rows[0] === undefined)
             return undefined;
         try {
@@ -355,90 +569,48 @@ export class PostgresRecordStorage extends RecordStorage {
             });
         }
     }
-    /**
-     * Acquires the transaction lock for one record slot.
-     *
-     * @param client Provides the active transaction client.
-     * @param id Identifies the record slot.
-     * @returns A promise that resolves after lock acquisition.
-     */
-    lockSlot(client, id) {
-        return client
-            .query("SELECT pg_advisory_xact_lock($1)", [this.casKey(id)])
-            .then(() => undefined);
-    }
-    /**
-     * Acquires record-slot locks in stable order to avoid deadlocks.
-     *
-     * @param client Provides the active transaction client.
-     * @param ids Identify the record slots.
-     * @returns A promise that resolves after every lock is acquired.
-     */
-    async lockSlots(client, ids) {
-        const keys = [...new Set(ids.map((id) => this.casKey(id)))];
-        keys.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
-        for (const key of keys)
-            await client.query("SELECT pg_advisory_xact_lock($1)", [key]);
-    }
     /**
      * Writes one record on a caller-managed client.
      *
-     * @param client Provides the active transaction client.
+     * @param client Provides the acquired client.
      * @param record Supplies the record to write.
-     * @param id Identifies the record.
-     * @param locked Whether the caller already holds the record lock.
      * @returns A promise that resolves after the upsert.
      */
-    async writeOn(client, record, id = this.recordSpec.idValueIn(record), locked = false) {
-        if (!locked)
-            await this.lockSlot(client, id);
+    async writeOn(client, record) {
+        const id = this.recordSpec.idValueIn(record);
         await client.query(this.upsertSql(), this.values(record, id));
     }
     /**
      * Deletes one record on a caller-managed client.
      *
-     * @param client Provides the active transaction client.
+     * @param client Provides the acquired client.
      * @param id Identifies the record.
-     * @param locked Whether the caller already holds the record lock.
      * @returns Whether PostgreSQL deleted a row.
      */
-    async deleteOn(client, id, locked = false) {
-        if (!locked)
-            await this.lockSlot(client, id);
+    async deleteOn(client, id) {
         return (await client.query(this.deleteSql(), [this.id(id)])).rowCount === 1;
     }
     /**
      * Stores an immutable record or confirms an identical existing record.
      *
-     * @param client Provides the active transaction client.
+     * @param client Provides the acquired client.
      * @param record Supplies the immutable record.
-     * @param locked Whether the caller already holds the record lock.
      * @returns A promise that resolves after insertion or identity confirmation.
      */
-    async appendImmutableOn(client, record, locked = false) {
+    async appendImmutableOn(client, record) {
         const id = this.recordSpec.idValueIn(record);
-        if (!locked)
-            await this.lockSlot(client, id);
-        const inserted = await client.query(this.immutableSql(), this.values(record));
-        if (inserted.rowCount === 1)
-            return;
-        const existing = await this.readOn(client, id);
-        if (existing === undefined || this.same(existing, record))
-            return;
-        throw new PostgresStorageOperationError("PostgreSQL immutable record collides.");
-    }
-    /**
-     * Checks that an immutable record is absent or byte-identical.
-     *
-     * @param client Provides the active client.
-     * @param record Supplies the immutable record.
-     * @returns A promise that rejects for a conflicting stored payload.
-     */
-    async assertImmutableOn(client, record) {
-        const existing = await this.readOn(client, this.recordSpec.idValueIn(record));
-        if (existing === undefined || this.same(existing, record))
-            return;
-        throw new PostgresStorageOperationError("PostgreSQL immutable record collides.");
+        for (let attempt = 0; attempt < 3; attempt += 1) {
+            const inserted = await client.query(this.immutableSql(), this.values(record));
+            if (inserted.rowCount === 1)
+                return;
+            const existing = await this.readOn(client, id);
+            if (existing === undefined)
+                continue;
+            if (this.same(existing, record))
+                return;
+            throw new PostgresStorageOperationError("PostgreSQL immutable record collides.");
+        }
+        throw new PostgresStorageOperationError("PostgreSQL immutable record contention exceeded.");
     }
     /**
      * Executes provider SQL and decodes its record rows.
@@ -472,24 +644,6 @@ export class PostgresRecordStorage extends RecordStorage {
             throw new PostgresStorageOperationError(`PostgreSQL history column is not declared: ${name}`);
         return ColumnMappings.value(this.#columns, column.type, value);
     }
-    /**
-     * Calculates a stable advisory-lock key within the selected database and schema.
-     *
-     * @param domain Separates lock purposes.
-     * @param identity Identifies the protected resource.
-     * @returns A signed PostgreSQL advisory-lock key.
-     */
-    historyKey(domain, identity) {
-        return createHash("sha256")
-            .update(`spine-postgres-${domain}\0`)
-            .update(this.lifecycle.databaseName)
-            .update("\0")
-            .update(this.lifecycle.schema)
-            .update("\0")
-            .update(identity.join("\0"))
-            .digest()
-            .readBigInt64BE();
-    }
     /**
      * Encodes one record as ordered table-column values.
      *
@@ -667,9 +821,16 @@ export class PostgresRecordStorage extends RecordStorage {
         const clauses = [];
         if (query.ids !== undefined)
             clauses.push(`"ID" IN (${query.ids.map((id) => bind.add(this.id(id))).join(", ")})`);
-        for (const filter of query.filters ?? [])
-            clauses.push(`${this.column(filter.column === "id" ? "ID" : filter.column)} ` +
-                `IS NOT DISTINCT FROM ${bind.add(this.value(filter.column, filter.value))}`);
+        for (const filter of query.filters ?? []) {
+            const column = this.column(filter.column === "id" ? "ID" : filter.column);
+            const accepted = RecordQuery.acceptedValues(filter);
+            const alternatives = accepted.map((value) => `${column} IS NOT DISTINCT FROM ${bind.add(this.value(filter.column, value))}`);
+            clauses.push(accepted.length === 0
+                ? "1=0"
+                : accepted.length === 1
+                    ? (alternatives[0] ?? "1=0")
+                    : `(${alternatives.join(" OR ")})`);
+        }
         return clauses;
     }
     /**
@@ -730,7 +891,10 @@ export class PostgresRecordStorage extends RecordStorage {
     afterTerm(column, direction, value, bind) {
         if (value === null)
             return direction === "desc" ? "FALSE" : `${column} IS NOT NULL`;
-        return `(${column} IS NOT NULL AND ${column} ${direction === "desc" ? "<" : ">"} ${bind.add(value)})`;
+        const comparison = `(${column} IS NOT NULL AND ${column} ${direction === "desc" ? "<" : ">"} ${bind.add(value)})`;
+        return direction === "desc" && column !== '"ID"'
+            ? `(${comparison} OR ${column} IS NULL)`
+            : comparison;
     }
     /**
      * Builds SQL for one normalized query predicate recursively.
@@ -857,15 +1021,6 @@ export class PostgresRecordStorage extends RecordStorage {
     offsetSql(bind, offset) {
         return ` LIMIT ${bind.add(9223372036854775807n)} OFFSET ${bind.add(offset)}`;
     }
-    /**
-     * Calculates the advisory key for one record mutation.
-     *
-     * @param id Identifies the record.
-     * @returns The signed advisory-lock key.
-     */
-    casKey(id) {
-        return this.historyKey("record-mutation", [this.table.tableName, String(this.id(id))]);
-    }
 }
 /**
  * Allocates PostgreSQL placeholders and collects their values.
@@ -937,15 +1092,6 @@ function operator(value) {
             throw new PostgresStorageOperationError("PostgreSQL query operator is invalid.");
         })());
 }
-/**
- * Reports whether a failed transaction may be attempted once more.
- *
- * @param error Supplies the failure.
- * @returns Whether PostgreSQL classified it as retryable.
- */
-function retryable(error) {
-    return PostgresTransactionErrors.retryable(error);
-}
 /**
  * Converts an arbitrary failure to the package's record-operation error.
  *
@@ -955,6 +1101,6 @@ function retryable(error) {
 function operationError(error) {
     return error instanceof PostgresStorageOperationError || error instanceof PostgresStorageDataError
         ? error
-        : new PostgresStorageOperationError("PostgreSQL record operation failed.");
+        : new PostgresStorageOperationError("PostgreSQL record operation failed.", { cause: error });
 }
 //# sourceMappingURL=record-storage.js.map