@spine-event-engine/storage-datastore 2.0.0-snapshot.18 → 2.0.0-snapshot.20

package/REFERENCE.md

@@ -109,12 +109,14 @@ This is deliberately the overlap, not MySQL parity: nested or disjunctive
 predicates and provider-illegal inequality/order shapes reject before provider
 access. Normalized plans have no offset; `RecordQuery.offset` is separate.
 
-The internal Entity commit reads current and immutable keys then applies current,
-enabled histories, and delivery events in one Datastore transaction. It rejects
-more than 25 entity groups, 500 mutations, or its conservative transaction-size
-limit before opening the transaction. Current mismatch returns `conflict`.
-An already-applied identical retry returns `committed`; divergent immutable
-content fails. Only ABORTED provider failures retry, for at most three attempts.
+The provider Entity commit writes the supplied current record, enabled histories,
+and delivery events in one Datastore transaction. It does not compare current
+state with an expected previous record. The operation rejects more than 25
+entity groups, 500 mutations, or its conservative transaction-size limit before
+opening the transaction. Success resolves without a value. Identical immutable
+retries remain accepted; divergent immutable content fails. Associated records
+are still completed when the current record already matches the supplied value.
+Only ABORTED provider failures retry, for at most three attempts.
 
 History reads use stable finite keyset pages. State history provides backward,
 state-at-time, trim, and truncate behavior; event history provides backward and

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

@@ -1,9 +1,11 @@
 import { type Message } from "@bufbuild/protobuf";
-import { type EntityCommitInput, type EntityCommitResult, type EntityCommitStorage, type EntityEventHistoryPort, type EntityRecordStorage, type EntityStateHistoryPort, type EntityStorageInput } 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.
  *
+ * @typeParam I Record identifier type.
+ * @typeParam R Stored Protobuf message type.
  * @param spec The generated record-family contract.
  * @param group The optional generated storage group.
  * @returns The opened record-storage handle.
@@ -11,6 +13,9 @@ import { RecordSpec, type RecordStorage } from "@spine-event-engine/storage";
 export type OpenEntityRecords = <I, R extends Message>(spec: RecordSpec<I, R>, group?: import("@spine-event-engine/storage").StorageGroup) => RecordStorage<I, R>;
 /**
  * Groups Entity current and optional history record families.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
  */
 export declare class DatastoreEntityStorage<I, S extends Message> {
     #private;
@@ -61,22 +66,89 @@ export declare class DatastoreEntityCommitStorage implements EntityCommitStorage
     /**
      * Commits one Entity state transition and its generated history records.
      *
+     * @typeParam I Entity identifier type.
+     * @typeParam S Entity state message type.
      * @param input The Entity mutation to commit.
-     * @returns The committed or conflicting outcome.
+     * @returns Completion after Datastore commits the mutation.
+     */
+    commit<I, S extends Message>(input: EntityCommitInput<I, S>): Promise<void>;
+    /**
+     * Retries the prepared Datastore transaction after bounded aborts.
+     *
+     * @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.
      */
-    commit<I, S extends Message>(input: EntityCommitInput<I, S>): Promise<EntityCommitResult>;
     private run;
+    /**
+     * Builds affected rows before opening a transaction.
+     *
+     * @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.
+     */
     private prepare;
+    /**
+     * Applies one prepared transaction attempt and rolls back on failure.
+     *
+     * @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.
+     */
     private tryCommit;
+    /**
+     * Loads affected keys in stable order within one transaction.
+     *
+     * @param transaction Supplies the active Datastore transaction.
+     * @param prepared Supplies affected rows.
+     * @returns Existing data indexed by key.
+     */
     private load;
-    private conflict;
+    /**
+     * Rejects divergent data already stored under immutable keys.
+     *
+     * @param prepared Supplies proposed immutable rows.
+     * @param values Supplies existing data for affected keys.
+     */
     private validateImmutable;
+    /**
+     * Writes missing immutable rows and changed current state in the transaction.
+     *
+     * @param transaction Supplies the active Datastore transaction.
+     * @param prepared Supplies current and immutable rows.
+     * @param values Supplies existing data for affected keys.
+     */
     private apply;
+    /**
+     * Closes temporary record-family handles after the commit attempt.
+     *
+     * @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.
+     */
     private closeRecords;
     /**
      * Closes this commit storage to further commits.
      */
     close(): void;
+    /**
+     * Validates the Entity, tenant, history, and Event boundaries of a commit.
+     *
+     * @typeParam I Entity identifier type.
+     * @typeParam S Entity state type.
+     * @param input Supplies the proposed commit.
+     */
     private validate;
 }
 //# sourceMappingURL=entity-history.d.ts.map

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,kBAAkB,EACvB,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;;;;;;GAMG;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;;GAEG;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;IAI9C;;;;;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;;;;;OAKG;IACG,MAAM,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EAAE,KAAK,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,kBAAkB,CAAC;YA4BjF,GAAG;IAuBjB,OAAO,CAAC,OAAO;YAeD,SAAS;YAoBT,IAAI;YAgBJ,QAAQ;IAetB,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,YAAY;IAYpB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,QAAQ;CAcjB"}
+{"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"}

