@spine-event-engine/client-node 2.0.0-snapshot.2 → 2.0.0-snapshot.21

package/README.md

@@ -1,29 +1,49 @@
 # Spine client for Node.js
 
-Use this package from a Node.js application to post commands, send queries, or
-create subscriptions for query-side views. It creates the Node HTTP/2 transport;
-the same request and subscription API is shared with the browser client.
+Use this package from a Node.js ESM application to post commands, send queries,
+or create subscriptions for query-side views. It owns the Node HTTP/2 transport;
+the request and subscription API is shared with the browser client.
 
-For detailed public contracts and limits, read the [reference](REFERENCE.md).
+This is an experimental snapshot. Install the snapshot explicitly while its API
+and packaging continue to evolve:
 
-The [browser client and gateway guide](../../docs/BROWSER_CLIENT_AUTH_EXTENSION_GUIDE.md)
-explains the gateway boundary shared by Node and browser clients.
+```sh
+pnpm add @spine-event-engine/client-node@snapshot
+```
+
+For detailed public contracts, lifecycle rules, and limits, read the
+[reference](REFERENCE.md).
+
+## 💡 Who should use it?
+
+- ✅ Node.js services, workers, and command-line applications that call a Spine
+  application gateway.
+- ✅ Applications that already own a generated Spine model package and a
+  reachable local or deployed Spine service.
+- ❌ Browser applications; use `@spine-event-engine/client-web` instead.
 
-## 💡 Why use it?
+## 🚀 Post a command to a local application
 
-- ✅ Posts commands and reads entities through typed Spine services.
-- ✅ Creates, activates, and cancels subscriptions.
-- ✅ Manages the Node HTTP/2 connection and closes it predictably.
-- ✅ Builds safe entity queries from generated `(column)` declarations.
+Before running this example, use Node.js with ESM support, generate and build
+your application's Proto model, and start that application's local Spine
+service. For the concrete Message Board workspace walkthrough, clone this
+repository, run `pnpm install --frozen-lockfile && pnpm typecheck:build`, then
+start `pnpm --dir examples/message-board/app start`. That command starts the
+single-tenant local service at `http://127.0.0.1:8090`.
 
-## 🚀 Connect to an application server
+The imports below are the Message Board workspace model contract: its
+`package.json` exports compiled `generated/*.js` modules after the setup above.
+They are not an installable dependency for an external application. In your
+application, depend on your own generated model package and replace this model
+package name and generated export paths with the ones declared by its
+`package.json` and `spine-proto.json`.
 
-Create one client for the process or application component that manages the
-connection. A client created with `connectTo()` creates and closes its HTTP/2
-session.
+Create one client for the component that manages the connection. A client from
+`connectTo()` owns its HTTP/2 session, so always close it.
+
+<!-- docs-snippet-path: examples/message-board/app/src/index.ts -->
 
 ```ts
-// docs-snippet-path: examples/message-board/app/src/index.ts
 import { create } from "@bufbuild/protobuf";
 import { timestampFromDate } from "@bufbuild/protobuf/wkt";
 import { Client } from "@spine-event-engine/client-node";
@@ -34,7 +54,7 @@ import {
 } from "@spine-event-engine/example-message-board-model/generated/spine/examples/messageboard/message_board_pb.js";
 import { UserIdSchema } from "@spine-event-engine/example-message-board-model/generated/spine/examples/messageboard/user_pb.js";
 
-const client = Client.connectTo("http://127.0.0.1:8080", { tenant: "tasks" });
+const client = Client.connectTo("http://127.0.0.1:8090");
 const request = client.onBehalfOf("alice");
 const result = await request.post(
   PostMessageSchema,
@@ -47,18 +67,16 @@ const result = await request.post(
     postedAt: timestampFromDate(new Date()),
   }),
 );
-if (result.kind === "rejection") console.log(result.rejection);
+if (result.kind !== "ok") throw new Error(`Message was not accepted: ${result.kind}`);
 await client.close();
 ```
 
 The URL is an application gateway URL. It is not an instruction to expose a
