@spine-event-engine/server 2.0.0-snapshot.11

package/dist/entity/entity.js

@@ -0,0 +1,981 @@
+/*
+ * 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 { clone, fromBinary, toBinary } from "@bufbuild/protobuf";
+import { EntityQuery, } from "@spine-event-engine/core";
+import { ActorContextSchema, ValidationErrorSchema, } from "@spine-event-engine/proto";
+import { describeEntityMetadata, } from "./entity-metadata.js";
+import { EntityTransaction, } from "./entity-transaction.js";
+const processManagerQueries = new WeakMap();
+/**
+ * Binds the repository-scoped query capability for one Process Manager invocation.
+ *
+ * @internal
+ */
+export const processManagerQueryAccess = Object.freeze({
+    bind(entity, execute, actorContext) {
+        const capability = {
+            execute,
+            actorContext: clone(ActorContextSchema, actorContext),
+            active: true,
+        };
+        processManagerQueries.set(entity, capability);
+        return () => {
+            capability.active = false;
+            processManagerQueries.delete(entity);
+        };
+    },
+    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 that owns 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.
+     *
+     * @param predicate Predicate evaluated against registered state columns.
+     * @returns This query for fluent configuration.
+     */
+    where(predicate) {
+        this.#builder.where(predicate);
+        return this;
+    }
+    /**
+     * Sets the state fields returned by the server.
+     *
+     * @param paths Generated state-field property names to include.
+     * @returns This query for fluent configuration.
+     */
+    mask(...paths) {
+        this.#builder.mask(...paths);
+        return this;
+    }
+    /**
+     * Sets the ordering for matching states by one registered column.
+     *
+     * @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 states = await capability.execute(this.#builder.buildPlan(), 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.
+ */
+export class TransactionalEntityScopeError extends Error {
+    // prettier-ignore
+    /**
+     * Scope failure reason.
+     */
+    reason;
+    /**
+     * Operation rejected by the current transaction scope.
+     */
+    operation;
+    /**
+     * Creates a deterministic transaction-scope error.
+     *
+     * @param reason Scope failure reason.
+     * @param operation Operation rejected by the scope.
+     */
+    constructor(reason, operation) {
+        super(reason === "duplicate"
+            ? `Cannot ${operation}: transactional entity already has an active transaction.`
+            : `Cannot ${operation}: transactional entity requires an active transaction.`);
+        this.name = "TransactionalEntityScopeError";
+        this.reason = reason;
+        this.operation = operation;
+        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.
+ *
+ * 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.
+ */
+export class Entity {
+    #id;
+    #schema;
+    #metadata;
+    #state;
+    #version;
+    #lifecycle;
+    #lifecycleFlagsChanged = false;
+    /**
+     * Creates an entity shell from caller-provided state and metadata inputs.
+     *
+     * @param options Identity, schema, state, version, and lifecycle inputs.
+     */
+    constructor(options) {
+        this.#id = options.id;
+        this.#schema = options.schema;
+        this.#metadata = describeEntityMetadata(options.schema);
+        this.#state = EntitySnapshots.clone(options.schema, options.state);
+        this.#version = EntityVersions.clone(options.version);
+        this.#lifecycle = {
+            archived: options.lifecycle?.archived ?? false,
+            deleted: options.lifecycle?.deleted ?? false,
+        };
+    }
+    /**
+     * Gets the stable entity identifier.
+     *
+     * @returns The caller-owned entity identifier.
+     */
+    get id() {
+        return this.#id;
+    }
+    /**
+     * Gets the generated Protobuf-ES schema describing this entity's state.
+     *
+     * @returns The generated state schema.
+     */
+    get schema() {
+        return this.#schema;
+    }
+    /**
+     * Gets descriptor-derived metadata for this entity's state schema.
+     *
+     * @returns The frozen descriptor metadata.
+     */
+    get metadata() {
+        return this.#metadata;
+    }
+    /**
+     * Gets the current entity state snapshot.
+     *
+     * @returns A cloned state snapshot.
+     */
+    get state() {
+        return EntitySnapshots.clone(this.#schema, this.#state);
+    }
+    /**
+     * Gets the caller-owned plain version metadata snapshot.
+     *
+     * @returns A validated clone of the version metadata.
+     */
+    get version() {
+        return EntityVersions.clone(this.#version);
+    }
+    /**
+     * Gets the current lifecycle flag snapshot.
+     *
+     * @returns The archived and deleted flags.
+     */
+    get lifecycle() {
+        return {
+            archived: this.#lifecycle.archived,
+            deleted: this.#lifecycle.deleted,
+        };
+    }
+    /**
+     * Determines whether the entity is archived.
+     *
+     * @returns `true` when the entity is archived.
+     */
+    get isArchived() {
+        return this.#lifecycle.archived;
+    }
+    /**
+     * Determines whether the entity is deleted.
+     *
+     * @returns `true` when the entity is deleted.
+     */
+    get isDeleted() {
+        return this.#lifecycle.deleted;
+    }
+    /**
+     * Determines whether neither lifecycle flag marks the entity inactive.
+     *
+     * @returns `true` when the entity is active.
+     */
+    get isActive() {
+        return !this.isArchived && !this.isDeleted;
+    }
+    /**
+     * Determines whether lifecycle flags changed after construction.
+     *
+     * @returns `true` when lifecycle flags changed.
+     */
+    get lifecycleFlagsChanged() {
+        return this.#lifecycleFlagsChanged;
+    }
+    /**
+     * Replaces stored state from framework-owned subclass or runtime code.
+     *
+     * @param state Next entity state snapshot.
+     */
+    replaceState(state) {
+        this.#state = EntitySnapshots.clone(this.#schema, state);
+    }
+    /**
+     * Replaces caller-owned version metadata from framework-owned subclass or runtime code.
+     *
+     * @param version Next caller-owned version metadata.
+     */
+    replaceVersionMetadata(version) {
+        this.#version = EntityVersions.clone(version);
+    }
+    /**
+     * Replaces lifecycle flags from framework-owned subclass or runtime code.
+     *
+     * @param lifecycle Lifecycle flag changes to apply.
+     */
+    replaceLifecycleFlags(lifecycle) {
+        const next = {
+            archived: lifecycle.archived ?? this.#lifecycle.archived,
+            deleted: lifecycle.deleted ?? this.#lifecycle.deleted,
+        };
+        if (next.archived !== this.#lifecycle.archived || next.deleted !== this.#lifecycle.deleted) {
+            this.#lifecycle = next;
+            this.#lifecycleFlagsChanged = true;
+        }
+    }
+    /**
+     * Reads the newest retained state at or before `time`.
+     *
+     * This diagnostic facility is repository-bound and is not a remote API.
+     *
+     * @param time Timestamp of the requested state snapshot.
+     * @returns The retained state snapshot, if one exists.
+     */
+    stateAt(time) {
+        return entityHistoryAccess.stateAt(this, time);
+    }
+    /**
+     * Reads retained states in descending version order.
+     *
+     * @param depth Maximum number of retained states to read.
+     * @returns Retained state snapshots in descending version order.
+     */
+    stateHistoryBackward(depth) {
+        return entityHistoryAccess.states(this, depth);
+    }
+    /**
+     * Gets application-managed state-history retention.
+     *
+     * @returns State-history storage for this entity.
+     */
+    stateHistoryStorage() {
+        return entityHistoryAccess.stateMaintenance(this);
+    }
+}
+const boundEntityHistories = new WeakMap();
+/**
+ * Provides repository-only history binding.
+ *
+ * @internal
+ */
+export const entityHistoryAccess = Object.freeze({
+    bind(entity, binding) {
+        boundEntityHistories.set(entity, binding);
+    },
+    stateAt(entity, time) {
+        return EntityHistory.require(entity).stateAt(time);
+    },
+    states(entity, depth) {
+        return EntityHistory.require(entity).states(EntityHistory.depth(depth));
+    },
+    events(entity, depth) {
+        return EntityHistory.require(entity).events(EntityHistory.depth(depth));
+    },
+    stateMaintenance(entity) {
+        return EntityHistory.require(entity).stateMaintenance;
+    },
+    eventMaintenance(entity) {
+        return EntityHistory.require(entity).eventMaintenance;
+    },
+});
+/**
+ * Validates repository-bound history lookups.
+ */
+const EntityHistory = Object.freeze({
+    require(entity) {
+        const binding = boundEntityHistories.get(entity);
+        if (binding === undefined) {
+            throw new Error("Entity history is available only from repository execution.");
+        }
+        return binding;
+    },
+    depth(depth) {
+        if (!Number.isSafeInteger(depth) || depth <= 0) {
+            throw new RangeError("Entity history depth must be a positive safe integer.");
+        }
+        return depth;
+    },
+});
+/**
+ * Common in-memory entity shell with a protected scoped transaction draft.
+ *
+ * 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.
+ */
+export class TransactionalEntity extends Entity {
+    #transaction;
+    #stateChanged = false;
+    /**
+     * Determines whether accepted transaction state or lifecycle changes are visible.
+     *
+     * @returns `true` when the entity differs from its initial state.
+     */
+    get changed() {
+        return this.#stateChanged || this.lifecycleFlagsChanged;
+    }
+    /**
+     * Determines whether a protected transaction scope is currently active.
+     *
+     * @returns `true` when an active transaction scope exists.
+     */
+    isTransactionInProgress() {
+        return this.#transaction?.status === "active";
+    }
+    /**
+     * Starts a protected draft transaction from the entity's current snapshots.
+     *
+     * @throws {@link TransactionalEntityScopeError} when another transaction is active.
+     */
+    startTransaction() {
+        if (this.isTransactionInProgress()) {
+            throw new TransactionalEntityScopeError("duplicate", "startTransaction");
+        }
+        const previousVersion = this.version;
+        this.#transaction = new EntityTransaction({
+            schema: this.schema,
+            previous: this.state,
+            version: {
+                previous: previousVersion,
+                draft: EntityVersions.clone(previousVersion),
+            },
+            lifecycle: this.lifecycle,
+        });
+    }
+    /**
+     * Gets the current draft state snapshot.
+     *
+     * @returns A cloned current draft state snapshot.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    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.
+     *
+     * @returns Current archived and deleted draft flags.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    draftLifecycleFlags() {
+        return this.#requireTransaction("draftLifecycleFlags").lifecycle;
+    }
+    /**
+     * Updates the buffered draft state in place.
+     *
+     * @param mutator Changes the active draft state.
+     * @returns A cloned snapshot of the updated draft state.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    update(mutator) {
+        return this.#requireTransaction("update").update(mutator);
+    }
+    /**
+     * Tries to update and validate a scratch draft, applying it only when valid.
+     *
+     * Validation failures return immutable constraint violations. Other errors
+     * propagate and leave the active draft unchanged.
+     *
+     * @param mutator Changes the scratch draft state.
+     * @returns Immutable constraint violations, or an empty array when the update applies.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    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.
+     *
+     * @returns The archived and deleted draft flags.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    archiveDraft() {
+        return this.#requireTransaction("archiveDraft").archive();
+    }
+    /**
+     * Marks the buffered draft lifecycle as not archived.
+     *
+     * @returns The archived and deleted draft flags.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    unarchiveDraft() {
+        return this.#requireTransaction("unarchiveDraft").unarchive();
+    }
+    /**
+     * Marks the buffered draft lifecycle as deleted.
+     *
+     * @returns The archived and deleted draft flags.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    markDraftDeleted() {
+        return this.#requireTransaction("markDraftDeleted").markDeleted();
+    }
+    /**
+     * Marks the buffered draft lifecycle as not deleted.
+     *
+     * @returns The archived and deleted draft flags.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    restoreDraft() {
+        return this.#requireTransaction("restoreDraft").restore();
+    }
+    /**
+     * Commits the active draft transaction.
+     *
+     * Accepted commits apply state, version metadata, 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.
+     *
+     * @returns A cloned accepted or rejected transaction result.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    commitTransaction() {
+        const transaction = this.#requireTransaction("commitTransaction");
+        const result = transaction.commit();
+        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.replaceLifecycleFlags(result.lifecycle);
+            this.#transaction = undefined;
+            rejectedCommits.delete(this);
+        }
+        else {
+            rejectedCommits.set(this, EntityCommits.clone(result));
+        }
+        return EntityCommits.clone(result);
+    }
+    /**
+     * Rolls back the active draft without applying state, version, or lifecycle changes.
+     *
+     * @returns A cloned rollback result containing the discarded draft snapshots.
+     * @throws {@link TransactionalEntityScopeError} when no transaction is active.
+     */
+    rollbackTransaction() {
+        const result = this.#requireTransaction("rollbackTransaction").rollback();
+        this.#transaction = undefined;
+        return result;
+    }
+    #requireTransaction(operation) {
+        const transaction = this.#transaction;
+        if (transaction?.status !== "active") {
+            throw new TransactionalEntityScopeError("missing", operation);
+        }
+        return transaction;
+    }
+}
+/**
+ * Exposes framework-only transaction operations for repository execution.
+ *
+ * @internal
+ */
+export const transactionalEntityAccess = Object.freeze({
+    start(entity) {
+        TransactionAccess.call(entity, "startTransaction");
+    },
+    commit(entity) {
+        return TransactionAccess.call(entity, "commitTransaction");
+    },
+    rollback(entity) {
+        try {
+            TransactionAccess.call(entity, "rollbackTransaction");
+        }
+        catch (error) {
+            if (!TransactionAccess.isMissing(error)) {
+                throw error;
+            }
+        }
+    },
+    rejectedCommit(entity) {
+        const rejected = rejectedCommits.get(entity);
+        return rejected === undefined
+            ? undefined
+            : EntityCommits.clone(rejected);
+    },
+});
+/**
+ * Bridges repository code to protected transactional entity methods.
+ */
+const TransactionAccess = Object.freeze({
+    call(entity, methodName) {
+        const method = entity[methodName];
+        if (typeof method !== "function") {
+            throw new TypeError(`Transactional entity access requires "${methodName}".`);
+        }
+        return Reflect.apply(method, entity, []);
+    },
+    isMissing(error) {
+        return error instanceof TransactionalEntityScopeError && error.reason === "missing";
+    },
+});
+/**
+ * Abstract aggregate family marker over the common transactional entity shell.
+ *
+ * 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.
+ */
+export class Aggregate extends TransactionalEntity {
+    /**
+     * Creates an aggregate family shell from caller-provided state and metadata inputs.
+     *
+     * @param options Identity, schema, state, version, and lifecycle inputs.
+     */
+    constructor(options) {
+        super(options);
+        EntityFamilies.mark(this, "aggregate");
+    }
+    /**
+     * Reads retained diagnostic events in descending producer-version order.
+     *
+     * @param depth Maximum number of retained events to read.
+     * @returns Retained events in descending producer-version order.
+     */
+    eventHistoryBackward(depth) {
+        return entityHistoryAccess.events(this, depth);
+    }
+    /**
+     * Tests retained diagnostic events in descending producer-version order.
+     *
+     * @param depth Maximum number of retained events to inspect.
+     * @param predicate Tests each retained event.
+     * @returns `true` when a retained event matches the predicate.
+     */
+    async eventHistoryContains(depth, predicate) {
+        return (await this.eventHistoryBackward(depth)).some(predicate);
+    }
+    /**
+     * Gets application-managed diagnostic event-history retention.
+     *
+     * @returns Event-history storage for this entity.
+     */
+    eventStorage() {
+        return entityHistoryAccess.eventMaintenance(this);
+    }
+}
+/**
+ * Abstract projection family marker over the common transactional entity shell.
+ *
+ * This class intentionally adds only stable family identity. It does not add
+ * event subscriptions, event playing, repositories, version columns, query
+ * clients, or handler invocation.
+ */
+export class Projection extends TransactionalEntity {
+    /**
+     * Creates a projection family shell from caller-provided state and metadata inputs.
+     *
+     * @param options Identity, schema, state, version, and lifecycle inputs.
+     */
+    constructor(options) {
+        super(options);
+        EntityFamilies.mark(this, "projection");
+    }
+}
+/**
+ * Abstract process manager family marker over the common transactional entity shell.
+ *
+ * This class adds a protected, handler-scoped, read-only Projection query
+ * capability. It does not add command posting, repositories, bounded-context
+ * injection, or handler invocation.
+ */
+export class ProcessManager extends TransactionalEntity {
+    /**
+     * Creates a process manager family shell from caller-provided state and metadata inputs.
+     *
+     * @param options Identity, schema, state, version, and lifecycle inputs.
+     */
+    constructor(options) {
+        super(options);
+        EntityFamilies.mark(this, "process-manager");
+    }
+    /**
+     * Reads retained diagnostic events when this repository enabled Process Manager event history.
+     *
+     * @param depth Maximum number of retained events to read.
+     * @returns Retained events in descending producer-version order.
+     */
+    eventHistoryBackward(depth) {
+        return entityHistoryAccess.events(this, depth);
+    }
+    /**
+     * Tests retained diagnostic events when this repository enabled Process Manager event history.
+     *
+     * @param depth Maximum number of retained events to inspect.
+     * @param predicate Tests each retained event.
+     * @returns `true` when a retained event matches the predicate.
+     */
+    async eventHistoryContains(depth, predicate) {
+        return (await this.eventHistoryBackward(depth)).some(predicate);
+    }
+    /**
+     * Gets application-managed Process Manager diagnostic event-history retention.
+     *
+     * @returns Event-history storage for this Process Manager.
+     */
+    eventStorage() {
+        return entityHistoryAccess.eventMaintenance(this);
+    }
+    /**
+     * Starts a typed, eventually consistent read-side query during handler execution.
+     *
+     * The repository binds this capability only while it invokes a Process Manager
+     * handler. Reads use that signal's actor and tenant; they cannot mutate state
+     * or select a different tenant.
+     *
+     * @param schema Projection state schema to query.
+     * @param columns Generated descriptor-backed columns for `schema`.
+     * @returns A read-only Entity query.
+     */
+    select(schema, columns) {
+        const capability = processManagerQueryAccess.require(this);
+        return new ProcessManagerQuery(this, schema, EntityQuery.select({ schema, columns, context: capability.actorContext }));
+    }
+}
+/**
+ * Marks immutable entity families.
+ */
+const EntityFamilies = Object.freeze({
+    mark(entity, family) {
+        Object.defineProperty(entity, "entityFamily", {
+            configurable: false,
+            enumerable: false,
+            value: family,
+            writable: false,
+        });
+    },
+});
+/**
+ * Creates entity-state snapshots and compares state bytes.
+ */
+const EntitySnapshots = Object.freeze({
+    clone(schema, state) {
+        return fromBinary(schema, toBinary(schema, state, { writeUnknownFields: false }));
+    },
+    equal(schema, previous, next) {
+        const previousBinary = toBinary(schema, previous, { writeUnknownFields: false });
+        const nextBinary = toBinary(schema, next, { writeUnknownFields: false });
+        return (previousBinary.byteLength === nextBinary.byteLength &&
+            previousBinary.every((byte, index) => byte === nextBinary[index]));
+    },
+});
+/**
+ * Creates immutable transaction-result snapshots.
+ */
+const EntityCommits = Object.freeze({
+    clone(result) {
+        if (result.status === "accepted") {
+            return {
+                ...result,
+                version: {
+                    previous: EntityVersions.clone(result.version.previous),
+                    committed: EntityVersions.clone(result.version.committed),
+                },
+                lifecycle: { archived: result.lifecycle.archived, deleted: result.lifecycle.deleted },
+                validation: this.validation(result.validation),
+            };
+        }
+        return {
+            ...result,
+            version: {
+                previous: EntityVersions.clone(result.version.previous),
+                draft: EntityVersions.clone(result.version.draft),
+            },
+            lifecycle: { archived: result.lifecycle.archived, deleted: result.lifecycle.deleted },
+            validation: this.validation(result.validation),
+        };
+    },
+    validation(validation) {
+        if (validation.valid) {
+            return { valid: true, violations: [], error: undefined };
+        }
+        const error = clone(ValidationErrorSchema, validation.error);
+        return {
+            valid: false,
+            violations: error.constraintViolation,
+            error,
+        };
+    },
+});
+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