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

package/dist/memory/in-memory-entity-commit.js

@@ -11,430 +11,634 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { clone } from "@bufbuild/protobuf";
+import { clone, toBinary } from "@bufbuild/protobuf";
 import { EventSchema } from "@spine-event-engine/proto";
+import { AgentHistoryEntrySchema, ModelPreferenceSchema, } from "@spine-event-engine/proto/agent";
 import { EntityRecordSchema } from "@spine-event-engine/proto/generated/spine/server/entity/entity_pb.js";
-import { eventStoreAccess, eventStoreRecordSpec } from "../event/event-store.js";
+import { eventStoreRecordSpec, EventStoreGroups } from "../event/event-store.js";
 import { eventHistorySpec, stateHistorySpec } from "../entity/entity-history-record-spec.js";
+import { EntityCommitSnapshots, } from "../internal/entity-commit.js";
+import { AgentModelPreferences, } from "../internal/agent-model-preferences.js";
 import { TenantBoundary } from "../internal/tenancy.js";
-import { InMemoryEntityStorage, KeyedSerialQueue, MemoryEntityStorageFactory, ENTITY_SCOPE_MUTATION_KEY, } from "./in-memory-entity-history.js";
+import { MemoryEntityStorageFactory, ENTITY_SCOPE_MUTATION_KEY, InMemoryEntityHistory, MemoryEntityEventHistory, } from "./in-memory-entity-history.js";
 import { InMemoryRecordStorage } from "./in-memory-record-storage.js";
 import { TenantRecords } from "./tenant-records.js";