-Spine server directly to the internet.
-
-Node subscriptions use the same `createSubscription`, `activate`, and `cancel`
-API as the browser client; see the [client-web reference](../client-web/REFERENCE.md)
-for its lifecycle and recovery limits.
+Spine server directly to the internet. A successful call is an observation that
+the local service accepted the command; handle rejection and error outcomes in
+your application instead of assuming every command succeeds.
 
-## 🔎 Query entities by declared columns
+## 🔎 Query generated entities
 
 Generate entity columns from the model package, register them once, and build
 queries with those declared columns. The `./codegen` entry point is for model
@@ -66,45 +84,23 @@ generation; applications use the generated definition and `EntityQuery`.
 `limit()` requires an ordering. Only generated columns for the selected Entity
 may be used in its predicates.
 
-Generate those definitions in a model package with the Node code-generation
-plugin, then import the resulting declaration from that model:
-
-```sh
-protoc --spine-entity-columns_out=generated proto/spine/examples/messageboard/message_board.proto
-```
+The [reference](REFERENCE.md) documents the query builder and its column-safety
+rules.
 
-```ts
-// docs-snippet-path: examples/todo/src/index.ts
-import { Client, EntityColumn, EntityQuery } from "@spine-event-engine/client-node";
-import { create } from "@bufbuild/protobuf";
-import { ActorContextSchema } from "@spine-event-engine/proto";
-import { TaskListColumnDefinition } from "@spine-event-engine/example-todo/generated/spine/examples/todo/task_list_columns.js";
-import { TaskListSchema } from "@spine-event-engine/example-todo/generated/spine/examples/todo/task_list_pb.js";
-
-const columns = EntityColumn.register(TaskListSchema, TaskListColumnDefinition);
-const query = EntityQuery.select({
-  schema: TaskListSchema,
-  columns,
-  context: create(ActorContextSchema, { actor: { value: "alice" } }),
-})
-  .orderBy(columns.openTaskCount, "desc")
-  .limit(20)
-  .build();
-const client = Client.connectTo("http://127.0.0.1:8080");
-const response = await client.asGuest().send(query);
-console.log(response.message.length);
-await client.close();
-```
-
-## ⚠️ Connection behavior
+## ⚠️ Cleanup and limits
 
 The client does not make a server safe for public access. Put the authenticated
 application gateway at the network boundary. Commands are not retried
 automatically, and an interrupted subscription must be recreated before the
 application re-reads current entity state.
 
+Node subscriptions use the same `createSubscription`, `activate`, and `cancel`
+API as the browser client; see the [client-web reference](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/client-web/REFERENCE.md)
+for lifecycle and recovery limits. Close the client during process shutdown so
+its owned HTTP/2 session and subscriptions can finish cleanup.
+
 ## 🔗 Learn more
 
-- [Browser client](../client-web/README.md)
-- [Server](../server/README.md)
+- [Browser client](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/client-web/README.md)
+- [Server](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/server/README.md)
 - [Detailed coding-agent reference](REFERENCE.md)

package/REFERENCE.md

@@ -5,18 +5,28 @@ Start with the [Node client overview](README.md) for the shortest connection pat
 
 ## Client construction
 
-`Client.connectTo(baseUrl, options)` creates a shared `client-web` `Client` with a Node Connect HTTP/2 session. `client.close()` closes subscriptions and then aborts that session. `Client.usingTransport(transport, options)` uses a Connect transport supplied by the caller; closing the returned client does not close the supplied transport. Both factories use Node `randomUUID()` for command request identifiers.
+`Client.connectTo(baseUrl, options)` creates a shared `client-web` `Client` with a Node Connect HTTP/2 session. `client.close()` closes subscriptions and then aborts that session. `Client.usingTransport(transport, options)` uses a Connect transport supplied by the caller; closing the returned client does not close the supplied transport. Each `post()` creates its Command through the shared core signal-envelope helper, which assigns a fresh secure UUID-based Command ID.
 
 The returned kernel supports `asGuest()` and `onBehalfOf(user)` request scopes. A scope has `post(schema, value, options)`, `send(query, options)`, and `createSubscription(topic, options)`. See the [client-web reference](../client-web/REFERENCE.md) for command outcomes, cancellation, subscription lifecycle, recovery, and terminal behavior shared by both clients.
 
 ## Entity query API
 
