@spine-event-engine/storage-datastore 2.0.0-snapshot.2 → 2.0.0-snapshot.21

package/README.md

@@ -5,6 +5,9 @@ Datastore, including Firestore in Datastore mode. It implements the storage
 contract from `@spine-event-engine/storage`; it does not use Firestore Native
 APIs.
 
+This is an experimental snapshot package. Use Node 24 or newer, generated
+record schemas, and a configured Google Datastore client.
+
 For exact query limits, entity-storage behavior, and failure handling, see
 [REFERENCE documentation for agents](REFERENCE.md).
 
@@ -16,29 +19,57 @@ For exact query limits, entity-storage behavior, and failure handling, see
 - ✅ Rejects queries that exceed a finite reconciliation budget instead of
   returning incomplete results.
 
-## 🚀 Build it in this workspace
+## 🚀 First snapshot success
 
 ```sh
-pnpm typecheck:build
+mkdir spine-datastore-app && cd spine-datastore-app
+pnpm init
+pnpm add @spine-event-engine/storage-datastore@snapshot @spine-event-engine/storage@snapshot @bufbuild/protobuf @google-cloud/datastore
 ```
 
-Run this workspace-wide TypeScript build from the repository root. For an
-experimental npm consumer, install
-`@spine-event-engine/storage-datastore@2.0.0-snapshot.2` or the explicit
-`@spine-event-engine/storage-datastore@snapshot` tag.
+Create a `storage.ts` file from the factory example below, replace `my-project`
+with a Google Cloud project that you can access, and run it with Node 24 or
+newer. A successful read of `task-42` proves the installed snapshot can create,
+write, and read a Datastore record. The snapshot tag can change before a stable
+release.
 
 ## 🔌 Create a factory
 
 Give the adapter an already configured Datastore client when the application
 controls Google authentication and client lifetime.
 
+<!-- docs-snippet-path: packages/storage-datastore/src/index.ts -->
+
 ```ts
 import { Datastore } from "@google-cloud/datastore";
+import { create, ScalarType } from "@bufbuild/protobuf";
+import { StringValueSchema, type StringValue } from "@bufbuild/protobuf/wkt";
+import { ColumnTypes, RecordColumn, RecordSpec } from "@spine-event-engine/storage";
 import { DatastoreStorageFactory } from "@spine-event-engine/storage-datastore";
 
 const factory = DatastoreStorageFactory.newBuilder()
   .setClient(new Datastore({ projectId: "my-project" }))
   .build();
+const records = factory.createRecordStorage(
+  { name: "Tasks", multitenant: false },
+  new RecordSpec<string, StringValue>({
+    recordType: StringValueSchema,
+    idKind: "string",
+    extractId: (record) => record.value,
+    columns: [
+      new RecordColumn("value", ColumnTypes.scalar(ScalarType.STRING), (record) => record.value),
+    ],
+  }),
+);
+
+try {
+  await records.write(create(StringValueSchema, { value: "task-42" }));
+  const stored = await records.read("task-42");
+  if (stored?.value !== "task-42") throw new Error("The record was not stored.");
+} finally {
+  await records.close();
+  factory.close();
+}
 ```
 
 The builder always uses a client supplied by the caller. Its fixed finite reconciliation
@@ -47,6 +78,15 @@ through the normal storage API. When application values contain `Any`, configure
 a `StringifierRegistry` with that application's `TypeRegistry` before building;
 the layout section below explains why that mapping must remain reversible.
 
+## Build it in this workspace
+
+Contributors changing this repository can run the workspace-wide build from its
+root:
+
+```sh
+pnpm typecheck:build
+```
+
 ## 🧭 Understand tenants and kinds
 
 Datastore uses its native namespace as the tenant boundary. By default, Spine
@@ -109,7 +149,7 @@ mapping is used for writes, key lookups, filters, ordering continuations, and
 reads. Primitive values use their native Datastore representation. There is no
 `_scope`, copied ID, storage revision, fingerprint, marker, or compatibility
 entity. The runnable configuration is in the
-[Message Board deployment](../../examples/message-board/app/src/deployment-config.ts).
+[Message Board deployment](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/message-board/app/src/deployment-config.ts).
 
 When a user queries `board == BoardId("board-7")`, Spine converts that generated
 `BoardId` with the same stringifier and sends a Datastore property filter for
@@ -217,6 +257,6 @@ kind, and key. The runtime never chooses a winner.
 
 ## 🔗 Learn more
 
