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

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.
@@ -56,13 +58,15 @@ export declare class DatastoreEntityCommitStorage implements EntityCommitStorage
     #private;
     private readonly input;
     private readonly openRecords;
+    private readonly onClose;
     /**
      * Creates commit storage for one Entity persistence contract.
      *
      * @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);
     /**
      * Writes histories and delivery Events before the current Entity record.
      *
@@ -75,6 +79,167 @@ export declare class DatastoreEntityCommitStorage implements EntityCommitStorage
      * @returns Completion after every requested record write.
      */
     commit<I, S extends Message>(input: EntityCommitInput<I, S>): Promise<void>;
+    /**
+     * 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.
+     */
+    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 requiredNative;
+    /**
+     * Persists an admitted captured mutation and one safe retry.
+     *
+     * @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 openCommit;
     /**
      * Writes independent record families in Entity commit order.
      *
@@ -97,8 +262,37 @@ export declare class DatastoreEntityCommitStorage implements EntityCommitStorage
     private retryable;
     /**
      * Closes this commit storage to further commits.
+     *
+     * @returns Completion after admitted work and record cleanup settle.
      */
-    close(): void;
+    close(): Promise<void>;
+    /**
+     * Closes only when no commit remains admitted.
+     */
+    closeIdle(): void;
+    /**
+     * Rejects synchronous disposal while asynchronous work remains admitted.
+     */
+    assertIdle(): void;
+    /**
+     * Waits for every admitted commit before completing close.
+     *
+     * @returns Completion after admitted work and cleanup settle.
+     */
+    private drain;
+    /**
+     * Closes every retained record once after admitted work settles.
+     *
+     * @returns A cleanup failure, if any.
+     */
+    private closeRetained;
+    /**
+     * Closes every newly acquired handle and collects cleanup failures.
+     *
+     * @param ports The acquired record handles.
+     * @returns Cleanup failures from acquired handles.
+     */
+    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,EAML,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;AAK7E;;;;;;;;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;;;;;;;;;;OAUG;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,KAAK;IA0BnB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAWjB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;CAmBjB"}
+{"version":3,"file":"entity-history.d.ts","sourceRoot":"","sources":["../../src/datastore/entity-history.ts"],"names":[],"mappings":"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"}