@spine-event-engine/storage-postgres 2.0.0-snapshot.24 → 2.0.0-snapshot.26

package/dist/postgres/entity-commit.d.ts

@@ -1,10 +1,10 @@
 import { type Message } from "@bufbuild/protobuf";
+import { type ModelPreference } from "@spine-event-engine/proto/agent";
 import { type RecordSpec, type StorageGroup } from "@spine-event-engine/storage";
-import { type EntityCommitInput, type EntityCommitStorage, type EntityStorageInput } from "@spine-event-engine/storage/provider";
+import { type AgentCommitInput, type EntityCommitInput, type EntityCommitStorage, type EntityStorageInput } from "@spine-event-engine/storage/provider";
 import { PostgresRecordStorage } from "./record-storage.js";
-import type { PoolClient } from "pg";
 /**
- * Opens one PostgreSQL record family used by an Entity commit.
+ * Acquires one PostgreSQL record family used by an Entity commit.
  *
  * @typeParam I Record identifier type.
  * @typeParam R Stored Protobuf record type.
@@ -25,7 +25,7 @@ export declare class PostgresEntityCommitStorage<I, S extends Message> implement
      * Creates a PostgreSQL Entity commit handle for one Entity storage boundary.
      *
      * @param entity Defines the captured Entity source, state, and tenant scope.
-     * @param open Opens temporary current and history record-family handles.
+     * @param open Opens current and optional history record-family handles.
      * @param onClose Removes this handle from the factory's live-handle set.
      */
     constructor(entity: EntityStorageInput<I, S>, open: OpenRecords, onClose: () => void);
@@ -39,17 +39,74 @@ export declare class PostgresEntityCommitStorage<I, S extends Message> implement
      */
     commit<Id, State extends Message>(input: EntityCommitInput<Id, State>): Promise<void>;
     /**
-     * Prepares one Agent-fenced Entity mutation for its existing transaction client.
+     * Registers a commit before invoking provider construction callbacks.
      *
-     * @typeParam Id Typed Entity identifier.
-     * @typeParam State Entity state message type.
-     * @param input Changed Entity state and immutable history.
-     * @returns A transaction-bound conditional mutation and its close callback.
+     * @param action The admitted provider operation.
+     * @returns The admitted provider operation completion.
+     * @typeParam T Result type of the admitted provider operation.
      */
-    prepareAgentConditional<Id, State extends Message>(input: EntityCommitInput<Id, State>): Promise<{
-        apply(client: PoolClient, expectedVersion: number): Promise<void>;
-        close(): void;
-    }>;
+    private track;
+    /**
+     * Reads one detached preference image through the retained private family.
+     * @param entityId Typed Agent identifier.
+     * @returns Current complete image or absence.
+     */
+    readAgentPreferences(entityId: unknown): Promise<readonly ModelPreference[] | undefined>;
+    /**
+     * Commits state, final audit, and complete preferences in one native transaction.
+     * @param input Captured Agent transition and initial images.
+     * @returns Completion after the conditional group commits.
+     * @typeParam Id Typed Agent identifier.
+     * @typeParam State Generated Agent state.
+     */
+    commitAgent<Id, State extends Message>(input: AgentCommitInput<Id, State>): Promise<void>;
+    /**
+     * Acquires the retained current, Agent audit, and preference families.
+     *
+     * @returns The retained family group.
+     */
+    private agentRecords;
+    /**
+     * Checks the captured Entity scope and next version before native writes.
+     * @param id Captured Agent identifier.
+     * @param version Initial Entity version.
+     * @param mutation Optional prepared Entity mutation.
+     * @typeParam Id Typed Agent identifier.
+     * @typeParam State Generated Agent state.
+     */
+    private validateAgent;
+    /**
+     * Applies one transaction lock even when preference and current rows are absent.
+     * @param records Retained families.
+     * @param id Captured Agent ID.
+     * @param version Initial Entity version.
+     * @param expected Initial preference image.
+     * @param next Complete replacement record.
+     * @param mutation Optional Entity mutation.
+     * @param history Final audit entries.
+     * @typeParam Id Typed Agent identifier.
+     * @typeParam State Generated Agent state.
+     * @returns Completion after the conditional Agent transaction commits.
+     */
+    private commitAgentPrepared;
+    /**
+     * Adds final Agent audit through the admitted transaction client.
+     * @param client Active native transaction.
+     * @param storage Retained Agent history family.
+     * @param id Captured Agent identifier.
+     * @param history Final audit entries.
+     * @returns Completion after final audit rows are appended.
+     */
+    private appendAgentHistory;
+    /**
+     * Persists an admitted captured mutation, including a safe retry.
+     *
+     * @param prepared The immutable prepared mutation.
+     * @returns Completion after the captured mutation is persisted.
+     * @typeParam Id Entity identifier or record type.
+     * @typeParam State Generated Entity state message type.
+     */
+    private persist;
     /**
      * Determines whether a driver serialization failure occurred through provider error causes.
      *
@@ -59,8 +116,20 @@ export declare class PostgresEntityCommitStorage<I, S extends Message> implement
     private retryable;
     /**
      * Closes this handle to new commits while allowing started work to settle.
+     *
+     * @returns Completion after admitted work and retained records close.
+     */
+    close(): Promise<void>;
+    /**
+     * Closes only when no commit remains admitted.
+     */
+    closeIdle(): void;
+    /**
+     * Waits for admitted commits before releasing factory tracking.
+     *
+     * @returns Completion after admitted work and cleanup settle.
      */