-`EntityColumn.register(schema, definition)` validates and binds generated columns to one Entity schema. The generated `EntityColumnDefinition` comes from the package's `./codegen` entry point. `EntityQuery.select({ schema, columns, context })` starts a builder. It supports `where`, `orderBy`, `limit`, and `build`, plus static predicates `eq`, `gt`, `lt`, `ge`, `le`, `all`, and `either`.
+Normal model generation emits a `_query.ts` companion for each eligible Entity
+state. Import its named query, for example `TaskListQuery`, then call
+`TaskListQuery.create().openTaskCount().isAtLeast(1).build()`. The import
+registers its declared columns automatically. The built query contains no actor
+or tenant; `request.send(query)` binds both at execution.
+
+`EntityColumn.register(schema, definition)` and `EntityQuery.select(...)` remain
+available for existing low-level callers. Their schema-and-columns setup is not
+required when using a generated query.
 
 Predicates accept only columns registered for the selected Entity. `limit()` requires at least one order clause. The compiler packs declared values and the `version`, `archived`, and `deleted` system columns into the wire query. Builders and columns are immutable, so a predicate cannot be reused for a different Entity target.
 
 ## Code generation
 
-Use `protoc-gen-spine-entity-columns` or the `@spine-event-engine/client-node/codegen` entry point only from a model-generation workflow. Generated code uses `GeneratedEntityColumns`; application code should import the generated definition, register it, and construct queries through the public API above.
+Run the model package's normal `spine-proto generate` command. It emits the
+query companion and column registration together; application code imports the
+named query without a second generation command or manual registration.
 
 This package is Node-only because it imports Node HTTP/2 and code-generation dependencies. Browser applications use `@spine-event-engine/client-web`.

package/dist/client/node-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"node-client.d.ts","sourceRoot":"","sources":["../../src/client/node-client.ts"],"names":[],"mappings":"AAgBA,OAAO,EACL,MAAM,IAAI,SAAS,EACnB,KAAK,aAAa,EAEnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC;IAG5B;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAE/D;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC1E,CAsBC,CAAC"}
+{"version":3,"file":"node-client.d.ts","sourceRoot":"","sources":["../../src/client/node-client.ts"],"names":[],"mappings":"AAeA,OAAO,EACL,MAAM,IAAI,SAAS,EACnB,KAAK,aAAa,EAEnB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,QAAQ,CAAC;IAG5B;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAE/D;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAC1E,CAsBC,CAAC"}

package/dist/client/node-client.js

@@ -12,7 +12,6 @@
  * the License.
  */
 import { Http2SessionManager, createGrpcTransport } from "@connectrpc/connect-node";
-import { randomUUID } from "node:crypto";
 import { Client as WebClient, } from "@spine-event-engine/client-web";
 /**
  * Creates Node transport-backed instances of the shared browser-safe client kernel.
@@ -45,12 +44,10 @@ const NodeClientTransport = Object.freeze({
      *
      * @param transport Connect transport used for client operations.
      * @param onClose Optional cleanup for a transport owned by this package.
-     * @returns Shared transport contract with a UUID request-ID source.
+     * @returns Shared transport contract.
      */
     create(transport, onClose) {
-        return onClose === undefined
-            ? { transport, createRequestId: randomUUID }
-            : { transport, createRequestId: randomUUID, close: onClose };
+        return onClose === undefined ? { transport } : { transport, close: onClose };
     },
 });
 //# sourceMappingURL=node-client.js.map

