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

package/dist/entity/entity.js

@@ -11,10 +11,187 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { clone, fromBinary, toBinary } from "@bufbuild/protobuf";
-import { ValidationErrorSchema, } from "@spine-event-engine/proto";
+import { clone, create, fromBinary, toBinary, } from "@bufbuild/protobuf";
+import { EntityQuery, } from "@spine-event-engine/core";
+import { EntityQueryDescription } from "@spine-event-engine/core/codegen";
+import { VersionSchema, ActorContextSchema, ValidationErrorSchema, } from "@spine-event-engine/proto";
 import { describeEntityMetadata, } from "./entity-metadata.js";
 import { EntityTransaction, } from "./entity-transaction.js";
+const processManagerQueries = new WeakMap();
+/**
+ * Keeps Process Manager execution limits at the read boundary.
+ */
+const ProcessManagerQueryLimits = Object.freeze({
+    /**
+     * Rejects plans that exceed Process Manager result or explicit-ID limits.
+     *
+     * @param plan Compiled query plan to execute.
+     */
+    check(plan) {
+        if (plan.limit !== undefined && plan.limit > 1_000) {
+            throw new TypeError("Process Manager query limit may be at most 1000.");
+        }
+        if (plan.predicate !== undefined && this.ids(plan.predicate) > 1_000) {
+            throw new TypeError("Process Manager query ID filter may contain at most 1000 IDs.");
+        }
+    },
+    /**
+     * Returns the number of explicit IDs in a compiled predicate tree.
+     *
+     * @param predicate Compiled filter node.
+     * @returns Number of explicit IDs in that node.
+     */
+    ids(predicate) {
+        if (predicate.kind === "ids")
+            return predicate.ids.length;
+        if (predicate.kind === "comparison")
+            return 0;
+        return predicate.predicates.reduce((total, child) => total + this.ids(child), 0);
+    },
+});
+/**
+ * Binds the repository-scoped query capability for one Process Manager invocation.
+ *
+ * @internal
+ */
+export const processManagerQueryAccess = Object.freeze({
+    /**
+     * Enables read-side queries for the duration of one handler invocation.
+     *
+     * @param entity Process Manager receiving the query capability.
+     * @param execute Repository operation that runs queries.
+     * @param actorContext Actor and tenant of the incoming signal.
+     * @returns A function that disables and removes this capability.
+     */
+    bind(entity, execute, actorContext) {
+        const capability = {
+            execute,
+            actorContext: clone(ActorContextSchema, actorContext),
+            active: true,
+        };
+        processManagerQueries.set(entity, capability);
+        return () => {
+            capability.active = false;
+            processManagerQueries.delete(entity);
+        };
+    },
+    /**
+     * Gets the query capability of a currently executing Process Manager.
+     *
+     * @param entity Process Manager attempting a query.
+     * @returns The active repository query capability.
+     */
+    require(entity) {
+        const capability = processManagerQueries.get(entity);
+        if (capability?.active !== true) {
+            throw new Error("Process Manager queries are available only during repository handler execution.");
+        }
+        return capability;
+    },
+});
+/**
+ * A repository-scoped, read-only Entity query issued by a Process Manager.
+ *
+ * @typeParam Schema State schema read by the query.
+ * @typeParam Columns Registered descriptor-backed columns for `Schema`.
+ */
+export class ProcessManagerQuery {
+    #entity;
+    #schema;
+    #builder;
+    /**
+     * Creates the repository-scoped query facade.
+     *
+     * @internal
+     * @param entity Process Manager using this query capability.
+     * @param schema State schema read by this query.
+     * @param builder Typed query builder used to create the wire query.
+     */
+    constructor(entity, schema, builder) {
+        this.#entity = entity;
+        this.#schema = schema;
+        this.#builder = builder;
+    }
+    /**
+     * Adds the supplied Entity IDs to the query target.
+     *
+     * @param ids Entity IDs to include.
+     * @returns This query for fluent configuration.
+     */
+    byId(...ids) {
+        this.#builder.byId(...ids);
+        return this;
+    }
+    /**
+     * Adds a typed state predicate to the query.
+     *
+     * @typeParam Predicate Comparison supported by the registered columns.
+     * @param predicate Predicate evaluated against registered state columns.
+     * @returns This query for fluent configuration.
+     */
+    where(predicate) {
+        this.#builder.where(predicate);
+        return this;
+    }
+    /**
+     * Sets the ordering for matching states by one registered column.
+     *
+     * @typeParam Column Registered column supplying the ordered values.
+     * @param column Registered orderable column used for sorting.
+     * @param direction Optional sort direction, ascending by default.
+     * @returns This query for fluent configuration.
+     */
+    orderBy(column, direction = "asc") {
+        this.#builder.orderBy(column, direction);
+        return this;
+    }
+    /**
+     * Sets the returned-state limit to at most 1,000 entries.
+     *
+     * @param value Maximum number of states to return.
+     * @returns This query for fluent configuration.
+     */
+    limit(value) {
+        if (value > 1_000) {
+            throw new TypeError("Process Manager query limit may be at most 1000.");
+        }
+        this.#builder.limit(value);
+        return this;
+    }
+    /**
+     * Reads matching state snapshots from the eventually consistent query projection.
+     *
+     * @returns Readonly state snapshots, subject to the configured result limit.
+     */
+    async read() {
+        const capability = processManagerQueryAccess.require(this.#entity);
+        const plan = this.#builder.buildPlan();
+        ProcessManagerQueryLimits.check(plan);
+        const states = await capability.execute(plan, this.#schema, this.#builder.build());
+        return Object.freeze(states.slice(0, 1_000));
+    }
+    /**
+     * Reads the first state snapshot for one Entity ID.
+     *
+     * @param id Entity ID to read.
+     * @returns The eventually consistent state snapshot, or `undefined` when it is absent.
+     */
+    async findById(id) {
+        const states = await this.byId(id).read();
+        return states[0];
+    }
+    /**
+     * Reads every matching state snapshot within the configured result limit.
+     *
+     * This can be more expensive than an ID-targeted read because the projection must evaluate all
+     * matching states.
+     *
+     * @returns Readonly eventually consistent state snapshots.
+     */
+    async all() {
+        return await this.read();
+    }
+}
 const rejectedCommits = new WeakMap();
 /**
  * Error thrown when a transactional entity draft helper is used outside its scope.
@@ -45,15 +222,15 @@ export class TransactionalEntityScopeError extends Error {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
-const isProxy = process.getBuiltinModule("node:util").types.isProxy;
 /**
- * Common in-memory OOP shell for one server-side entity state.
+ * Identity, state, version, and lifecycle of one server-side Entity.
+ *
+ * Keeps the Entity ID, state schema, state, Spine Version, and lifecycle flags.
+ * State and Version accessors return copies, and lifecycle access returns a
+ * separate flag object. Repositories run handlers and manage storage.
  *
- * The shell exposes identity, descriptor-derived metadata, cloned state
- * snapshots, caller-owned plain version metadata snapshots, and lifecycle flags. It does not
- * invoke handlers, create transactions, write repositories or storage, dispatch
- * messages, increment versions, route IDs, query read models, start buses, or
- * mutate process-wide runtime state.
+ * @typeParam Id Domain identifier type.
+ * @typeParam Schema Generated schema describing the Entity state.
  */
 export class Entity {
     #id;
@@ -64,7 +241,7 @@ export class Entity {
     #lifecycle;
     #lifecycleFlagsChanged = false;
     /**
-     * Creates an entity shell from caller-provided state and metadata inputs.
+     * Initializes an Entity from its ID, schema, state, Version, and lifecycle flags.
      *
      * @param options Identity, schema, state, version, and lifecycle inputs.
      */
@@ -73,7 +250,7 @@ export class Entity {
         this.#schema = options.schema;
         this.#metadata = describeEntityMetadata(options.schema);
         this.#state = EntitySnapshots.clone(options.schema, options.state);
-        this.#version = EntityVersions.clone(options.version);
+        this.#version = clone(VersionSchema, options.version ?? create(VersionSchema));
         this.#lifecycle = {
             archived: options.lifecycle?.archived ?? false,
             deleted: options.lifecycle?.deleted ?? false,
@@ -82,7 +259,7 @@ export class Entity {
     /**
      * Gets the stable entity identifier.
      *
-     * @returns The caller-owned entity identifier.
+     * @returns The domain identifier supplied during construction.
      */
     get id() {
         return this.#id;
@@ -112,12 +289,12 @@ export class Entity {
         return EntitySnapshots.clone(this.#schema, this.#state);
     }
     /**
-     * Gets the caller-owned plain version metadata snapshot.
+     * Gets the current Spine Version without exposing the stored message.
      *
-     * @returns A validated clone of the version metadata.
+     * @returns A copy of the version number and timestamp.
      */
     get version() {
-        return EntityVersions.clone(this.#version);
+        return clone(VersionSchema, this.#version);
     }
     /**
      * Gets the current lifecycle flag snapshot.
@@ -163,7 +340,7 @@ export class Entity {
         return this.#lifecycleFlagsChanged;
     }
     /**
-     * Replaces stored state from framework-owned subclass or runtime code.
+     * Replaces stored state when framework transaction code accepts a draft.
      *
      * @param state Next entity state snapshot.
      */
@@ -171,15 +348,15 @@ export class Entity {
         this.#state = EntitySnapshots.clone(this.#schema, state);
     }
     /**
-     * Replaces caller-owned version metadata from framework-owned subclass or runtime code.
+     * Applies the Version calculated by a framework transaction.
      *
-     * @param version Next caller-owned version metadata.
+     * @param version Accepted version number and timestamp.
      */
-    replaceVersionMetadata(version) {
-        this.#version = EntityVersions.clone(version);
+    replaceVersion(version) {
+        this.#version = clone(VersionSchema, version);
     }
     /**
-     * Replaces lifecycle flags from framework-owned subclass or runtime code.
+     * Applies lifecycle flags accepted by framework transaction code.
      *
      * @param lifecycle Lifecycle flag changes to apply.
      */
@@ -229,21 +406,60 @@ const boundEntityHistories = new WeakMap();
  * @internal
  */
 export const entityHistoryAccess = Object.freeze({
+    /**
+     * Associates an Entity instance with its repository history operations.
+     *
+     * @param entity Entity instance loaded by the repository.
+     * @param binding Operations bound to that Entity's history.
+     */
     bind(entity, binding) {
         boundEntityHistories.set(entity, binding);
     },
+    /**
+     * Reads the most recent retained state no later than the requested time.
+     *
+     * @param entity Entity whose state is requested.
+     * @param time Latest allowed state timestamp.
+     * @returns The retained state, or undefined when none matches.
+     */
     stateAt(entity, time) {
         return EntityHistory.require(entity).stateAt(time);
     },
+    /**
+     * Reads retained states after checking the history read limit.
+     *
+     * @param entity Entity whose history is requested.
+     * @param depth Maximum number of states to return.
+     * @returns Retained states in descending version order.
+     */
     states(entity, depth) {
         return EntityHistory.require(entity).states(EntityHistory.depth(depth));
     },
+    /**
+     * Reads diagnostic Events after checking the history read limit.
+     *
+     * @param entity Entity that produced the Events.
+     * @param depth Maximum number of Events to return.
+     * @returns Retained Events in descending producer-version order.
+     */
     events(entity, depth) {
         return EntityHistory.require(entity).events(EntityHistory.depth(depth));
     },
+    /**
+     * Gets the state-history storage attached by the repository.
+     *
+     * @param entity Entity whose retained states are maintained.
+     * @returns Its state-history storage.
+     */
     stateMaintenance(entity) {
         return EntityHistory.require(entity).stateMaintenance;
     },
+    /**
+     * Gets diagnostic Event storage attached by the repository.
+     *
+     * @param entity Entity whose retained Events are maintained.
+     * @returns Its diagnostic Event storage.
+     */
     eventMaintenance(entity) {
         return EntityHistory.require(entity).eventMaintenance;
     },
@@ -252,6 +468,12 @@ export const entityHistoryAccess = Object.freeze({
  * Validates repository-bound history lookups.
  */
 const EntityHistory = Object.freeze({
+    /**
+     * Gets history operations installed during repository execution.
+     *
+     * @param entity Entity instance whose binding is required.
+     * @returns Its repository history operations.
+     */
     require(entity) {
         const binding = boundEntityHistories.get(entity);
         if (binding === undefined) {
@@ -259,6 +481,12 @@ const EntityHistory = Object.freeze({
         }
         return binding;
     },
+    /**
+     * Rejects history read limits that are not positive safe integers.
+     *
+     * @param depth Requested history read limit.
+     * @returns The validated limit.
+     */
     depth(depth) {
         if (!Number.isSafeInteger(depth) || depth <= 0) {
             throw new RangeError("Entity history depth must be a positive safe integer.");
@@ -267,16 +495,15 @@ const EntityHistory = Object.freeze({
     },
 });
 /**
- * Common in-memory entity shell with a protected scoped transaction draft.
+ * Entity base with one active transaction draft.
+ *
+ * Repository dispatch starts and finishes each transaction. Entity handlers
+ * change the draft state or lifecycle through protected helpers. A successful
+ * commit updates state, Spine Version, and lifecycle flags. A rejected commit
+ * leaves the draft active until the framework rolls it back.
  *
- * The transaction scope is backed by {@link EntityTransaction}. Subclasses can
- * start one active draft, mutate draft state/version/lifecycle through protected
- * helpers, and then commit or roll back the scope. Accepted commits replace this
- * entity's in-memory state, explicit version metadata, and lifecycle flags.
- * Rejected commits leave the transaction active so subclass code can correct the
- * draft or roll it back explicitly. This base does not write repositories,
- * emit events, dispatch handlers, increment versions, or manage global
- * transaction state.
+ * @typeParam Id Domain identifier type.
+ * @typeParam Schema Generated schema describing the Entity state.
  */
 export class TransactionalEntity extends Entity {
     #transaction;
@@ -312,7 +539,7 @@ export class TransactionalEntity extends Entity {
             previous: this.state,
             version: {
                 previous: previousVersion,
-                draft: EntityVersions.clone(previousVersion),
+                draft: clone(VersionSchema, previousVersion),
             },
             lifecycle: this.lifecycle,
         });
@@ -326,19 +553,6 @@ export class TransactionalEntity extends Entity {
     currentDraft() {
         return this.#requireTransaction("currentDraft").currentDraft;
     }
-    /**
-     * Gets the current draft version metadata snapshot.
-     *
-     * @returns Cloned previous and draft version metadata.
-     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
-     */
-    draftVersionMetadata() {
-        const version = this.#requireTransaction("draftVersionMetadata").version;
-        return {
-            previous: EntityVersions.clone(version.previous),
-            draft: EntityVersions.clone(version.draft),
-        };
-    }
     /**
      * Gets the current draft lifecycle flag snapshot.
      *
@@ -371,17 +585,6 @@ export class TransactionalEntity extends Entity {
     tryUpdate(mutator) {
         return this.#requireTransaction("tryUpdate").tryUpdate(mutator);
     }
-    /**
-     * Updates the buffered draft version metadata without computing version increments.
-     *
-     * @param draft Caller-owned version metadata for the active draft.
-     * @returns Cloned previous and draft version metadata.
-     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
-     */
-    updateDraftVersionMetadata(draft) {
-        this.#requireTransaction("updateDraftVersionMetadata").updateVersionMetadata(EntityVersions.clone(draft));
-        return this.draftVersionMetadata();
-    }
     /**
      * Marks the buffered draft lifecycle as archived.
      *
@@ -421,23 +624,24 @@ export class TransactionalEntity extends Entity {
     /**
      * Commits the active draft transaction.
      *
-     * Accepted commits apply state, version metadata, and lifecycle flags to this
+     * Accepted commits apply state, Spine Version, and lifecycle flags to this
      * entity and close the transaction. Rejected commits do not apply anything and
      * keep the transaction active for correction or explicit rollback.
      *
+     * @param producedEvents Whether handling returned Events, requiring a version advance.
      * @returns A cloned accepted or rejected transaction result.
      * @throws {@link TransactionalEntityScopeError} when no transaction is active.
      */
-    commitTransaction() {
+    commitTransaction(producedEvents = false) {
         const transaction = this.#requireTransaction("commitTransaction");
-        const result = transaction.commit();
+        const result = transaction.commit(producedEvents);
         if (result.status === "accepted") {
             if (result.previous === undefined ||
                 !EntitySnapshots.equal(this.schema, result.previous, result.next)) {
                 this.#stateChanged = true;
             }
             this.replaceState(result.next);
-            this.replaceVersionMetadata(result.version.committed);
+            this.replaceVersion(result.version.committed);
             this.replaceLifecycleFlags(result.lifecycle);
             this.#transaction = undefined;
             rejectedCommits.delete(this);
@@ -458,6 +662,12 @@ export class TransactionalEntity extends Entity {
         this.#transaction = undefined;
         return result;
     }
+    /**
+     * Gets the active transaction or rejects an out-of-scope operation.
+     *
+     * @param operation Draft operation being attempted.
+     * @returns The currently active transaction.
+     */
     #requireTransaction(operation) {
         const transaction = this.#transaction;
         if (transaction?.status !== "active") {
@@ -472,12 +682,29 @@ export class TransactionalEntity extends Entity {
  * @internal
  */
 export const transactionalEntityAccess = Object.freeze({
+    /**
+     * Starts the Entity's protected transaction before invoking its handler.
+     *
+     * @param entity Entity about to handle a signal.
+     */
     start(entity) {
         TransactionAccess.call(entity, "startTransaction");
     },
-    commit(entity) {
-        return TransactionAccess.call(entity, "commitTransaction");
+    /**
+     * Commits the handler's draft and records whether it returned Events.
+     *
+     * @param entity Entity whose handler has completed.
+     * @param producedEvents Whether handling returned domain Events.
+     * @returns The accepted or validation-rejected transaction result.
+     */
+    commit(entity, producedEvents = false) {
+        return TransactionAccess.call(entity, "commitTransaction", producedEvents);
     },
+    /**
+     * Rolls back an active draft, ignoring a transaction that has already closed.
+     *
+     * @param entity Entity whose handling failed or was rejected.
+     */
     rollback(entity) {
         try {
             TransactionAccess.call(entity, "rollbackTransaction");
@@ -488,6 +715,12 @@ export const transactionalEntityAccess = Object.freeze({
             }
         }
     },
+    /**
+     * Reads the validation failure retained for the Entity's latest rejected commit.
+     *
+     * @param entity Entity whose rejected result is requested.
+     * @returns A copy of the rejected result, or undefined when none is retained.
+     */
     rejectedCommit(entity) {
         const rejected = rejectedCommits.get(entity);
         return rejected === undefined
@@ -499,28 +732,44 @@ export const transactionalEntityAccess = Object.freeze({
  * Bridges repository code to protected transactional entity methods.
  */
 const TransactionAccess = Object.freeze({
-    call(entity, methodName) {
+    /**
+     * Invokes a protected transaction method from repository code.
+     *
+     * @param entity Instance receiving the method call.
+     * @param methodName Transaction method to invoke.
+     * @param args Arguments passed to the transaction method.
+     * @returns The method's result.
+     */
+    call(entity, methodName, ...args) {
         const method = entity[methodName];
         if (typeof method !== "function") {
             throw new TypeError(`Transactional entity access requires "${methodName}".`);
         }
-        return Reflect.apply(method, entity, []);
+        return Reflect.apply(method, entity, args);
     },
+    /**
+     * Tests whether an operation failed because no transaction was active.
+     *
+     * @param error Failure returned by a transaction operation.
+     * @returns True only for a missing transaction scope.
+     */
     isMissing(error) {
         return error instanceof TransactionalEntityScopeError && error.reason === "missing";
     },
 });
 /**
- * Abstract aggregate family marker over the common transactional entity shell.
+ * Base class for Aggregates with transactional state and Event-history access.
+ *
+ * Provides Aggregate family identity and protected repository-backed history
+ * methods. Repositories and bounded contexts handle dispatch, persistence, and
+ * Event publication; application handlers change state through draft helpers.
  *
- * This class intentionally adds only stable family identity. It does not add
- * command dispatch, snapshots, repositories, idempotency guards, or handler
- * invocation. Repository-bound diagnostic event-history reads are declared
- * below for the Aggregate family.
+ * @typeParam Id Domain identifier type.
+ * @typeParam Schema Generated schema describing the Aggregate state.
  */
 export class Aggregate extends TransactionalEntity {
     /**
-     * Creates an aggregate family shell from caller-provided state and metadata inputs.
+     * Creates an Aggregate from its identity, state, and metadata.
      *
      * @param options Identity, schema, state, version, and lifecycle inputs.
      */
@@ -557,15 +806,18 @@ export class Aggregate extends TransactionalEntity {
     }
 }
 /**
- * Abstract projection family marker over the common transactional entity shell.
+ * Base class for Projections with transactional state.
+ *
+ * Repositories and Bounded Contexts invoke Event handlers and persist state
+ * changes with the Projection's Version.
+ * Projections do not expose the diagnostic history methods of other families.
  *
- * This class intentionally adds only stable family identity. It does not add
- * event subscriptions, event playing, repositories, version columns, query
- * clients, or handler invocation.
+ * @typeParam Id Domain identifier type.
+ * @typeParam Schema Generated schema describing the Projection state.
  */
 export class Projection extends TransactionalEntity {
     /**
-     * Creates a projection family shell from caller-provided state and metadata inputs.
+     * Creates a Projection from its identity, state, and metadata.
      *
      * @param options Identity, schema, state, version, and lifecycle inputs.
      */
@@ -575,15 +827,18 @@ export class Projection extends TransactionalEntity {
     }
 }
 /**
- * Abstract process manager family marker over the common transactional entity shell.
+ * Base class for Process Managers coordinating a workflow through signals.
  *
- * This class intentionally adds only stable family identity. It does not add
- * process workflow execution, command posting, query clients, repositories,
- * bounded-context injection, or handler invocation.
+ * Provides transactional state, protected Event-history access, and
+ * handler-scoped queryable Entity-state reads through `select()`. Repositories and bounded
+ * contexts invoke handlers, persist changes, and deliver returned signals.
+ *
+ * @typeParam Id Domain identifier type.
+ * @typeParam Schema Generated schema describing the Process Manager state.
  */
 export class ProcessManager extends TransactionalEntity {
     /**
-     * Creates a process manager family shell from caller-provided state and metadata inputs.
+     * Creates a Process Manager from its identity, state, and metadata.
      *
      * @param options Identity, schema, state, version, and lifecycle inputs.
      */
@@ -618,11 +873,47 @@ export class ProcessManager extends TransactionalEntity {
     eventStorage() {
         return entityHistoryAccess.eventMaintenance(this);
     }
+    /**
+     * Binds either query form to the active handler capability.
+     *
+     * @typeParam QuerySchema Queried Entity state schema.
+     * @typeParam Columns Registered columns for the legacy builder.
+     * @typeParam Id Identifier type of a detached query.
+     * @param schemaOrQuery State schema or built context-free query.
+     * @param columns Columns required with a state schema.
+     * @returns Legacy builder or detached-query read facade.
+     */
+    select(schemaOrQuery, columns) {
+        const capability = processManagerQueryAccess.require(this);
+        if (schemaOrQuery instanceof EntityQueryDescription) {
+            const query = schemaOrQuery;
+            return Object.freeze({
+                read: async () => {
+                    const active = processManagerQueryAccess.require(this);
+                    const plan = query.buildPlan();
+                    ProcessManagerQueryLimits.check(plan);
+                    const wire = query.build();
+                    wire.context = clone(ActorContextSchema, active.actorContext);
+                    const states = await active.execute(plan, query.schema, wire);
+                    return Object.freeze(states.slice(0, 1_000));
+                },
+            });
+        }
+        if (columns === undefined)
+            throw new TypeError("Process Manager query columns are required.");
+        return new ProcessManagerQuery(this, schemaOrQuery, EntityQuery.select({ schema: schemaOrQuery, columns, context: capability.actorContext }));
+    }
 }
 /**
  * Marks immutable entity families.
  */
 const EntityFamilies = Object.freeze({
+    /**
+     * Records whether an Entity is an Aggregate, Projection, or Process Manager.
+     *
+     * @param entity Instance being constructed.
+     * @param family Kind of Entity being constructed.
+     */
     mark(entity, family) {
         Object.defineProperty(entity, "entityFamily", {
             configurable: false,
@@ -636,9 +927,26 @@ const EntityFamilies = Object.freeze({
  * Creates entity-state snapshots and compares state bytes.
  */
 const EntitySnapshots = Object.freeze({
+    /**
+     * Copies state through its schema, discarding unknown wire fields.
+     *
+     * @typeParam Schema Generated schema describing the state.
+     * @param schema Schema used for encoding and decoding.
+     * @param state State snapshot to copy.
+     * @returns An independent state message containing known fields.
+     */
     clone(schema, state) {
         return fromBinary(schema, toBinary(schema, state, { writeUnknownFields: false }));
     },
+    /**
+     * Compares the encoded known fields of two state snapshots.
+     *
+     * @typeParam Schema Generated schema shared by both snapshots.
+     * @param schema Schema used to encode the states.
+     * @param previous State before handling.
+     * @param next State after handling.
+     * @returns True when their encoded known fields are identical.
+     */
     equal(schema, previous, next) {
         const previousBinary = toBinary(schema, previous, { writeUnknownFields: false });
         const nextBinary = toBinary(schema, next, { writeUnknownFields: false });
@@ -647,16 +955,23 @@ const EntitySnapshots = Object.freeze({
     },
 });
 /**
- * Creates immutable transaction-result snapshots.
+ * Copies transaction version, lifecycle, and validation snapshots.
  */
 const EntityCommits = Object.freeze({
+    /**
+     * Copies version, lifecycle, and validation messages in a transaction result.
+     *
+     * @typeParam Schema Generated schema describing the transaction's state.
+     * @param result Accepted or rejected transaction result.
+     * @returns A result with independent version and validation metadata.
+     */
     clone(result) {
         if (result.status === "accepted") {
             return {
                 ...result,
                 version: {
-                    previous: EntityVersions.clone(result.version.previous),
-                    committed: EntityVersions.clone(result.version.committed),
+                    previous: clone(VersionSchema, result.version.previous),
+                    committed: clone(VersionSchema, result.version.committed),
                 },
                 lifecycle: { archived: result.lifecycle.archived, deleted: result.lifecycle.deleted },
                 validation: this.validation(result.validation),
@@ -665,13 +980,19 @@ const EntityCommits = Object.freeze({
         return {
             ...result,
             version: {
-                previous: EntityVersions.clone(result.version.previous),
-                draft: EntityVersions.clone(result.version.draft),
+                previous: clone(VersionSchema, result.version.previous),
+                draft: clone(VersionSchema, result.version.draft),
             },
             lifecycle: { archived: result.lifecycle.archived, deleted: result.lifecycle.deleted },
             validation: this.validation(result.validation),
         };
     },
+    /**
+     * Copies validation errors without exposing the stored violation messages.
+     *
+     * @param validation State-transition validation result.
+     * @returns An independent valid result or cloned validation error.
+     */
     validation(validation) {
         if (validation.valid) {
             return { valid: true, violations: [], error: undefined };
@@ -684,146 +1005,4 @@ const EntityCommits = Object.freeze({
         };
     },
 });
-const maxVersionMetadataDepth = 1_000;
-/**
- * Validates and clones caller-provided plain version metadata.
- */
-const EntityVersions = Object.freeze({
-    clone(version) {
-        return this.value(version, "$", new WeakSet(), 0);
-    },
-    value(value, path, stack, depth) {
-        if (depth > maxVersionMetadataDepth) {
-            throw this.error(path, "excessive nesting depth");
-        }
-        if (value === null) {
-            return value;
-        }
-        switch (typeof value) {
-            case "string":
-            case "number":
-            case "boolean":
-            case "bigint":
-            case "symbol":
-            case "undefined":
-                return value;
-            case "function":
-                throw this.error(path, "function");
-            case "object":
-                return this.object(value, path, stack, depth);
-        }
-    },
-    object(value, path, stack, depth) {
-        if (isProxy(value))
-            throw this.error(path, "Proxy");
-        if (ArrayBuffer.isView(value))
-            throw this.error(path, this.kind(value));
-        if (value instanceof ArrayBuffer || this.isSharedBuffer(value)) {
-            throw this.error(path, this.kind(value));
-        }
-        if (stack.has(value))
-            throw this.error(path, "cyclic object");
-        stack.add(value);
-        try {
-            if (Array.isArray(value))
-                return this.array(value, path, stack, depth);
-            if (!this.isPlainObject(value))
-                throw this.error(path, this.kind(value));
-            const clone = Object.create(this.prototype(value));
-            const descriptors = Object.getOwnPropertyDescriptors(value);
-            const [symbolKey] = Object.getOwnPropertySymbols(descriptors);
-            if (symbolKey !== undefined) {
-                throw this.error(`${path}[${String(symbolKey)}]`, "symbol-keyed property");
-            }
-            for (const [key, descriptor] of Object.entries(descriptors)) {
-                const childPath = `${path}.${key}`;
-                if (!descriptor.enumerable)
-                    throw this.error(childPath, "non-enumerable property");
-                if (!("value" in descriptor))
-                    throw this.error(childPath, "accessor property");
-                Object.defineProperty(clone, key, {
-                    configurable: true,
-                    enumerable: true,
-                    value: this.value(descriptor.value, childPath, stack, depth + 1),
-                    writable: true,
-                });
-            }
-            return clone;
-        }
-        finally {
-            stack.delete(value);
-        }
-    },
-    array(value, path, stack, depth) {
-        if (this.prototype(value) !== Array.prototype)
-            throw this.error(path, "Array");
-        const descriptors = Object.getOwnPropertyDescriptors(value);
-        const [symbolKey] = Object.getOwnPropertySymbols(descriptors);
-        if (symbolKey !== undefined) {
-            throw this.error(`${path}[${String(symbolKey)}]`, "symbol-keyed property");
-        }
-        const lengthDescriptor = descriptors.length;
-        if (lengthDescriptor === undefined || !("value" in lengthDescriptor)) {
-            throw this.error(path, "array without data length");
-        }
-        const length = lengthDescriptor.value;
-        const clone = new Array(length);
-        for (const [key, descriptor] of Object.entries(descriptors)) {
-            if (key === "length")
-                continue;
-            if (!this.isArrayKey(key, length))
-                throw this.error(`${path}.${key}`, "custom array property");
-            if (!descriptor.enumerable)
-                throw this.error(`${path}[${key}]`, "non-enumerable property");
-            if (!("value" in descriptor))
-                throw this.error(`${path}[${key}]`, "accessor property");
-        }
-        for (let index = 0; index < length; index += 1) {
-            const key = String(index);
-            const descriptor = descriptors[key];
-            if (descriptor === undefined || !("value" in descriptor)) {
-                throw this.error(`${path}[${key}]`, "sparse array element");
-            }
-            Object.defineProperty(clone, index, {
-                configurable: true,
-                enumerable: true,
-                value: this.value(descriptor.value, `${path}[${key}]`, stack, depth + 1),
-                writable: true,
-            });
-        }
-        return clone;
-    },
-    isArrayKey(key, length) {
-        const index = Number(key);
-        return Number.isInteger(index) && index >= 0 && index < length && String(index) === key;
-    },
-    isPlainObject(value) {
-        const prototype = this.prototype(value);
-        return prototype === Object.prototype || prototype === null;
-    },
-    prototype(value) {
-        return Object.getPrototypeOf(value);
-    },
-    kind(value) {
-        if (value instanceof Date)
-            return "Date";
-        if (value instanceof Map)
-            return "Map";
-        if (value instanceof Set)
-            return "Set";
-        if (ArrayBuffer.isView(value))
-            return "typed array";
-        if (value instanceof ArrayBuffer)
-            return "ArrayBuffer";
-        if (this.isSharedBuffer(value))
-            return "SharedArrayBuffer";
-        return "object";
-    },
-    isSharedBuffer(value) {
-        return typeof SharedArrayBuffer !== "undefined" && value instanceof SharedArrayBuffer;
-    },
-    error(path, kind) {
-        return new TypeError(`Entity version metadata must be plain snapshot data; ${path} contains ${kind}.`);
-    },
-});
 //# sourceMappingURL=entity.js.map