-    close(): void;
+    private drain;
     /**
      * Applies one validated Entity commit as ordered independent writes.
      *

package/dist/postgres/entity-commit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-commit.d.ts","sourceRoot":"","sources":["../../src/postgres/entity-commit.ts"],"names":[],"mappings":"AAcA,OAAO,EAAY,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAO5D,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,EAML,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,IAAI,CAAC;AAErC;;;;;GAKG;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EACtC,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EACtB,KAAK,CAAC,EAAE,YAAY,KACjB,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAwIjC;;;;;GAKG;AACH,qBAAa,2BAA2B,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAE,YAAW,mBAAmB;;IAWzF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B;;;;;;OAMG;gBAEgB,MAAM,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EAChC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,IAAI;IAGtC;;;;;;;OAOG;IACG,MAAM,CAAC,EAAE,EAAE,KAAK,SAAS,OAAO,EAAE,KAAK,EAAE,iBAAiB,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB3F;;;;;;;OAOG;IACG,uBAAuB,CAAC,EAAE,EAAE,KAAK,SAAS,OAAO,EACrD,KAAK,EAAE,iBAAiB,CAAC,EAAE,EAAE,KAAK,CAAC,GAClC,OAAO,CAAC;QACT,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QAClE,KAAK,IAAI,IAAI,CAAC;KACf,CAAC;IAmBF;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAWjB;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;;;;;;OAQG;YACW,KAAK;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAkBhB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAepB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAWzB"}
+{"version":3,"file":"entity-commit.d.ts","sourceRoot":"","sources":["../../src/postgres/entity-commit.ts"],"names":[],"mappings":"AAcA,OAAO,EAAmB,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAEnE,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,iCAAiC,CAAC;AAOzC,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACjF,OAAO,EAUL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACxB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAG5D;;;;;GAKG;AACH,KAAK,WAAW,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EACtC,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EACtB,KAAK,CAAC,EAAE,YAAY,KACjB,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAoOjC;;;;;GAKG;AACH,qBAAa,2BAA2B,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAE,YAAW,mBAAmB;;IAsBzF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAV1B;;;;;;OAMG;gBAEgB,MAAM,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EAChC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,MAAM,IAAI;IAGtC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,EAAE,KAAK,SAAS,OAAO,EAAE,KAAK,EAAE,iBAAiB,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrF;;;;;;OAMG;IACH,OAAO,CAAC,KAAK;IAoBb;;;;OAIG;IACH,oBAAoB,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,eAAe,EAAE,GAAG,SAAS,CAAC;IAiBxF;;;;;;OAMG;IACH,WAAW,CAAC,EAAE,EAAE,KAAK,SAAS,OAAO,EAAE,KAAK,EAAE,gBAAgB,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA8BzF;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAkBpB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAgBrB;;;;;;;;;;;;OAYG;YACW,mBAAmB;IAkCjC;;;;;;;OAOG;YACW,kBAAkB;IAchC;;;;;;;OAOG;YACW,OAAO;IAkCrB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAWjB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAUtB;;OAEG;IACH,SAAS,IAAI,IAAI;IA0BjB;;;;OAIG;YACW,KAAK;IAkBnB;;;;;;;;OAQG;YACW,KAAK;IAWnB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;IAiBhB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAepB;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;CAWzB"}

package/dist/postgres/entity-commit.js

@@ -11,14 +11,16 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { toBinary } from "@bufbuild/protobuf";
+import { clone, toBinary } from "@bufbuild/protobuf";
+import { AgentHistoryEntrySchema, } from "@spine-event-engine/proto/agent";
 import { EntityRecordSchema, } from "@spine-event-engine/proto/generated/spine/server/entity/entity_pb.js";
 import {} from "@spine-event-engine/storage";
-import { TenantBoundary, EntityCommitSnapshots, eventHistorySpec, eventStoreRecordSpec, stateHistorySpec, } from "@spine-event-engine/storage/provider";
+import { TenantBoundary, AgentHistoryRecords, AgentModelPreferences, EntityCommitSnapshots, eventHistorySpec, eventStoreRecordSpec, EventStoreGroups, stateHistorySpec, } from "@spine-event-engine/storage/provider";
+import { AgentHistoryHash } from "./agent-history.js";
 import { PostgresStorageErrors, PostgresStorageOperationError } from "./errors.js";
 import { PostgresRecordStorage } from "./record-storage.js";
 /**
- * Opens and closes the exact record families participating in one commit.
+ * Stores current and optional record families across commits on one handle.
  *
  * @typeParam I Entity identifier type.
  * @typeParam S Entity state message type.
@@ -28,23 +30,78 @@ class PostgresCommitRecords {
     states;
     diagnostics;
     events;
+    history;
+    preferences;
     #handles;
     /**
-     * Opens the current record family and each enabled immutable family.
+     * Whether this record family is closed.
+     */
+    #closed = false;
+    /**
+     * Acquires the current record family for one Entity scope.
      *
-     * @param input Describes the Entity commit and enabled histories.
      * @param open Opens one record family.
+     * @param entity The Entity persistence contract.
+     */
+    constructor(entity, open) {
+        this.current = open(entity.recordSpec);
+        this.#handles = [this.current];
+    }
+    /**
+     * Acquires only missing requested families, rolling back a failed new group.
+     *
+     * @param input The captured Entity persistence input.
+     * @param open Opens a generated record family.
+     */
+    ensure(input, open) {
+        const acquired = [];
+        try {
+            const states = input.states?.length
+                ? (this.states ?? this.openState(input, open, acquired))
+                : undefined;
+            const diagnostics = input.diagnostics?.length
+                ? (this.diagnostics ?? this.openDiagnostic(input, open, acquired))
+                : undefined;
+            const events = input.events?.length
+                ? (this.events ?? this.openEvents(input, open, acquired))
+                : undefined;
+            this.states = states ?? this.states;
+            this.diagnostics = diagnostics ?? this.diagnostics;
+            this.events = events ?? this.events;
+            this.#handles.push(...acquired);
+        }
+        catch (error) {
+            const failures = this.closeGroup(acquired);
+            if (failures.length)
+                throw new AggregateError([error, ...failures], "PostgreSQL family acquisition failed.");
+            throw error;
+        }
+    }
+    /**
+     * Stores the two Agent record families, rolling back only failed acquisition.
+     * @param open Opens a private record family.
      */