package/dist/client/node-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"node-client.js","sourceRoot":"","sources":["../../src/client/node-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpF,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EACL,MAAM,IAAI,SAAS,GAGpB,MAAM,gCAAgC,CAAC;AAGxC;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAoBd,MAAM,CAAC,MAAM,CAAC;IACjB,kBAAkB;IAElB;;OAEG;IACH,SAAS,CAAC,OAAe,EAAE,UAAyB,EAAE;QACpD,MAAM,QAAQ,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAClD,OAAO,SAAS,CAAC,cAAc,CAC7B,mBAAmB,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE;YAC1F,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC,CAAC,EACF,OAAO,CACR,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,SAAoB,EAAE,UAAyB,EAAE;QAC9D,OAAO,SAAS,CAAC,cAAc,CAAC,mBAAmB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;IAClF,CAAC;CACF,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IACxC,kBAAkB;IAElB;;;;;;OAMG;IACH,MAAM,CAAC,SAAoB,EAAE,OAAoB;QAC/C,OAAO,OAAO,KAAK,SAAS;YAC1B,CAAC,CAAC,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE;YAC5C,CAAC,CAAC,EAAE,SAAS,EAAE,eAAe,EAAE,UAAU,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IACjE,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"node-client.js","sourceRoot":"","sources":["../../src/client/node-client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AACpF,OAAO,EACL,MAAM,IAAI,SAAS,GAGpB,MAAM,gCAAgC,CAAC;AAGxC;;GAEG;AACH,MAAM,CAAC,MAAM,MAAM,GAoBd,MAAM,CAAC,MAAM,CAAC;IACjB,kBAAkB;IAElB;;OAEG;IACH,SAAS,CAAC,OAAe,EAAE,UAAyB,EAAE;QACpD,MAAM,QAAQ,GAAG,IAAI,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAClD,OAAO,SAAS,CAAC,cAAc,CAC7B,mBAAmB,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE;YAC1F,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,CAAC,CAAC,EACF,OAAO,CACR,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,cAAc,CAAC,SAAoB,EAAE,UAAyB,EAAE;QAC9D,OAAO,SAAS,CAAC,cAAc,CAAC,mBAAmB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC;IAClF,CAAC;CACF,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,CAAC;IACxC,kBAAkB;IAElB;;;;;;OAMG;IACH,MAAM,CAAC,SAAoB,EAAE,OAAoB;QAC/C,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;IAC/E,CAAC;CACF,CAAC,CAAC"}

package/dist/codegen/index.d.ts

@@ -1,6 +1,7 @@
+import { GeneratedEntityColumns as CoreGeneratedEntityColumns } from "@spine-event-engine/core/codegen";
 /**
  * Generated-code-only helpers for descriptor-backed Entity metadata.
  */
-export { GeneratedEntityColumns } from "../entity/entity-column.js";
+export declare const GeneratedEntityColumns: typeof CoreGeneratedEntityColumns;
 export type { EntityColumnDefinition, EntityColumnDefinitionEntry, } from "../entity/entity-column.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/codegen/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,YAAY,EACV,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,sBAAsB,IAAI,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAExG;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,OAAO,0BAAuD,CAAC;AACpG,YAAY,EACV,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC"}

package/dist/codegen/index.js

@@ -11,8 +11,9 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
+import { GeneratedEntityColumns as CoreGeneratedEntityColumns } from "@spine-event-engine/core/codegen";
 /**
  * Generated-code-only helpers for descriptor-backed Entity metadata.
  */
-export { GeneratedEntityColumns } from "../entity/entity-column.js";
+export const GeneratedEntityColumns = CoreGeneratedEntityColumns;
 //# sourceMappingURL=index.js.map

package/dist/codegen/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/codegen/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,sBAAsB,IAAI,0BAA0B,EAAE,MAAM,kCAAkC,CAAC;AAExG;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAsC,0BAA0B,CAAC"}

package/dist/entity/entity-column.d.ts

@@ -1,158 +1,67 @@
-import { type DescField, type Message, type MessageShape } from "@bufbuild/protobuf";
+import type { Message } from "@bufbuild/protobuf";
 import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
