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

package/dist/event/event-store.js

@@ -11,35 +11,94 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { clone, create, ScalarType, toBinary } from "@bufbuild/protobuf";
+import { clone, create, equals, ScalarType } from "@bufbuild/protobuf";
 import { TimestampSchema } from "@bufbuild/protobuf/wkt";
 import { EventIdSchema, EventSchema, TenantIdSchema } from "@spine-event-engine/proto";
 import { RecordColumn } from "../record/record-column.js";
 import { ColumnTypes } from "../record/column-type.js";
 import { RecordSpec } from "../record/record-spec.js";
+import { StorageGroup } from "../record/storage-group.js";
 import { TenantBoundary } from "../internal/tenancy.js";
-const savedEventStores = new WeakMap();
+const idleClosers = new WeakMap();
+const eventStoreSelections = new WeakMap();
+/**
+ * Stable physical Event record family for one logical context and store role.
+ */
+export const EventStoreGroups = Object.freeze({
+    /**
+     * Selects the readable Bounded Context name and retains the Event Store role.
+     *
+     * @param contextName Framework-validated logical context name.
+     * @param role Domain or paired System Event store.
+     * @returns Stable physical Event family selector.
+     */
+    forContext(contextName, role = "domain") {
+        const group = new StorageGroup(contextName);
+        eventStoreSelections.set(group, { name: contextName, role });
+        return group;
+    },
+    identity(group) {
+        const selection = eventStoreSelections.get(group);
+        return selection === undefined
+            ? undefined
+            : JSON.stringify(["EventStore", selection.role, selection.name]);
+    },
+});
 /**
  * Framework event store backed by record storage.
  *
- * Snapshots input events before queued work, rejects missing, blank, and
- * duplicate IDs in one batch, and rejects IDs already stored for the same
- * captured storage context.
+ * Snapshots input Events and rejects missing, blank, or repeated IDs within a
+ * batch. Immutable append accepts identical complete stored Events and leaves
+ * completed prefixes when a later insert fails. Admission methods reject every
+ * existing ID, including an identical Event.
  */
 export class EventStore {
+    /**
+     * Selected Event Store context.
+     */
     #context;
+    /**
+     * Opens Event record-family handles.
+     */
     #factory;
+    /**
+     * Record family selected by the logical context and store role.
+     */
+    #group;
+    /**
+     * Retains one record storage per complete tenant boundary.
+     */
+    #storages = new Map();
+    /**
+     * Tracks admitted physical storage groups until their complete operation settles.
+     */
+    #active = new Set();
+    /**
+     * Reuses one asynchronous close result across repeated calls.
+     */
+    #closing;
+    /**
+     * Retains the terminal result of synchronous assembly cleanup.
+     */
+    #idleOutcome;
+    /**
+     * Whether this Event Store accepts operations.
+     */
     #open = true;
     /**
      * Creates an event store for one storage context.
      *
      * @param context Specifies the storage context.
      * @param factory Creates the backing record storage.
+     * @param group Selects a separate Event record family when supplied.
      */
-    constructor(context, factory) {
+    constructor(context, factory, group) {
         this.#context = EventContexts.base(context);
         this.#factory = factory;
-        savedEventStores.set(this, { context: this.#context, factory });
+        this.#group = group ?? EventStoreGroups.forContext(this.#context.name);
+        idleClosers.set(this, () => {
+            this.#closeIdle();
+        });
     }
     /**
      * Returns whether this Event Store still accepts operations.
@@ -50,13 +109,84 @@ export class EventStore {
         return this.#open;
     }
     /**
-     * Closes this Event Store. Operation-selected storage handles close after use.
+     * Rejects new work, drains admitted storage groups, and closes retained handles.
+     * Repeated calls return the same close result.
+     *
+     * @returns Completion after all admitted work and storage cleanup settle.
      */
     close() {
+        if (this.#closing !== undefined)
+            return this.#closing;
+        if (this.#idleOutcome !== undefined) {
+            const error = this.#idleOutcome.error;
+            return error === undefined ? Promise.resolve() : Promise.reject(error);
+        }
         this.#open = false;
+        this.#closing = this.drainAndClose();
+        return this.#closing;
+    }
+    /**
+     * Closes an idle store during synchronous assembly cleanup.
+     * Active storage work is a misuse and leaves all handles open.
+     *
+     */
+    #closeIdle() {
+        if (this.#active.size > 0 || (this.#closing !== undefined && this.#idleOutcome === undefined))
+            throw new Error("EventStore closeIdle requires no active storage work.");
+        if (this.#idleOutcome !== undefined) {
+            if (this.#idleOutcome.error !== undefined)
+                throw this.#idleOutcome.error;
+            return;
+        }
+        this.#open = false;
+        try {
+            this.closeStorages();
+            this.#idleOutcome = {};
+        }
+        catch (error) {
+            this.#idleOutcome = { error: error };
+            throw error;
+        }
     }
     /**
-     * Validates that one generated Spine event can be appended without storing it.
+     * Waits for admitted physical work and then closes every retained handle.
+     *
+     * @returns Completion after admitted work and cleanup settle.
+     */
+    async drainAndClose() {
+        await Promise.allSettled([...this.#active]);
+        try {
+            this.closeStorages();
+            this.#idleOutcome = {};
+        }
+        catch (error) {
+            this.#idleOutcome = { error: error };
+            throw error;
+        }
+    }
+    /**
+     * Closes every retained handle and reports all cleanup failures.
+     */
+    closeStorages() {
+        const storages = [...this.#storages.values()];
+        this.#storages.clear();
+        const errors = [];
+        for (const storage of storages) {
+            try {
+                storage.close();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1)
+            throw new AggregateError(errors, "EventStore close failed.");
+    }
+    /**
+     * Validates strict new admission without storing an Event. An identical
+     * existing Event still rejects; this precheck does not reserve its ID.
      *
      * @param event Supplies the event to validate.
      * @returns Completes when the event is accepted.
@@ -67,8 +197,9 @@ export class EventStore {
         await this.checkUnique([EventIds.require(record)], context);
     }
     /**
-     * Accepts one event, runs caller acceptance, and appends using one captured
-     * storage context.
+     * Checks strict new admission, runs caller acceptance, then atomically inserts
+     * under one captured context. Competing callbacks may both run, but only one
+     * absent-slot insertion can succeed.
      *
      * @param event Supplies the event to accept.
      * @param onAccepted Runs after uniqueness validation and before append.
@@ -83,52 +214,30 @@ export class EventStore {
         return clone(EventSchema, record);
     }
     /**
-     * Writes one generated Spine event, rejecting missing, blank, or duplicate IDs.
+     * Writes one complete Event, accepting an identical immutable retry without
+     * overwriting it. A conflicting Event at the same ID rejects.
      *
      * @param event Supplies the event to append.
      * @returns Completes when the event is appended.
      */
     async append(event) {
         const record = clone(EventSchema, event);
-        await this.appendUnique([record], EventContexts.snapshotForEvent(this.#context, record));
+        await this.appendImmutable([record], EventContexts.snapshotForEvent(this.#context, record));
     }
     /**
-     * Writes generated Spine events in order, rejecting missing, blank, or duplicate IDs.
+     * Writes generated Events in order, accepting identical immutable retries.
+     * A later failure retains the completed prefix for retry with the same IDs.
      *
      * @param events Supplies the events to append.
      * @returns Completes when the events are appended.
      */
     async appendAll(events) {
+        this.requireOpen();
         const records = [...events].map((event) => clone(EventSchema, event));
         if (records.length > 0) {
-            await this.appendUnique(records, EventContexts.batch(this.#context, records));
+            await this.appendImmutable(records, EventContexts.batch(this.#context, records));
         }
     }
-    /**
-     * Writes generated Spine events and returns a one-shot rollback token.
-     *
-     * @param events Supplies the events to append.
-     * @returns Resolves to the rollback token for this append.
-     */
-    async appendAllWithRollback(events) {
-        const records = [...events].map((event) => clone(EventSchema, event));
-        const ids = records.map((record) => EventIds.require(record));
-        const context = records.length === 0 ? undefined : EventContexts.batch(this.#context, records);
-        if (context !== undefined) {
-            await this.appendUnique(records, context);
-        }
-        let used = false;
-        return Object.freeze({
-            rollback: async () => {
-                if (used) {
-                    throw new Error("Event rollback token has already been used.");
-                }
-                used = true;
-                if (context !== undefined)
-                    await this.deleteIds(ids, context);
-            },
-        });
-    }
     /**
      * Reads persisted events through the underlying record-storage query seam.
      *
@@ -137,208 +246,103 @@ export class EventStore {
      */
     async read(query = {}) {
         this.requireOpen();
-        const storage = this.#factory.createRecordStorage(EventContexts.snapshot(this.#context), eventStoreRecordSpec);
-        try {
-            return await storage.query(query);
-        }
-        finally {
-            storage.close();
-        }
+        return this.runStorage(EventContexts.snapshot(this.#context), (storage) => storage.query(query));
     }
     /**
-     * Persists one batch only when every original Event ID is available.
+     * Writes strictly new Events after caller acceptance.
      *
-     * @param records Original Event envelopes.
-     * @param context Captured tenant and Bounded Context.
-     * @returns Completion after all unique Events are persisted.
+     * @param records Supplies validated Event snapshots.
+     * @param context Selects their storage boundary.
+     * @returns Completion after every strict insertion.
      */
     async appendUnique(records, context) {
         this.requireOpen();
         const ids = records.map((record) => EventIds.require(record));
         EventIds.rejectDuplicates(ids);
-        await eventStoreAccess.withLock(this.#factory, context, async () => {
-            const storage = this.#factory.createRecordStorage(context, eventStoreRecordSpec);
-            try {
-                await EventIds.insertUnique(storage, records);
-            }
-            finally {
-                storage.close();
-            }
-        });
+        await this.runStorage(context, (storage) => EventIds.insertUnique(storage, records));
     }
     /**
-     * Deletes the IDs inserted by a failed legacy batch operation.
+     * Writes captured immutable Events, accepting identical stored retries.
      *
-     * @param ids IDs inserted by the current batch.
-     * @param context Captured tenant and Bounded Context.
-     * @returns Completion after those IDs are removed.
+     * @param records Supplies ordered Event snapshots.
+     * @param context Selects their single storage boundary.
+     * @returns Completion after every immutable Event is confirmed.
      */
-    async deleteIds(ids, context) {
+    async appendImmutable(records, context) {
         this.requireOpen();
-        await eventStoreAccess.withLock(this.#factory, context, async () => {
-            const storage = this.#factory.createRecordStorage(context, eventStoreRecordSpec);
-            try {
-                for (const id of ids) {
-                    await storage.delete(id);
-                }
-            }
-            finally {
-                storage.close();
-            }
-        });
+        EventIds.rejectDuplicates(records.map((record) => EventIds.require(record)));
+        await this.runStorage(context, (storage) => EventIds.insertImmutable(storage, records));
     }
     /**
-     * Checks that no ID in a batch is already stored for this Bounded Context and tenant.
+     * Checks strict admission without writing an Event.
      *
-     * @param ids Original Event IDs.
-     * @param context Captured tenant and Bounded Context.
-     * @returns Completion after duplicate validation.
+     * @param ids Supplies IDs that must be absent.
+     * @param context Selects the storage boundary.
+     * @returns Completion when no ID is stored.
      */
     async checkUnique(ids, context) {
         this.requireOpen();
         EventIds.rejectDuplicates(ids);
-        await eventStoreAccess.withLock(this.#factory, context, async () => {
-            const storage = this.#factory.createRecordStorage(context, eventStoreRecordSpec);
-            try {
-                await EventIds.rejectStored(storage, ids);
-            }
-            finally {
-                storage.close();
-            }
-        });
+        await this.runStorage(context, (storage) => EventIds.rejectStored(storage, ids));
     }
     /**
-     * Rejects calls after this Event Store closes.
-     */
-    requireOpen() {
-        if (!this.#open)
-            throw new Error("EventStore is closed.");
-    }
-}
-const EventStoreLocks = Object.freeze({
-    queues: new WeakMap(),
-    /**
-     * Serializes Event ID checks and insertion for one captured Bounded Context and tenant.
+     * Executes one complete physical storage operation through settlement.
      *
-     * @param factory Storage provider used for the Event family.
-     * @param context Captured tenant and Bounded Context.
-     * @param work Operation run under the Bounded Context and tenant lock.
-     * @returns Result returned by the operation.
-     * @typeParam T Operation result.
-     */
-    async withLock(factory, context, work) {
-        const queues = this.queueMap(factory);
-        const key = EventContexts.key(context);
-        const previous = queues.get(key) ?? Promise.resolve();
-        const next = previous.then(work, work);
-        const stored = next.then(() => undefined, () => undefined);
-        queues.set(key, stored);
+     * @typeParam T Operation result type.
+     * @param context Captured tenant scope.
+     * @param onStorage Work admitted against the retained handle.
+     * @returns The operation result or its original failure.
+     */
+    async runStorage(context, onStorage) {
+        const storage = this.storageFor(context);
+        const work = Promise.resolve().then(() => onStorage(storage));
+        this.#active.add(work);
         try {
-            return await next;
+            return await work;
         }
         finally {
-            if (queues.get(key) === stored) {
-                queues.delete(key);
-            }
-        }
-    },
-    /**
-     * Returns the serial queue map for one storage provider.
-     *
-     * @param factory Storage provider used for the Event family.
-     * @returns Bounded Context and tenant queues for this provider.
-     */
-    queueMap(factory) {
-        let queues = this.queues.get(factory);
-        if (queues === undefined) {
-            queues = new Map();
-            this.queues.set(factory, queues);
+            this.#active.delete(work);
         }
-        return queues;
-    },
-});
-/**
- * Exposes captured Event Store coordination to provider and Agent delivery paths.
- * @internal
- */
-export const eventStoreAccess = Object.freeze({
-    // prettier-ignore
+    }
     /**
-     * Runs work under the same factory/context lock used by direct Event Store appends.
+     * Returns retained record storage for the captured tenant boundary.
      *
-     * @param factory The factory that owns the Event Store records.
-     * @param context The Event Store context to serialize.
-     * @param work The operation to run while holding the lock.
-     * @returns The operation result.
-     * @typeParam T Result returned by the transaction callback.
-     */
-    withLock(factory, context, work) {
-        return EventStoreLocks.withLock(factory, context, work);
-    },
+     * @param context Complete tenant-scoped storage context.
+     * @returns The retained record storage.
+     */
+    storageFor(context) {
+        this.requireOpen();
+        const key = TenantBoundary.of(context).key;
+        const existing = this.#storages.get(key);
+        if (existing !== undefined)
+            return existing;
+        const storage = this.#factory.createRecordStorage(context, eventStoreRecordSpec, this.#group);
+        this.#storages.set(key, storage);
+        return storage;
+    }
     /**
-     * Reuses one EventStore's captured tenant and Bounded Context for saved-output retry.
+     * Rejects operations after this Event Store closes.
      */
-    async appendOrVerifyOriginal(store, event) {
-        if (!store.isOpen())
+    requireOpen() {
+        if (!this.#open)
             throw new Error("EventStore is closed.");
-        const binding = savedEventStores.get(store);
-        if (binding === undefined)
-            throw new Error("Saved Agent Event requires an EventStore instance.");
-        const record = clone(EventSchema, event);
-        const context = EventContexts.snapshotForEvent(binding.context, record);
-        const id = EventIds.require(record);
-        await this.withLock(binding.factory, context, async () => {
-            const storage = binding.factory.createRecordStorage(context, eventStoreRecordSpec);
-            try {
-                await SavedEvents.appendOrVerify(storage, id, record);
-            }
-            finally {
-                storage.close();
-            }
-        });
-        return record;
-    },
-});
+    }
+}
 /**
- * Keeps saved-output insert and complete-envelope comparison together.
+ * Gives server assembly access to synchronous idle cleanup through the provider entrypoint.
+ * @internal
  */
-const SavedEvents = {
+export const eventStoreAccess = {
     /**
-     * Applies atomic insert and compares every original Event byte after a collision.
+     * Closes an idle Event Store during synchronous assembly rollback.
      *
-     * @param event Original event envelope.
-     * @param id Complete persisted record identity.
-     * @param storage Native record storage for this row.
-     * @returns Completion after exact-envelope insertion or verification.
+     * @param store Framework Event Store to close.
      */
-    async appendOrVerify(storage, id, event) {
-        if (!storage.atomicCompareAndSet)
-            throw new Error("Saved Agent Event requires atomic record compare-and-set.");
-        try {
-            if (await storage.compareAndSet(id, undefined, event))
-                return;
-        }
-        catch (error) {
-            const stored = await storage.read(id);
-            if (stored !== undefined && this.same(stored, event))
-                return;
-            throw error;
-        }
-        const stored = await storage.read(id);
-        if (stored === undefined || !this.same(stored, event))
-            throw new Error("Saved Agent Event ID conflicts with another envelope.");
-    },
-    /**
-     * Compares complete Protobuf envelopes, including unknown fields.
-     *
-     * @param left First value in the comparison.
-     * @param right Second value in the comparison.
-     * @returns Whether the two original Event envelopes have identical bytes.
-     */
-    same(left, right) {
-        const a = toBinary(EventSchema, left);
-        const b = toBinary(EventSchema, right);
-        return a.length === b.length && a.every((byte, index) => byte === b[index]);
+    closeIdle(store) {
+        const close = idleClosers.get(store);
+        if (close === undefined)
+            throw new TypeError("EventStore idle cleanup requires an EventStore.");
+        close();
     },
 };
 /**
@@ -347,10 +351,10 @@ const SavedEvents = {
 const EventIds = {
     // prettier-ignore
     /**
-     * Validates an event to have a non-blank ID.
+     * Validates that an Event has a non-blank ID.
      *
-     * @param event Original event envelope.
-     * @returns Present value or an error when missing.
+     * @param event Supplies the Event envelope.
+     * @returns Its validated ID.
      */
     require(event) {
         if (event.id === undefined)
@@ -363,9 +367,9 @@ const EventIds = {
     /**
      * Rejects IDs that already exist in storage.
      *
-     * @param ids Original event identities.
-     * @param storage Native record storage for this row.
-     * @returns Completion after duplicate-ID validation.
+     * @param storage Reads existing Events.
+     * @param ids Supplies IDs that must be absent.
+     * @returns Completion when no ID exists.
      */
     async rejectStored(storage, ids) {
         if ((await storage.index({ ids })).length > 0) {
@@ -373,48 +377,53 @@ const EventIds = {
         }
     },
     /**
-     * Writes each event ID and rejects the whole batch on collision.
+     * Writes each strictly new Event, retaining a completed prefix on failure.
      *
-     * @param records Records participating in this operation.
-     * @param storage Native record storage for this row.
-     * @returns Completion after unique Event IDs are persisted.
+     * @param storage Supplies atomic record insertion.
+     * @param records Supplies accepted Event snapshots.
+     * @returns Completion after every new Event is stored.
      */
     async insertUnique(storage, records) {
         if (!storage.atomicCompareAndSet) {
             throw new Error("EventStore requires atomic record compare-and-set.");
         }
-        const inserted = [];
-        try {
-            for (const record of records) {
-                const id = EventIds.require(record);
-                if (!(await storage.compareAndSet(id, undefined, record))) {
-                    throw new Error("EventStore requires unique event IDs.");
-                }
-                inserted.push({ id, record });
+        for (const record of records) {
+            const id = EventIds.require(record);
+            if (!(await storage.compareAndSet(id, undefined, record))) {
+                throw new Error("EventStore requires unique event IDs.");
             }
         }
-        catch (error) {
-            const failures = [];
-            for (const { id, record } of inserted.reverse()) {
-                try {
-                    if (!(await storage.compareAndSet(id, record, undefined))) {
-                        failures.push(new Error("EventStore append rollback lost its stored event."));
-                    }
-                }
-                catch (rollbackError) {
-                    failures.push(rollbackError);
+    },
+    /**
+     * Writes immutable Events or confirms complete equality at the same ID.
+     *
+     * @param storage Supplies atomic single-record insertion and reads.
+     * @param records Supplies ordered Event snapshots.
+     * @returns Completion after each Event is present unchanged.
+     */
+    async insertImmutable(storage, records) {
+        if (!storage.atomicCompareAndSet)
+            throw new Error("EventStore requires atomic record compare-and-set.");
+        for (const record of records) {
+            const id = EventIds.require(record);
+            for (let attempt = 0; attempt < 2; attempt += 1) {
+                if (await storage.compareAndSet(id, undefined, record))
+                    break;
+                const stored = await storage.read(id);
+                if (stored !== undefined) {
+                    if (!equals(EventSchema, stored, record))
+                        throw new Error("EventStore requires unique event IDs.");
+                    break;
                 }
+                if (attempt === 1)
+                    throw new Error("EventStore immutable insert could not confirm its ID.");
             }
-            if (failures.length > 0) {
-                throw new AggregateError([error, ...failures], "EventStore append rollback failed.");
-            }
-            throw error;
         }
     },
     /**
      * Rejects repeated IDs within one append operation.
      *
-     * @param ids Original event identities.
+     * @param ids Supplies the IDs in the operation.
      */
     rejectDuplicates(ids) {
         const seen = new Set();
@@ -426,15 +435,15 @@ const EventIds = {
     },
 };
 /**
- * Captures tenant-aware event-store contexts and their lock keys.
+ * Captures tenant-aware event-store contexts.
  */
 const EventContexts = {
     // prettier-ignore
     /**
      * Captures one storage context.
      *
-     * @param context Captured event storage context.
-     * @returns Base event storage context.
+     * @param context Supplies context and optional default tenant.
+     * @returns An immutable context snapshot.
      */
     base(context) {
         return context.multitenant
@@ -448,10 +457,10 @@ const EventContexts = {
             : Object.freeze({ name: context.name, multitenant: false });
     },
     /**
-     * Captures the selected tenant for an Event Store read.
+     * Returns a complete storage context for a read.
      *
-     * @param context Event Store storage context and selected tenant.
-     * @returns Immutable storage context for the read.
+     * @param context Supplies an explicit default tenant when required.
+     * @returns A complete tenant-scoped storage context.
      */
     snapshot(context) {
         if (!context.multitenant)
@@ -469,9 +478,9 @@ const EventContexts = {
     /**
      * Captures one context using an event envelope tenant when present.
      *
-     * @param context Captured event storage context.
-     * @param event Original event envelope.
-     * @returns Captured storage context for this Event and tenant.
+     * @param context Supplies the Event Store default boundary.
+     * @param event Supplies an optional envelope tenant.
+     * @returns The Event's complete storage context.
      */
     snapshotForEvent(context, event) {
         if (!context.multitenant)
@@ -486,11 +495,11 @@ const EventContexts = {
         });
     },
     /**
-     * Checks every Event in one batch uses the same captured tenant.
+     * Returns one tenant boundary for every Event in a batch.
      *
-     * @param context Event Store storage context before envelope validation.
-     * @param events Original Event envelopes in the batch.
-     * @returns Immutable storage context shared by every Event in the batch.
+     * @param context Supplies the Event Store default boundary.
+     * @param events Supplies the complete Event batch.
+     * @returns Their shared storage context.
      */
     batch(context, events) {
         const first = events[0];
@@ -507,8 +516,8 @@ const EventContexts = {
     /**
      * Reads an explicit tenant from an event envelope.
      *
-     * @param event Original event envelope.
-     * @returns Tenant encoded in the original Event when present.
+     * @param event Supplies the envelope origin.
+     * @returns Its tenant when present.
      */
     readEventTenant(event) {
         switch (event.context?.origin.case) {
@@ -523,21 +532,12 @@ const EventContexts = {
     /**
      * Converts a typed tenant ID to its storage-scope value.
      *
-     * @param tenantId Tenant identifier captured for this operation.
-     * @returns Tenant identity when configured.
+     * @param tenantId Supplies the optional tenant ID.
+     * @returns An independent tenant ID when present.
      */
     tenantValue(tenantId) {
         return tenantId === undefined ? undefined : clone(TenantIdSchema, tenantId);
     },
-    /**
-     * Creates a deterministic key for a context-scoped append lock.
-     *
-     * @param context Captured event storage context.
-     * @returns Complete encoded invocation identity.
-     */
-    key(context) {
-        return TenantBoundary.of(context).key;
-    },
 };
 /**
  * Provides the canonical event-store record layout to provider-only internals.