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

package/README.md

@@ -5,13 +5,37 @@ Spine TS application. Use it when application code needs to validate a message,
 pack it into `google.protobuf.Any`, create a command or event envelope, or look
 up a generated message schema by its Spine type URL.
 
+This is an experimental snapshot package. Use Node 24 or newer and generated
+Spine message schemas.
+
+## Install and validate one message
+
+Install the package with the generated model schemas your application uses:
+
+```sh
+pnpm add @spine-event-engine/core@snapshot @spine-event-engine/proto@snapshot @bufbuild/protobuf
+```
+
+Then validate and pack one generated message before adding routing or server assembly:
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { AnyMessages, Validate } from "@spine-event-engine/core";
+import { UserIdSchema } from "@spine-event-engine/proto";
+
+const userId = create(UserIdSchema, { value: "ava" });
+Validate.check(UserIdSchema, userId);
+const packed = AnyMessages.pack(UserIdSchema, userId);
+console.log(AnyMessages.unpack(packed, UserIdSchema)?.value);
+```
+
 ## Message-interface tokens
 
 A generated interface export has one name in two TypeScript namespaces: use it
 as a type for message shape and as a value token in a repository `.route(...)`
 call. The To-Do `TaskEvent` token groups task events; its authored
 `TaskAssignmentEvent` counterpart groups assignment events. Start with the
-[To-Do walkthrough](../../examples/todo/USER_GUIDE.md) for the complete path.
+[To-Do walkthrough](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/todo/USER_GUIDE.md) for the complete path.
 
 For the detailed contract and integration notes, see
 [REFERENCE documentation for agents](REFERENCE.md).
@@ -30,9 +54,8 @@ pnpm typecheck:build
 ```
 
 Run this workspace-wide TypeScript build from the repository root. For an
-experimental npm consumer, install
-`@spine-event-engine/core@2.0.0-snapshot.2` or the explicit
-`@spine-event-engine/core@snapshot` tag.
+experimental npm consumer, install `@spine-event-engine/core@snapshot`.
+The snapshot tag can change before a stable release.
 
 ## ✅ Validate a message
 
@@ -115,6 +138,35 @@ that generated `BoardId`. An application can register another reversible
 mapping in `StringifierRegistry`. If compact Proto JSON encounters an `Any`,
 also call `setTypeRegistry()` with the application's generated `TypeRegistry`.
 
+## Query Projection state
+
+Normal `spine-proto generate` emits a `_query.ts` companion for eligible Aggregate, Projection,
+and Process Manager states. For example, Todo can import its generated `TaskListQuery` and build
+a context-free query:
+
+<!-- docs-snippet-path: examples/todo/src/index.ts -->
+
+```ts
+import { TaskListQuery } from "../generated/spine/examples/todo/task_list_query.js";
+
+// Find nonempty lists, starting with the most open tasks.
+const query = TaskListQuery.create()
+  .openTaskCount()
+  .isAtLeast(1)
+  .orderBy("openTaskCount", "desc")
+  .limit(10)
+  .build();
+```
+
+The companion registers its descriptor-backed columns when imported. Successive comparisons use
+AND; `either(...)` accepts synchronous condition-only callbacks for OR branches. Apply IDs,
+ordering, limits, and `build()` to the outer query. `byId(...)` uses the first state field.
+`limit()` requires `orderBy()` and accepts a positive integer.
+Ordered columns also expose `isGreaterThan`, `isAtLeast`, `isLessThan`, and `isAtMost`.
+Every build captures a detached value;
+the client or Process Manager supplies actor and tenant context when it executes the query.
+`EntityQuery` remains available for callers using the existing schema-and-columns builder.
+
 ## 🚫 Throw a generated domain rejection
 
 The model generator creates typed rejection factories for top-level messages in
@@ -122,8 +174,9 @@ an application's `*rejections.proto` files. Application code imports that
 generated companion and throws its factory result. This example is from a
 source file in the Todo model package's `src` directory.
 