-import { type Version } from "@spine-event-engine/proto";
+import { EntityColumn as CoreEntityColumn, type EntityColumn as CoreEntityColumnType, type EntityColumnDefinition as CoreEntityColumnDefinition, type EntityColumnDefinitionEntry as CoreColumnDefinitionEntry, type EntityColumnOperator as CoreEntityColumnOperator, type EntityColumnValue as CoreEntityColumnValue, type EntityColumnValueKind as CoreColumnValueKind, type EntityColumns as CoreEntityColumns, type EntityComparison as CoreEntityComparison, type EntityEqualityOperator as CoreEntityEqualityOperator, type EntityOrderingOperator as CoreEntityOrderingOperator } from "@spine-event-engine/core";
+import { GeneratedEntityColumns } from "@spine-event-engine/core/codegen";
 /**
  * Operators available for every Entity column.
  */
-export type EntityEqualityOperator = "equal";
+export type EntityEqualityOperator = CoreEntityEqualityOperator;
 /**
  * Operators available for naturally ordered Entity column values.
  */
-export type EntityOrderingOperator = EntityEqualityOperator | "greaterThan" | "lessThan" | "greaterOrEqual" | "lessOrEqual";
+export type EntityOrderingOperator = CoreEntityOrderingOperator;
 /**
  * Comparison family derived from a column's Protobuf field descriptor.
  */
-export type EntityComparison = "equality" | "ordering";
+export type EntityComparison = CoreEntityComparison;
 /**
  * Runtime value category derived from a column's Protobuf field descriptor.
  */
-export type EntityColumnValueKind = "bigint" | "boolean" | "bytes" | "enum" | "message" | "number" | "string";
+export type EntityColumnValueKind = CoreColumnValueKind;
 /**
  * Represents one generated column declaration paired with its descriptor.
+ *
+ * @typeParam Comparison Comparison family supported by the column.
  */
-export interface EntityColumnDefinitionEntry<Comparison extends EntityComparison = EntityComparison> {
-    /**
-     * Identifies the generated Protobuf field declared as a column.
-     */
-    readonly field: DescField;
-    /**
-     * Identifies the comparison family supported by the field.
-     */
-    readonly comparison: Comparison;
-}
-type StateFieldName<Schema extends GenMessage<Message>> = Exclude<keyof MessageShape<Schema>, "$typeName" | "$unknown"> & string;
-type CollectionFieldName<Schema extends GenMessage<Message>> = {
-    [Name in StateFieldName<Schema>]: NonNullable<MessageShape<Schema>[Name]> extends readonly unknown[] ? Name : NonNullable<MessageShape<Schema>[Name]> extends object ? string extends keyof NonNullable<MessageShape<Schema>[Name]> ? Name : never : never;
-}[StateFieldName<Schema>];
-type SupportedStateFieldName<Schema extends GenMessage<Message>> = Exclude<StateFieldName<Schema> & keyof Schema["field"], CollectionFieldName<Schema>>;
-type EntityColumnEntries = Readonly<Record<string, EntityColumnDefinitionEntry>>;
-type SupportedEntryConstraint<Schema extends GenMessage<Message>, Entries extends EntityColumnEntries> = Exclude<keyof Entries, SupportedStateFieldName<Schema>> extends never ? unknown : never;
-/**
- * Brands generated column definitions for nominal type safety.
- */
-declare const generatedDefinitionBrand: unique symbol;
+export type EntityColumnDefinitionEntry<Comparison extends EntityComparison = EntityComparison> = CoreColumnDefinitionEntry<Comparison>;
 /**
  * Describes descriptor-backed column metadata emitted next to an Entity schema.
  *
- * The package root exports this type, but not its value constructor. Application
- * code therefore consumes generated metadata instead of authoring string keys.
- */
-export interface EntityColumnDefinition<Schema extends GenMessage<Message>, Entries extends EntityColumnEntries> {
-    /**
-     * Brands metadata with its owning schema and generated entries.
-     */
-    readonly [generatedDefinitionBrand]: readonly [Schema, Entries];
-    /**
-     * Stores exact generated entries, validated again during registration.
-     * @internal
-     */
-    readonly entries: Entries;
-}
-/**
- * Creates immutable Entity-column metadata emitted by the companion generator.
+ * @typeParam Schema Generated Protobuf schema that owns the columns.
+ * @typeParam Entries Generated column entries for the schema.
  */