package/dist/datastore/entity-history.js

@@ -23,6 +23,9 @@ import { Datastore } from "@google-cloud/datastore";
 import { DatastoreRecordStorage } from "./record-storage.js";
 /**
  * Groups Entity current and optional history record families.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
  */
 export class DatastoreEntityStorage {
     // prettier-ignore
@@ -100,8 +103,10 @@ export class DatastoreEntityCommitStorage {
     /**
      * Commits one Entity state transition and its generated history records.
      *
+     * @typeParam I Entity identifier type.
+     * @typeParam S Entity state message type.
      * @param input The Entity mutation to commit.
-     * @returns The committed or conflicting outcome.
+     * @returns Completion after Datastore commits the mutation.
      */
     async commit(input) {
         this.validate(input);
@@ -116,18 +121,31 @@ export class DatastoreEntityCommitStorage {
             : undefined;
         const events = this.openRecords(eventStoreRecordSpec);
         try {
-            return await this.run(input, current, states, diagnostics, events);
+            await this.run(input, current, states, diagnostics, events);
         }
         finally {
             this.closeRecords(current, states, diagnostics, events);
         }
     }
+    /**
+     * Retries the prepared Datastore transaction after bounded aborts.
+     *
+     * @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.
+     */
     async run(input, current, states, diagnostics, events) {
         const prepared = this.prepare(input, current, states, diagnostics, events);
         validateCommitSize(prepared.map((row) => row.entity));
         for (let attempt = 0; attempt < 3; attempt += 1) {
             try {
-                return await this.tryCommit(input, current, prepared);
+                await this.tryCommit(current, prepared);
+                return;
             }
             catch (error) {
                 if (isAborted(error) && attempt < 2) {
@@ -139,6 +157,17 @@ export class DatastoreEntityCommitStorage {
         }
         throw new Error("Datastore transaction did not complete.");
     }
+    /**
+     * Builds affected rows before opening a transaction.
+     *
+     * @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.
+     */
     prepare(input, current, states, diagnostics, events) {
         return coalesceImmutableRows([
             ...preparedRows(current, [input.next], false),
@@ -147,23 +176,35 @@ export class DatastoreEntityCommitStorage {
             ...preparedRows(events, input.events ?? [], true),
         ]);
     }
-    async tryCommit(input, current, prepared) {
+    /**
+     * Applies one prepared transaction attempt and rolls back on failure.
+     *
+     * @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.
+     */
+    async tryCommit(current, prepared) {
         const transaction = current.transaction();
         try {
             await transaction.run();
             const values = await this.load(transaction, prepared);
-            if (await this.conflict(transaction, input, current, values))
-                return "conflict";
             this.validateImmutable(prepared, values);
             this.apply(transaction, prepared, values);
             await transaction.commit();
-            return "committed";
         }
         catch (error) {
             await rollback(transaction);
             throw error;
         }
     }
+    /**
+     * Loads affected keys in stable order within one transaction.
+     *
+     * @param transaction Supplies the active Datastore transaction.
+     * @param prepared Supplies affected rows.
+     * @returns Existing data indexed by key.
+     */
     async load(transaction, prepared) {
         const keys = [...uniqueKeys(prepared.map((row) => row.entity.key))].sort((left, right) => keyId(left).localeCompare(keyId(right)));
         const values = [];
@@ -174,14 +215,12 @@ export class DatastoreEntityCommitStorage {
             ]);
         return new Map(values);
     }
-    async conflict(transaction, input, current, values) {
-        const live = values.get(keyId(current.transactionEntity(input.next).key));
-        const expected = input.expected === undefined ? undefined : current.transactionEntity(input.expected).data;
-        if (sameData(live, expected) || sameData(live, current.transactionEntity(input.next).data))
-            return false;
-        await transaction.rollback();
-        return true;
-    }
+    /**
+     * Rejects divergent data already stored under immutable keys.
+     *
+     * @param prepared Supplies proposed immutable rows.
+     * @param values Supplies existing data for affected keys.
+     */
     validateImmutable(prepared, values) {
         for (const row of prepared.filter((item) => item.immutable)) {
             const previous = values.get(keyId(row.entity.key));
@@ -189,6 +228,13 @@ export class DatastoreEntityCommitStorage {
                 throw new Error("Immutable history record has divergent content.");
         }
     }
+    /**
+     * Writes missing immutable rows and changed current state in the transaction.
+     *
+     * @param transaction Supplies the active Datastore transaction.
+     * @param prepared Supplies current and immutable rows.
+     * @param values Supplies existing data for affected keys.
+     */
     apply(transaction, prepared, values) {
         for (const row of prepared) {
             const previous = values.get(keyId(row.entity.key));
@@ -196,6 +242,14 @@ export class DatastoreEntityCommitStorage {
                 transaction.save(row.entity);
         }
     }
+    /**
+     * Closes temporary record-family handles after the commit attempt.
+     *
+     * @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.
+     */
     closeRecords(current, states, diagnostics, events) {
         current.close();
         states?.close();
@@ -208,6 +262,13 @@ export class DatastoreEntityCommitStorage {
     close() {
         this.#open = false;
     }
+    /**
+     * Validates the Entity, tenant, history, and Event boundaries of a commit.
+     *
+     * @typeParam I Entity identifier type.
+     * @typeParam S Entity state type.
+     * @param input Supplies the proposed commit.
+     */
     validate(input) {
         if (!this.#open)
             throw new Error("Entity commit storage is closed.");
@@ -222,22 +283,52 @@ export class DatastoreEntityCommitStorage {
         validateEvents(input.events ?? []);
     }
 }
+/**
+ * Provides the current Entity records through one record-family handle.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ */
 class CurrentStorage {
     input;
     records;
+    /**
+     * Creates current-record access for one Entity storage contract.
+     *
+     * @param input Defines the Entity identity and columns.
+     * @param records Provides current Entity record storage.
+     */
     constructor(input, records) {
         this.input = input;
         this.records = records;
     }
+    /**
+     * Reads one current Entity record.
+     *
+     * @param id Identifies the Entity.
+     * @returns The current record, or undefined when none is stored.
+     */
     read(id) {
         return this.records.read(id);
     }
+    /**
+     * Stores the current record for its Entity.
+     *
+     * @param record Supplies the current Entity record.
+     * @returns Completion after the record is stored.
+     */
     async write(record) {
         const id = record.entityId === undefined ? undefined : this.input.id.unpack(record.entityId);
         if (id === undefined)
             throw new Error("Entity current record ID does not match its Entity ID schema.");
         await this.records.write(record);
     }
+    /**
+     * Returns current Entity records and their configured columns.
+     *
+     * @param plan Specifies the normalized query.
+     * @returns Matching Entity records and column values.
+     */
     async query(plan) {
         return (await this.records.queryPlanEntries(plan)).map((entry) => ({
             ...entry,
@@ -245,17 +336,43 @@ class CurrentStorage {
         }));
     }
 }
+/**
+ * Provides retained Entity state history through one record-family handle.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ */
 class StateHistory {
     input;
     records;
+    /**
+     * Creates state-history access for one Entity storage contract.
+     *
+     * @param input Defines the Entity identity and state schema.
+     * @param records Provides retained state-history records.
+     */
     constructor(input, records) {
         this.input = input;
         this.records = records;
     }
+    /**
+     * Stores one immutable state-history record.
+     *
+     * @param record Supplies the state-history record.
+     * @returns Completion after the record is retained.
+     */
     append(record) {
         this.requireOpen();
         return immutable(this.records, record);
     }
+    /**
+     * Reads recent state-history records in reverse order.
+     *
+     * @param id Identifies the Entity.
+     * @param depth Sets the maximum number of records to read.
+     * @param from Sets an optional upper version bound.
+     * @returns Matching records from newest to oldest.
+     */
     async backward(id, depth, from) {
         this.requireOpen();
         requireDepth(depth);
@@ -267,6 +384,13 @@ class StateHistory {
             { property: "created", direction: "desc" },
         ], depth);
     }
+    /**
+     * Reads the Entity state recorded at or before a time.
+     *
+     * @param id Identifies the Entity.
+     * @param time Sets the latest creation time to include.
+     * @returns The matching state, or undefined when none exists.
+     */
     async stateAt(id, time) {
         this.requireOpen();
         const page = await this.provider().queryProviderPage({
@@ -282,6 +406,13 @@ class StateHistory {
             ? undefined
             : fromBinary(this.input.stateSchema, found.state.value);
     }
+    /**
+     * Stores no more than the newest state-history records for an Entity.
+     *
+     * @param id Identifies the Entity.
+     * @param keep Sets the number of newest records to retain.
+     * @returns Completion after older records are removed.
+     */
     async trim(id, keep) {
         this.requireOpen();
         requireKeep(keep);
@@ -300,6 +431,12 @@ class StateHistory {
                 break;
         }
     }
+    /**
+     * Removes state-history records created before a time.
+     *
+     * @param time Sets the exclusive creation-time boundary.
+     * @returns Completion after matching records are removed.
+     */
     async truncate(time) {
         this.requireOpen();
         for (;;) {
@@ -316,16 +453,35 @@ class StateHistory {
                 break;
         }
     }
+    /**
+     * Closes the state-history record handle.
+     */
     close() {
         this.records.close();
     }
+    /**
+     * Returns the Datastore provider for state-history queries.
+     *
+     * @returns The typed Datastore record-storage handle.
+     */
     provider() {
         return this.records;
     }
+    /**
+     * Rejects operations after the record handle closes.
+     */
     requireOpen() {
         if (!this.records.isOpen())
             throw new Error("Entity history storage is closed.");
     }
+    /**
+     * Reads a bounded sequence of matching state-history pages.
+     *
+     * @param filters Specifies the Datastore filters.
+     * @param order Specifies the Datastore sort order.
+     * @param depth Sets the maximum number of records to read.
+     * @returns Matching records in page order.
+     */
     async pages(filters, order, depth) {
         const result = [];
         let cursor;
@@ -344,17 +500,43 @@ class StateHistory {
         return result;
     }
 }
+/**
+ * Provides retained Entity Event history through one record-family handle.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ */
 class EventHistory {
     input;
     records;
+    /**
+     * Creates Event-history access for one Entity storage contract.
+     *
+     * @param input Defines the Entity identity and state schema.
+     * @param records Provides retained Event-history records.
+     */
     constructor(input, records) {
         this.input = input;
         this.records = records;
     }
+    /**
+     * Stores one immutable Entity Event-history record.
+     *
+     * @param event Supplies the Event-history record.
+     * @returns Completion after the Event is retained.
+     */
     append(event) {
         this.requireOpen();
         return immutable(this.records, event);
     }
+    /**
+     * Reads recent Entity Events in reverse order.
+     *
+     * @param id Identifies the Entity.
+     * @param depth Sets the maximum number of Events to read.
+     * @param from Sets an optional upper version bound.
+     * @returns Matching Events from newest to oldest.
+     */
     async backward(id, depth, from) {
         this.requireOpen();
         requireDepth(depth);
@@ -380,6 +562,12 @@ class EventHistory {
         }
         return result;
     }
+    /**
+     * Removes Entity Events created before a time.
+     *
+     * @param time Sets the exclusive creation-time boundary.
+     * @returns Completion after matching Events are removed.
+     */
     async truncate(time) {
         this.requireOpen();
         for (;;) {
@@ -396,17 +584,37 @@ class EventHistory {
                 break;
         }
     }
+    /**
+     * Closes the Event-history record handle.
+     */
     close() {
         this.records.close();
     }
+    /**
+     * Returns the Datastore provider for Event-history queries.
+     *
+     * @returns The typed Datastore record-storage handle.
+     */
     provider() {
         return this.records;
     }
+    /**
+     * Rejects operations after the record handle closes.
+     */
     requireOpen() {
         if (!this.records.isOpen())
             throw new Error("Entity history storage is closed.");
     }
 }
+/**
+ * Stores a history record once and rejects divergent content for its ID.
+ *
+ * @typeParam I Record identifier type.
+ * @typeParam R Stored Protobuf message type.
+ * @param records Provides immutable history record storage.
+ * @param record Supplies the history record to retain.
+ * @returns Completion after the record is present.
+ */
 async function immutable(records, record) {
     const id = records.recordSpec.idValueIn(record);
     if (await records.compareAndSet(id, undefined, record))
@@ -417,6 +625,16 @@ async function immutable(records, record) {
     if (!same(toBinary(records.recordSpec.recordType, existing), toBinary(records.recordSpec.recordType, record)))
         throw new Error("Immutable history record has divergent content.");
 }
+/**
+ * Prepares Datastore rows for one record family.
+ *
+ * @typeParam I Record identifier type.
+ * @typeParam R Stored Protobuf message type.
+ * @param storage Provides the record-family handle when enabled.
+ * @param records Supplies records to prepare.
+ * @param immutable Marks whether existing rows must remain unchanged.
+ * @returns The prepared rows for the transaction.
+ */
 function preparedRows(storage, records, immutable) {
     if (storage === undefined) {
         if (records.length > 0)
@@ -430,6 +648,13 @@ function preparedRows(storage, records, immutable) {
         entity: storage.transactionEntity(record),
     }));
 }
+/**
+ * Removes duplicate immutable rows and rejects conflicting content.
+ *
+ * @typeParam R Prepared row type.
+ * @param rows Supplies prepared current and history rows.
+ * @returns Rows with duplicate immutable keys removed.
+ */
 function coalesceImmutableRows(rows) {
     const seen = new Map();
     return rows.filter((row) => {
@@ -456,6 +681,15 @@ function requireKeep(value) {
     if (!Number.isSafeInteger(value) || value < 0)
         throw new Error("History retention must be a non-negative safe integer.");
 }
+/**
+ * Creates a Datastore filter for one Entity identifier.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ * @param input Defines the Entity ID schema.
+ * @param id Identifies the Entity to match.
+ * @returns The Datastore Entity ID filter.
+ */
 function entityFilter(input, id) {
     return { property: "entity_id", operator: "=", value: input.id.pack(id) };
 }
@@ -492,6 +726,12 @@ function abortBackoff(attempt) {
     const delayMs = 20 * (attempt + 1) + Math.floor(Math.random() * 40);
     return new Promise((resolve) => setTimeout(resolve, delayMs));
 }
+/**
+ * Rolls back a failed Datastore transaction when possible.
+ *
+ * @param transaction Supplies the transaction to roll back.
+ * @returns Completion after rollback finishes or fails.
+ */
 async function rollback(transaction) {
     try {
         await transaction.rollback();
@@ -520,6 +760,13 @@ function validateEvents(events) {
         new Set(ids).size !== ids.length)
         throw new Error("Entity commit requires non-blank unique delivery-event IDs.");
 }
+/**
+ * Checks that current and history records identify the committed Entity.
+ *
+ * @typeParam I Entity identifier type.
+ * @typeParam S Entity state message type.
+ * @param input Supplies the Entity commit to check.
+ */
 function validateCommitEntityId(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))