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

package/dist/datastore/entity-history.d.ts

@@ -1,8 +1,10 @@
 import { type Message } from "@bufbuild/protobuf";
+import { type ModelPreference } from "@spine-event-engine/proto/agent";
+import { type AgentCommitInput } from "@spine-event-engine/storage/provider";
 import { type EntityCommitInput, type EntityCommitStorage, type EntityEventHistoryPort, type EntityRecordStorage, type EntityStateHistoryPort, type EntityStorageInput } from "@spine-event-engine/storage/provider";
 import { RecordSpec, type RecordStorage } from "@spine-event-engine/storage";
 /**
- * Opens one generated record family with its resolved Datastore layout.
+ * Acquires one generated record family with its resolved Datastore layout.
  *
  * @typeParam I Record identifier type.
  * @typeParam R Stored Protobuf message type.
@@ -50,98 +52,247 @@ export declare class DatastoreEntityStorage<I, S extends Message> {
     isOpen(): boolean;
 }
 /**
- * Coordinates an Entity mutation through one Datastore transaction.
+ * Writes one Datastore Entity mutation in independent record order.
  */
 export declare class DatastoreEntityCommitStorage implements EntityCommitStorage {
     #private;
     private readonly input;
     private readonly openRecords;
+    private readonly onClose;
     /**
-     * Creates transactional commit storage for one Entity persistence contract.
+     * Creates commit storage for one Entity persistence contract.
      *
-     * @param input The Entity persistence contract served by this instance.
-     * @param openRecords The function that opens generated record families.
+     * @param input Defines the Entity source and tenant boundary.
+     * @param openRecords Opens each generated record family.
+     * @param onClose Releases factory tracking after terminal cleanup.
      */
-    constructor(input: EntityStorageInput<unknown, Message>, openRecords: OpenEntityRecords);
+    constructor(input: EntityStorageInput<unknown, Message>, openRecords: OpenEntityRecords, onClose?: () => void);
     /**
-     * Commits one Entity state transition and its generated history records.
+     * Writes histories and delivery Events before the current Entity record.
+     *
+     * A failed save may leave a completed prefix. One transient retry replays
+     * captured records with the same versions and Event IDs.
      *
      * @typeParam I Entity identifier type.
      * @typeParam S Entity state message type.
-     * @param input The Entity mutation to commit.
-     * @returns Completion after Datastore commits the mutation.
+     * @param input Supplies the prepared Entity mutation.
+     * @returns Completion after every requested record write.
      */
     commit<I, S extends Message>(input: EntityCommitInput<I, S>): Promise<void>;
     /**
-     * Retries the prepared Datastore transaction after bounded aborts.
+     * Registers a commit before invoking provider construction callbacks.
      *
-     * @typeParam I Entity identifier type.
-     * @typeParam S Entity state type.
-     * @param input Supplies current and immutable records.
-     * @param current Provides current Entity storage.
-     * @param states Provides state history when enabled.
-     * @param diagnostics Provides diagnostic history when enabled.
-     * @param events Provides delivery Event storage.
-     * @returns Completion after a successful transaction.
+     * @param action The admitted provider operation.
+     * @returns The admitted provider operation completion.
+     * @typeParam T Result type of the admitted provider operation.
+     */
+    private track;
+    /**
+     * Reads a detached current preference image from native storage.
+     * @param entityId Typed Agent identifier.
+     * @returns Complete selections or absent record.
+     */
+    readAgentPreferences(entityId: unknown): Promise<readonly ModelPreference[] | undefined>;
+    /**
+     * Commits Agent state, final audit, and preferences in one native transaction.
+     * @param input Captured live Agent transition.
+     * @returns Completion after a conditional group commits.
+     * @typeParam I Typed Agent identifier.
+     * @typeParam S Generated Agent state.
+     */
+    commitAgent<I, S extends Message>(input: AgentCommitInput<I, S>): Promise<void>;
+    /**
+     * Acquires every missing native family before publishing retained references.
+     * @param mutation Optional Entity mutation requiring history families.
+     * @returns Native handles for one Agent commit.
+     */
+    private agentRows;
+    /**
+     * Acquires only missing native Agent families without publishing partial acquisition.
+     * @param mutation Optional Entity mutation.
+     * @param acquired Collects newly opened handles for rollback.
+     * @returns Complete native family group.
+     */
+    private acquireAgentRows;
+    /**
+     * Acquires mutation families needed by the admitted Agent turn.
+     * @param mutation Optional changed Entity mutation.
+     * @param acquired Newly opened handles retained for rollback.
+     * @returns Optional mutation families.
+     */
+    private agentMutationRows;
+    /**
+     * Acquires one native record family and records its rollback obligation.
+     * @param spec Declarative record layout.
+     * @param group Optional physical family.
+     * @param acquired Newly opened handles.
+     * @returns Native record family.
+     * @typeParam Id Typed record identifier.
+     * @typeParam R Generated record.
+     */
+    private openAgentRecord;
+    /**
+     * Stores the complete acquired Agent group after every family succeeds.
+     * @param rows Complete native family group.
+     */
+    private retainAgentRows;
+    /**
+     * Checks the built-in native transaction capability.
+     * @param port Selected record family.
+     * @returns Native record family.
+     * @typeParam Id Typed record identifier.
+     * @typeParam R Generated record.
+     */
+    private native;
+    /**
+     * Validates the Entity scope and exactly one next Version before I/O.
+     * @param id Captured Agent ID.
+     * @param version Initial Entity Version.
+     * @param mutation Optional prepared Entity mutation.
+     * @typeParam I Typed Entity identifier.
+     * @typeParam S Generated Entity state.
+     */
+    private validateAgent;
+    /**
+     * Executes a captured Agent transition in one native transaction.
+     * @param rows Retained native families.
+     * @param id Captured Agent ID.
+     * @param version Initial Entity version.
+     * @param expected Initial preference image.
+     * @param next Complete replacement preferences.
+     * @param mutation Optional Entity mutation.
+     * @param history Final audit entries.
+     * @typeParam I Typed Entity identifier.
+     * @typeParam S Generated Entity state.
+     * @returns Completion after the native transaction settles.
+     */
+    private agentTransaction;
+    /**
+     * Checks both current images and stages the complete final group.
+     * @param tx Native transaction.
+     * @param staged Rows saved only after all checks pass.
+     * @param rows Retained native families.
+     * @param id Captured Agent identifier.
+     * @param version Initial Entity Version.
+     * @param expected Initial preference image.
+     * @param next Replacement preference record.
+     * @param mutation Optional Entity mutation.
+     * @param history Final audit entries.
+     * @typeParam I Typed Entity identifier.
+     * @typeParam S Generated Entity state.
+     * @returns Completion after all conditional rows are staged.
+     */
+    private agentLocked;
+    /**
+     * Records final Agent audit rows in the admitted native transaction.
+     * @param history Final Agent audit entries.
+     * @param id Captured typed Agent identifier.
+     * @param staged Rows staged for atomic commit.
+     * @param storage Retained provider record family.
+     * @param tx Active native transaction.
+     * @returns Completion after final audit rows are staged.
+     */
+    private appendAgentAudit;
+    /**
+     * Reads a native row within the Agent transaction.
+     * @param tx Active native transaction.
+     * @param storage Retained record family.
+     * @param id Typed record identifier.
+     * @returns Decoded row or absence.
+     * @typeParam Id Typed record identifier.
+     * @typeParam R Generated record.
+     */
+    private agentRead;
+    /**
+     * Checks one immutable final record before staging it.
+     * @param tx Active native transaction.
+     * @param staged Collected native rows.
+     * @param storage Retained record family.
+     * @param record Proposed immutable record.
+     * @typeParam Id Typed record identifier.
+     * @typeParam R Generated record.
+     * @returns Completion after the immutable row is checked and staged.
+     */
+    private agentImmutable;
+    /**
+     * Checks an enabled native history family.
+     * @param storage Optional native family.
+     * @returns Enabled native record family.
+     * @typeParam Id Typed record ID.
+     * @typeParam R Generated record.
      */
-    private run;
+    private requiredNative;
     /**
-     * Builds affected rows before opening a transaction.
+     * Persists an admitted captured mutation and one safe retry.
      *
-     * @typeParam I Entity identifier type.
-     * @param input Supplies records to materialize.
-     * @param current Provides current Entity storage.
-     * @param states Provides state history when enabled.
-     * @param diagnostics Provides diagnostic history when enabled.
-     * @param events Provides delivery Event storage.
-     * @returns Deduplicated rows for the transaction.
+     * @param prepared The immutable prepared mutation.
+     * @returns Completion after the captured mutation is persisted.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
+     */
+    private persist;
+    /**
+     * Acquires only missing requested families and rolls back a failed group.
+     *
+     * @param input The captured Entity persistence input.
+     * @returns The retained records required by this commit.
+     * @typeParam I Entity identifier or record type.
+     * @typeParam S Generated Entity state message type.
      */
-    private prepare;
+    private openCommit;
     /**
-     * Applies one prepared transaction attempt and rolls back on failure.
+     * Writes independent record families in Entity commit order.
      *
      * @typeParam I Entity identifier type.
-     * @param current Opens a transaction for the Entity scope.
-     * @param prepared Supplies current and immutable rows.
-     * @returns Completion after the transaction commits.
+     * @typeParam S Entity state message type.
+     * @param input Supplies immutable prepared records.
+     * @param current Stores current Entity state.
+     * @param states Stores state history when requested.
+     * @param diagnostics Stores diagnostic Events when requested.
+     * @param events Stores delivery Events when requested.
+     * @returns Completion after every requested record write.
      */
-    private tryCommit;
+    private apply;
     /**
-     * Loads affected keys in stable order within one transaction.
+     * Determines whether a Datastore abort occurred through provider error causes.
      *
-     * @param transaction Supplies the active Datastore transaction.
-     * @param prepared Supplies affected rows.
-     * @returns Existing data indexed by key.
+     * @param error Supplies the operation failure.
+     * @returns Whether one captured-input replay is safe.
      */
-    private load;
+    private retryable;
     /**
-     * Rejects divergent data already stored under immutable keys.
+     * Closes this commit storage to further commits.
      *
-     * @param prepared Supplies proposed immutable rows.
-     * @param values Supplies existing data for affected keys.
+     * @returns Completion after admitted work and record cleanup settle.
+     */
+    close(): Promise<void>;
+    /**
+     * Closes only when no commit remains admitted.
      */
-    private validateImmutable;
+    closeIdle(): void;
     /**
-     * Writes missing immutable rows and changed current state in the transaction.
+     * Rejects synchronous disposal while asynchronous work remains admitted.
+     */
+    assertIdle(): void;
+    /**
+     * Waits for every admitted commit before completing close.
      *
-     * @param transaction Supplies the active Datastore transaction.
-     * @param prepared Supplies current and immutable rows.
-     * @param values Supplies existing data for affected keys.
+     * @returns Completion after admitted work and cleanup settle.
      */
-    private apply;
+    private drain;
     /**
-     * Closes temporary record-family handles after the commit attempt.
+     * Closes every retained record once after admitted work settles.
      *
-     * @param current Supplies current Entity storage.
-     * @param states Supplies state history when enabled.
-     * @param diagnostics Supplies diagnostic history when enabled.
-     * @param events Supplies delivery Event storage.
+     * @returns A cleanup failure, if any.
      */
-    private closeRecords;
+    private closeRetained;
     /**
-     * Closes this commit storage to further commits.
+     * Closes every newly acquired handle and collects cleanup failures.
+     *
+     * @param ports The acquired record handles.
+     * @returns Cleanup failures from acquired handles.
      */
-    close(): void;
+    private closeGroup;
     /**
      * Validates the Entity, tenant, history, and Event boundaries of a commit.
      *

package/dist/datastore/entity-history.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-history.d.ts","sourceRoot":"","sources":["../../src/datastore/entity-history.ts"],"names":[],"mappings":"AAcA,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAQ/E,OAAO,EAKL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,kBAAkB,EACxB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAe7E;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EACnD,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,EACtB,KAAK,CAAC,EAAE,OAAO,6BAA6B,EAAE,YAAY,KACvD,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAEzB;;;;;GAKG;AACH,qBAAa,sBAAsB,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO;;IAGtD;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,CAAC,CAAC;IAE3C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAM9C;;;;;OAKG;gBACS,KAAK,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,EAAE,iBAAiB;IAsB3E;;OAEG;IACH,KAAK,IAAI,IAAI;IAOb;;;;OAIG;IACH,MAAM,IAAI,OAAO;CAGlB;AAED;;GAEG;AACH,qBAAa,4BAA6B,YAAW,mBAAmB;;IAUpE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAR9B;;;;;OAKG;gBAEgB,KAAK,EAAE,kBAAkB,CAAC,OAAO,EAAE,OAAO,CAAC,EAC3C,WAAW,EAAE,iBAAiB;IAGjD;;;;;;;OAOG;IACG,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BjF;;;;;;;;;;;OAWG;YACW,GAAG;IAwBjB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO;IAef;;;;;;;OAOG;YACW,SAAS;IAiBvB;;;;;;OAMG;YACW,IAAI;IAgBlB;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;;;;OAMG;IACH,OAAO,CAAC,KAAK;IAYb;;;;;;;OAOG;IACH,OAAO,CAAC,YAAY;IAYpB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;CAcjB"}
+{"version":3,"file":"entity-history.d.ts","sourceRoot":"","sources":["../../src/datastore/entity-history.ts"],"names":[],"mappings":"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"}