-export declare const GeneratedEntityColumns: Readonly<{
-    /**
-     * Creates immutable metadata for one generated Entity schema.
-     *
-     * @param schema Generated Protobuf schema that owns the declared fields.
-     * @param entries Generated field descriptors and their comparison families.
-     * @returns Metadata accepted by {@link EntityColumn.register}.
-     */
-    define<Schema extends GenMessage<Message>, const Entries extends EntityColumnEntries>(schema: Schema, entries: Entries & SupportedEntryConstraint<NoInfer<Schema>, Entries>): EntityColumnDefinition<Schema, Entries>;
-}>;
-type OperatorsFor<Entry> = Entry extends EntityColumnDefinitionEntry<"ordering"> ? EntityOrderingOperator : EntityEqualityOperator;
+export type EntityColumnDefinition<Schema extends GenMessage<Message>, Entries extends Readonly<Record<string, EntityColumnDefinitionEntry>>> = CoreEntityColumnDefinition<Schema, Entries>;
 /**
  * Represents the typed column collection returned for one generated Entity definition.
+ *
+ * @typeParam Schema Generated Protobuf schema that owns the columns.
+ * @typeParam Entries Generated column entries for the schema.
  */
-export type EntityColumns<Schema extends GenMessage<Message>, Entries extends EntityColumnEntries> = Readonly<{
-    [Name in keyof Entries & StateFieldName<Schema>]: EntityColumn<Schema, Name, MessageShape<Schema>[Name], OperatorsFor<Entries[Name]>>;
-} & {
-    /**
-     * Identifies the Entity version system column.
-     */
-    readonly version: EntityColumn<Schema, "version", Version>;
-    /**
-     * Identifies the Entity archived system column.
-     */
-    readonly archived: EntityColumn<Schema, "archived", boolean, EntityEqualityOperator>;
-    /**
-     * Identifies the Entity deleted system column.
-     */
-    readonly deleted: EntityColumn<Schema, "deleted", boolean, EntityEqualityOperator>;
-}>;
+export type EntityColumns<Schema extends GenMessage<Message>, Entries extends Readonly<Record<string, EntityColumnDefinitionEntry>>> = CoreEntityColumns<Schema, Entries>;
 /**
  * Extracts the value type carried by an Entity column.
+ *
+ * @typeParam Column Entity column whose value type is extracted.
  */
-export type EntityColumnValue<Column extends EntityColumn> = Column extends EntityColumn<GenMessage<Message>, string, infer Value> ? Value : never;
+export type EntityColumnValue<Column extends EntityColumn> = CoreEntityColumnValue<Column>;
 /**
  * Extracts the legal operator union carried by an Entity column.
+ *
+ * @typeParam Column Entity column whose operator type is extracted.
  */
-export type EntityColumnOperator<Column extends EntityColumn> = Column extends EntityColumn<GenMessage<Message>, string, unknown, infer Operator> ? Operator : never;
+export type EntityColumnOperator<Column extends EntityColumn> = CoreEntityColumnOperator<Column>;
 /**
- * An immutable, nominal, descriptor-backed Entity column.
+ * Represents an immutable, nominal, descriptor-backed Entity column.
  *
- * Instances can only be obtained by registering generated metadata for a
- * Entity schema. This prevents consumers from constructing arbitrary
- * string columns that have no corresponding Protobuf declaration.
+ * @typeParam Schema Generated Protobuf schema that owns the column.
+ * @typeParam Name Protobuf-ES property name for the column.
+ * @typeParam Value Value stored in the column.
+ * @typeParam Operator Operators accepted by the column.
+ */
+export type EntityColumn<Schema extends GenMessage<Message> = GenMessage<Message>, Name extends string = string, Value = unknown, Operator extends EntityOrderingOperator = EntityOrderingOperator> = CoreEntityColumnType<Schema, Name, Value, Operator>;
+/**
+ * Exposes the canonical Entity-column constructor through this compatibility package.
  */
