@spine-event-engine/storage-datastore 2.0.0-snapshot.10

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,262 @@
+# Google Cloud Datastore storage for Spine TS
+
+`@spine-event-engine/storage-datastore` stores Spine TS records in Google Cloud
+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).
+
+## 💡 Why use it?
+
+- ✅ Stores Spine records in Google Cloud Datastore or Firestore in Datastore mode.
+- ✅ Pushes supported filters and ordering to Datastore.
+- ✅ Preserves atomic compare-and-set writes through provider transactions.
+- ✅ Rejects queries that exceed a finite reconciliation budget instead of
+  returning incomplete results.
+
+## 🚀 First snapshot success
+
+```sh
+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
+```
+
+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
+bound is 1,000 records. Pass the factory to the server or create record storage
+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
+converts a complete generated `TenantId` to the safe reversible Spine JVM forms:
+`Dexample.org` for a domain or `Vtenant-a` for a plain value. Spine JVM's email
+form replaces `@` with `-at-`; two different emails can therefore become the
+same namespace. Spine TS rejects that unsafe default. To use email tenant IDs,
+install the same reversible custom namespace converter in both runtimes.
+Single-tenant storage keeps the namespace already configured on the
+caller-supplied client. A Bounded Context name helps diagnostics; it never changes
+a namespace, kind, or key.
+
+Suppose a projection state is declared like this:
+
+```proto
+package spine.examples.messageboard;
+
+message MessageView {
+  MessageId id = 1 [(required) = true, (set_once) = true];
+  BoardId board = 2 [(column) = true];
+  UserId author = 3 [(column) = true];
+  string text = 4;
+}
+```
+
+With the default layout, its kind is the full Proto type name, for example
+`spine.examples.messageboard.MessageView`. One entity looks conceptually like
+this:
+
+| Datastore part | Stored value                              |
+| -------------- | ----------------------------------------- |
+| namespace      | `Vtenant-a`                               |
+| kind           | `spine.examples.messageboard.MessageView` |
+| key name       | `{"value":"message-42"}`                  |
+| `bytes`        | unindexed `EntityRecord` with the state   |
+| `archived`     | native boolean                            |
+| `deleted`      | native boolean                            |
+| `version`      | native integer                            |
+| `board`        | `{"value":"board-7"}`                     |
+| `author`       | `{"value":"user-3"}`                      |
+
+`archived`, `deleted`, and `version` come from Spine's generated `EntityRecord`;
+they are Entity lifecycle/version facts, not a provider revision. `board` and
+`author` exist because the Proto fields use `(column)`. The unindexed `bytes`
+payload remains authoritative.
+
+The same identity and value mapping is used at each step: `Identifiers` turn
+the record ID into the key name, while the configured `StringifierRegistry`
+turns message-valued IDs and `(column)` values into reversible text. Do not
+pre-stringify a query value in application code. `RecordQuery<I>` statically
+types IDs only; Datastore checks the string filter name and `unknown` value
+against the record descriptor and column mapping, then applies the registry
+mapping used on write.
+
+Message-valued IDs and columns use compact Proto JSON by default. Supply the
+application `TypeRegistry` as shown above when a stored framework value contains
+an `Any`; it tells Proto JSON how to expand the packed application type.
+Applications can also register one reversible custom `Stringifier`. The same
+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](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
+`board == '{"value":"board-7"}'`. Datastore uses the declared property and its
+indexes to find matching keys; Spine decodes the authoritative `bytes` payload
+for each result.
+
+## 🔐 Configure credentials and indexes
+
+Credential selection belongs to the official Google client. For example, an
+application can use Application Default Credentials or pass `credentials` or
+`keyFilename` in its Datastore options. Keep credentials out of source code and
+logs.
+
+Queries that combine equality filters and ordering can require composite
+indexes. Kind names depend on the application's Proto types and layout choices,
+so the framework cannot ship one universal index file. Keep the required
+indexes in the application and deploy them before serving those queries. For
+example:
+
+```yaml
+indexes:
+  - kind: spine.examples.orders.OrderView
+    properties:
+      - name: status
+      - name: when_created
+        direction: desc
+```
+
+```sh
+gcloud datastore indexes create index.yaml
+gcloud datastore indexes list
+```
+
+Wait until each required index is ready before serving its query combinations.
+
+Retained Entity histories need separate indexes because their kinds and
+ordering differ from current state. For a state type named
+`spine.examples.board.Message`, the usual backward-history index is:
+
+```yaml
+indexes:
+  - kind: spine.examples.board.Message_EntityRecord
+    properties:
+      - name: entity_id
+      - name: version
+        direction: desc
+      - name: created
+        direction: desc
+```
+
+`stateAt()` instead orders `created` and then `version`, both descending.
+Diagnostic event history uses the corresponding
+`<state-source>_Event` grouped kind and the same `entity_id`, `version`, and
+`created` columns. Inspect the concrete query shapes your application serves
+and add the matching Datastore composite indexes; the adapter never creates
+them automatically.
+
+## 📏 Understand query limits
+
+The adapter has a fixed finite client-side reconciliation budget of `1000`.
+When a query needs more candidates than that budget,
+`DatastoreQueryLimitError` is thrown instead of returning a partial result.
+There is no unlimited scan setting or Datastore-specific cursor API.
+Provider filters and ordering are pushed down; public query offsets and mixed
+local/provider limits are reconciled locally within that finite bound.
+
+Ordinary `write()` and `writeAll()` calls are independent provider writes. Use
+compare-and-set for an atomic conditional record update, or an Entity commit
+for one atomic current-state/history/event mutation.
+
+## 🧪 Verify with a local emulator
+
+The optional emulator suite needs an already-running Firestore emulator in
+Datastore mode.
+
+```sh
+gcloud emulators firestore start --database-mode=datastore-mode --host-port=127.0.0.1:8081
+DATASTORE_EMULATOR_HOST=127.0.0.1:8081 \
+  pnpm --filter @spine-event-engine/storage-datastore test:emulator
+```
+
+Use a disposable project for the credential-gated cloud smoke test. Neither
+test substitutes for production index, quota, or consistency planning.
+
+## ⚠️ Before production
+
+Deploy every composite index used by the application, select quotas and retry
+policy for its workload, and keep Google credentials outside source control.
+This adapter does not provide an unlimited scan mode or a Datastore-specific
+cursor API.
+
+Before starting this corrected layout in an existing project, inventory every
+native namespace and kind:
+
+```sh
+pnpm --dir packages/storage-datastore inventory:legacy -- --project my-project
+```
+
+The command exits nonzero if discovery fails or it finds an old `_scope`
+property or scope-derived key name. Do not start the corrected runtime until it
+passes. Old rows are invisible to direct keys; move them offline, and stop if
+rows from old Bounded Context partitions would become the same namespace,
+kind, and key. The runtime never chooses a winner.
+
+## 🔗 Learn more
+
+- [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

@@ -0,0 +1,147 @@
+# @spine-event-engine/storage-datastore reference
+
+This reference is for agents configuring the Google Cloud Datastore adapter.
+
+## Public entry point
+
+Import `DatastoreStorageFactory`, `DatastoreStorageFactoryBuilder`,
+`RecordLayout`, `CreateRecordStorage`, `CreateEntityStorage`,
+`NamespaceConverter`, `DefaultNamespaceConverter`, `DatastoreIdColumn`,
+`DatastoreColumnMapping`, and `DatastoreQueryLimitError` from
+`@spine-event-engine/storage-datastore`.
+Create a factory with `DatastoreStorageFactory.newBuilder().setClient(client)`.
+The adapter never closes that client.
+
+The builder is mutable until `build()` and the built factory receives a
+snapshot. The last registration for the same identity wins. Record resolution
+uses this precedence:
+
+1. an exact source-plus-record creator;
+2. a record-only creator;
+3. an exact source-plus-record layout;
+4. a record-only layout; and
+5. the default kind.
+
+`setNamespaceConverter(...)` replaces complete `TenantId`/native namespace
+conversion. `setStringifierRegistry(...)` supplies reversible mappings for
+message-valued IDs and ordinary message columns. The stringifier registry is
+snapshotted by `build()`; a custom namespace converter is retained and must
+remain behaviorally immutable for the factory lifetime. `organizeRecords(...)`
+changes a kind. `useRecordStorage(...)` replaces a record-family provider.
+`Identifiers` select the key representation, and the same configured
+stringifier maps a message-valued ID or declared column on write, direct lookup,
+filter, ordering continuation, and read. `RecordQuery<I>` statically types IDs
+only. Datastore maps filter values through its record column mapping at runtime;
+its sort-property mapping is the requested field name. Callers do not construct
+a provider string or infer shared filter/sort-name validation.
+`useEntityStorage(...)` replaces the complete coherent Entity handle, including
+its commit capability. Custom providers receive the storage context, record or
+Entity contract, and caller-supplied client, but not the built-in converter or
+stringifier registry; they must provide equivalent tenant, ID, and column mapping. The
+built-in Entity provider does not mix custom record creators into one transaction.
+
+## Physical layout
+
+Every record family uses the source Proto full name as its default kind. A
+grouped family uses `<group>_<record-simple-name>`. A layout registration can
+replace only the kind. Rows contain unindexed Protobuf `bytes` and the declared
+indexed columns. Current Entity rows declare `archived`, `deleted`, and Entity
+`version` in addition to model `(column)` fields; Entity `version` is not a
+provider revision. No scope, ID copy, storage revision, schema fingerprint,
+marker, or compatibility entity is stored. The Bounded Context name is
+diagnostic only.
+
+Single tenancy preserves the caller client's configured/default namespace.
+Multitenancy converts the complete generated `TenantId` to a native namespace.
+The default converter supports the reversible JVM `D<domain>` and `V<value>`
+forms. It rejects email tenants because JVM's `E` conversion replaces `@` with
+`-at-` and is not injective. Email tenants require one reversible custom
+converter installed in both TS and JVM. Catalog admission rejects empty,
+non-round-tripping, or colliding converter results before provider work. The
+key contains only the resolved kind and mapped record ID. Message IDs use
+compact Proto JSON or their
+registered custom stringifier; `string`, `int32`, and `int64` IDs use their
+direct text form as the key name. `bytes` and `__key__` are reserved. Blank
+kinds, kinds or key names over 1,500 UTF-8 bytes, unsupported values, non-finite
+numbers, and integers outside their declared/provider range fail before an
+RPC. Stored `bytes` remain authoritative; declared properties are rematerialized
+after decoding.
+
+`keep()` bridges native `__namespace__` metadata lag without storing a tenant
+record. Its early-admission cache retains at most 1,000 tenants for at most 60
+seconds and removes an entry sooner when native metadata becomes visible. A
+full cache fails closed; applications can retry after metadata appears or an
+entry expires.
+
+Declared string and boolean columns use native values. Integer columns use
+Datastore int values, float/double columns use Datastore double values, bytes
+use blobs, enums use their numeric value, Timestamp uses the native timestamp,
+Version uses its number, and ordinary messages use the same compact Proto JSON
+or custom stringifier as query operands. Null is stored as native null. The
+application type registry is required when default Proto JSON expands `Any`.
+
+Entity current records use `EntityRecord`; enabled state history uses grouped
+`EntityStateKey`/`EntityRecord`; diagnostic history uses grouped
+`EventId`/`Event`; Event Store is a separate ungrouped Event family. Disabled
+histories allocate no record handle or Datastore row.
+
+## Queries and commits
+
+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
+disjunctive predicates, oversized key sets, and illegal inequality/order shapes
+reject before provider access; they never trigger an unfiltered reconciliation
+read.
+`writeAll()` uses batches of at most 500 mutations and is not atomic across
+batches.
+
+Provider-legal ID predicates, declared-property comparisons, and ordering are
+pushed only when Datastore can execute the whole selected conjunction. Runtime
+descriptor/column validation happens before that decision. An omitted query
+budget uses the shared 10,000-record materialization bound, but Datastore's
+explicit value cannot exceed 10,000. Datastore's accepted/provider ceiling is
+1,000 rows. It may read one overflow-lookahead row
+(1,001 raw rows) to reject an oversized scan rather than materializing more
+rows. There is no public Datastore cursor API.
+
+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.
+
+History reads use stable finite keyset pages. State history provides backward,
+state-at-time, trim, and truncate behavior; event history provides backward and
+truncate behavior. Timestamp comparisons include seconds and nanoseconds.
+Long maintenance can commit several bounded chunks, so a later failure leaves
+earlier chunks durable and the caller retries the same idempotent operation.
+
+The factory has one tenant catalog. It reads native `__namespace__` metadata,
+converts only namespaces recognized by its `NamespaceConverter`, and keeps an early
+in-memory cache for newly admitted tenants. `keep()` stores no `TenantId` row or
+other discovery record; Datastore exposes native metadata after an application
+entity is written in that namespace.
+
+Before deployment to an existing project, run `pnpm --dir
+packages/storage-datastore inventory:legacy -- --project <project-id>`. It
+enumerates native namespaces and kinds and fails closed on discovery errors,
+an old `_scope` property, or a scope-derived key name. Passing the inventory is
+a startup prerequisite; the application performs migration offline, with no
+dual-layout reads or automatic conflict winner.
+
+## Operations and errors
+
+Malformed payloads fail with a redacted decoding error. Physical Datastore
+errors are surfaced without payload data. The emulator suite is required for
+provider acceptance; cloud smoke remains credential-gated.
+
+`build()` and storage-handle creation issue no request. Closing the factory is
+idempotent and prevents creation of another handle without closing the
+caller-supplied client or already-created handles. Each record, Entity, and commit
+handle has an independent idempotent lifecycle and rejects work after it is closed.

package/dist/datastore/column-mapping.d.ts

@@ -0,0 +1,28 @@
+import { StringifierRegistry } from "@spine-event-engine/core";
+import type { ColumnMapping, ColumnTypeMapping, RecordColumnType } from "@spine-event-engine/storage";
+/**
+ * Converts typed Protobuf column values to Spine JVM Datastore values.
+ */
+export declare class DatastoreColumnMapping implements ColumnMapping<unknown> {
+    #private;
+    /**
+     * Creates a JVM-compatible Datastore column mapping.
+     *
+     * @param stringifiers The schema-bound message stringifiers.
+     */
+    constructor(stringifiers?: StringifierRegistry);
+    /**
+     * Returns the conversion for one generated column type.
+     *
+     * @param type The generated Protobuf column type.
+     * @returns The JVM-compatible Datastore conversion.
+     */
+    of<V>(type: RecordColumnType<V>): ColumnTypeMapping<V, unknown>;
+    /**
+     * Returns native Datastore null.
+     *
+     * @returns The null conversion.
+     */
+    ofNull(): ColumnTypeMapping<null, unknown>;
+}
+//# sourceMappingURL=column-mapping.d.ts.map

package/dist/datastore/column-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-mapping.d.ts","sourceRoot":"","sources":["../../src/datastore/column-mapping.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAKrC;;GAEG;AACH,qBAAa,sBAAuB,YAAW,aAAa,CAAC,OAAO,CAAC;;IAGnE;;;;OAIG;gBACS,YAAY,GAAE,mBAA+C;IAIzE;;;;;OAKG;IACH,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,iBAAiB,CAAC,CAAC,EAAE,OAAO,CAAC;IAkB/D;;;;OAIG;IACH,MAAM,IAAI,iBAAiB,CAAC,IAAI,EAAE,OAAO,CAAC;CAG3C"}