+<!-- docs-snippet-path: examples/todo/src/index.ts -->
+
 ```ts
-// docs-snippet-path: examples/todo/src/index.ts
 import { create } from "@bufbuild/protobuf";
 import { TaskIdSchema } from "../generated/spine/examples/todo/task_id_pb.js";
 import { TaskAlreadyDone } from "../generated/spine/examples/todo/task_rejections.js";
@@ -145,7 +198,7 @@ by hand.
 
 ## 🔗 Learn more
 
-- [Protobuf package](../proto/README.md)
-- [Model-generation tools](../proto-tools/README.md)
-- [Server](../server/README.md)
+- [Protobuf package](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/proto/README.md)
+- [Model-generation tools](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/proto-tools/README.md)
+- [Server](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/server/README.md)
 - [Reference for coding agents](REFERENCE.md)

package/REFERENCE.md

@@ -18,6 +18,30 @@ Import from `@spine-event-engine/core`. The package exports `Validate`,
 `StringifierRegistry`, the `Stringifier` contract, and their exported input,
 result, and metadata types.
 
+Descriptor-backed `EntityColumn` and `EntityQuery` behavior is canonical in
+core. The generated `GeneratedEntityColumns` helper is intentionally excluded
+from the root: generated model code imports it from
+`@spine-event-engine/core/codegen`. `@spine-event-engine/client-node` retains
+its compatibility exports and its `/codegen` forwarding entry point.
+
+Normal Proto generation emits `_query.ts` companions for eligible Entity states, including nested
+states. Their exported `StateQuery.create()` methods expose marked columns and the `version`,
+`archived`, and `deleted` system columns. `build()` returns an independent query description with
+no actor or tenant context; it can be reused by a Process Manager, browser client, or subscription.
+Successive comparisons form a conjunction, and `either(...)` combines synchronous condition-only
+callback branches as a disjunction. Apply IDs, ordering, limits, and build to the outer query.
+Generated field methods that conflict with `build`, `either`, `byId`, `orderBy`,
+`limit`, `create`, `constructor`, or JavaScript object methods receive a `Column` suffix; a
+numeric suffix resolves a further collision. Nested query exports join message names with `_`.
+The first declared state field supplies the ID type even when its name is not `id`.
+
+## Subscription lifecycle SPI
+
+Framework integrations that coordinate subscription activation import
+`SUBSCRIPTION_ACTIVATION_HANDSHAKE_MS` from
+`@spine-event-engine/core/spi/subscription-lifecycle`. This is not an
+application subscription API and is not exported from the core root.
+
 ## Storage value helpers
 
 `Identifiers` packs and unpacks the generated-message and supported primitive
@@ -62,9 +86,13 @@ non-empty and whitespace-free. `AnyMessages.pack()` validates unless
 Spine-aware `Any`. `unpack()` and `unpackUsing()` return `undefined` for an
 unknown/mismatched URL or malformed bytes.
 
-`SignalEnvelopes.command()` and `.event()` clone caller-supplied IDs and
-contexts and pack the supplied domain message. They do not create IDs,
-timestamps, actor context, tenant context, storage records, or routing data.
+`SignalEnvelopes.command()` and `.event()` generate fresh secure UUID v4 IDs,
+clone caller-supplied contexts, and pack the supplied domain message. They use
+`crypto.randomUUID()` when available, otherwise secure `crypto.getRandomValues()`;
+they fail when neither secure API exists. They do not create timestamps, actor
+context, tenant context, storage records, or routing data. Existing envelope
+transport and storage continue to retain their supplied IDs without validating
+that those existing values have UUID format.
 
 ## Registry
 

package/dist/codegen/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generated-code-only Entity column declaration helpers.
+ */
+export { GeneratedEntityColumns } from "../entity/entity-column.js";
+export { GeneratedEntityQueries } from "../query/generated-entity-query.js";
+export { EntityQueryDescription } from "../query/entity-query.js";
+export type { EntityQueryDraft } from "../query/entity-query.js";
+export type { GeneratedQueryBuilder } from "../query/generated-entity-query.js";
+export type { EntityColumnDefinition, EntityColumnDefinitionEntry, } from "../entity/entity-column.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +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,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAClE,YAAY,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,YAAY,EAAE,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChF,YAAY,EACV,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC"}

package/dist/codegen/index.js

@@ -0,0 +1,20 @@
+/*
+ * 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.
+ */
+/**
+ * Generated-code-only Entity column declaration helpers.
+ */
+export { GeneratedEntityColumns } from "../entity/entity-column.js";
+export { GeneratedEntityQueries } from "../query/generated-entity-query.js";
+export { EntityQueryDescription } from "../query/entity-query.js";
+//# sourceMappingURL=index.js.map

package/dist/codegen/index.js.map

@@ -0,0 +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;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC"}

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

@@ -0,0 +1,158 @@
+import { type DescField, type Message, type MessageShape } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { type Version } from "@spine-event-engine/proto";
+/**
+ * Operators available for every Entity column.
+ */
+export type EntityEqualityOperator = "equal";
+/**
+ * Operators available for naturally ordered Entity column values.
+ */
+export type EntityOrderingOperator = EntityEqualityOperator | "greaterThan" | "lessThan" | "greaterOrEqual" | "lessOrEqual";
+/**
+ * Comparison family derived from a column's Protobuf field descriptor.
+ */
+export type EntityComparison = "equality" | "ordering";
+/**
+ * Runtime value category derived from a column's Protobuf field descriptor.
+ */
+export type EntityColumnValueKind = "bigint" | "boolean" | "bytes" | "enum" | "message" | "number" | "string";
+/**
+ * Represents one generated column declaration paired with its descriptor.
+ */
+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;
+/**
+ * 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.
+ */
+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;
+/**
+ * Represents the typed column collection returned for one generated Entity definition.
+ */
+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>;
+}>;
+/**
+ * Extracts the value type carried by an Entity column.
+ */
+export type EntityColumnValue<Column extends EntityColumn> = Column extends EntityColumn<GenMessage<Message>, string, infer Value> ? Value : never;
+/**
+ * Extracts the legal operator union carried by an Entity column.
+ */
+export type EntityColumnOperator<Column extends EntityColumn> = Column extends EntityColumn<GenMessage<Message>, string, unknown, infer Operator> ? Operator : never;
+/**
+ * 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.
+ */
+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 {};
+//# sourceMappingURL=entity-column.d.ts.map

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

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

package/dist/entity/entity-column.js

@@ -0,0 +1,303 @@
+/*
+ * 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 { getOption, hasOption, } from "@bufbuild/protobuf";
+import { column, entity, EntityOption_Kind } from "@spine-event-engine/proto";
+import { EntityFieldClassification } from "../query/entity-field-classification.js";
+/**
+ * Creates immutable Entity-column metadata emitted by the companion generator.
+ */
+export const GeneratedEntityColumns = Object.freeze({
+    define(schema, entries) {
+        const captured = EntityColumnFacts.captureDefinition(schema, entries);
+        const copiedEntries = Object.fromEntries(Object.entries(entries).map(([name, entry]) => {
+            EntityColumnFacts.deepFreeze(entry.field);
+            return [name, Object.freeze({ field: entry.field, comparison: entry.comparison })];
+        }));
+        const definition = Object.freeze({
+            entries: Object.freeze(copiedEntries),
+        });
+        capturedDefinitions.set(definition, captured);
+        return definition;
+    },
+});
+const equalityOperators = Object.freeze(["equal"]);
+const orderingOperators = Object.freeze([
+    "equal",
+    "greaterThan",
+    "lessThan",
+    "greaterOrEqual",
+    "lessOrEqual",
+]);
+const systemNames = new Set(["version", "archived", "deleted"]);
+const cache = new WeakMap();
+const entityColumnConstructionToken = Symbol("EntityColumnConstructionToken");
+const capturedDefinitions = new WeakMap();
+/**
+ * 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.
+ */
+export class EntityColumn {
+    /**
+     * Generated Protobuf schema that owns this column.
+     */
+    schema;
+    /**
+     * Protobuf field name, or the canonical system-column name.
+     */
+    name;
+    /**
+     * Protobuf-ES property name, or the canonical system-column name.
+     */
+    localName;
+    /**
+     * Whether the column came from the state descriptor or Entity storage metadata.
+     */
+    source;
+    /**
+     * Exact declared field descriptor; system columns have no state field.
+     */
+    descriptor;
+    /**
+     * Runtime value category derived from the descriptor.
+     */
+    valueKind;
+    /**
+     * Fully qualified message type for message-valued columns.
+     */
+    messageType;
+    /**
+     * Supported comparison family.
+     */
+    comparison;
+    /**
+     * Exact operator set accepted for this column.
+     */
+    operators;
+    constructor(input, token) {
+        if (token !== entityColumnConstructionToken) {
+            throw new TypeError("Entity columns can only be constructed during registration.");
+        }
+        this.schema = input.schema;
+        this.name = input.name;
+        this.localName = input.localName;
+        this.source = input.source;
+        this.descriptor = input.descriptor;
+        this.valueKind = input.valueKind;
+        this.messageType = input.messageType;
+        this.comparison = input.comparison;
+        this.operators = input.operators;
+        Object.freeze(this);
+    }
+    /**
+     * 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, definition) {
+        const existing = cache.get(schema);
+        if (existing?.definitions.has(definition) === true) {
+            return existing.columns;
+        }
+        const captured = capturedDefinitions.get(definition);
+        EntityColumnFacts.validateSchema(schema, captured);
+        const declared = EntityColumnFacts.validateDefinition(schema, definition, captured);
+        if (existing !== undefined) {
+            existing.definitions.add(definition);
+            return existing.columns;
+        }
+        const result = {};
+        for (const [localName, field, fieldName, metadata] of declared) {
+            result[localName] = new EntityColumn({
+                schema,
+                name: fieldName,
+                localName,
+                source: "declared",
+                descriptor: field,
+                valueKind: metadata.valueKind,
+                messageType: metadata.messageType,
+                comparison: metadata.comparison,
+                operators: EntityColumnFacts.operatorsFor(metadata.comparison),
+            }, entityColumnConstructionToken);
+        }
+        result.version = new EntityColumn({
+            schema,
+            name: "version",
+            localName: "version",
+            source: "system",
+            valueKind: "message",
+            messageType: "spine.core.Version",
+            comparison: "ordering",
+            operators: orderingOperators,
+        }, entityColumnConstructionToken);
+        for (const name of ["archived", "deleted"]) {
+            result[name] = new EntityColumn({
+                schema,
+                name,
+                localName: name,
+                source: "system",
+                valueKind: "boolean",
+                comparison: "equality",
+                operators: equalityOperators,
+            }, entityColumnConstructionToken);
+        }
+        const columns = Object.freeze(result);
+        cache.set(schema, {
+            definitions: new WeakSet([definition]),
+            columns,
+        });
+        return columns;
+    }
+}
+/**
+ * Internal descriptor facts used while generated column metadata is registered.
+ */
+const EntityColumnFacts = Object.freeze({
+    // prettier-ignore
+    /**
+     * Validates that a schema declares one supported Entity kind.
+     */
+    validateSchema(schema, captured) {
+        const entityKind = captured?.schema === schema
+            ? captured.entityKind
+            : hasOption(schema, entity)
+                ? getOption(schema, entity).kind
+                : undefined;
+        if (entityKind !== EntityOption_Kind.AGGREGATE &&
+            entityKind !== EntityOption_Kind.PROJECTION &&
+            entityKind !== EntityOption_Kind.PROCESS_MANAGER) {
+            throw new TypeError(`Entity column schema "${schema.typeName}" must declare Entity kind.`);
+        }
+    },
+    /**
+     * Validates and describes every declared generated column.
+     */
+    validateDefinition(schema, definition, captured) {
+        const facts = captured?.schema === schema
+            ? captured
+            : EntityColumnFacts.captureDefinition(schema, definition.entries);
+        const annotated = new Map(facts.annotated);
+        const result = [];
+        for (const [localName, entry] of Object.entries(definition.entries)) {
+            if (systemNames.has(localName)) {
+                throw new TypeError(`Entity column definition cannot replace system column "${localName}".`);
+            }
+            if (entry === undefined)
+                continue;
+            const fieldFacts = facts.entries.get(localName) ?? EntityColumnFacts.captureField(entry.field);
+            if (fieldFacts.parent !== schema || fieldFacts.localName !== localName) {
+                throw new TypeError(`Entity column definition key "${localName}" must reference field "${localName}".`);
+            }
+            if (!fieldFacts.markedColumn) {
+                throw new TypeError(`Entity field "${localName}" is not marked (column).`);
+            }
+            const metadata = EntityColumnFacts.describeField(fieldFacts);
+            if (entry.comparison !== metadata.comparison) {
+                throw new TypeError(`Entity column "${localName}" requires ${metadata.comparison} comparison metadata.`);
+            }
+            annotated.delete(localName);
+            result.push([localName, fieldFacts.field, fieldFacts.name, metadata]);
+        }
+        const missing = annotated.keys().next().value;
+        if (missing !== undefined) {
+            throw new TypeError(`Entity column definition is missing annotated field "${missing}".`);
+        }
+        return result;
+    },
+    /**
+     * Derives runtime metadata from one validated descriptor.
+     */
+    describeField(field) {
+        const metadata = field.classification;
+        if (!metadata.supported && metadata.reason === "singular") {
+            throw new TypeError(`Entity column "${field.localName}" must be singular; repeated and map fields are unsupported.`);
+        }
+        if (!metadata.supported) {
+            throw new TypeError(`Entity column "${field.localName}" cannot belong to a oneof.`);
+        }
+        return metadata;
+    },
+    /**
+     * Captures immutable facts from one generated definition.
+     */
+    captureDefinition(schema, entries) {
+        const annotated = new Map(schema.fields
+            .filter((field) => hasOption(field, column) && getOption(field, column))
+            .map((field) => [field.localName, field]));
+        const capturedEntries = new Map();
+        for (const [localName, entry] of Object.entries(entries)) {
+            capturedEntries.set(localName, EntityColumnFacts.captureField(entry.field));
+        }
+        return Object.freeze({
+            schema,
+            entityKind: hasOption(schema, entity) ? getOption(schema, entity).kind : undefined,
+            annotated,
+            entries: capturedEntries,
+        });
+    },
+    /**
+     * Captures immutable facts from one generated field descriptor.
+     */
+    captureField(field) {
+        return Object.freeze({
+            field,
+            parent: field.parent,
+            localName: field.localName,
+            name: field.name,
+            markedColumn: hasOption(field, column) && getOption(field, column),
+            classification: Object.freeze(EntityFieldClassification.classify(field)),
+        });
+    },
+    /**
+     * Deeply freezes a descriptor graph without freezing typed-array views.
+     */
+    deepFreeze(root) {
+        const pending = [root];
+        const visited = new WeakSet();
+        while (pending.length > 0) {
+            const current = pending.pop();
+            if (current === undefined || visited.has(current))
+                continue;
+            visited.add(current);
+            if (ArrayBuffer.isView(current))
+                continue;
+            for (const key of Reflect.ownKeys(current)) {
+                const property = Object.getOwnPropertyDescriptor(current, key);
+                if (property !== undefined &&
+                    "value" in property &&
+                    EntityColumnFacts.isObject(property.value)) {
+                    pending.push(property.value);
+                }
+            }
+            Object.freeze(current);
+        }
+    },
+    /**
+     * Checks whether a value can participate in a descriptor graph.
+     */
+    isObject(value) {
+        return (typeof value === "object" && value !== null) || typeof value === "function";
+    },
+    /**
+     * Returns the supported operator set for a comparison family.
+     */
+    operatorsFor(comparison) {
+        return comparison === "ordering" ? orderingOperators : equalityOperators;
+    },
+});
+//# sourceMappingURL=entity-column.js.map