-export declare class EntityColumn<Schema extends GenMessage<Message> = GenMessage<Message>, Name extends string = string, Value = unknown, Operator extends EntityOrderingOperator = EntityOrderingOperator> {
-    private readonly entityColumnBrand;
-    /**
-     * Generated Protobuf schema that owns this column.
-     */
-    readonly schema: Schema;
-    /**
-     * Protobuf field name, or the canonical system-column name.
-     */
-    readonly name: string;
-    /**
-     * Protobuf-ES property name, or the canonical system-column name.
-     */
-    readonly localName: Name;
-    /**
-     * Whether the column came from the state descriptor or Entity storage metadata.
-     */
-    readonly source: "declared" | "system";
-    /**
-     * Exact declared field descriptor; system columns have no state field.
-     */
-    readonly descriptor: DescField | undefined;
-    /**
-     * Runtime value category derived from the descriptor.
-     */
-    readonly valueKind: EntityColumnValueKind;
-    /**
-     * Fully qualified message type for message-valued columns.
-     */
-    readonly messageType: string | undefined;
-    /**
-     * Supported comparison family.
-     */
-    readonly comparison: EntityComparison;
-    /**
-     * Exact operator set accepted for this column.
-     */
-    readonly operators: readonly Operator[];
-    private constructor();
-    /**
-     * Registers generated Entity-column metadata for a schema.
-     *
-     * @param schema Generated Entity schema that owns the metadata.
-     * @param definition Immutable generated field metadata.
-     * @returns Stable immutable columns for the Entity schema.
-     */
-    static register<Schema extends GenMessage<Message>, const Entries extends EntityColumnEntries>(schema: Schema, definition: EntityColumnDefinition<Schema, Entries>): EntityColumns<Schema, Entries>;
-}
-export {};
+export declare const EntityColumn: typeof CoreEntityColumn;
+export { GeneratedEntityColumns };
 //# sourceMappingURL=entity-column.d.ts.map

package/dist/entity/entity-column.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-column.d.ts","sourceRoot":"","sources":["../../src/entity/entity-column.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"entity-column.d.ts","sourceRoot":"","sources":["../../src/entity/entity-column.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EACL,YAAY,IAAI,gBAAgB,EAChC,KAAK,YAAY,IAAI,oBAAoB,EACzC,KAAK,sBAAsB,IAAI,0BAA0B,EACzD,KAAK,2BAA2B,IAAI,yBAAyB,EAC7D,KAAK,oBAAoB,IAAI,wBAAwB,EACrD,KAAK,iBAAiB,IAAI,qBAAqB,EAC/C,KAAK,qBAAqB,IAAI,mBAAmB,EACjD,KAAK,aAAa,IAAI,iBAAiB,EACvC,KAAK,gBAAgB,IAAI,oBAAoB,EAC7C,KAAK,sBAAsB,IAAI,0BAA0B,EACzD,KAAK,sBAAsB,IAAI,0BAA0B,EAC1D,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,0BAA0B,CAAC;AAEhE;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,oBAAoB,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,CAAC;AAExD;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,CAAC,UAAU,SAAS,gBAAgB,GAAG,gBAAgB,IAC5F,yBAAyB,CAAC,UAAU,CAAC,CAAC;AAExC;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,CAChC,MAAM,SAAS,UAAU,CAAC,OAAO,CAAC,EAClC,OAAO,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC,IACnE,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,CACvB,MAAM,SAAS,UAAU,CAAC,OAAO,CAAC,EAClC,OAAO,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC,IACnE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvC;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,MAAM,SAAS,YAAY,IAAI,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAE3F;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,CAAC,MAAM,SAAS,YAAY,IAAI,wBAAwB,CAAC,MAAM,CAAC,CAAC;AAEjG;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,CACtB,MAAM,SAAS,UAAU,CAAC,OAAO,CAAC,GAAG,UAAU,CAAC,OAAO,CAAC,EACxD,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,KAAK,GAAG,OAAO,EACf,QAAQ,SAAS,sBAAsB,GAAG,sBAAsB,IAC9D,oBAAoB,CAAC,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,CAAC;AAExD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,OAAO,gBAAmC,CAAC;AAEtE,OAAO,EAAE,sBAAsB,EAAE,CAAC"}