-- [Storage API](../storage/README.md)
-- [Datastore guide](../../docs/USER_GUIDE.md#12-develop-with-google-cloud-datastore)
+- [Storage API](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/storage/README.md)
+- [Datastore guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/USER_GUIDE.md#6-persist-application-data)
 - [Reference for coding agents](REFERENCE.md)

package/REFERENCE.md

@@ -89,7 +89,7 @@ histories allocate no record handle or Datastore row.
 
 Queries run inside the selected native namespace. Normalized plans admit only
 IDs (up to Datastore's legal key filter bound), equality, one inequality column,
-flat conjunction, inequality-compatible ordering, limit, and mask. Nested or
+flat conjunction, inequality-compatible ordering, and limit. Nested or
 disjunctive predicates, oversized key sets, and illegal inequality/order shapes
 reject before provider access; they never trigger an unfiltered reconciliation
 read.
@@ -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/delivery-cleanup.d.ts

@@ -1,5 +1,5 @@
 import type { Message } from "@bufbuild/protobuf";
-import { type DeliveryCleanupInput, type DeliveryCleanupStorage } from "@spine-event-engine/storage/internal/delivery-cleanup";
+import { type DeliveryCleanupInput, type DeliveryCleanupStorage } from "@spine-event-engine/storage/provider";
 import type { RecordSpec, StorageContext } from "@spine-event-engine/storage";
 import { DatastoreRecordStorage } from "./record-storage.js";
 /**

package/dist/datastore/delivery-cleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"delivery-cleanup.d.ts","sourceRoot":"","sources":["../../src/datastore/delivery-cleanup.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC5B,MAAM,uDAAuD,CAAC;AAC/D,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;GAEG;AACH,qBAAa,+BAAgC,YAAW,sBAAsB;;IAS1E,OAAO,CAAC,QAAQ,CAAC,WAAW;IAN9B;;;;OAIG;gBAEgB,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EACjD,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,KACnB,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;IAGnC;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,SAAS,OAAO,EAAE,SAAS,EAAE,aAAa,SAAS,OAAO,EACzF,KAAK,EAAE,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,CAAC,GAC1E,OAAO,CAAC,OAAO,CAAC;IA8DnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAGb,OAAO,CAAC,MAAM,CAAC,KAAK;IAQpB,OAAO,CAAC,MAAM,CAAC,MAAM;CAGtB"}
+{"version":3,"file":"delivery-cleanup.d.ts","sourceRoot":"","sources":["../../src/datastore/delivery-cleanup.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC5B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;GAEG;AACH,qBAAa,+BAAgC,YAAW,sBAAsB;;IAS1E,OAAO,CAAC,QAAQ,CAAC,WAAW;IAN9B;;;;OAIG;gBAEgB,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,EACjD,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC,KACnB,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC;IAGnC;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,WAAW,SAAS,OAAO,EAAE,SAAS,EAAE,aAAa,SAAS,OAAO,EACzF,KAAK,EAAE,oBAAoB,CAAC,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,CAAC,GAC1E,OAAO,CAAC,OAAO,CAAC;IA8DnB;;OAEG;IACH,KAAK,IAAI,IAAI;IAGb,OAAO,CAAC,MAAM,CAAC,KAAK;IAQpB,OAAO,CAAC,MAAM,CAAC,MAAM;CAGtB"}

package/dist/datastore/delivery-cleanup.js

@@ -11,7 +11,7 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { cleanupOperationActive, } from "@spine-event-engine/storage/internal/delivery-cleanup";
+import { cleanupOperationActive, } from "@spine-event-engine/storage/provider";
 import { DatastoreRecordStorage } from "./record-storage.js";
 /**
  * Coordinates one fenced delivered Inbox deletion in Datastore.

package/dist/datastore/delivery-cleanup.js.map

@@ -1 +1 @@
-{"version":3,"file":"delivery-cleanup.js","sourceRoot":"","sources":["../../src/datastore/delivery-cleanup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"delivery-cleanup.js","sourceRoot":"","sources":["../../src/datastore/delivery-cleanup.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EACL,sBAAsB,GAIvB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAE7D;;GAEG;AACH,MAAM,OAAO,+BAA+B;IASvB;IARnB,KAAK,GAAG,IAAI,CAAC;IAEb;;;;OAIG;IACH,YACmB,WAGgB;QAHhB,gBAAW,GAAX,WAAW,CAGK;IAChC,CAAC;IAEJ;;;;;OAKG;IACH,KAAK,CAAC,MAAM,CACV,KAA2E;QAE3E,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;QACxE,IAAI,CAAC,+BAA+B,CAAC,MAAM,CAAC,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACjE,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAChE,MAAM,QAAQ,GAAG,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QACrE,MAAM,WAAW,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QAC3C,IAAI,CAAC;YACH,MAAM,WAAW,CAAC,GAAG,EAAE,CAAC;YACxB,MAAM,aAAa,GAAG,+BAA+B,CAAC,KAAK,CACzD,MAAM,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAC9E,CAAC;YACF,IAAI,CAAC,+BAA+B,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IACE,aAAa,KAAK,SAAS;gBAC3B,CAAC,QAAQ,CAAC,wBAAwB,CAAC,aAAa,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;gBACzE,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC,EACzE,CAAC;gBACD,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,aAAa,GAAG,KAAK,CAAC,iBAAiB,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACpE,MAAM,WAAW,GAAG,+BAA+B,CAAC,KAAK,CACvD,MAAM,WAAW,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,CAAC,CACzC,CAAC;YACF,IACE,WAAW,KAAK,SAAS;gBACzB,CAAC,KAAK,CAAC,wBAAwB,CAAC,WAAW,EAAE,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,EAClE,CAAC;gBACD,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;gBAC9E,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IAAI,CAAC,+BAA+B,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,WAAW,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YACtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,uBAAuB,CAAC,aAAa,CAAC,CAAC,EAAE,CAAC;gBAC9E,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,IAAI,CAAC,+BAA+B,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBACnD,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC;gBAC7B,OAAO,KAAK,CAAC;YACf,CAAC;YACD,MAAM,WAAW,CAAC,MAAM,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,WAAW,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACpD,MAAM,KAAK,CAAC;QACd,CAAC;gBAAS,CAAC;YACT,KAAK,CAAC,KAAK,EAAE,CAAC;YACd,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;IACO,MAAM,CAAC,KAAK,CAAC,KAAc;QACjC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;YACzB,KAAK,CAAC,MAAM,GAAG,CAAC;YAChB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;YAC5B,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI;YACjB,CAAC,CAAE,KAAK,CAAC,CAAC,CAAsC;YAChD,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IACO,MAAM,CAAC,MAAM,CAAC,KAAgD;QACpE,OAAO,sBAAsB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACjD,CAAC;CACF"}

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/internal/entity-history";
+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,qDAAqD,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAkB,KAAK,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAc7F;;;;;;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"}