@spine-event-engine/storage 2.0.0-snapshot.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,160 @@
+# Storage API and in-memory storage for Spine TS
+
+`@spine-event-engine/storage` defines the storage API used by Spine TS and
+includes an in-memory implementation for local development and tests. Use it
+when an application needs a small record store, or when an adapter needs to
+implement the same storage contract for a durable provider.
+
+For detailed query, lifecycle, and adapter notes, see
+[REFERENCE documentation for agents](REFERENCE.md).
+
+## 💡 Why use it?
+
+- ✅ Gives every Spine repository one storage contract.
+- ✅ Includes a fast in-memory implementation for development and tests.
+- ✅ Supports typed IDs, declared columns, filtering, sorting, and limits.
+- ✅ Lets applications select persistence without changing domain handlers.
+
+## 🚀 Build it in this workspace
+
+```sh
+pnpm typecheck:build
+```
+
+Run this workspace-wide TypeScript build from the repository root. For an
+experimental npm consumer, install
+`@spine-event-engine/storage@2.0.0-snapshot.2` or the explicit
+`@spine-event-engine/storage@snapshot` tag.
+
+## 🧪 Start with the Proto fields people may query
+
+Persistence begins in the Proto model. Mark only the fields that need to be
+filtered or sorted with `(column)`. The complete message is always kept as
+authoritative bytes; an unmarked field is not silently promoted to a provider
+property.
+
+```proto
+message TaskView {
+  TaskId id = 1;
+  UserId assignee = 2 [(column) = true];
+  string title = 3;
+}
+```
+
+Here `assignee` is a query column. `title` stays in the serialized record. The
+generated record specification carries that declaration into the selected
+storage adapter.
+
+## 🧪 Store a Protobuf record in memory
+
+Create a `RecordSpec` to describe the record type, identity, and searchable
+columns. Its source type defaults to the record type. Pass it to an
+`InMemoryStorageFactory` with the storage context.
+
+```ts
+import { create, ScalarType } from "@bufbuild/protobuf";
+import { StringValueSchema, type StringValue } from "@bufbuild/protobuf/wkt";
+import {
+  ColumnTypes,
+  InMemoryStorageFactory,
+  RecordColumn,
+  RecordSpec,
+} from "@spine-event-engine/storage";
+
+const records = new InMemoryStorageFactory().createRecordStorage(
+  { name: "Users", multitenant: false },
+  new RecordSpec<string, StringValue>({
+    recordType: StringValueSchema,
+    idKind: "string",
+    extractId: (user) => user.value,
+    columns: [
+      new RecordColumn("value", ColumnTypes.scalar(ScalarType.STRING), (user) => user.value),
+    ],
+  }),
+);
+
+await records.write(create(StringValueSchema, { value: "ava" }));
+const user = await records.read("ava");
+const users = await records.query({
+  filters: [{ column: "value", value: "ava" }],
+  sort: [{ field: "value", direction: "asc" }],
+  limit: 20,
+});
+```
+
+`InMemoryStorageFactory` creates a fresh backend by default. Pass the same
+`InMemoryStorageBackend` to separate factories only when they intentionally
+need to share rows. Query named columns, sort them, and limit the result; the
+column names come from the declared `RecordSpec`/Proto mapping. `RecordQuery<I>`
+types its IDs. Providers apply their documented runtime mapping and validation
+to filter names and values: MySQL checks declared columns, while other adapters
+can support different query shapes. A provider can push down supported ID and
+declared-column query parts while preserving the common result semantics.
+
+The storage API clones data at its boundaries. For the base factory and the
+in-memory implementation, closing a factory prevents new record handles while
+existing handles remain usable. Closing a record handle invalidates that
+handle's later operations. Other adapters can close live handles; see their
+[Datastore reference](../storage-datastore/REFERENCE.md) and
+[MySQL reference](../storage-rdbms/REFERENCE.md) before choosing shutdown
+behavior.
+
+## 🧩 Keep compatible record families separate
+
+Most applications only need a `RecordSpec`. Sometimes two record families use
+the same source type and record type but must remain separate: for example,
+two independently retained views of the same Task state records.
+Pass a `StorageGroup` as the optional third argument to give that family its
+separate physical storage group. The group is deliberately separate from the
+`RecordSpec`, because the record layout has not changed.
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { StringValueSchema, type StringValue } from "@bufbuild/protobuf/wkt";
+import { InMemoryStorageFactory, RecordSpec, StorageGroup } from "@spine-event-engine/storage";
+
+const factory = new InMemoryStorageFactory();
+const stateHistorySpec = new RecordSpec<string, StringValue>({
+  recordType: StringValueSchema,
+  idKind: "string",
+  extractId: (state) => state.value,
+});
+
+const auditStates = factory.createRecordStorage(
+  { name: "Tasks", multitenant: false },
+  stateHistorySpec,
+  new StorageGroup("example.tasks.TaskState.audit"),
+);
+
+await auditStates.write(create(StringValueSchema, { value: "first" }));
+```
+
+Use a group only when otherwise compatible records must not share rows. The
+ordinary Event Store is intentionally ungrouped.
+
+## 🗄️ Choose a durable adapter
+
+`@spine-event-engine/storage-datastore` provides Google Cloud Datastore
+storage. `@spine-event-engine/storage-rdbms` provides MySQL storage. Configure
+those packages in application code and pass the resulting factory to the Spine
+server; this package does not choose a database.
+
+| Need                        | Adapter                                                                   |
+| --------------------------- | ------------------------------------------------------------------------- |
+| Local development and tests | `InMemoryStorageFactory` in this package                                  |
+| Google Cloud Datastore      | [`@spine-event-engine/storage-datastore`](../storage-datastore/README.md) |
+| MySQL                       | [`@spine-event-engine/storage-rdbms`](../storage-rdbms/README.md)         |
+
+## ⚠️ Lifecycle differences
+
+The common API defines record behavior, not deployment policy. Provider
+adapters may close live handles, impose query budgets, or require indexes and
+credentials. Read the selected adapter guide before configuring production
+shutdown and queries.
+
+## 🔗 Learn more
+
+- [Datastore adapter](../storage-datastore/README.md)
+- [MySQL adapter](../storage-rdbms/README.md)
+- [Server](../server/README.md)
+- [Reference for coding agents](REFERENCE.md)

package/REFERENCE.md

@@ -0,0 +1,120 @@
+# @spine-event-engine/storage reference
+
+This reference is for agents working with the Spine TS storage contract.
+
+## Public entry point
+
+Import public types from `@spine-event-engine/storage`. The entry point exports
+`StorageFactory`, `RecordStorage`, `RecordSpec`, `RecordSpecOptions`, `RecordColumn`, `RecordQuery`,
+`RecordMask`, `StorageGroup`, `ColumnTypes`, `ColumnMappings`, the exported
+column-mapping contracts, `TenantBoundary`, `TenantCatalog`,
+`TenantCatalogProvider`, `InMemoryStorageFactory`,
+`InMemoryStorageBackend`, event-store types, normalized query policy/evaluator
+types, and entity history interfaces.
+The `./internal/entity-history` subpath supplies Entity records, source-type
+inputs, and current/state/event-history ports. The separate
+`./internal/entity-commit` subpath supplies atomic commit input/result types,
+`EntityCommitStorage`, and `EntityCommitStorageFactories`; both are
+framework/provider seams, not application-facing remote APIs.
+
+## Record storage
+
+`StorageFactory.createRecordStorage(context, spec, group?)` returns an
+independently closeable `RecordStorage`. A single-tenant context forbids a
+tenant ID. A multitenant context requires a complete generated `TenantId`.
+The Bounded Context name is diagnostic only. A `RecordSpec` fixes the
+source type, stored record type, identity extractor, ID schema or primitive ID
+kind, and materialized columns. `sourceType` defaults to `recordType`; Entity
+record specifications use the entity state type as their source type.
+`RecordSpecOptions` is the public constructor-input contract for those fields.
+For generated application records, Proto `(column)` declarations determine the
+materialized fields. A field without that declaration remains only in the
+authoritative serialized record; providers do not infer columns from every
+field in the message.
+
+`StorageGroup` is an optional external physical-family identity. It is not part
+of `RecordSpec`: use it only when records with an otherwise compatible layout
+must remain distinct. The in-memory provider keys physical identity by backend,
+tenant boundary, source type, and either the named group or the explicit
+ungrouped value. It keeps different source types and
+different groups separate even when they use the same stored record type.
+`idType`, `recordType`, `sourceType`, and `columns` are read-only accessors.
+
+`RecordStorage` supports `write`, `writeAll`, `read`, `delete`, `compareAndSet`,
+`index`, `query`, `queryEntries`, `queryPlan`, and `queryPlanEntries`. It clones
+IDs and messages at its public boundary. `RecordQuery.ids` filters actual
+storage slots, while `index()` returns logical IDs extracted from record bodies.
+Its `atomicCompareAndSet` capability defaults to `false`. A provider sets it to
+`true` only when `compareAndSet()` is atomic across compatible handles; code
+that needs that guarantee must reject a handle that does not declare it.
+
+## Query behavior
+
+Record queries validate positive limits, non-negative offsets, and
+continuations that match the requested sort fields. Query plans are normalized
+and checked against adapter capabilities. If a provider returns more candidates
+than a plan's explicit query budget, or the exported
+`defaultQueryCandidateLimit` of 10,000 when it is omitted,
+`QueryCandidateLimitError` is thrown before
+local materialization can return a partial semantic result.
+An explicit query budget must be a positive safe integer no greater
+than 10,000.
+
+An accepted query budget is distinct from the one-row raw-provider
+overflow lookahead used to detect excess: the shared default accepts 10,000
+records and can fetch 10,001 raw rows; a provider may declare a lower accepted
+ceiling, such as Datastore's 1,000 accepted / 1,001 raw rows.
+
+`StorageQueryPolicy` validates normalized plans and
+`StorageQueryEvaluator` applies the portable query semantics. Provider packages
+can push down supported ID, declared-column, and sort parts of a plan, but must
+preserve these semantics and enforce their documented bounds. `RecordQuery<I>`
+statically types IDs only; filter and sort names are strings and filter values
+are `unknown`. Each provider documents the runtime mapping and validation it
+applies before using those inputs; callers cannot infer shared filter or sort
+name validation from the common query shape.
+
+The normalized-plan matrix is intentionally provider-specific. MySQL admits
+IDs; equality and the five comparisons on mapped orderable columns; nested
+`all` and `either`; declared-column ordering; positive limits; and masks.
+Datastore admits only IDs, equality, one provider-legal inequality column, flat
+`all`, compatible ordering, limits, and masks. Both reject unsupported shapes
+before provider access. Normalized plans never include offset: the existing
+`RecordQuery.offset` path is separate. MySQL executes every admitted predicate,
+order, and finite bound in contained parameterized SQL; Datastore executes only
+that stated overlap. See each provider reference for mappings and index needs.
+
+## Lifecycle
+
+The base `StorageFactory.close()` prevents later record-storage creation. The
+in-memory factory follows that behavior and leaves existing record handles open
+until each handle closes. `RecordStorage.close()` rejects that handle's later
+operations. Datastore follows the base factory behavior. Adapters can define a
+stronger shutdown lifecycle: the MySQL factory closes live handles while it
+drains its pool. Read the [Datastore reference](../storage-datastore/REFERENCE.md)
+and [MySQL reference](../storage-rdbms/REFERENCE.md) before relying on shutdown
+behavior. The in-memory backend is ephemeral and process-local. Passing one
+`InMemoryStorageBackend` to multiple in-memory factories deliberately shares
+its scoped rows.
+
+## Entity storage
+
+The `./internal/entity-history` seam supplies the framework's Entity storage
+ports. Current Entity state is a generated `spine.server.entity.EntityRecord`.
+Retained state history stores generated `EntityStateKey`/`EntityRecord` rows in
+a `StorageGroup` named after the Entity state type. Retained diagnostic event
+history stores generated `EventId`/`Event` rows in that same state-type-named
+group. The framework Event Store is a separate, ungrouped `EventId`/`Event`
+record family.
+
+History ports are lazy. When a history is disabled, the in-memory provider does
+not open or allocate its grouped records. Current Entity loading always uses
+the current record, never retained history. Event history is diagnostic data,
+not a source for rebuilding current state.
+
+The separate `./internal/entity-commit` port combines one current record with
+the nonempty enabled history families and delivery events. For the in-memory
+provider only, that operation stages and atomically publishes its touched
+families. Its outcomes are `"committed"` and `"conflict"`; it has no receipt or
+`"replayed"` outcome. Other providers define and document their atomicity
+guarantees.

package/dist/entity/entity-history-record-spec.d.ts

@@ -0,0 +1,26 @@
+import { type Message } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { type Event, type EventId } from "@spine-event-engine/proto";
+import { type EntityRecord } from "@spine-event-engine/proto/generated/spine/server/entity/entity_pb.js";
+import { type EntityStateKey } from "@spine-event-engine/proto/generated/spine/server/entity/state_key_pb.js";
+import { RecordSpec } from "../record/record-spec.js";
+import { StorageGroup } from "../record/storage-group.js";
+/**
+ * Creates the generated state-history layout for one Entity state type.
+ * @param stateType The served Entity state message type.
+ * @returns The separate group and record specification for retained states.
+ */
+export declare function stateHistorySpec(stateType: GenMessage<Message>): {
+    readonly group: StorageGroup;
+    readonly spec: RecordSpec<EntityStateKey, EntityRecord>;
+};
+/**
+ * Creates the generated diagnostic event-history layout for one Entity state type.
+ * @param stateType The served Entity state message type.
+ * @returns The separate group and record specification for retained events.
+ */
+export declare function eventHistorySpec(stateType: GenMessage<Message>): {
+    readonly group: StorageGroup;
+    readonly spec: RecordSpec<EventId, Event>;
+};
+//# sourceMappingURL=entity-history-record-spec.d.ts.map

package/dist/entity/entity-history-record-spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-history-record-spec.d.ts","sourceRoot":"","sources":["../../src/entity/entity-history-record-spec.ts"],"names":[],"mappings":"AAcA,OAAO,EAAsB,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,OAAO,EAA8B,KAAK,KAAK,EAAE,KAAK,OAAO,EAAE,MAAM,2BAA2B,CAAC;AACjG,OAAO,EAEL,KAAK,YAAY,EAClB,MAAM,sEAAsE,CAAC;AAC9E,OAAO,EAEL,KAAK,cAAc,EACpB,MAAM,yEAAyE,CAAC;AAIjF,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE1D;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG;IAChE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;CACzD,CA+BA;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,UAAU,CAAC,OAAO,CAAC,GAAG;IAChE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;CAC3C,CA8BA"}

package/dist/entity/entity-history-record-spec.js

@@ -0,0 +1,77 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { create, ScalarType } from "@bufbuild/protobuf";
+import { AnySchema, TimestampSchema } from "@bufbuild/protobuf/wkt";
+import { EventIdSchema, EventSchema } from "@spine-event-engine/proto";
+import { EntityRecordSchema, } from "@spine-event-engine/proto/generated/spine/server/entity/entity_pb.js";
+import { EntityStateKeySchema, } from "@spine-event-engine/proto/generated/spine/server/entity/state_key_pb.js";
+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";
+/**
+ * Creates the generated state-history layout for one Entity state type.
+ * @param stateType The served Entity state message type.
+ * @returns The separate group and record specification for retained states.
+ */
+export function stateHistorySpec(stateType) {
+    return {
+        group: new StorageGroup(stateType.typeName),
+        spec: new RecordSpec({
+            sourceType: stateType,
+            recordType: EntityRecordSchema,
+            idSchema: EntityStateKeySchema,
+            extractId: (record) => {
+                if (record.entityId === undefined) {
+                    throw new Error("State history requires EntityRecord.entityId.");
+                }
+                return create(EntityStateKeySchema, {
+                    entityId: record.entityId,
+                    version: record.version?.number ?? 0,
+                });
+            },
+            columns: [
+                new RecordColumn("entity_id", ColumnTypes.message(AnySchema), (record) => record.entityId),
+                new RecordColumn("created", ColumnTypes.message(TimestampSchema), (record) => record.version?.timestamp ?? create(TimestampSchema)),
+                new RecordColumn("version", ColumnTypes.scalar(ScalarType.INT32), (record) => record.version?.number ?? 0),
+            ],
+        }),
+    };
+}
+/**
+ * Creates the generated diagnostic event-history layout for one Entity state type.
+ * @param stateType The served Entity state message type.
+ * @returns The separate group and record specification for retained events.
+ */
+export function eventHistorySpec(stateType) {
+    return {
+        group: new StorageGroup(stateType.typeName),
+        spec: new RecordSpec({
+            sourceType: EventSchema,
+            recordType: EventSchema,
+            idSchema: EventIdSchema,
+            extractId: (event) => {
+                if (event.id === undefined)
+                    throw new Error("Event history requires Event.id.");
+                return event.id;
+            },
+            columns: [
+                new RecordColumn("entity_id", ColumnTypes.message(AnySchema), (event) => event.context?.producerId),
+                new RecordColumn("created", ColumnTypes.message(TimestampSchema), (event) => event.context?.timestamp ?? create(TimestampSchema)),
+                new RecordColumn("version", ColumnTypes.scalar(ScalarType.INT32), (event) => event.context?.version?.number ?? 0),
+            ],
+        }),
+    };
+}
+//# sourceMappingURL=entity-history-record-spec.js.map

package/dist/entity/entity-history-record-spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-history-record-spec.js","sourceRoot":"","sources":["../../src/entity/entity-history-record-spec.ts"],"names":[],"mappings":"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"}