-    constructor(input, open) {
-        const current = open(input.entity.recordSpec);
-        const handles = [current];
-        this.current = current;
-        this.states = input.states?.length ? this.openState(input, open, handles) : undefined;
-        this.diagnostics = input.diagnostics?.length
-            ? this.openDiagnostic(input, open, handles)
-            : undefined;
-        this.events = input.events?.length ? this.openEvents(open, handles) : undefined;
-        this.#handles = handles;
+    ensureAgent(open) {
+        const acquired = [];
+        try {
+            const history = this.history ??
+                open(AgentHistoryRecords.spec((value) => AgentHistoryHash.value(value)), AgentHistoryRecords.group);
+            if (this.history === undefined)
+                acquired.push(history);
+            const preferences = this.preferences ??
+                open(AgentModelPreferences.spec((value) => AgentHistoryHash.value(value)), AgentModelPreferences.group);
+            if (this.preferences === undefined)
+                acquired.push(preferences);
+            this.history = history;
+            this.preferences = preferences;
+            this.#handles.push(...acquired);
+        }
+        catch (error) {
+            const failures = this.closeGroup(acquired);
+            if (failures.length)
+                throw new AggregateError([error, ...failures], "PostgreSQL Agent family acquisition failed.");
+            throw error;
+        }
     }
     /**
      * Prepares every record family before ordered writes begin.
@@ -79,14 +136,38 @@ class PostgresCommitRecords {
             await this.current.historyExecutor().write(client, snapshot.next);
     }
     /**
-     * Closes every temporary record-family handle.
+     * Closes every retained record-family handle.
      */
     close() {
-        for (const handle of this.#handles)
-            handle.close();
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        const failures = this.closeGroup(this.#handles);
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length)
+            throw new AggregateError(failures, "PostgreSQL commit records close failed.");
+    }
+    /**
+     * Closes every newly acquired handle and collects cleanup failures.
+     *
+     * @param handles The acquired record handles.
+     * @returns Cleanup failures from acquired handles.
+     */
+    closeGroup(handles) {
+        const failures = [];
+        for (const handle of handles) {
+            try {
+                handle.close();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        return failures;
     }
     /**
-     * Opens the Entity state-history record family.
+     * Acquires the Entity state-history record family.
      *
      * @param input Describes the Entity state schema.
      * @param open Opens one record family.
@@ -100,7 +181,7 @@ class PostgresCommitRecords {
         return handle;
     }
     /**
-     * Opens the Entity diagnostic-event history record family.
+     * Acquires the Entity diagnostic-event history record family.
      *
      * @param input Describes the Entity state schema.
      * @param open Opens one record family.
@@ -114,14 +195,15 @@ class PostgresCommitRecords {
         return handle;
     }
     /**
-     * Opens the shared event-store record family.
+     * Acquires the shared event-store record family.
      *
+     * @param input Supplies the context and Event family.
      * @param open Opens one record family.
      * @param handles Collects handles that must close after the commit.
      * @returns The event-store record storage.
      */
-    openEvents(open, handles) {
-        const handle = open(eventStoreRecordSpec);
+    openEvents(input, open, handles) {
+        const handle = open(eventStoreRecordSpec, EventStoreGroups.forContext(input.context.name));
         handles.push(handle);
         return handle;
     }
@@ -137,11 +219,18 @@ export class PostgresEntityCommitStorage {
     open;
     onClose;
     #open = true;
+    #records;
+    /**
+     * Synchronous idle-close result, including any cleanup failure.
+     */
+    #idleOutcome;
+    #active = new Set();
+    #closing;
     /**
      * Creates a PostgreSQL Entity commit handle for one Entity storage boundary.
      *
      * @param entity Defines the captured Entity source, state, and tenant scope.
-     * @param open Opens temporary current and history record-family handles.
+     * @param open Opens current and optional history record-family handles.
      * @param onClose Removes this handle from the factory's live-handle set.
      */
     constructor(entity, open, onClose) {
@@ -157,11 +246,203 @@ export class PostgresEntityCommitStorage {
      * @param input Defines the next current record plus histories.
      * @returns Completion after every requested record write.
      */
-    async commit(input) {
-        this.validate(input);
-        const prepared = EntityCommitSnapshots.capture(input);
-        const records = new PostgresCommitRecords(prepared, this.open);
+    commit(input) {
+        if (!this.#open)
+            return Promise.reject(new PostgresStorageOperationError("Entity commit storage is closed."));
+        return this.track(() => {
+            this.validate(input);
+            const prepared = EntityCommitSnapshots.capture(input);
+            return this.persist(prepared);
+        });
+    }
+    /**
+     * Registers a commit before invoking provider construction callbacks.
+     *
+     * @param action The admitted provider operation.
+     * @returns The admitted provider operation completion.
+     * @typeParam T Result type of the admitted provider operation.
+     */
+    track(action) {
+        let complete;
+        let fail;
+        const work = new Promise((resolve, reject) => {
+            complete = resolve;
+            fail = reject;
+        });
+        this.#active.add(work);
+        void work.then(() => this.#active.delete(work), () => this.#active.delete(work));
+        try {
+            action().then(complete, fail);
+        }
+        catch (error) {
+            fail(error);
+        }
+        return work;
+    }
+    /**
+     * Reads one detached preference image through the retained private family.
+     * @param entityId Typed Agent identifier.
+     * @returns Current complete image or absence.
+     */
+    readAgentPreferences(entityId) {
+        if (!this.#open)
+            return Promise.reject(new PostgresStorageOperationError("Entity commit storage is closed."));
+        return this.track(async () => {
+            const key = AgentModelPreferences.key(this.entity, entityId);
+            const records = this.agentRecords();
+            await records.prepare();
+            const slot = `v1:${AgentHistoryHash.value(AgentModelPreferences.text(key))}`;
+            const storage = records.preferences;
+            if (storage === undefined)
+                throw new Error("Agent preference storage is unavailable.");
+            const found = await storage.read(slot);
+            if (found === undefined)
+                return undefined;
+            AgentModelPreferences.requireIdentity(found, key);
+            return AgentModelPreferences.copy(found.preferences);
+        });
+    }
+    /**
+     * Commits state, final audit, and complete preferences in one native transaction.
+     * @param input Captured Agent transition and initial images.
+     * @returns Completion after the conditional group commits.
+     * @typeParam Id Typed Agent identifier.
+     * @typeParam State Generated Agent state.
+     */
+    commitAgent(input) {
+        if (!this.#open)
+            return Promise.reject(new PostgresStorageOperationError("Entity commit storage is closed."));
+        return this.track(async () => {
+            const id = this.entity.id.clone(input.entityId);
+            const key = AgentModelPreferences.key(this.entity, id);
+            const expected = input.expectedPreferences === undefined
+                ? undefined
+                : AgentModelPreferences.copy(input.expectedPreferences);
+            const next = AgentModelPreferences.record(key, input.preferences);
+            const mutation = input.entityCommit && EntityCommitSnapshots.capture(input.entityCommit);
+            const history = input.historyEntries?.map((entry) => clone(AgentHistoryEntrySchema, entry)) ?? [];
+            this.validateAgent(id, input.expectedVersion, mutation);
+            const records = this.agentRecords();
+            if (mutation !== undefined)
+                records.ensure(mutation, this.open);
+            await records.prepare();
+            await this.commitAgentPrepared(records, id, input.expectedVersion, expected, next, mutation, history);
+        });
+    }
+    /**
+     * Acquires the retained current, Agent audit, and preference families.
+     *
+     * @returns The retained family group.
+     */
+    agentRecords() {
+        const records = this.#records ?? new PostgresCommitRecords(this.entity, this.open);
+        try {
+            records.ensureAgent(this.open);
+            this.#records ??= records;
+            return records;
+        }
+        catch (error) {
+            if (this.#records === undefined) {
+                try {
+                    records.close();
+                }
+                catch (cleanup) {
+                    throw new AggregateError([error, cleanup], "PostgreSQL Agent family cleanup failed.");
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Checks the captured Entity scope and next version before native writes.
+     * @param id Captured Agent identifier.
+     * @param version Initial Entity version.
+     * @param mutation Optional prepared Entity mutation.
+     * @typeParam Id Typed Agent identifier.
+     * @typeParam State Generated Agent state.
+     */
+    validateAgent(id, version, mutation) {
+        if (!Number.isSafeInteger(version) || version < 0)
+            throw new TypeError("Agent commit requires a valid initial Entity Version.");
+        if (mutation === undefined)
+            return;
+        this.validate(mutation);
+        if (this.entity.id.key(id) !== this.entity.id.key(mutation.entityId) ||
+            mutation.next.version?.number !== version + 1)
+            throw new Error("Agent commit requires the same Entity ID and one new Version.");
+    }
+    /**
+     * Applies one transaction lock even when preference and current rows are absent.
+     * @param records Retained families.
+     * @param id Captured Agent ID.
+     * @param version Initial Entity version.
+     * @param expected Initial preference image.
+     * @param next Complete replacement record.
+     * @param mutation Optional Entity mutation.
+     * @param history Final audit entries.
+     * @typeParam Id Typed Agent identifier.
+     * @typeParam State Generated Agent state.
+     * @returns Completion after the conditional Agent transaction commits.
+     */
+    async commitAgentPrepared(records, id, version, expected, next, mutation, history) {
+        const preferenceStorage = records.preferences;
+        const historyStorage = records.history;
+        if (preferenceStorage === undefined || historyStorage === undefined || next.key === undefined)
+            throw new Error("Agent commit storage is incomplete.");
+        const preferences = preferenceStorage.historyExecutor();
+        const key = next.key;
+        const slot = `v1:${AgentHistoryHash.value(AgentModelPreferences.text(key))}`;
+        await preferences.transaction(async (client) => {
+            await client.query("SELECT pg_advisory_xact_lock($1)", [
+                preferences.lock("agent-preferences", slot),
+            ]);
+            const prior = await preferences.read(client, slot, "for-update");
+            if (prior !== undefined)
+                AgentModelPreferences.requireIdentity(prior, key);
+            if (!AgentModelPreferences.same(prior?.preferences, expected))
+                throw new Error("Agent model preferences changed during the live turn.");
+            if (mutation === undefined) {
+                const current = await records.current.historyExecutor().read(client, id, "for-update");
+                if ((current?.version?.number ?? 0) !== version)
+                    throw new Error("Agent initial Entity Version is no longer current.");
+            }
+            else
+                await records.applyConditional(client, mutation, version);
+            await this.appendAgentHistory(client, historyStorage, id, history);
+            await preferences.write(client, next);
+        });
+    }
+    /**
+     * Adds final Agent audit through the admitted transaction client.
+     * @param client Active native transaction.
+     * @param storage Retained Agent history family.
+     * @param id Captured Agent identifier.
+     * @param history Final audit entries.
+     * @returns Completion after final audit rows are appended.
+     */
+    async appendAgentHistory(client, storage, id, history) {
+        const executor = storage.historyExecutor();
+        for (const entry of history)
+            await executor.appendImmutable(client, AgentHistoryRecords.record(this.entity.stateSchema.typeName, this.entity.id.key(id), entry));
+    }
+    /**
+     * Persists an admitted captured mutation, including a safe retry.
+     *
+     * @param prepared The immutable prepared mutation.
+     * @returns Completion after the captured mutation is persisted.
+     * @typeParam Id Entity identifier or record type.
+     * @typeParam State Generated Entity state message type.
+     */
+    async persist(prepared) {
+        let records = this.#records;
+        let fresh = false;
         try {
+            if (records === undefined) {
+                records = new PostgresCommitRecords(this.entity, this.open);
+                fresh = true;
+            }
+            records.ensure(prepared, this.open);
+            this.#records ??= records;
             await records.prepare();
             try {
                 await this.apply(prepared, records);
@@ -173,37 +454,16 @@ export class PostgresEntityCommitStorage {
             }
         }
         catch (error) {
+            if (fresh && this.#records === undefined) {
+                try {
+                    records?.close();
+                }
+                catch (cleanup) {
+                    throw new AggregateError([error, cleanup], "PostgreSQL commit acquisition failed.");
+                }
+            }
             throw PostgresStorageErrors.operation(error);
         }
-        finally {
-            records.close();
-        }
-    }
-    /**
-     * Prepares one Agent-fenced Entity mutation for its existing transaction client.
-     *
-     * @typeParam Id Typed Entity identifier.
-     * @typeParam State Entity state message type.
-     * @param input Changed Entity state and immutable history.
-     * @returns A transaction-bound conditional mutation and its close callback.
-     */
-    async prepareAgentConditional(input) {
-        this.validate(input);
-        const snapshot = EntityCommitSnapshots.capture(input);
-        const records = new PostgresCommitRecords(snapshot, this.open);
-        try {
-            await records.prepare();
-        }
-        catch (error) {
-            records.close();
-            throw error;
-        }
-        return {
-            apply: (client, expectedVersion) => records.applyConditional(client, snapshot, expectedVersion),
-            close: () => {
-                records.close();
-            },
-        };
     }
     /**
      * Determines whether a driver serialization failure occurred through provider error causes.
@@ -225,12 +485,76 @@ export class PostgresEntityCommitStorage {
     }
     /**
      * Closes this handle to new commits while allowing started work to settle.
+     *
+     * @returns Completion after admitted work and retained records close.
      */
     close() {
-        if (this.#open) {
-            this.#open = false;
+        this.#open = false;
+        if (this.#idleOutcome !== undefined)
+            return (this.#closing ??=
+                this.#idleOutcome.error === undefined
+                    ? Promise.resolve()
+                    : Promise.reject(this.#idleOutcome.error));
+        return (this.#closing ??= this.drain());
+    }
+    /**
+     * Closes only when no commit remains admitted.
+     */
+    closeIdle() {
+        if (this.#active.size)
+            throw new Error("Entity commit cannot close idle while work is active.");
+        if (this.#idleOutcome !== undefined) {
+            if (this.#idleOutcome.error !== undefined)
+                throw this.#idleOutcome.error;
+            return;
+        }
+        if (this.#closing !== undefined)
+            throw new Error("Entity commit close is in progress.");
+        this.#open = false;
+        const errors = [];
+        try {
+            this.#records?.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        this.#records = undefined;
+        try {
+            this.onClose();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        const failure = errors.length > 1 ? new AggregateError(errors) : errors[0];
+        this.#idleOutcome = failure === undefined ? {} : { error: failure };
+        if (failure !== undefined)
+            throw failure;
+    }
+    /**
+     * Waits for admitted commits before releasing factory tracking.
+     *
+     * @returns Completion after admitted work and cleanup settle.
+     */
+    async drain() {
+        await Promise.allSettled([...this.#active]);
+        const errors = [];
+        try {
+            this.#records?.close();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        this.#records = undefined;
+        try {
             this.onClose();
         }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length)
+            throw new AggregateError(errors, "PostgreSQL commit close failed.");
     }
     /**
      * Applies one validated Entity commit as ordered independent writes.
@@ -260,8 +584,6 @@ export class PostgresEntityCommitStorage {
      * @param input Defines the Entity records to validate.
      */
     validate(input) {
-        if (!this.#open)
-            throw new PostgresStorageOperationError("Entity commit storage is closed.");
         if (input.entity.sourceType.typeName !== this.entity.sourceType.typeName)
             throw new PostgresStorageOperationError("Entity commit source type is incompatible.");
         if (input.entity.stateSchema.typeName !== this.entity.stateSchema.typeName)