+import { AgentHistoryIndex } from "./agent-history-index.js";
+import { AgentHistoryMutationQueue } from "./agent-history-mutation-queue.js";
+import { InMemoryStorageBackend } from "./in-memory-storage-backend.js";
+import { KeyedSerialQueue } from "./in-memory-entity-history.js";
 /**
- * Implements provider Entity commits for one shared in-memory backend.
+ * Writes in-memory Entity records in order and retains a completed prefix.
  */
 export class MemoryEntityCommitStorage {
-    #entities;
-    #factory;
-    #openRecords;
-    #input;
+    entities;
+    openRecords;
+    input;
+    backend;
+    onClose;
+    /**
+     * Tenant boundary selected by this handle.
+     */
     #tenantKey;
+    /**
+     * Whether this handle uses multitenant storage.
+     */
     #multitenant;
+    /**
+     * Whether this handle accepts commits.
+     */
     #open = true;
+    #active = new Set();
+    #agent;
+    /**
+     * Repeatable asynchronous close completion.
+     */
+    #closing;
+    #idleOutcome;
+    #entity;
+    /**
+     * Retained state-history records.
+     */
+    #states;
+    #diagnostics;
+    #delivery;
     /**
-     * Creates a commit handle bound to one Entity source type.
+     * Creates one source- and tenant-bound commit handle.
      *
-     * @param entities Opens the matching current Entity storage.
-     * @param factory Provides the Event Store coordination lock.
-     * @param openRecords Opens exact generic-record backing slices.
-     * @param input Defines the Entity storage source type.
-     */
-    constructor(entities, factory, openRecords, input) {
-        this.#entities = entities;
-        this.#factory = factory;
-        this.#openRecords = openRecords;
-        this.#input = input;
+     * @param entities Opens current Entity storage.
+     * @param openRecords Opens generated history and Event record slices.
+     * @param input Captures the Entity source and tenant boundary.
+     * @param backend Shared tenant memory families for preferences and audit.
+     * @param onClose Releases factory tracking after terminal cleanup.
+     */
+    constructor(entities, openRecords, input, backend, onClose = () => undefined) {
+        this.entities = entities;
+        this.openRecords = openRecords;
+        this.input = input;
+        this.backend = backend;
+        this.onClose = onClose;
         this.#tenantKey = TenantBoundary.of(input.context).key;
         this.#multitenant = input.context.multitenant;
     }
     /**
-     * Applies one fully preflighted in-memory Entity commit.
+     * Binds shared Agent families only when this handle performs Agent work.
+     * @returns Cached preference, audit, and mutation-queue families.
+     */
+    agentFamilies() {
+        if (this.#agent !== undefined)
+            return this.#agent;
+        const tenant = TenantBoundary.of(this.input.context);
+        this.#agent = {
+            preferences: InMemoryStorageBackend.bind(this.backend, "entity", tenant, `agent-preferences:${this.input.stateSchema.typeName}`, () => new Map()),
+            history: InMemoryStorageBackend.bind(this.backend, "entity", tenant, `agent-history:${this.input.stateSchema.typeName}`, () => new Map()),
+            queue: AgentHistoryMutationQueue.bind(this.backend, tenant),
+        };
+        return this.#agent;
+    }
+    /**
+     * Writes history, diagnostics, delivery Events, then current state.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state type.
-     * @param input Defines the current record, retained histories, and delivery events.
-     * @returns Completion after the in-memory commit.
+     * @param input Supplies the proposed mutation.
+     * @returns Completion after every record has been stored.
      */
     commit(input) {
-        this.#requireOpen();
-        this.#requireCompatible(input);
-        const tenant = TenantBoundary.of(input.context);
-        const context = tenant.tenantId === undefined
-            ? { name: input.context.name, multitenant: false }
-            : { name: input.context.name, multitenant: true, tenantId: tenant.tenantId };
-        const snapshot = {
-            ...input,
-            context,
-            entity: { ...input.entity, context },
-            entityId: input.entity.id.clone(input.entityId),
-            next: clone(EntityRecordSchema, input.next),
-            ...(input.states === undefined
-                ? {}
-                : { states: input.states.map((record) => clone(EntityRecordSchema, record)) }),
-            ...(input.diagnostics === undefined
-                ? {}
-                : { diagnostics: input.diagnostics.map((event) => clone(EventSchema, event)) }),
-            ...(input.events === undefined
-                ? {}
-                : { events: input.events.map((event) => clone(EventSchema, event)) }),
-        };
-        const backend = this.#entities.backend(snapshot.entity);
-        const work = () => backend.mutationQueue.run(ENTITY_SCOPE_MUTATION_KEY, () => this.#commit(snapshot, backend));
-        return snapshot.events === undefined || snapshot.events.length === 0
-            ? work()
-            : eventStoreAccess.withLock(this.#factory, snapshot.context, work);
+        this.requireOpen();
+        this.requireCompatible(input);
+        return this.track(() => {
+            const snapshot = EntityCommitSnapshots.capture(input);
+            return this.apply(snapshot);
+        });
     }
     /**
-     * Applies an Agent completion only while the current Entity Version matches.
-     *
-     * @typeParam I Typed Entity identifier.
-     * @typeParam S Generated Entity state.
-     * @param entity Existing Entity layout.
-     * @param entityId Typed Entity identifier.
-     * @param expectedVersion Version observed before Agent handlers ran.
-     * @param input Current-state mutation, absent for a no-op.
-     * @param extra Staged execution and history publication with restoration.
-     * @returns Completion after conditional Entity and execution publication.
-     */
-    commitConditional(entity, entityId, expectedVersion, input, extra) {
-        this.#requireOpen();
-        const backend = this.#entities.backend(entity);
-        const work = () => backend.mutationQueue.run(ENTITY_SCOPE_MUTATION_KEY, async () => {
-            this.#checkCurrentVersion(backend, entity.id.key(entityId), expectedVersion);
-            if (input === undefined) {
-                try {
-                    extra.apply();
-                }
-                catch (error) {
-                    extra.restore();
-                    throw error;
-                }
-                return;
-            }
-            await this.#commit(input, backend, extra);
+     * Reads a detached current preference image from the retained tenant family.
+     * @param entityId Typed Agent identifier.
+     * @returns Complete selections or absent record.
+     */
+    readAgentPreferences(entityId) {
+        this.requireOpen();
+        return this.track(async () => {
+            const key = AgentModelPreferences.key(this.input, entityId);
+            const record = this.agentFamilies().preferences.get(await this.preferenceSlot(key));
+            if (record === undefined)
+                return undefined;
+            AgentModelPreferences.requireIdentity(record, key);
+            return AgentModelPreferences.copy(record.preferences);
         });
-        return input?.events?.length
-            ? eventStoreAccess.withLock(this.#factory, entity.context, work)
-            : work();
     }
     /**
-     * Checks the current Version while the Entity mutation queue is held.
+     * Commits Agent state, final audit, and preferences under shared memory queues.
+     * @param input Captured initial images and prepared transition.
+     * @returns Completion after one conditional group.
+     * @typeParam I Typed Agent identifier.
+     * @typeParam S Generated Agent state.
      */
-    #checkCurrentVersion(backend, key, expected) {
-        const current = backend.current.get(key);
-        const actual = current?.version?.number ?? 0;
-        if (actual !== expected)
-            throw new Error("Agent execution initial Entity Version is no longer current.");
+    commitAgent(input) {
+        this.requireOpen();
+        return this.track(async () => {
+            const entityId = this.input.id.clone(input.entityId);
+            const key = AgentModelPreferences.key(this.input, entityId);
+            const expected = input.expectedPreferences?.map((item) => clone(ModelPreferenceSchema, item));
+            const next = AgentModelPreferences.record(key, input.preferences);
+            const entityCommit = input.entityCommit &&
+                EntityCommitSnapshots.capture(input.entityCommit);
+            const history = input.historyEntries?.map((entry) => clone(AgentHistoryEntrySchema, entry)) ?? [];
+            this.validateAgentCommit(entityId, input.expectedVersion, entityCommit);
+            const agentKey = this.input.id.key(entityId);
+            const slot = await this.preferenceSlot(key);
+            return this.agentFamilies().queue.run(agentKey, () => this.commitAgentLocked(entityId, slot, input.expectedVersion, expected, next, entityCommit, history));
+        });
     }
     /**
-     * Closes this commit handle without closing sibling handles.
+     * Validates the fixed Entity identity and one-version transition.
+     * @param entityId Captured Agent identifier.
+     * @param expectedVersion Initial Entity Version.
+     * @param entityCommit Optional prepared current-state mutation.
      */
-    close() {
-        this.#open = false;
+    validateAgentCommit(entityId, expectedVersion, entityCommit) {
+        if (!Number.isSafeInteger(expectedVersion) || expectedVersion < 0)
+            throw new TypeError("Agent commit requires a valid initial Entity Version.");
+        if (entityCommit === undefined)
+            return;
+        this.requireCompatible(entityCommit);
+        if (this.input.id.key(entityId) !== this.input.id.key(entityCommit.entityId) ||
+            entityCommit.next.version?.number !== expectedVersion + 1)
+            throw new Error("Agent commit requires the same Entity ID and one new Version.");
+    }
+    /**
+     * Records final audit and preference replacements inside the Entity mutation.
+     * @param entityId Captured Agent identifier.
+     * @param slot Bounded preference record slot.
+     * @param expectedVersion Initial Entity Version.
+     * @param expected Initial preference image.
+     * @param next Complete next preference record.
+     * @param entityCommit Optional prepared current-state mutation.
+     * @param history Captured final audit rows.
+     * @returns Completion after one conditional group.
+     */
+    commitAgentLocked(entityId, slot, expectedVersion, expected, next, entityCommit, history) {
+        const agentKey = this.input.id.key(entityId);
+        const priorIndex = this.agentFamilies().history.get(agentKey);
+        const index = priorIndex ?? new AgentHistoryIndex();
+        const staged = index.withEntries(history);
+        const prior = this.agentFamilies().preferences.get(slot);
+        const extra = this.agentPublication(slot, next, expected, prior, agentKey, index, priorIndex, staged);
+        return this.runAgentConditional(this.input, entityId, expectedVersion, entityCommit, extra);
     }
     /**
-     * Prepares and publishes one affected-record Entity commit under its existing queue.
+     * Replaces preference and final audit rows with rollback for failed Entity work.
+     * @param slot Bounded preference record slot.
+     * @param next Complete next preference record.
+     * @param expected Initial preference image.
+     * @param prior Previously retained preference record.
+     * @param agentKey Canonical Agent identifier.
+     * @param index Current or new audit index.
+     * @param priorIndex Previously retained audit index.
+     * @param staged Reversible final audit batch.
+     * @returns Reversible publication callbacks.
+     */
+    agentPublication(slot, next, expected, prior, agentKey, index, priorIndex, staged) {
+        return {
+            apply: () => {
+                if (next.key === undefined)
+                    throw new TypeError("Agent preference record requires identity.");
+                if (prior !== undefined)
+                    AgentModelPreferences.requireIdentity(prior, next.key);
+                if (!AgentModelPreferences.same(prior?.preferences, expected))
+                    throw new Error("Agent model preference image conflict.");
+                staged.apply();
+                this.agentFamilies().history.set(agentKey, index);
+                this.agentFamilies().preferences.set(slot, next);
+            },
+            restore: () => {
+                staged.restore();
+                if (priorIndex === undefined)
+                    this.agentFamilies().history.delete(agentKey);
+                if (prior === undefined)
+                    this.agentFamilies().preferences.delete(slot);
+                else
+                    this.agentFamilies().preferences.set(slot, prior);
+            },
+        };
+    }
+    /**
+     * Calculates a bounded v1 slot from complete preference identity evidence.
+     * @param key Complete generated Agent identity.
+     * @returns Fixed 67-character provider slot.
+     */
+    async preferenceSlot(key) {
+        const runtime = globalThis;
+        const bytes = new runtime.TextEncoder().encode(AgentModelPreferences.text(key));
+        const hash = new Uint8Array(await runtime.crypto.subtle.digest("SHA-256", bytes));
+        return `v1:${Array.from(hash, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+    }
+    /**
+     * Performs the captured conditional Agent change.
+     *
+     * @param entity The Entity persistence contract.
+     * @param entityId The captured Entity identifier.
+     * @param expectedVersion The required prior Entity version.
+     * @param extra The additional conditional records.
+     * @param input The captured Entity persistence input.
+     * @returns Completion after the conditional Agent change settles.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
+     */
+    runAgentConditional(entity, entityId, expectedVersion, input, extra) {
+        const backend = this.entities.backend(entity);
+        const key = entity.id.key(entityId);
+        const snapshot = input === undefined ? undefined : EntityCommitSnapshots.capture(input);
+        if (snapshot !== undefined) {
+            this.requireCompatible(snapshot);
+            this.requireEnabledHistories(snapshot);
+            this.validateRows(snapshot);
+            if (snapshot.diagnostics?.length || snapshot.events?.length)
+                throw new Error("Agent completion cannot save delivery Events as Entity commit obligations.");
+        }
+        return backend.mutationQueue.run(ENTITY_SCOPE_MUTATION_KEY, () => this.applyAgentConditional(entity, backend, key, expectedVersion, snapshot, extra));
+    }
+    /**
+     * Applies one prepared Agent transition and restores affected rows on failure.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state type.
-     * @param input Supplies current and immutable records.
-     * @param liveBackend Supplies the live current-record map and queue.
+     * @param entity Configured Entity storage layout.
+     * @param backend Shared current records for this Entity scope.
+     * @param key Canonical Entity ID key.
+     * @param expectedVersion Version read before handler execution.
+     * @param snapshot Optional captured Entity state transition.
+     * @param extra Applies or restores Agent audit records and model preferences.
+     * @returns Completion after the transition is stored.
      */
-    async #commit(input, liveBackend, extra) {
-        const stage = this.stage(input, liveBackend);
+    applyAgentConditional(entity, backend, key, expectedVersion, snapshot, extra) {
+        const prior = backend.current.get(key);
+        if ((prior?.version?.number ?? 0) !== expectedVersion)
+            throw new Error("Agent execution initial Entity Version is no longer current.");
+        const layout = snapshot?.states?.length ? stateHistorySpec(entity.stateSchema) : undefined;
+        const states = layout === undefined
+            ? undefined
+            : this.openRecords(entity.context, layout.spec, layout.group);
+        const prepared = layout === undefined
+            ? []
+            : (snapshot?.states ?? []).map((record) => layout.spec.materialize(record));
+        const priorStates = prepared.map((record) => states?.capture(record.id));
         try {
-            await this.#writeStage(input, stage);
-            this.#publish(stage, liveBackend, extra);
+            this.writeAgentStates(states, prepared);
+            if (snapshot !== undefined)
+                backend.current.set(key, snapshot.next);
+            extra.apply();
         }
-        finally {
-            stage.entity.close();
+        catch (error) {
+            extra.restore();
+            if (prior === undefined)
+                backend.current.delete(key);
+            else
+                backend.current.set(key, prior);
+            for (const priorState of priorStates)
+                if (priorState !== undefined)
+                    states?.apply(priorState);
+            throw error;
         }
+        return Promise.resolve();
     }
     /**
-     * Opens only record families used by one commit.
+     * Writes immutable Agent state history after checking each Version slot.
      *
-     * @typeParam I Entity identifier type.
-     * @typeParam S Entity state type.
-     * @param input Supplies configured histories and delivery Events.
-     * @returns Live affected record families and their layouts.
+     * @param states State-history records when that family is configured.
+     * @param prepared Materialized state rows from the captured transition.
      */
-    live(input) {
-        this.#requireEnabledHistories(input);
-        const stateLayout = input.states?.length
-            ? stateHistorySpec(input.entity.stateSchema)
-            : undefined;
-        const eventLayout = input.diagnostics?.length
-            ? eventHistorySpec(input.entity.stateSchema)
-            : undefined;
-        const states = stateLayout === undefined
-            ? undefined
-            : this.#openRecords(input.context, stateLayout.spec, stateLayout.group);
-        const diagnostics = eventLayout === undefined
-            ? undefined
-            : this.#openRecords(input.context, eventLayout.spec, eventLayout.group);
-        const events = input.events?.length
-            ? this.#openRecords(input.context, eventStoreRecordSpec)
-            : undefined;
-        return { stateLayout, eventLayout, states, diagnostics, events };
+    writeAgentStates(states, prepared) {
+        if (states === undefined)
+            return;
+        for (const record of prepared) {
+            const existing = states.read(record.id);
+            if (existing !== undefined &&
+                !this.sameBytes(toBinary(EntityRecordSchema, existing), toBinary(EntityRecordSchema, record.record)))
+                throw new Error("Agent state history collides with another Version.");
+            states.write(record);
+        }
+    }
+    /**
+     * Closes retained resources after admitted work settles.
+     *
+     * @returns The repeatable close outcome.
+     */
+    close() {
+        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 retained adapters only when no commit is 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 failure = this.closeRetained();
+        this.#idleOutcome = failure === undefined ? {} : { error: failure };
+        this.onClose();
+        if (failure !== undefined)
+            throw failure;
     }
     /**
-     * Captures affected rows and creates isolated adapters for preparation.
+     * Applies one captured mutation without cross-record compensation.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state type.
-     * @param input Supplies the proposed record changes.
-     * @param backend Supplies the live current-record map.
-     * @returns The prepared affected-record workspace.
-     */
-    stage(input, backend) {
-        const live = this.live(input);
-        const key = input.entity.id.key(input.entityId);
-        const previous = backend.current.get(key);
-        const ids = this.#ids(input, live);
-        const stagedBackend = {
-            current: new Map(previous === undefined ? [] : [[key, previous]]),
-            mutationQueue: new KeyedSerialQueue(),
-        };
-        const stagedStates = InMemoryCommitValues.stage(live.states, ids.stateIds);
-        const stagedDiagnostics = InMemoryCommitValues.stage(live.diagnostics, ids.diagnosticIds);
-        const stagedEvents = InMemoryCommitValues.stage(live.events, ids.deliveryIds);
-        const entity = new InMemoryEntityStorage(this.#stagedInput(input.entity, live.stateLayout, stagedStates, live.eventLayout, stagedDiagnostics), stagedBackend);
-        return {
-            live,
-            key,
-            previous,
-            ...ids,
-            stagedBackend,
-            stagedStates,
-            stagedDiagnostics,
-            stagedEvents,
-            entity,
-        };
+     * @param input Supplies immutable record snapshots.
+     * @returns Completion after every requested record write.
+     */
+    async apply(input) {
+        this.requireEnabledHistories(input);
+        this.validateRows(input);
+        const [entity, states, diagnostics, delivery] = this.openCommit(input);
+        for (const state of input.states ?? [])
+            await states?.append(state);
+        for (const diagnostic of input.diagnostics ?? [])
+            await diagnostics?.append(diagnostic);
+        for (const event of input.events ?? []) {
+            if (event.id === undefined || delivery === undefined)
+                throw new Error("Entity commit requires delivery-event IDs.");
+            await this.appendEvent(delivery, event.id, event);
+        }
+        await entity.current.write(input.next);
     }
     /**
-     * Materializes the storage identities and delivery rows before live application.
+     * Acquires only missing record families and retains them for this handle.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state type.
-     * @param input Supplies the changed records.
-     * @param live Supplies generated history layouts.
-     * @returns Affected keys and cloned delivery rows.
-     */
-    #ids(input, live) {
-        const stateIds = (input.states ?? []).map((record) => {
-            const layout = live.stateLayout;
-            if (layout === undefined)
-                throw new TypeError("Cannot read properties of undefined (reading 'spec')");
-            return layout.spec.materialize(record).id;
+     * @param input Supplies requested history and delivery records.
+     * @returns Retained Entity and requested family handles.
+     */
+    openCommit(input) {
+        const acquired = [];
+        try {
+            const entity = this.#entity ?? this.openCurrent(input, acquired);
+            const states = input.states?.length
+                ? (this.#states ?? this.openStates(input, acquired))
+                : undefined;
+            const diagnostics = input.diagnostics?.length
+                ? (this.#diagnostics ?? this.openDiagnostics(input, acquired))
+                : undefined;
+            const delivery = input.events?.length
+                ? (this.#delivery ?? this.openDelivery(input, acquired))
+                : undefined;
+            this.#entity = entity;
+            if (states !== undefined)
+                this.#states = states;
+            if (diagnostics !== undefined)
+                this.#diagnostics = diagnostics;
+            if (delivery !== undefined)
+                this.#delivery = delivery;
+            return [entity, states, diagnostics, delivery];
+        }
+        catch (error) {
+            const failures = this.closeGroup(acquired);
+            if (failures.length)
+                throw new AggregateError([error, ...failures], "Entity commit acquisition failed.");
+            throw error;
+        }
+    }
+    /**
+     * Acquires the current Entity adapter once.
+     *
+     * @param acquired Newly acquired handles to close on failure.
+     * @param input The captured Entity persistence input.
+     * @returns The retained current Entity record handle.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
+     */
+    openCurrent(input, acquired) {
+        const entityInput = { ...input.entity };
+        delete entityInput.stateHistoryStorage;
+        delete entityInput.eventHistoryStorage;
+        const entity = this.entities.create(entityInput);
+        acquired.push(entity);
+        return entity;
+    }
+    /**
+     * Acquires retained state-history storage and its adapter.
+     *
+     * @param acquired Newly acquired handles to close on failure.
+     * @param input The captured Entity persistence input.
+     * @returns The retained state-history record handle.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
+     */
+    openStates(input, acquired) {
+        const states = input.states?.length ? stateHistorySpec(input.entity.stateSchema) : undefined;
+        if (states === undefined)
+            throw new Error("State history was not requested.");
+        const records = new InMemoryRecordStorage(input.context, states.spec, () => this.openRecords(input.context, states.spec, states.group));
+        acquired.push(records);
+        const adapter = new InMemoryEntityHistory({
+            id: input.entity.id,
+            records,
+            stateSchema: input.entity.stateSchema,
+            queue: this.entities.backend(input.entity).mutationQueue,
         });
-        const diagnosticIds = (input.diagnostics ?? []).map((event) => {
-            const layout = live.eventLayout;
-            if (layout === undefined)
-                throw new TypeError("Cannot read properties of undefined (reading 'spec')");
-            return layout.spec.materialize(event).id;
+        return adapter;
+    }
+    /**
+     * Acquires retained diagnostic history storage and its adapter.
+     *
+     * @param acquired Newly acquired handles to close on failure.
+     * @param input The captured Entity persistence input.
+     * @returns The retained diagnostic Event record handle.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
+     */
+    openDiagnostics(input, acquired) {
+        const layout = eventHistorySpec(input.entity.stateSchema);
+        const records = new InMemoryRecordStorage(input.context, layout.spec, () => this.openRecords(input.context, layout.spec, layout.group));
+        acquired.push(records);
+        return new MemoryEntityEventHistory({
+            id: input.entity.id,
+            records,
+            queue: this.entities.backend(input.entity).mutationQueue,
         });
-        const materialized = (input.events ?? []).map((event) => eventStoreRecordSpec.materialize(clone(eventStoreRecordSpec.recordType, event)));
-        const deliveryIds = materialized.map((record) => record.id);
-        return { stateIds, diagnosticIds, materialized, deliveryIds };
     }
     /**
-     * Validates and writes only staged records before any live change.
+     * Acquires retained delivery Event storage.
      *
-     * @typeParam I Entity identifier type.
-     * @typeParam S Entity state type.
-     * @param input Supplies the proposed record changes.
-     * @param stage Supplies affected-record adapters and materialized Events.
+     * @param acquired Newly acquired handles to close on failure.
+     * @param input The captured Entity persistence input.
+     * @returns The retained delivery Event record handle.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
      */
-    async #writeStage(input, stage) {
-        const nextId = input.next.entityId === undefined ? undefined : input.entity.id.unpack(input.next.entityId);
-        if (nextId === undefined || input.entity.id.key(nextId) !== stage.key)
-            throw new Error("Entity commit current record identifies another Entity.");
-        if (new Set(stage.deliveryIds.map((id) => id.value)).size !== stage.deliveryIds.length ||
-            stage.deliveryIds.some((id) => stage.stagedEvents?.read(id) !== undefined))
-            throw new Error("Entity commit requires unique delivery-event IDs.");
-        await stage.entity.current.write(input.next);
-        for (const state of input.states ?? [])
-            await stage.entity.states.append(state);
-        for (const diagnostic of input.diagnostics ?? [])
-            await stage.entity.events.append(diagnostic);
-        stage.stagedEvents?.writeAll(stage.materialized);
+    openDelivery(input, acquired) {
+        const group = EventStoreGroups.forContext(input.context.name);
+        const records = new InMemoryRecordStorage(input.context, eventStoreRecordSpec, () => this.openRecords(input.context, eventStoreRecordSpec, group));
+        acquired.push(records);
+        return records;
     }
     /**
-     * Applies prepared rows synchronously and restores affected entries on failure.
+     * Registers provider work before invoking the operation.
      *
-     * @param stage Supplies the complete affected-record preparation.
-     * @param backend Supplies the live current-record map.
-     */
-    #publish(stage, backend, extra) {
-        const changes = [
-            ...InMemoryCommitValues.changes(stage.live.states, stage.stagedStates, stage.stateIds),
-            ...InMemoryCommitValues.changes(stage.live.diagnostics, stage.stagedDiagnostics, stage.diagnosticIds),
-            ...InMemoryCommitValues.changes(stage.live.events, stage.stagedEvents, stage.deliveryIds),
-        ];
-        const next = stage.stagedBackend.current.get(stage.key);
+     * @param action The admitted provider operation.
+     * @returns The admitted provider operation completion.
+     * @typeParam Value 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 {
-            for (const change of changes)
-                change.apply();
-            backend.current.set(stage.key, next);
-            extra?.apply();
+            action().then(complete, fail);
         }
         catch (error) {
-            extra?.restore();
-            if (stage.previous === undefined)
-                backend.current.delete(stage.key);
-            else
-                backend.current.set(stage.key, stage.previous);
-            for (const change of changes.reverse())
-                change.restore();
-            throw error;
+            fail(error);
         }
+        return work;
+    }
+    /**
+     * Waits for admitted commits and reports every retained close failure.
+     *
+     * @returns Completion after admitted work and cleanup settle.
+     */
+    async drain() {
+        await Promise.allSettled([...this.#active]);
+        const failure = this.closeRetained();
+        this.onClose();
+        if (failure !== undefined)
+            throw failure;
     }
     /**
-     * Connects affected staged history slices to the existing Entity adapters.
+     * Closes retained adapters once after no commit remains active.
+     *
+     * @returns A cleanup failure, if any.
+     */
+    closeRetained() {
+        const ports = [];
+        for (const port of [this.#delivery, this.#diagnostics, this.#states, this.#entity]) {
+            if (port !== undefined)
+                ports.push(port);
+        }
+        this.#delivery = undefined;
+        this.#diagnostics = undefined;
+        this.#states = undefined;
+        this.#entity = undefined;
+        const failures = this.closeGroup(ports);
+        if (failures.length === 1)
+            return failures[0];
+        return failures.length
+            ? new AggregateError(failures, "Entity commit close failed.")
+            : undefined;
+    }
+    /**
+     * Closes every newly acquired handle and collects cleanup failures.
+     *
+     * @param ports The acquired record handles.
+     * @returns Cleanup failures from acquired handles.
+     */
+    closeGroup(ports) {
+        const failures = [];
+        for (const port of ports) {
+            try {
+                port.close();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+        }
+        return failures;
+    }
+    /**
+     * Writes one immutable delivery Event or accepts an identical retry.
+     *
+     * @param storage Supplies atomic single-record insertion.
+     * @param id Identifies the delivery Event.
+     * @param event Supplies the captured Event.
+     * @returns Completion after an identical Event is stored.
+     */
+    async appendEvent(storage, id, event) {
+        if (await storage.compareAndSet(id, undefined, event))
+            return;
+        const prior = await storage.read(id);
+        if (prior === undefined ||
+            !this.sameBytes(toBinary(EventSchema, prior), toBinary(EventSchema, event))) {
+            throw new Error("Entity commit requires unique delivery-event IDs.");
+        }
+    }
+    /**
+     * Compares two stored Protobuf byte sequences.
+     *
+     * @param left First byte sequence.
+     * @param right Second byte sequence.
+     * @returns Whether every byte matches.
+     */
+    sameBytes(left, right) {
+        return left.length === right.length && left.every((value, index) => value === right[index]);
+    }
+    /**
+     * Validates current identity and duplicate delivery IDs before writes.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state type.
-     * @param entity Supplies the Entity storage layout.
-     * @param stateLayout Supplies the enabled state-history layout.
-     * @param states Supplies the affected staged state rows.
-     * @param eventLayout Supplies the enabled diagnostic-history layout.
-     * @param diagnostics Supplies the affected staged diagnostic rows.
-     * @returns The staged Entity storage layout.
-     */
-    #stagedInput(entity, stateLayout, states, eventLayout, diagnostics) {
-        const base = { ...entity };
-        delete base.stateHistoryStorage;
-        delete base.eventHistoryStorage;
-        return {
-            ...base,
-            ...(stateLayout === undefined || states === undefined
-                ? {}
-                : {
-                    stateHistoryStorage: new InMemoryRecordStorage(entity.context, stateLayout.spec, () => states),
-                }),
-            ...(eventLayout === undefined || diagnostics === undefined
-                ? {}
-                : {
-                    eventHistoryStorage: new InMemoryRecordStorage(entity.context, eventLayout.spec, () => diagnostics),
-                }),
-        };
+     * @param input Supplies the captured mutation.
+     */
+    validateRows(input) {
+        const nextId = input.next.entityId === undefined ? undefined : input.entity.id.unpack(input.next.entityId);
+        if (nextId === undefined || input.entity.id.key(nextId) !== input.entity.id.key(input.entityId))
+            throw new Error("Entity commit current record identifies another Entity.");
+        const ids = (input.events ?? []).map((event) => event.id?.value);
+        if (ids.some((id) => id === undefined || id.trim() === "") || new Set(ids).size !== ids.length)
+            throw new Error("Entity commit requires unique delivery-event IDs.");
     }
     /**
-     * Rejects history rows when their corresponding history is disabled.
+     * Rejects disabled history families.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state type.
-     * @param input Supplies the requested histories.
+     * @param input Supplies the proposed histories.
      */
-    #requireEnabledHistories(input) {
-        if ((input.states?.length ?? 0) > 0 && !input.entity.stateHistory) {
+    requireEnabledHistories(input) {
+        if ((input.states?.length ?? 0) > 0 && !input.entity.stateHistory)
             throw new Error("Entity commit cannot append state history when it is disabled.");
-        }
-        if ((input.diagnostics?.length ?? 0) > 0 && !input.entity.eventHistory) {
+        if ((input.diagnostics?.length ?? 0) > 0 && !input.entity.eventHistory)
             throw new Error("Entity commit cannot append event history when it is disabled.");
-        }
     }
     /**
-     * Checks the tenant and Entity source type captured by this handle.
+     * Checks the tenant and source captured by this handle.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state type.
      * @param input Supplies the requested scope.
      */
-    #requireCompatible(input) {
+    requireCompatible(input) {
         if (input.context.multitenant !== this.#multitenant ||
             TenantBoundary.of(input.context).key !== this.#tenantKey ||
             TenantBoundary.of(input.entity.context).key !== this.#tenantKey ||
-            input.entity.sourceType.typeName !== this.#input.sourceType.typeName) {
+            input.entity.sourceType.typeName !== this.input.sourceType.typeName) {
             throw new Error("Entity commit handle cannot commit another Entity storage scope.");
         }
     }
     /**
      * Rejects commits after this handle closes.
      */
-    #requireOpen() {
+    requireOpen() {
         if (!this.#open)
             throw new Error("Entity commit storage is closed.");
     }
 }
-/**
- * Prepares only affected materialized rows for an in-memory commit.
- */
-const InMemoryCommitValues = Object.freeze({
-    /**
-     * Captures the affected live rows in an isolated tenant slice.
-     *
-     * @typeParam I Record identifier type.
-     * @typeParam R Record message type.
-     * @param live Supplies the live tenant slice when enabled.
-     * @param ids Identifies affected slots.
-     * @returns An isolated slice with only affected prior entries.
-     */
-    stage(live, ids) {
-        if (live === undefined)
-            return undefined;
-        const staged = new TenantRecords();
-        for (const id of ids)
-            staged.apply(live.capture(id));
-        return staged;
-    },
-    /**
-     * Builds synchronous apply and restore operations for affected slots.
-     *
-     * @typeParam I Record identifier type.
-     * @typeParam R Record message type.
-     * @param live Supplies the live tenant slice when enabled.
-     * @param staged Supplies fully prepared replacements.
-     * @param ids Identifies affected slots.
-     * @returns Operations that preserve complete prior entries and absence.
-     */
-    changes(live, staged, ids) {
-        if (live === undefined || staged === undefined)
-            return [];
-        const seen = new Set();
-        return ids.flatMap((id) => {
-            const prior = live.capture(id);
-            if (seen.has(prior.key))
-                return [];
-            seen.add(prior.key);
-            const prepared = staged.capture(id);
-            return [new MemoryCommitChange(live, prepared, prior)];
-        });
-    },
-});
-/**
- * Applies one affected materialized row and restores its complete prior slot.
- *
- * @typeParam I Record identifier type.
- * @typeParam R Record message type.
- */
-class MemoryCommitChange {
-    live;
-    prepared;
-    prior;
-    /**
-     * Captures the prepared and prior versions of one slot.
-     *
-     * @param live Supplies the affected tenant slice.
-     * @param prepared Supplies the replacement entry or absence.
-     * @param prior Supplies the complete prior entry or absence.
-     */
-    constructor(live, prepared, prior) {
-        this.live = live;
-        this.prepared = prepared;
-        this.prior = prior;
-    }
-    /**
-     * Applies the fully prepared materialized row.
-     */
-    apply() {
-        this.live.apply(this.prepared);
-    }
-    /**
-     * Restores the complete prior row or absence.
-     */
-    restore() {
-        this.live.apply(this.prior);
-    }
-}
 //# sourceMappingURL=in-memory-entity-commit.js.map