@spine-event-engine/server 2.0.0-snapshot.12 → 2.0.0-snapshot.15

package/dist/repository/repository.js

@@ -84,8 +84,8 @@ export class RepositoryIdentityError extends Error {
  * and write changed projection state through the context-owned `Stand`. With
  * authentic process-manager metadata, built contexts can execute command
  * assignees, event reactors, and event-commanding handlers, storing changed
- * process-manager state through tenant-scoped Stand records with numeric
- * versions. The `events` option declares generated event schemas emitted by
+ * process-manager state through tenant-scoped Stand records with full Spine
+ * Versions. The `events` option declares generated event schemas emitted by
  * aggregate and process-manager producer handlers. The repository surface still
  * does not expose direct entity lookup/storage APIs, inbox/delivery management,
  * caches, lifecycle monitors, or transport startup.
@@ -271,9 +271,21 @@ Object.freeze(Repository);
  * @internal
  */
 export const repositoryAccess = Object.freeze({
+    /**
+     * Checks whether a value has registered repository identity metadata.
+     *
+     * @param repository Value to inspect.
+     * @returns Whether the value is a repository view.
+     */
     hasInstance(repository) {
         return repositorySnapshots.has(repository);
     },
+    /**
+     * Copies a repository's immutable identity metadata.
+     *
+     * @param repository Repository to inspect.
+     * @returns A copy-safe identity snapshot.
+     */
     snapshot(repository) {
         const snapshot = repositorySnapshots.get(repository);
         if (snapshot === undefined) {
@@ -281,6 +293,12 @@ export const repositoryAccess = Object.freeze({
         }
         return RepositoryIdentity.cloneRepositorySnapshot(snapshot);
     },
+    /**
+     * Reads schemas for Events this repository can emit.
+     *
+     * @param repository Repository to inspect.
+     * @returns Registered produced Event schemas.
+     */
     producedEventSchemas(repository) {
         const schemas = repositoryProducedEventSchemas.get(repository);
         if (schemas === undefined) {
@@ -288,15 +306,39 @@ export const repositoryAccess = Object.freeze({
         }
         return schemas;
     },
+    /**
+     * Looks up command dispatch for the repository.
+     *
+     * @param repository Repository to inspect.
+     * @returns A dispatcher when command routes are registered.
+     */
     commandDispatcher(repository) {
         return repositoryDispatchers.get(repository)?.command;
     },
+    /**
+     * Looks up Event dispatch for the repository.
+     *
+     * @param repository Repository to inspect.
+     * @returns A dispatcher when Event routes are registered.
+     */
     eventDispatcher(repository) {
         return repositoryDispatchers.get(repository)?.event;
     },
+    /**
+     * Looks up state-update System Event dispatch for the repository.
+     *
+     * @param repository Repository to inspect.
+     * @returns A dispatcher when state subscriptions are registered.
+     */
     systemEventDispatcher(repository) {
         return repositoryDispatchers.get(repository)?.systemEvent;
     },
+    /**
+     * Lists Entity state types subscribed by this repository.
+     *
+     * @param repository Repository to inspect.
+     * @returns A frozen list of state type names.
+     */
     stateSubscriptionTypes(repository) {
         const routing = repositoryRoutings.get(repository);
         if (routing === undefined) {
@@ -304,6 +346,13 @@ export const repositoryAccess = Object.freeze({
         }
         return Object.freeze(routing.stateSchemas.map((schema) => schema.typeName));
     },
+    /**
+     * Resolves an Entity state-change route for a Projection repository.
+     *
+     * @param repository Repository to route through.
+     * @param event Entity state-change System Event.
+     * @returns The matching route, or `undefined` for an unrelated state.
+     */
     routeStateUpdate(repository, event) {
         const routing = repositoryRoutings.get(repository);
         if (routing === undefined) {
@@ -311,12 +360,32 @@ export const repositoryAccess = Object.freeze({
         }
         return routing.routeStateUpdate(event);
     },
+    /**
+     * Looks up the Aggregate or Process Manager inbox replay target.
+     *
+     * @param repository Repository to inspect.
+     * @returns Its replay target, when registered.
+     */
     entityInboxTarget(repository) {
         return repositoryEntityInboxTargets.get(repository);
     },
+    /**
+     * Looks up the Projection inbox replay target.
+     *
+     * @param repository Repository to inspect.
+     * @returns Its replay target, when registered.
+     */
     projectionInboxTarget(repository) {
         return repositoryProjectionInboxTargets.get(repository);
     },
+    /**
+     * Dispatches an Event directly to a registered Projection.
+     *
+     * @param repository Projection repository to dispatch through.
+     * @param event Event to deliver.
+     * @param rebuild Whether to load deleted state for rebuilding.
+     * @returns Completion after the Projection receives the Event.
+     */
     dispatchProjectionDirect(repository, event, rebuild) {
         const dispatch = repositoryProjectionDirect.get(repository);
         if (dispatch === undefined) {
@@ -324,9 +393,20 @@ export const repositoryAccess = Object.freeze({
         }
         return dispatch(event, rebuild);
     },
+    /**
+     * Stores a built context runtime for repository dispatch.
+     *
+     * @param repository Repository receiving runtime services.
+     * @param runtime Context runtime to bind.
+     */
     bindRuntime(repository, runtime) {
         repositoryRuntimes.set(repository, Object.freeze(runtime));
     },
+    /**
+     * Removes runtime dispatch state and closes tracked storage handles.
+     *
+     * @param repository Repository to detach.
+     */
     clearRuntime(repository) {
         repositoryRuntimes.delete(repository);
         repositoryDispatchGuards.delete(repository);
@@ -339,15 +419,31 @@ export const repositoryAccess = Object.freeze({
     },
 });
 const inboxDedupMs = 30_000;
+/**
+ * Loads and persists Aggregate state within one tenant storage context.
+ */
 class AggregateExecutionSupport {
     #repository;
     #runtime;
     #storageContext;
+    /**
+     * Binds an Aggregate repository to runtime and tenant storage services.
+     *
+     * @param repository Aggregate repository being executed.
+     * @param runtime Built context services.
+     * @param storageContext Tenant-aware storage location.
+     */
     constructor(repository, runtime, storageContext) {
         this.#repository = repository;
         this.#runtime = runtime;
         this.#storageContext = storageContext;
     }
+    /**
+     * Restores an Aggregate from Stand or creates its initial state and binds history.
+     *
+     * @param entityId Aggregate identifier to load.
+     * @returns Aggregate instance, current record, history ports, and version.
+     */
     async loadAggregate(entityId) {
         const storageInput = RepositoryStorage.entityStorageInput(this.#repository, this.#storageContext);
         const storage = RepositoryStorage.openRepositoryEntityStorage(this.#repository, this.#runtime.storageFactory, storageInput);
@@ -371,53 +467,55 @@ class AggregateExecutionSupport {
             storageInput,
         });
     }
+    /**
+     * Normalizes a handler result to a frozen signal list.
+     *
+     * @param produced Raw handler result.
+     * @returns No signals, one signal, or the copied result array.
+     */
     normalizeProducedSignals(produced) {
         if (produced === undefined) {
             return Object.freeze([]);
         }
         if (Array.isArray(produced)) {
-            return Object.freeze(Array.from(produced));
+            return Object.freeze(Array.from(produced).filter((item) => item !== undefined));
         }
         return Object.freeze([produced]);
     }
     /**
-     * Store the current aggregate record before its diagnostic and delivery journals.
+     * Stores Aggregate state and diagnostic and delivery Events in one atomic commit.
+     *
+     * @param loaded Aggregate and commit storage to update.
+     * @param entityId Aggregate identifier.
+     * @param events Produced Events to retain.
+     * @param diagnostics Events to retain in the diagnostic history.
+     * @returns `true` after a successful commit; conflicts throw.
      */
-    async persistAggregateUpdate(loaded, entityId, version, events) {
+    async persistAggregateUpdate(loaded, entityId, events, diagnostics = events) {
         const lifecycle = RepositoryEntities.repositoryLifecycle(loaded.entity);
         const state = RepositoryEntities.repositoryState(loaded.entity);
-        const deferred = await standAccess.deferUpdate(this.#runtime.stand, this.#repository.stateSchema, state, RepositoryStand.standUpdateOptions(this.#storageContext.tenantId, create(VersionSchema, { number: RepositorySignals.eventVersionNumber(version) }), lifecycle));
+        const versionMessage = RepositoryEntities.repositoryVersion(loaded.entity);
+        const deferred = await standAccess.deferUpdate(this.#runtime.stand, this.#repository.stateSchema, state, RepositoryStand.standUpdateOptions(this.#storageContext.tenantId, versionMessage, lifecycle));
         try {
-            const createdAt = events[events.length - 1]?.context?.timestamp ?? create(TimestampSchema);
-            const outcome = await loaded.commits.commit({
-                context: this.#storageContext,
-                entity: loaded.storageInput,
-                entityId,
-                ...(loaded.current === undefined ? {} : { expected: loaded.current }),
-                next: EntityRecords.pack(this.#repository.stateSchema, entityId, state, version, lifecycle),
-                ...(RepositoryStorage.historyConfiguration(this.#repository).stateHistory
-                    ? {
-                        states: [
-                            EntityRecords.pack(this.#repository.stateSchema, entityId, state, create(VersionSchema, {
-                                number: RepositorySignals.eventVersionNumber(version),
-                                timestamp: createdAt,
-                            }), lifecycle),
-                        ],
-                    }
-                    : {}),
-                diagnostics: events.map((event) => clone(EventSchema, event)),
-                events,
-            });
-            if (outcome !== "committed") {
-                deferred.cancel();
+            const outcome = await this.#commitAggregateRecord(loaded, entityId, state, versionMessage, lifecycle, events, diagnostics);
+            if (outcome !== "committed")
                 throw new Error("Concurrent Aggregate state commit conflict.");
-            }
             entityStateHistoryCaches.get(loaded.entity)?.clear();
         }
         catch (error) {
             deferred.cancel();
             throw error;
         }
+        this.#notifyAggregate(deferred, events);
+        return true;
+    }
+    /**
+     * Notifies Stand after an Aggregate commit and reports delivery failure.
+     *
+     * @param deferred Deferred Stand update created before the commit.
+     * @param events Produced Events available for failure reporting.
+     */
+    #notifyAggregate(deferred, events) {
         try {
             deferred.notify();
         }
@@ -426,16 +524,58 @@ class AggregateExecutionSupport {
             if (event !== undefined)
                 this.#runtime.publisher.reportFailure("event", event, error);
         }
-        return true;
     }
+    /**
+     * Writes one Aggregate state and its optional history with the same Version.
+     *
+     * @param loaded Loaded Aggregate and commit storage.
+     * @param entityId Aggregate identifier.
+     * @param state Accepted Aggregate state.
+     * @param version Current Spine Version.
+     * @param lifecycle Accepted lifecycle flags.
+     * @param events Produced Events to retain and publish.
+     * @param diagnostics Events to retain in the diagnostic history.
+     * @returns The storage commit outcome.
+     */
+    #commitAggregateRecord(loaded, entityId, state, version, lifecycle, events, diagnostics) {
+        const record = EntityRecords.pack(this.#repository.stateSchema, entityId, state, version, lifecycle);
+        return loaded.commits.commit({
+            context: this.#storageContext,
+            entity: loaded.storageInput,
+            entityId,
+            ...(loaded.current === undefined ? {} : { expected: loaded.current }),
+            next: record,
+            ...(RepositoryStorage.historyConfiguration(this.#repository).stateHistory
+                ? { states: [record] }
+                : {}),
+            diagnostics: diagnostics.map((event) => clone(EventSchema, event)),
+            events,
+        });
+    }
+    /**
+     * Writes a copied Event to the Aggregate diagnostic history.
+     *
+     * @param loaded Aggregate with its history port.
+     * @param entityId Aggregate identifier retained for the caller contract.
+     * @param event Event to append.
+     * @returns Completion after the history append.
+     */
     async appendDiagnosticEvent(loaded, entityId, event) {
         await loaded.events.append(clone(EventSchema, event));
     }
     /**
-     * Complete persistence before scheduling best-effort stored-event dispatch.
+     * Completes persistence before scheduling best-effort stored-Event dispatch.
+     *
+     * @param loaded Aggregate and commit storage to update.
+     * @param entityId Aggregate identifier.
+     * @param events Produced Events to persist and dispatch.
+     * @param dispatch Publishes one committed Event.
+     * @param onPersisted Runs after durable persistence.
+     * @param diagnostics Events to retain in diagnostic history with this commit.
+     * @returns A deferred follow-up that dispatches the Events.
      */
-    async persistAggregateAndDispatch(loaded, entityId, version, events, dispatch, onPersisted) {
-        const committed = await this.persistAggregateUpdate(loaded, entityId, version, events);
+    async persistAggregateAndDispatch(loaded, entityId, events, dispatch, onPersisted, diagnostics = events) {
+        const committed = await this.persistAggregateUpdate(loaded, entityId, events, diagnostics);
         if (!committed)
             return () => Promise.resolve();
         await onPersisted();
@@ -450,31 +590,55 @@ class AggregateExecutionSupport {
             }));
         };
     }
+    /**
+     * Restores an Aggregate or creates one with initial state and version zero.
+     *
+     * @param entityId Aggregate identifier.
+     * @param current Stored state and lifecycle, when present.
+     * @returns The constructed Aggregate instance.
+     */
     #instantiateAggregate(entityId, current) {
         const entityType = this.#repository.entityType;
         const options = {
             id: entityId,
             schema: this.#repository.stateSchema,
             state: current?.state ?? this.#defaultState(entityId),
-            version: current?.version ?? 0n,
+            version: current?.versionMessage ?? create(VersionSchema),
         };
         if (current !== undefined) {
             options.lifecycle = { archived: current.archived, deleted: current.deleted };
         }
         return new entityType(options);
     }
+    /**
+     * Creates generated initial state with its canonical identifier field set.
+     *
+     * @param entityId Identifier to place in the state.
+     * @returns A new state message.
+     */
     #defaultState(entityId) {
         return create(this.#repository.stateSchema, {
             [this.#repository.idField.localName]: entityId,
         });
     }
 }
+/**
+ * Executes one routed Aggregate Command and stores its resulting Events.
+ */
 class AggregateCommandExecution {
     #repository;
     #routing;
     #runtime;
     #command;
     #support;
+    /**
+     * Captures routing, runtime, Command, and tenant-scoped persistence services.
+     *
+     * @param repository Aggregate repository receiving the Command.
+     * @param routing Registered Command routes and schemas.
+     * @param runtime Built context services.
+     * @param command Command to execute.
+     */
     constructor(repository, routing, runtime, command) {
         this.#repository = repository;
         this.#routing = routing;
@@ -482,6 +646,12 @@ class AggregateCommandExecution {
         this.#command = command;
         this.#support = new AggregateExecutionSupport(repository, runtime, RepositoryTenants.storageContextForCommand(this.#runtime.context, this.#command));
     }
+    /**
+     * Validates the Command and executes its assignee when registered.
+     *
+     * @param replayedRoute Accepted route from durable inbox replay, when present.
+     * @returns A deferred dispatch follow-up, or `undefined` without an assignee.
+     */
     async run(replayedRoute) {
         void RepositorySignals.requireCommandId(this.#command);
         const intake = this.#readIntake(replayedRoute);
@@ -489,6 +659,12 @@ class AggregateCommandExecution {
             return undefined;
         return this.#runAssignee(intake);
     }
+    /**
+     * Decodes the Command and selects its registered assignee.
+     *
+     * @param replayedRoute Accepted inbox route, when present.
+     * @returns Decoded message and route with an assignee, or `undefined`.
+     */
     #readIntake(replayedRoute) {
         const commandMessage = EntityInvocation.requireSignalMessage(this.#command.message, "command");
         const commandSchema = RepositoryRoutes.schemaForTypeUrl(this.#routing.commandSchemas, commandMessage.typeUrl, "command");
@@ -497,36 +673,57 @@ class AggregateCommandExecution {
         const assignee = this.#routing.commandReadiness?.findCommandAssignee(route.messageFullTypeName);
         return assignee === undefined ? undefined : Object.freeze({ message, route, assignee });
     }
+    /**
+     * Invokes the assignee, persists its Events, or publishes a declared rejection.
+     *
+     * @param intake Decoded Command, target route, and assignee.
+     * @returns A deferred Event follow-up or a rejection follow-up.
+     */
     async #runAssignee(intake) {
         const loaded = await this.#support.loadAggregate(intake.route.entityId);
         this.#publishCommandDispatch(intake.route.entityId);
-        const commandContext = EntityInvocation.commandHandlerContext(this.#command);
         let produced;
         try {
-            produced = await this.#invokeAssignee(loaded.entity, intake.assignee.handler.methodName, intake.message, intake.assignee.handler.parameterCount, commandContext);
+            produced = await this.#invokeAssignee(loaded.entity, intake.assignee.handler, intake.message, EntityInvocation.commandHandlerContext(this.#command));
         }
         catch (error) {
-            if (!RejectionThrowable.is(error)) {
-                throw error;
-            }
-            RepositorySignals.requireDeclaredRejection(intake.assignee.handler, error);
-            return RepositorySignals.postRejectionEvent(this.#runtime, this.#repository, this.#command, intake.route.entityId, error);
+            return this.#postAssigneeRejection(intake, error);
         }
-        const events = this.#requiredEvents(produced, intake.route.entityId, loaded.version);
+        const events = this.#bindProducedEvents(this.#support.normalizeProducedSignals(produced), intake.route.entityId, RepositoryEntities.priorVersion(loaded.current));
         return this.#persistAssigneeResult(loaded, intake.route.entityId, events);
     }
+    /**
+     * Publishes a declared rejection from the invoked Aggregate assignee.
+     *
+     * @param intake Assignee and target route for the rejected Command.
+     * @param error Handler failure to classify and publish.
+     * @returns A rejection follow-up when one is created.
+     */
+    #postAssigneeRejection(intake, error) {
+        if (!RejectionThrowable.is(error))
+            throw error;
+        RepositorySignals.requireDeclaredRejection(intake.assignee.handler, error);
+        return RepositorySignals.postRejectionEvent(this.#runtime, this.#repository, this.#command, intake.route.entityId, error);
+    }
+    /**
+     * Publishes a best-effort Command dispatch diagnostic.
+     *
+     * @param entityId Target Aggregate identifier.
+     */
     #publishCommandDispatch(entityId) {
         HandlerDispatchPublisher.command(this.#runtime, this.#repository, this.#command, entityId);
     }
-    #requiredEvents(produced, entityId, version) {
-        const events = this.#bindProducedEvents(this.#support.normalizeProducedSignals(produced), entityId, version, true);
-        if (events.length === 0)
-            throw new Error("Repository aggregate command handlers must return at least one event.");
-        return events;
-    }
+    /**
+     * Stores accepted Aggregate changes and publishes a state-change diagnostic.
+     *
+     * @param loaded Aggregate and commit storage.
+     * @param entityId Target Aggregate identifier.
+     * @param events Bound Events from the assignee.
+     * @returns A deferred committed-Event dispatch follow-up.
+     */
     #persistAssigneeResult(loaded, entityId, events) {
         const committedVersion = loaded.version + 1n;
-        return this.#support.persistAggregateAndDispatch(loaded, entityId, committedVersion, events, (event) => this.#runtime.publisher.publishCommittedEvent(event), () => {
+        return this.#support.persistAggregateAndDispatch(loaded, entityId, events, (event) => this.#runtime.publisher.publishCommittedEvent(event), () => {
             if (!RepositoryEntities.repositoryChanged(loaded.entity))
                 return;
             EntityStateChangePublisher.command(this.#runtime, this.#repository, this.#command, entityId, loaded.oldState, loaded.current === undefined
@@ -537,11 +734,24 @@ class AggregateCommandExecution {
                 }, RepositoryEntities.repositoryState(loaded.entity), RepositoryEntities.repositoryLifecycle(loaded.entity), RepositorySignals.eventVersionNumber(committedVersion));
         });
     }
-    async #invokeAssignee(entity, methodName, message, parameterCount, context) {
+    /**
+     * Invokes an assignee in a fenced Entity transaction with output validation.
+     *
+     * @param entity Aggregate instance to mutate.
+     * @param handler Assignee declaration to invoke.
+     * @param message Decoded Command message.
+     * @param context Copied Command context for the handler.
+     * @returns The handler's raw result after a successful commit.
+     */
+    async #invokeAssignee(entity, handler, message, context) {
         transactionalEntityAccess.start(entity);
         try {
-            const produced = await EntityInvocation.invokeEntityMethod(entity, methodName, message, parameterCount, context);
-            const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
+            const produced = await EntityInvocation.invokeEntityMethod(entity, handler.methodName, message, handler.parameterCount, context);
+            const signals = this.#support.normalizeProducedSignals(produced);
+            if (signals.length === 0)
+                throw new Error("Repository aggregate command handlers must return at least one event.");
+            RepositoryHandlers.requireDeclaredOutputs(handler, signals);
+            const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, true));
             if (commit.status === "rejected") {
                 throw new TransitionValidationError(commit.validation.error);
             }
@@ -552,20 +762,41 @@ class AggregateCommandExecution {
             throw error;
         }
     }
-    #bindProducedEvents(produced, entityId, lastVersion, allowEnvelopes) {
+    /**
+     * Binds each produced result to the target and pre-dispatch version.
+     *
+     * @param produced Handler results to bind.
+     * @param entityId Target Aggregate identifier.
+     * @param lastVersion Producer version before this dispatch.
+     * @returns Frozen bound Event list.
+     */
+    #bindProducedEvents(produced, entityId, lastVersion) {
         const dispatchVersion = lastVersion;
-        return Object.freeze(produced.map((signal) => this.#bindProducedEvent(signal, entityId, dispatchVersion, allowEnvelopes)));
+        return Object.freeze(produced.map((signal) => this.#bindProducedEvent(signal, entityId, dispatchVersion)));
     }
-    #bindProducedEvent(signal, entityId, version, allowEnvelopes) {
+    /**
+     * Packs a domain Event with producer context.
+     *
+     * @param signal One handler result.
+     * @param entityId Target Aggregate identifier.
+     * @param version Producer version before dispatch.
+     * @returns Event bound to this Aggregate.
+     */
+    #bindProducedEvent(signal, entityId, version) {
         const metadata = this.#runtime.signalMetadata.eventFromCommand(this.#command, {
-            version: RepositorySignals.eventVersionNumber(version),
+            version: version.number,
         });
-        const bound = allowEnvelopes && EntityInvocation.isEventEnvelope(signal)
-            ? clone(EventSchema, signal)
-            : this.#packDomainEvent(signal, metadata);
-        bound.context = RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId);
+        const bound = this.#packDomainEvent(signal, metadata);
+        bound.context = RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId, version);
         return bound;
     }
+    /**
+     * Packs a declared domain Event message into an Event envelope.
+     *
+     * @param message Generated Event message from the handler.
+     * @param metadata ID and context derived from the source Command.
+     * @returns Packed Event envelope.
+     */
     #packDomainEvent(message, metadata) {
         const typeName = EntityInvocation.messageTypeName(message);
         const schema = this.#routing.producedEventSchemas.find((candidate) => candidate.typeName === typeName);
@@ -579,12 +810,23 @@ class AggregateCommandExecution {
         });
     }
 }
+/**
+ * Runs Aggregate Event reactors and persists their state and Event results.
+ */
 class AggregateEventExecution {
     #repository;
     #routing;
     #runtime;
     #event;
     #support;
+    /**
+     * Captures Event routing and tenant-scoped Aggregate storage services.
+     *
+     * @param repository Aggregate repository receiving the Event.
+     * @param routing Registered Event routes and schemas.
+     * @param runtime Built context services.
+     * @param event Source Event to react to.
+     */
     constructor(repository, routing, runtime, event) {
         this.#repository = repository;
         this.#routing = routing;
@@ -592,6 +834,13 @@ class AggregateEventExecution {
         this.#event = event;
         this.#support = new AggregateExecutionSupport(repository, runtime, RepositoryTenants.storageContextForEvent(this.#runtime.context, this.#event));
     }
+    /**
+     * Executes matching reactors for one routed Aggregate target.
+     *
+     * @param entityId Target Aggregate identifier.
+     * @param acceptedRoute Route accepted before execution.
+     * @returns Completion after matching reactors run.
+     */
     async runTarget(entityId, acceptedRoute) {
         const intake = this.#readIntake(acceptedRoute);
         if (intake.reactors.length === 0) {
@@ -599,40 +848,74 @@ class AggregateEventExecution {
         }
         await this.#executeEntity(entityId, intake);
     }
+    /**
+     * Decodes the Event and selects reactors, including state-only handlers.
+     *
+     * @param acceptedRoute Route accepted before execution.
+     * @returns Decoded message, route, and matching reactors.
+     */
     #readIntake(acceptedRoute) {
         const eventMessage = EntityInvocation.requireSignalMessage(this.#event.message, "event");
         const eventSchema = RepositoryRoutes.schemaForTypeUrl(this.#routing.eventSchemas, eventMessage.typeUrl, "event");
         const message = EntityInvocation.unpackRequired(eventMessage, eventSchema, "event");
         const route = acceptedRoute;
-        const reactors = this.#routing
-            .eventReactors(route.messageFullTypeName, message, this.#event.context?.external === true)
-            .filter((reactor) => RepositoryHandlers.handlerEmittedSchemas(reactor.handler).length > 0);
+        const reactors = this.#routing.eventReactors(route.messageFullTypeName, message, this.#event.context?.external === true);
         return Object.freeze({
             message,
             route,
             reactors: Object.freeze([...reactors]),
         });
     }
+    /**
+     * Invokes reactors, persists their result, and journals the source Event.
+     *
+     * @param entityId Target Aggregate identifier.
+     * @param intake Decoded Event and matching reactors.
+     * @returns Completion after persistence and journaling.
+     */
     async #executeEntity(entityId, intake) {
         const loaded = await this.#support.loadAggregate(entityId);
         const produced = await this.#invokeHandlers(entityId, loaded, intake);
-        await this.#persistProducedEvents(loaded, entityId, produced);
-        await this.#support.appendDiagnosticEvent(loaded, entityId, DispatchGuards.guardedJournalEvent(this.#repository, this.#event, entityId));
+        const source = DispatchGuards.guardedJournalEvent(this.#repository, this.#event, entityId);
+        await this.#persistProducedEvents(loaded, entityId, produced, source);
         return undefined;
     }
-    async #persistProducedEvents(loaded, entityId, produced) {
-        if (produced.length === 0)
+    /**
+     * Stores changed state or produced Events and schedules reactor publication.
+     *
+     * @param loaded Aggregate and commit storage.
+     * @param entityId Target Aggregate identifier.
+     * @param produced Events returned by reactors.
+     * @param source Source Event retained for diagnostic history.
+     * @returns Completion after accepted state and Events are stored.
+     */
+    async #persistProducedEvents(loaded, entityId, produced, source) {
+        if (produced.length === 0 && !RepositoryEntities.repositoryChanged(loaded.entity)) {
+            await this.#support.appendDiagnosticEvent(loaded, entityId, source);
             return;
-        const dispatch = await this.#support.persistAggregateAndDispatch(loaded, entityId, loaded.version + 1n, produced, (event) => this.#runtime.publisher.publishReactorEvent(event), () => {
+        }
+        const dispatch = await this.#support.persistAggregateAndDispatch(loaded, entityId, produced, (event) => this.#runtime.publisher.publishReactorEvent(event), () => {
             this.#publishStateChange(loaded, entityId);
-        });
+        }, [source, ...produced]);
         void dispatch();
     }
+    /**
+     * Publishes an Entity state-change System Event when the Aggregate changed.
+     *
+     * @param loaded Aggregate before and after handling.
+     * @param entityId Target Aggregate identifier.
+     */
     #publishStateChange(loaded, entityId) {
         if (!RepositoryEntities.repositoryChanged(loaded.entity))
             return;
         EntityStateChangePublisher.event(this.#runtime, this.#repository, this.#event, entityId, loaded.oldState, this.#lifecycleSnapshot(loaded), RepositoryEntities.repositoryState(loaded.entity), RepositoryEntities.repositoryLifecycle(loaded.entity), RepositorySignals.eventVersionNumber(loaded.version + 1n));
     }
+    /**
+     * Reads lifecycle flags from the prior stored Aggregate record.
+     *
+     * @param loaded Aggregate with its optional prior record.
+     * @returns Prior flags, or `undefined` for a new Aggregate.
+     */
     #lifecycleSnapshot(loaded) {
         return loaded.current === undefined
             ? undefined
@@ -641,13 +924,21 @@ class AggregateEventExecution {
                 deleted: loaded.current.lifecycleFlags?.deleted ?? false,
             };
     }
+    /**
+     * Invokes matching reactors in one Entity transaction and commits their changes.
+     *
+     * @param entityId Target Aggregate identifier.
+     * @param loaded Restored Aggregate and version.
+     * @param intake Decoded Event and matching reactors.
+     * @returns Frozen list of produced Events.
+     */
     async #invokeHandlers(entityId, loaded, intake) {
         const eventContext = EntityInvocation.eventHandlerContext(this.#event);
         const events = [];
         transactionalEntityAccess.start(loaded.entity);
         try {
             await this.#invokeReactors(entityId, loaded, intake, eventContext, events);
-            await this.#commitEntity(loaded.entity);
+            await this.#commitEntity(loaded.entity, events.length > 0);
             return Object.freeze(events);
         }
         catch (error) {
@@ -655,23 +946,57 @@ class AggregateEventExecution {
             throw error;
         }
     }
+    /**
+     * Invokes each reactor, checks its declared output, and collects bound Events.
+     *
+     * @param entityId Target Aggregate identifier.
+     * @param loaded Restored Aggregate and producer version.
+     * @param intake Decoded Event and matching reactors.
+     * @param eventContext Copied source Event context.
+     * @param events Output list to append to.
+     * @returns Completion after all reactors run.
+     */
     async #invokeReactors(entityId, loaded, intake, eventContext, events) {
         if (intake.reactors.length > 0)
             HandlerDispatchPublisher.reactor(this.#runtime, this.#repository, this.#event, entityId);
         for (const reactor of intake.reactors) {
             const produced = await EntityInvocation.invokeEntityMethod(loaded.entity, reactor.handler.methodName, intake.message, reactor.handler.parameterCount, eventContext);
-            events.push(...this.#bindProducedEvents(this.#support.normalizeProducedSignals(produced), entityId, loaded.version));
+            RepositoryHandlers.requireDeclaredOutputs(reactor.handler, this.#support.normalizeProducedSignals(produced));
+            events.push(...this.#bindProducedEvents(this.#support.normalizeProducedSignals(produced), entityId, RepositoryEntities.priorVersion(loaded.current)));
         }
     }
-    async #commitEntity(entity) {
-        const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
+    /**
+     * Applies a fenced Entity commit and raises transition rejection.
+     *
+     * @param entity Aggregate instance to commit.
+     * @param producedEvents Whether reactors produced Events.
+     * @returns Completion after a successful fenced commit.
+     */
+    async #commitEntity(entity, producedEvents) {
+        const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, producedEvents));
         if (commit.status === "rejected")
             throw new TransitionValidationError(commit.validation.error);
     }
+    /**
+     * Binds reactor results using the pre-dispatch Aggregate version.
+     *
+     * @param produced Domain Event messages from reactors.
+     * @param entityId Target Aggregate identifier.
+     * @param lastVersion Producer version before this Event.
+     * @returns Frozen Event envelope list.
+     */
     #bindProducedEvents(produced, entityId, lastVersion) {
         const version = lastVersion;
         return Object.freeze(produced.map((signal) => this.#bindProducedEvent(signal, entityId, version)));
     }
+    /**
+     * Packs a declared reactor result with source and producer context.
+     *
+     * @param signal One domain Event message.
+     * @param entityId Target Aggregate identifier.
+     * @param version Producer version before dispatch.
+     * @returns Bound Event envelope.
+     */
     #bindProducedEvent(signal, entityId, version) {
         const typeName = EntityInvocation.messageTypeName(signal);
         const schema = this.#routing.producedEventSchemas.find((candidate) => candidate.typeName === typeName);
@@ -679,21 +1004,33 @@ class AggregateEventExecution {
             throw new Error(`Repository aggregate execution cannot pack event message "${typeName}".`);
         }
         const metadata = this.#runtime.signalMetadata.eventFromEvent(this.#event, {
-            version: RepositorySignals.eventVersionNumber(version),
+            version: version.number,
         });
         return create(EventSchema, {
             id: metadata.id,
             message: AnyMessages.pack(schema, signal),
-            context: RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId),
+            context: RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId, version),
         });
     }
 }
+/**
+ * Routes subscribed Events and state updates to a Projection.
+ */
 class ProjectionEventExecution {
     #repository;
     #routing;
     #runtime;
     #event;
     #rebuild;
+    /**
+     * Captures Projection routing, runtime, source Event, and loading mode.
+     *
+     * @param repository Projection repository receiving the Event.
+     * @param routing Registered Event and state routes.
+     * @param runtime Built context services.
+     * @param event Source Event to deliver.
+     * @param rebuild Whether to restore deleted state for rebuilding.
+     */
     constructor(repository, routing, runtime, event, rebuild = false) {
         this.#repository = repository;
         this.#routing = routing;
@@ -701,10 +1038,28 @@ class ProjectionEventExecution {
         this.#event = event;
         this.#rebuild = rebuild;
     }
+    /**
+     * Delivers a decoded Entity state update to one Projection target.
+     *
+     * @param repository Projection repository receiving the update.
+     * @param routing Registered state-update routes.
+     * @param runtime Built context services.
+     * @param event Source state-change System Event.
+     * @param entityId Target Projection identifier.
+     * @param route Accepted state-update route.
+     * @param subscribers State subscribers to invoke.
+     * @returns Completion after the target receives the state.
+     */
     static async runStateTarget(repository, routing, runtime, event, entityId, route, subscribers) {
         const execution = new ProjectionEventExecution(repository, routing, runtime, event);
         await execution.#executeStateTarget(entityId, route.state, subscribers);
     }
+    /**
+     * Delivers an accepted Event to the durable Projection inbox.
+     *
+     * @param acceptedRoute Route accepted before dispatch.
+     * @returns Completion after inbox handoff.
+     */
     async run(acceptedRoute) {
         const intake = this.#readIntake(acceptedRoute);
         if (intake.subscribers.length === 0) {
@@ -714,6 +1069,13 @@ class ProjectionEventExecution {
             await InboxHandoff.handoffProjectionEvent(this.#repository, this.#runtime, this.#event, entityId);
         }
     }
+    /**
+     * Delivers an accepted Event for one Projection target.
+     *
+     * @param entityId Target Projection identifier.
+     * @param acceptedRoute Route accepted before replay.
+     * @returns Completion after target delivery.
+     */
     async runTarget(entityId, acceptedRoute) {
         const intake = this.#readIntake(acceptedRoute);
         if (intake.subscribers.length === 0) {
@@ -721,6 +1083,12 @@ class ProjectionEventExecution {
         }
         await this.#executeTarget(entityId, intake.subscribers);
     }
+    /**
+     * Dispatches directly to all routed Projection targets.
+     *
+     * @param acceptedRoute Route accepted before direct dispatch, when present.
+     * @returns Completion after all targets receive the Event.
+     */
     async runDirect(acceptedRoute) {
         const intake = this.#readIntake(acceptedRoute);
         if (intake.subscribers.length === 0) {
@@ -730,6 +1098,13 @@ class ProjectionEventExecution {
             await this.#executeTarget(entityId, intake.subscribers);
         }
     }
+    /**
+     * Invokes Event subscribers and stores a changed Projection state.
+     *
+     * @param entityId Target Projection identifier.
+     * @param subscribers Selected Event subscribers.
+     * @returns Completion after handling and any state commit.
+     */
     async #executeTarget(entityId, subscribers) {
         const packedMessage = EntityInvocation.requireSignalMessage(this.#event.message, "event");
         const tenantOptions = RepositoryTenants.standTenantOptions(this.#runtime.context, this.#event);
@@ -741,6 +1116,14 @@ class ProjectionEventExecution {
             ? undefined
             : EntityRecords.unpack(this.#repository.stateSchema, loaded.current).state, mode);
     }
+    /**
+     * Invokes state subscribers and stores a changed Projection state.
+     *
+     * @param entityId Target Projection identifier.
+     * @param state Decoded source Entity state.
+     * @param subscribers Selected state subscribers.
+     * @returns Completion after handling and any state commit.
+     */
     async #executeStateTarget(entityId, state, subscribers) {
         const tenantOptions = RepositoryTenants.standTenantOptions(this.#runtime.context, this.#event);
         const loaded = await this.#loadProjection(entityId, tenantOptions, "stored");
@@ -749,6 +1132,12 @@ class ProjectionEventExecution {
             ? undefined
             : EntityRecords.unpack(this.#repository.stateSchema, loaded.current).state, "stored");
     }
+    /**
+     * Resolves the route, decodes the Event, and filters its subscribers.
+     *
+     * @param acceptedRoute Route accepted before delivery, when present.
+     * @returns Route and matching subscribers.
+     */
     #readIntake(acceptedRoute) {
         const route = acceptedRoute ?? this.#repository.routeEvent(this.#event);
         const packedMessage = EntityInvocation.requireSignalMessage(this.#event.message, "event");
@@ -760,61 +1149,119 @@ class ProjectionEventExecution {
             subscribers,
         });
     }
+    /**
+     * Persists changed Projection state, notifies Stand, and publishes the change.
+     *
+     * @param loaded Projection and commit storage.
+     * @param tenantOptions Stand tenant selection.
+     * @param oldState State before delivery, when present.
+     * @param mode Stored or rebuild loading mode.
+     * @returns Completion after a changed state is stored and published.
+     */
     async #storeIfChanged(loaded, tenantOptions, oldState, mode) {
         if (!RepositoryEntities.repositoryChanged(loaded.entity)) {
             return;
         }
         const entityId = loaded.entity.id;
         const state = RepositoryEntities.repositoryState(loaded.entity);
-        const version = BigInt(this.#event.context?.version?.number ?? 0);
+        const version = RepositoryEntities.repositoryVersion(loaded.entity);
         const lifecycle = RepositoryEntities.repositoryLifecycle(loaded.entity);
-        const deferred = await standAccess.deferUpdate(this.#runtime.stand, this.#repository.stateSchema, state, RepositoryStand.standUpdateOptions(tenantOptions.tenantId, this.#event.context?.version, lifecycle));
+        const deferred = await standAccess.deferUpdate(this.#runtime.stand, this.#repository.stateSchema, state, RepositoryStand.standUpdateOptions(tenantOptions.tenantId, version, lifecycle));
+        await this.#commitProjectionOrCancel(loaded, entityId, state, version, lifecycle, deferred);
+        this.#notifyProjection(deferred);
+        this.#publishProjectionChange(loaded, oldState, mode, state, lifecycle, version);
+    }
+    /**
+     * Cancels a deferred Stand update when Projection storage rejects its commit.
+     *
+     * @param loaded Loaded Projection and commit storage.
+     * @param entityId Projection identifier.
+     * @param state Accepted Projection state.
+     * @param version Current Spine Version.
+     * @param lifecycle Accepted lifecycle flags.
+     * @param deferred Deferred Stand update to cancel if storage rejects the commit.
+     * @returns Completion after a successful storage commit.
+     */
+    async #commitProjectionOrCancel(loaded, entityId, state, version, lifecycle, deferred) {
         try {
-            const outcome = await loaded.commits.commit({
-                context: loaded.storageInput.context,
-                entity: loaded.storageInput,
-                entityId,
-                ...(loaded.current === undefined ? {} : { expected: loaded.current }),
-                next: EntityRecords.pack(this.#repository.stateSchema, entityId, state, this.#event.context?.version ?? version, lifecycle),
-                ...(RepositoryStorage.historyConfiguration(this.#repository).stateHistory
-                    ? {
-                        states: [
-                            EntityRecords.pack(this.#repository.stateSchema, entityId, state, this.#event.context?.version ?? version, lifecycle),
-                        ],
-                    }
-                    : {}),
-            });
-            if (outcome !== "committed") {
-                deferred.cancel();
+            const outcome = await this.#commitProjectionRecord(loaded, entityId, state, version, lifecycle);
+            if (outcome !== "committed")
                 throw new Error("Concurrent Projection state commit conflict.");
-            }
         }
         catch (error) {
             deferred.cancel();
             throw error;
         }
+    }
+    /**
+     * Notifies Stand after a Projection commit and reports delivery failure.
+     *
+     * @param deferred Deferred Stand update to notify.
+     */
+    #notifyProjection(deferred) {
         try {
             deferred.notify();
         }
         catch (error) {
             this.#runtime.publisher.reportFailure("event", this.#event, error);
         }
-        EntityStateChangePublisher.event(this.#runtime, this.#repository, this.#event, entityId, oldState, mode === "rebuild"
+    }
+    /**
+     * Persists one Projection update with the same Version in current and history records.
+     *
+     * @param loaded Loaded Projection and commit storage.
+     * @param entityId Projection identifier.
+     * @param state Accepted Projection state.
+     * @param version Current Spine Version.
+     * @param lifecycle Accepted lifecycle flags.
+     * @returns The storage commit outcome.
+     */
+    #commitProjectionRecord(loaded, entityId, state, version, lifecycle) {
+        const record = EntityRecords.pack(this.#repository.stateSchema, entityId, state, version, lifecycle);
+        return loaded.commits.commit({
+            context: loaded.storageInput.context,
+            entity: loaded.storageInput,
+            entityId,
+            ...(loaded.current === undefined ? {} : { expected: loaded.current }),
+            next: record,
+            ...(RepositoryStorage.historyConfiguration(this.#repository).stateHistory
+                ? { states: [record] }
+                : {}),
+        });
+    }
+    /**
+     * Publishes a Projection state change with its committed Entity version.
+     *
+     * @param loaded Loaded Projection and prior record.
+     * @param oldState State before dispatch, when available.
+     * @param mode Normal or rebuilding delivery mode.
+     * @param state Accepted Projection state.
+     * @param lifecycle Accepted lifecycle flags.
+     * @param version Committed Spine Version.
+     */
+    #publishProjectionChange(loaded, oldState, mode, state, lifecycle, version) {
+        EntityStateChangePublisher.event(this.#runtime, this.#repository, this.#event, loaded.entity.id, oldState, mode === "rebuild"
             ? lifecycle
             : loaded.current === undefined
                 ? undefined
                 : {
                     archived: loaded.current.lifecycleFlags?.archived ?? false,
                     deleted: loaded.current.lifecycleFlags?.deleted ?? false,
-                }, state, lifecycle, this.#event.context?.version?.number ?? 0);
+                }, state, lifecycle, version.number);
     }
+    /**
+     * Invokes Event subscribers in one Entity transaction.
+     *
+     * @param entity Projection instance to update.
+     * @param subscribers Selected Event subscribers.
+     * @param packedMessage Packed source Event message.
+     * @returns Completion after the subscriber transaction commits.
+     */
     async #invokeSubscribers(entity, subscribers, packedMessage) {
         transactionalEntityAccess.start(entity);
         try {
             for (const subscriber of subscribers) {
-                const subscriberMessage = EntityInvocation.unpackRequired(packedMessage, subscriber.handler.schema, "event");
-                const eventContext = EntityInvocation.eventHandlerContext(this.#event);
-                await EntityInvocation.invokeEntityMethod(entity, subscriber.handler.methodName, subscriberMessage, subscriber.handler.parameterCount, eventContext);
+                await this.#invokeSubscriber(entity, subscriber, packedMessage);
             }
             const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
             if (commit.status === "rejected") {
@@ -826,12 +1273,37 @@ class ProjectionEventExecution {
             throw error;
         }
     }
+    /**
+     * Invokes one Event subscriber and checks its raw return value.
+     *
+     * @param entity Projection instance to update.
+     * @param subscriber Selected Event subscriber.
+     * @param packedMessage Packed source Event message.
+     * @returns Completion after the subscriber returns undefined.
+     */
+    async #invokeSubscriber(entity, subscriber, packedMessage) {
+        const message = EntityInvocation.unpackRequired(packedMessage, subscriber.handler.schema, "event");
+        const context = EntityInvocation.eventHandlerContext(this.#event);
+        const result = await EntityInvocation.invokeEntityMethod(entity, subscriber.handler.methodName, message, subscriber.handler.parameterCount, context);
+        if (result !== undefined)
+            throw new Error(`Projection subscriber "${subscriber.handler.methodName}" must not return signals.`);
+    }
+    /**
+     * Invokes state subscribers in one Entity transaction.
+     *
+     * @param entity Projection instance to update.
+     * @param subscribers Selected state subscribers.
+     * @param state Decoded source Entity state.
+     * @returns Completion after the subscriber transaction commits.
+     */
     async #invokeStateSubscribers(entity, subscribers, state) {
         transactionalEntityAccess.start(entity);
         try {
             for (const subscriber of subscribers) {
                 const context = EntityInvocation.eventHandlerContext(this.#event);
-                await EntityInvocation.invokeEntityMethod(entity, subscriber.handler.methodName, state, subscriber.handler.parameterCount, context);
+                const result = await EntityInvocation.invokeEntityMethod(entity, subscriber.handler.methodName, state, subscriber.handler.parameterCount, context);
+                if (result !== undefined)
+                    throw new Error(`Projection subscriber "${subscriber.handler.methodName}" must not return signals.`);
             }
             const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
             if (commit.status === "rejected")
@@ -842,41 +1314,34 @@ class ProjectionEventExecution {
             throw error;
         }
     }
+    /**
+     * Restores or creates a Projection and binds its storage history.
+     *
+     * @param entityId Target Projection identifier.
+     * @param options Stand tenant selection.
+     * @param mode Stored or rebuild loading mode.
+     * @returns Loaded Projection, current record, and commit storage.
+     */
     async #loadProjection(entityId, options, mode) {
         const stored = await standAccess.readCurrent(this.#runtime.stand, this.#repository.stateSchema, entityId, options);
-        const entityType = this.#repository.entityType;
-        const entity = new entityType({
-            id: entityId,
-            schema: this.#repository.stateSchema,
-            state: stored === undefined || (mode === "rebuild" && stored.deleted)
-                ? this.#defaultState(entityId)
-                : stored.state,
-            version: mode === "rebuild" && stored?.deleted
-                ? 0
-                : RepositoryStand.projectionVersion(stored?.version),
-            lifecycle: mode === "rebuild" && stored?.deleted
-                ? { archived: false, deleted: false }
-                : { archived: stored?.archived ?? false, deleted: stored?.deleted ?? false },
-        });
-        const storageInput = RepositoryStorage.entityStorageInput(this.#repository, RepositoryTenants.storageContextForTenant(this.#runtime.context, options.tenantId));
-        const storage = RepositoryStorage.openRepositoryEntityStorage(this.#repository, this.#runtime.storageFactory, storageInput);
-        RepositoryHistoryInternals.bindEntityHistory(entity, storage, entityId, this.#repository.stateSchema);
-        return Object.freeze({
-            commits: storage.commits,
-            current: stored === undefined
-                ? undefined
-                : EntityRecords.pack(this.#repository.stateSchema, entityId, stored.state, stored.versionMessage, { archived: stored.archived, deleted: stored.deleted }),
-            entity,
-            storageInput,
-        });
-    }
-    #defaultState(entityId) {
-        return create(this.#repository.stateSchema, {
-            [this.#repository.idField.localName]: entityId,
-        });
+        const entity = RepositoryEntities.instantiate(this.#repository, entityId, stored, mode === "rebuild" && stored?.deleted === true);
+        const { commits, events, storageInput } = RepositoryEntities.bindStorage(this.#repository, this.#runtime, options.tenantId, entityId, entity);
+        return RepositoryEntities.loaded(entity, stored, commits, events, storageInput, this.#repository.stateSchema, entityId);
     }
 }
+/**
+ * Binds Process Manager query access to Stand for one handler invocation.
+ */
 const ProcessManagerQueries = Object.freeze({
+    /**
+     * Binds tenant-aware query reads and returns a release callback.
+     *
+     * @param entity Process Manager receiving query access.
+     * @param runtime Context Stand and query services.
+     * @param actorContext Actor metadata from the source signal.
+     * @param tenantId Tenant for query reads, when present.
+     * @returns Callback that removes the query binding.
+     */
     bind(entity, runtime, actorContext, tenantId) {
         const context = actorContext === undefined
             ? create(ActorContextSchema)
@@ -890,108 +1355,169 @@ const ProcessManagerQueries = Object.freeze({
         }, context);
     },
 });
+/**
+ * Loads and commits Process Manager state and optional diagnostic history.
+ */
 class ProcessManagerExecutionSupport {
     #repository;
     #runtime;
+    /**
+     * Binds a Process Manager repository to its runtime services.
+     *
+     * @param repository Process Manager repository being executed.
+     * @param runtime Built context services.
+     */
     constructor(repository, runtime) {
         this.#repository = repository;
         this.#runtime = runtime;
     }
+    /**
+     * Normalizes a handler result to a frozen signal list.
+     *
+     * @param produced Raw handler result.
+     * @returns No signals, one signal, or the copied result array.
+     */
     normalizeProducedSignals(produced) {
         if (produced === undefined) {
             return Object.freeze([]);
         }
         if (Array.isArray(produced)) {
-            return Object.freeze(Array.from(produced));
+            return Object.freeze(Array.from(produced).filter((item) => item !== undefined));
         }
         return Object.freeze([produced]);
     }
+    /**
+     * Restores or creates a Process Manager and binds its history storage.
+     *
+     * @param entityId Process Manager identifier to load.
+     * @param options Stand tenant selection.
+     * @returns Loaded instance, current record, and commit storage.
+     */
     async load(entityId, options) {
         const stored = await standAccess.readCurrent(this.#runtime.stand, this.#repository.stateSchema, entityId, options);
-        const entityType = this.#repository.entityType;
-        const entity = new entityType({
-            id: entityId,
-            schema: this.#repository.stateSchema,
-            state: stored === undefined ? this.#defaultState(entityId) : stored.state,
-            version: RepositoryStand.projectionVersion(stored?.version),
-            lifecycle: { archived: stored?.archived ?? false, deleted: stored?.deleted ?? false },
-        });
-        const storageInput = RepositoryStorage.entityStorageInput(this.#repository, RepositoryTenants.storageContextForTenant(this.#runtime.context, options.tenantId));
-        const storage = RepositoryStorage.openRepositoryEntityStorage(this.#repository, this.#runtime.storageFactory, storageInput);
-        RepositoryHistoryInternals.bindEntityHistory(entity, storage, entityId, this.#repository.stateSchema);
-        return Object.freeze({
-            commits: storage.commits,
-            current: stored === undefined
-                ? undefined
-                : EntityRecords.pack(this.#repository.stateSchema, entityId, stored.state, stored.versionMessage, { archived: stored.archived, deleted: stored.deleted }),
-            entity,
-            storageInput,
-        });
+        const entity = RepositoryEntities.instantiate(this.#repository, entityId, stored, false);
+        const { commits, events, storageInput } = RepositoryEntities.bindStorage(this.#repository, this.#runtime, options.tenantId, entityId, entity);
+        return RepositoryEntities.loaded(entity, stored, commits, events, storageInput, this.#repository.stateSchema, entityId);
     }
-    async commit(loaded, options, createdAt, events) {
-        const changed = RepositoryEntities.repositoryChanged(loaded.entity);
-        if (!changed && events.length === 0)
+    /**
+     * Stores changed Process Manager state or produced Events under one Version.
+     *
+     * @param loaded Process Manager and commit storage.
+     * @param options Stand tenant selection.
+     * @param events Produced or diagnostic Events to retain when configured.
+     * @returns `true` after a successful commit or unchanged no-op.
+     */
+    async commit(loaded, options, events) {
+        const version = RepositoryEntities.repositoryVersion(loaded.entity);
+        const priorNumber = loaded.current?.version?.number ?? 0;
+        if (version.number === priorNumber) {
+            await this.#appendUnchangedDiagnostics(loaded, events);
             return true;
+        }
         const entityId = loaded.entity.id;
         const state = RepositoryEntities.repositoryState(loaded.entity);
         const lifecycle = RepositoryEntities.repositoryLifecycle(loaded.entity);
-        const version = changed
-            ? BigInt(RepositoryStand.processManagerVersion(loaded.entity))
-            : BigInt(loaded.current?.version?.number ?? 0);
-        const deferred = changed
-            ? await standAccess.deferUpdate(this.#runtime.stand, this.#repository.stateSchema, state, RepositoryStand.standUpdateOptions(options.tenantId, create(VersionSchema, { number: Number(version) }), lifecycle))
-            : undefined;
+        const deferred = await standAccess.deferUpdate(this.#runtime.stand, this.#repository.stateSchema, state, RepositoryStand.standUpdateOptions(options.tenantId, version, lifecycle));
+        await this.#storeProcessManagerRecord(loaded, entityId, state, version, lifecycle, events, deferred);
+        this.#notifyProcessManager(deferred, events);
+        return true;
+    }
+    /**
+     * Writes configured Process Manager diagnostics without storing unchanged state.
+     *
+     * @param loaded Process Manager and its diagnostic Event history.
+     * @param events Input and produced Events to retain when history is configured.
+     * @returns Completion after all configured diagnostic Events are appended.
+     */
+    async #appendUnchangedDiagnostics(loaded, events) {
+        if (!RepositoryStorage.historyConfiguration(this.#repository).processManagerEventHistory)
+            return;
+        for (const event of events)
+            await loaded.events.append(clone(EventSchema, event));
+    }
+    /**
+     * Stores accepted Process Manager state and cancels Stand notification on failure.
+     *
+     * @param loaded Process Manager and commit storage.
+     * @param entityId Process Manager identifier.
+     * @param state Accepted Process Manager state.
+     * @param version Current Spine Version.
+     * @param lifecycle Accepted lifecycle flags.
+     * @param events Diagnostic Events to retain when configured.
+     * @param deferred Stand update to notify or cancel.
+     * @returns Completion after durable persistence.
+     */
+    async #storeProcessManagerRecord(loaded, entityId, state, version, lifecycle, events, deferred) {
         try {
-            const history = RepositoryStorage.historyConfiguration(this.#repository);
-            const outcome = await loaded.commits.commit({
-                context: loaded.storageInput.context,
-                entity: loaded.storageInput,
-                entityId,
-                ...(loaded.current === undefined ? {} : { expected: loaded.current }),
-                next: EntityRecords.pack(this.#repository.stateSchema, entityId, state, version, lifecycle),
-                ...(changed && history.stateHistory
-                    ? {
-                        states: [
-                            EntityRecords.pack(this.#repository.stateSchema, entityId, state, create(VersionSchema, { number: Number(version), timestamp: createdAt }), lifecycle),
-                        ],
-                    }
-                    : {}),
-                ...(history.processManagerEventHistory
-                    ? {
-                        diagnostics: events.map((event) => clone(EventSchema, event)),
-                    }
-                    : {}),
-            });
+            const outcome = await this.#commitProcessManagerRecord(loaded, entityId, state, version, lifecycle, events);
             if (outcome !== "committed") {
-                deferred?.cancel();
                 throw new Error("Concurrent Process Manager state commit conflict.");
             }
             entityStateHistoryCaches.get(loaded.entity)?.clear();
         }
         catch (error) {
-            deferred?.cancel();
+            deferred.cancel();
             throw error;
         }
+    }
+    /**
+     * Stores one Process Manager version in current and optional history records.
+     *
+     * @param loaded Loaded Process Manager and commit storage.
+     * @param entityId Process Manager identifier.
+     * @param state Accepted Process Manager state.
+     * @param version Current Spine Version.
+     * @param lifecycle Accepted lifecycle flags.
+     * @param events Diagnostic Events to retain when configured.
+     * @returns The storage commit outcome.
+     */
+    #commitProcessManagerRecord(loaded, entityId, state, version, lifecycle, events) {
+        const history = RepositoryStorage.historyConfiguration(this.#repository);
+        const record = EntityRecords.pack(this.#repository.stateSchema, entityId, state, version, lifecycle);
+        return loaded.commits.commit({
+            context: loaded.storageInput.context,
+            entity: loaded.storageInput,
+            entityId,
+            ...(loaded.current === undefined ? {} : { expected: loaded.current }),
+            next: record,
+            ...(history.stateHistory ? { states: [record] } : {}),
+            ...(history.processManagerEventHistory
+                ? { diagnostics: events.map((event) => clone(EventSchema, event)) }
+                : {}),
+        });
+    }
+    /**
+     * Notifies Stand after a Process Manager commit and reports delivery failure.
+     *
+     * @param deferred Deferred Stand update to notify.
+     * @param events Produced or diagnostic Events available for failure reporting.
+     */
+    #notifyProcessManager(deferred, events) {
         try {
-            deferred?.notify();
+            deferred.notify();
         }
         catch (error) {
             this.#runtime.publisher.reportFailure("event", events[events.length - 1] ?? create(EventSchema), error);
         }
-        return true;
-    }
-    #defaultState(entityId) {
-        return create(this.#repository.stateSchema, {
-            [this.#repository.idField.localName]: entityId,
-        });
     }
 }
+/**
+ * Executes a routed Process Manager Command and publishes its results.
+ */
 class ProcessManagerCommandExecution {
     #repository;
     #routing;
     #runtime;
     #command;
     #support;
+    /**
+     * Captures Process Manager routing, runtime, and source Command.
+     *
+     * @param repository Process Manager repository receiving the Command.
+     * @param routing Registered Command routes and schemas.
+     * @param runtime Built context services.
+     * @param command Source Command to execute.
+     */
     constructor(repository, routing, runtime, command) {
         this.#repository = repository;
         this.#routing = routing;
@@ -999,6 +1525,12 @@ class ProcessManagerCommandExecution {
         this.#command = command;
         this.#support = new ProcessManagerExecutionSupport(repository, runtime);
     }
+    /**
+     * Invokes the registered Command handler and commits its results.
+     *
+     * @param replayedRoute Accepted route from durable inbox replay, when present.
+     * @returns A deferred Command follow-up, rejection follow-up, or `undefined`.
+     */
     async run(replayedRoute) {
         RepositorySignals.requireCommandId(this.#command);
         const intake = this.#readIntake(replayedRoute);
@@ -1018,9 +1550,20 @@ class ProcessManagerCommandExecution {
             return RepositorySignals.postRejectionEvent(this.#runtime, this.#repository, this.#command, intake.route.entityId, error);
         }
     }
+    /**
+     * Publishes a best-effort Command dispatch diagnostic.
+     *
+     * @param entityId Target Process Manager identifier.
+     */
     #publishDispatch(entityId) {
         HandlerDispatchPublisher.command(this.#runtime, this.#repository, this.#command, entityId);
     }
+    /**
+     * Decodes a registered Command and finds its assignee.
+     *
+     * @param replayedRoute Accepted inbox route, when present.
+     * @returns Decoded Command, route, and assignee, or `undefined`.
+     */
     #readIntake(replayedRoute) {
         const commandMessage = EntityInvocation.requireSignalMessage(this.#command.message, "command");
         const commandSchema = RepositoryRoutes.schemaForTypeUrl(this.#routing.commandSchemas, commandMessage.typeUrl, "command");
@@ -1029,10 +1572,19 @@ class ProcessManagerCommandExecution {
         const assignee = this.#routing.commandReadiness?.findCommandAssignee(route.messageFullTypeName);
         return assignee === undefined ? undefined : Object.freeze({ assignee, message, route });
     }
+    /**
+     * Commits Process Manager changes and publishes produced Events and Commands.
+     *
+     * @param loaded Process Manager and commit storage.
+     * @param tenantOptions Stand tenant selection.
+     * @param intake Assignee and target route.
+     * @param producedSignals Validated handler results.
+     * @returns Deferred Command publication when Commands were produced.
+     */
     async #commitAndPublish(loaded, tenantOptions, intake, producedSignals) {
         const commands = this.#commandOutputs(intake.assignee, producedSignals);
-        const events = this.#eventOutputs(intake.assignee, producedSignals, intake.route.entityId);
-        const committed = await this.#support.commit(loaded, tenantOptions, RepositorySignals.executionTimestamp(), events);
+        const events = this.#eventOutputs(intake.assignee, producedSignals, intake.route.entityId, RepositoryEntities.priorVersion(loaded.current));
+        const committed = await this.#support.commit(loaded, tenantOptions, events);
         if (!committed)
             return undefined;
         this.#publishChangedState(loaded, intake.route.entityId);
@@ -1043,6 +1595,13 @@ class ProcessManagerCommandExecution {
                 await this.#postCommands(commands, this.#command);
             };
     }
+    /**
+     * Binds substitution results as Commands and requires nonempty output.
+     *
+     * @param assignee Invoked Command handler declaration.
+     * @param produced Validated handler results.
+     * @returns Bound Commands, or an empty list for assignment handlers.
+     */
     #commandOutputs(assignee, produced) {
         if (assignee.handler.kind !== "command-substitution")
             return Object.freeze([]);
@@ -1052,11 +1611,26 @@ class ProcessManagerCommandExecution {
         }
         return commands;
     }
-    #eventOutputs(assignee, produced, entityId) {
+    /**
+     * Binds assignment results as Events.
+     *
+     * @param assignee Invoked Command handler declaration.
+     * @param produced Validated handler results.
+     * @param entityId Target Process Manager identifier.
+     * @param version Process Manager Version before this dispatch.
+     * @returns Bound Events, or an empty list for substitution handlers.
+     */
+    #eventOutputs(assignee, produced, entityId, version) {
         return assignee.handler.kind === "command-assignment"
-            ? this.#bindProducedEvents(produced, entityId)
+            ? this.#bindProducedEvents(produced, entityId, version)
             : Object.freeze([]);
     }
+    /**
+     * Publishes a state-change System Event when the Process Manager changed.
+     *
+     * @param loaded Process Manager before and after handling.
+     * @param entityId Target Process Manager identifier.
+     */
     #publishChangedState(loaded, entityId) {
         if (RepositoryEntities.repositoryChanged(loaded.entity)) {
             EntityStateChangePublisher.command(this.#runtime, this.#repository, this.#command, entityId, loaded.current === undefined
@@ -1066,9 +1640,18 @@ class ProcessManagerCommandExecution {
                 : {
                     archived: loaded.current.lifecycleFlags?.archived ?? false,
                     deleted: loaded.current.lifecycleFlags?.deleted ?? false,
-                }, RepositoryEntities.repositoryState(loaded.entity), RepositoryEntities.repositoryLifecycle(loaded.entity), RepositoryStand.processManagerVersion(loaded.entity));
+                }, RepositoryEntities.repositoryState(loaded.entity), RepositoryEntities.repositoryLifecycle(loaded.entity), RepositoryEntities.repositoryVersion(loaded.entity).number);
         }
     }
+    /**
+     * Binds query access for one Command handler invocation.
+     *
+     * @param entity Process Manager instance.
+     * @param assignee Registered Command handler.
+     * @param message Decoded Command message.
+     * @param tenantId Tenant for query reads, when present.
+     * @returns Validated handler signals.
+     */
     async #invoke(entity, assignee, message, tenantId) {
         const releaseQuery = ProcessManagerQueries.bind(entity, this.#runtime, this.#command.context?.actorContext, tenantId);
         try {
@@ -1078,43 +1661,73 @@ class ProcessManagerCommandExecution {
             releaseQuery();
         }
     }
+    /**
+     * Invokes the Command handler in a fenced Entity transaction.
+     *
+     * @param entity Process Manager instance to mutate.
+     * @param assignee Registered Command handler.
+     * @param message Decoded Command message.
+     * @returns Validated handler signals after commit.
+     */
     async #invokeCommandHandler(entity, assignee, message) {
         transactionalEntityAccess.start(entity);
         try {
             const produced = await EntityInvocation.invokeEntityMethod(entity, assignee.handler.methodName, message, assignee.handler.parameterCount, EntityInvocation.commandHandlerContext(this.#command));
-            const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
+            const signals = this.#support.normalizeProducedSignals(produced);
+            if (signals.length === 0)
+                throw new Error("Repository Process Manager command handlers must return a signal.");
+            RepositoryHandlers.requireDeclaredOutputs(assignee.handler, signals);
+            const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, assignee.handler.kind === "command-assignment" && signals.length > 0));
             if (commit.status === "rejected") {
                 throw new TransitionValidationError(commit.validation.error);
             }
-            return this.#support.normalizeProducedSignals(produced);
+            return signals;
         }
         catch (error) {
             transactionalEntityAccess.rollback(entity);
             throw error;
         }
     }
-    #bindProducedEvents(produced, entityId) {
-        let sequence = 0;
-        return Object.freeze(produced.map((signal) => {
-            sequence += 1;
-            return this.#bindProducedEvent(signal, entityId, sequence);
-        }));
+    /**
+     * Binds assignment results as Process Manager Events.
+     *
+     * @param produced Domain Event messages from the handler.
+     * @param entityId Target Process Manager identifier.
+     * @param version Process Manager Version before this dispatch.
+     * @returns Frozen Event envelope list.
+     */
+    #bindProducedEvents(produced, entityId, version) {
+        return Object.freeze(produced.map((signal) => this.#bindProducedEvent(signal, entityId, version)));
     }
-    #bindProducedEvent(signal, entityId, sequence) {
+    /**
+     * Packs one declared Event with source and producer context.
+     *
+     * @param signal Domain Event message to pack.
+     * @param entityId Target Process Manager identifier.
+     * @param version Process Manager Version before this dispatch.
+     * @returns Bound Event envelope.
+     */
+    #bindProducedEvent(signal, entityId, version) {
         const typeName = EntityInvocation.messageTypeName(signal);
         const schema = this.#routing.producedEventSchemas.find((candidate) => candidate.typeName === typeName);
         if (schema === undefined) {
             throw new Error(`Repository process-manager execution cannot pack event message "${typeName}".`);
         }
         const metadata = this.#runtime.signalMetadata.eventFromCommand(this.#command, {
-            version: RepositoryStand.processManagerProducedVersion(sequence),
+            version: version.number,
         });
         return create(EventSchema, {
             id: metadata.id,
             message: AnyMessages.pack(schema, signal),
-            context: RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId),
+            context: RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId, version),
         });
     }
+    /**
+     * Packs declared substitution results as Commands from the source Command.
+     *
+     * @param produced Domain Command messages from the handler.
+     * @returns Frozen Command envelope list.
+     */
     #bindProducedCommands(produced) {
         return Object.freeze(produced.map((signal) => {
             const typeName = EntityInvocation.messageTypeName(signal);
@@ -1130,12 +1743,24 @@ class ProcessManagerCommandExecution {
             });
         }));
     }
+    /**
+     * Publishes each produced Command in handler order.
+     *
+     * @param commands Bound Commands to publish.
+     * @param source Source Command retained for the caller contract.
+     * @returns Completion after all Commands are published.
+     */
     async #postCommands(commands, source) {
         void source;
         for (const command of commands) {
             await this.#runtime.publisher.publishCommand(command);
         }
     }
+    /**
+     * Schedules publication of produced Events.
+     *
+     * @param events Bound Events to publish.
+     */
     #postEvents(events) {
         for (const event of events) {
             // spine-log-boundary: server.repository_event_follow_up
@@ -1143,12 +1768,23 @@ class ProcessManagerCommandExecution {
         }
     }
 }
+/**
+ * Runs Process Manager Event handlers and persists their results.
+ */
 class ProcessManagerEventExecution {
     #repository;
     #routing;
     #runtime;
     #event;
     #support;
+    /**
+     * Captures Process Manager routing, runtime, and source Event.
+     *
+     * @param repository Process Manager repository receiving the Event.
+     * @param routing Registered Event routes and schemas.
+     * @param runtime Built context services.
+     * @param event Source Event to execute.
+     */
     constructor(repository, routing, runtime, event) {
         this.#repository = repository;
         this.#routing = routing;
@@ -1156,6 +1792,12 @@ class ProcessManagerEventExecution {
         this.#event = event;
         this.#support = new ProcessManagerExecutionSupport(repository, runtime);
     }
+    /**
+     * Delivers a routed Event to the durable Process Manager inbox.
+     *
+     * @param acceptedRoute Route accepted before dispatch.
+     * @returns Completion after inbox handoff.
+     */
     async run(acceptedRoute) {
         const intake = this.#readIntake(acceptedRoute);
         if (intake.reactors.length === 0 && intake.commanders.length === 0) {
@@ -1168,6 +1810,13 @@ class ProcessManagerEventExecution {
         }
         await InboxHandoff.handoffPmEvents(this.#repository, this.#runtime, this.#event, intake.route.entityIds);
     }
+    /**
+     * Delivers a routed Event for one target under the duplicate-dispatch guard.
+     *
+     * @param entityId Target Process Manager identifier.
+     * @param acceptedRoute Route accepted before replay.
+     * @returns Completion after guarded target execution.
+     */
     async runTarget(entityId, acceptedRoute) {
         const intake = this.#readIntake(acceptedRoute);
         if (intake.reactors.length === 0 && intake.commanders.length === 0) {
@@ -1178,6 +1827,12 @@ class ProcessManagerEventExecution {
             await this.#executeEntity(entityId, intake);
         });
     }
+    /**
+     * Decodes the Event and selects matching reactors and Command producers.
+     *
+     * @param acceptedRoute Route accepted before execution.
+     * @returns Decoded message, route, reactors, and Command producers.
+     */
     #readIntake(acceptedRoute) {
         const eventMessage = EntityInvocation.requireSignalMessage(this.#event.message, "event");
         const eventSchema = RepositoryRoutes.schemaForTypeUrl(this.#routing.eventSchemas, eventMessage.typeUrl, "event");
@@ -1192,22 +1847,36 @@ class ProcessManagerEventExecution {
             commanders,
         });
     }
+    /**
+     * Invokes handlers, commits state, and publishes resulting Events and Commands.
+     *
+     * @param entityId Target Process Manager identifier.
+     * @param intake Decoded Event and matching handlers.
+     * @returns Completion after accepted results are published.
+     */
     async #executeEntity(entityId, intake) {
         const tenantOptions = RepositoryTenants.standTenantOptions(this.#runtime.context, this.#event);
         const loaded = await this.#support.load(entityId, tenantOptions);
         const produced = await this.#invokeHandlers(entityId, loaded.entity, intake, tenantOptions.tenantId);
-        const events = this.#bindProducedEvents(produced.events, entityId);
+        const events = this.#bindProducedEvents(produced.events, entityId, RepositoryEntities.priorVersion(loaded.current));
+        const commands = this.#bindProducedCommands(produced.commands);
         const diagnostics = [
             DispatchGuards.guardedJournalEvent(this.#repository, this.#event, entityId),
             ...events,
         ];
-        const committed = await this.#support.commit(loaded, tenantOptions, this.#event.context?.timestamp ?? create(TimestampSchema), diagnostics);
+        const committed = await this.#support.commit(loaded, tenantOptions, diagnostics);
         if (!committed)
             return;
         this.#publishChangedState(loaded, entityId);
         this.#postEvents(events);
-        await this.#postCommands(this.#bindProducedCommands(produced.commands));
+        await this.#postCommands(commands);
     }
+    /**
+     * Publishes a state-change System Event when the Process Manager changed.
+     *
+     * @param loaded Process Manager before and after handling.
+     * @param entityId Target Process Manager identifier.
+     */
     #publishChangedState(loaded, entityId) {
         if (!RepositoryEntities.repositoryChanged(loaded.entity))
             return;
@@ -1218,8 +1887,13 @@ class ProcessManagerEventExecution {
             : {
                 archived: loaded.current.lifecycleFlags?.archived ?? false,
                 deleted: loaded.current.lifecycleFlags?.deleted ?? false,
-            }, RepositoryEntities.repositoryState(loaded.entity), RepositoryEntities.repositoryLifecycle(loaded.entity), RepositoryStand.processManagerVersion(loaded.entity));
+            }, RepositoryEntities.repositoryState(loaded.entity), RepositoryEntities.repositoryLifecycle(loaded.entity), RepositoryEntities.repositoryVersion(loaded.entity).number);
     }
+    /**
+     * Validates source Event metadata when handlers can produce follow-ups.
+     *
+     * @param intake Matching reactors and Command producers.
+     */
     #validateSourceEventIdForFollowUps(intake) {
         const emitsFollowUpEvents = intake.reactors.some((reactor) => RepositoryHandlers.handlerEmittedSchemas(reactor.handler).length > 0);
         if (!emitsFollowUpEvents && intake.commanders.length === 0) {
@@ -1227,6 +1901,15 @@ class ProcessManagerEventExecution {
         }
         void this.#runtime.signalMetadata.originFromEvent(this.#event);
     }
+    /**
+     * Invokes Event handlers in one transaction with temporary query access.
+     *
+     * @param entityId Target Process Manager identifier.
+     * @param entity Process Manager instance.
+     * @param intake Decoded Event and matching handlers.
+     * @param tenantId Tenant for query reads, when present.
+     * @returns Validated Command and Event message lists.
+     */
     async #invokeHandlers(entityId, entity, intake, tenantId) {
         const eventContext = EntityInvocation.eventHandlerContext(this.#event);
         const commands = [];
@@ -1235,7 +1918,7 @@ class ProcessManagerEventExecution {
         transactionalEntityAccess.start(entity);
         try {
             await this.#invokeEventHandlers(entityId, entity, intake, eventContext, events, commands);
-            await this.#commitEntity(entity);
+            await this.#commitEntity(entity, events.length > 0);
             return Object.freeze({
                 commands: Object.freeze(commands),
                 events: Object.freeze(events),
@@ -1249,45 +1932,93 @@ class ProcessManagerEventExecution {
             releaseQuery();
         }
     }
+    /**
+     * Invokes reactors and Command producers, collecting their separate outputs.
+     *
+     * @param entityId Target Process Manager identifier.
+     * @param entity Process Manager instance.
+     * @param intake Decoded Event and matching handlers.
+     * @param context Copied source Event context.
+     * @param events Output list for Event messages.
+     * @param commands Output list for Command messages.
+     * @returns Completion after matching handlers run.
+     */
     async #invokeEventHandlers(entityId, entity, intake, context, events, commands) {
         if (intake.reactors.length > 0)
             HandlerDispatchPublisher.reactor(this.#runtime, this.#repository, this.#event, entityId);
         await this.#invokeHandlersInto(entity, intake.reactors, intake.message, context, events);
         await this.#invokeHandlersInto(entity, intake.commanders, intake.message, context, commands);
     }
+    /**
+     * Invokes each selected handler and appends its declared results.
+     *
+     * @param entity Process Manager instance.
+     * @param handlers Handler registrations to invoke.
+     * @param message Decoded source Event message.
+     * @param context Copied source Event context.
+     * @param output Result list to append to.
+     * @returns Completion after all selected handlers run.
+     */
     async #invokeHandlersInto(entity, handlers, message, context, output) {
         for (const handler of handlers) {
             const produced = await EntityInvocation.invokeEntityMethod(entity, handler.handler.methodName, message, handler.handler.parameterCount, context);
-            output.push(...this.#support.normalizeProducedSignals(produced));
+            const signals = this.#support.normalizeProducedSignals(produced);
+            RepositoryHandlers.requireDeclaredOutputs(handler.handler, signals);
+            output.push(...signals);
         }
     }
-    async #commitEntity(entity) {
-        const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current));
+    /**
+     * Applies a fenced Entity commit and raises transition rejection.
+     *
+     * @param entity Process Manager instance to commit.
+     * @param producedEvents Whether handlers produced Events.
+     * @returns Completion after a successful fenced commit.
+     */
+    async #commitEntity(entity, producedEvents) {
+        const commit = await commitFenced(entity, (current) => transactionalEntityAccess.commit(current, producedEvents));
         if (commit.status === "rejected")
             throw new TransitionValidationError(commit.validation.error);
     }
-    #bindProducedEvents(produced, entityId) {
-        let sequence = 0;
-        return Object.freeze(produced.map((signal) => {
-            sequence += 1;
-            return this.#bindProducedEvent(signal, entityId, sequence);
-        }));
+    /**
+     * Binds reactor results as Process Manager Events.
+     *
+     * @param produced Domain Event messages from handlers.
+     * @param entityId Target Process Manager identifier.
+     * @param version Process Manager Version before this dispatch.
+     * @returns Frozen Event envelope list.
+     */
+    #bindProducedEvents(produced, entityId, version) {
+        return Object.freeze(produced.map((signal) => this.#bindProducedEvent(signal, entityId, version)));
     }
-    #bindProducedEvent(signal, entityId, sequence) {
+    /**
+     * Packs one declared Event with source and producer context.
+     *
+     * @param signal Domain Event message to pack.
+     * @param entityId Target Process Manager identifier.
+     * @param version Process Manager Version before this dispatch.
+     * @returns Bound Event envelope.
+     */
+    #bindProducedEvent(signal, entityId, version) {
         const typeName = EntityInvocation.messageTypeName(signal);
         const schema = this.#routing.producedEventSchemas.find((candidate) => candidate.typeName === typeName);
         if (schema === undefined) {
             throw new Error(`Repository process-manager execution cannot pack event message "${typeName}".`);
         }
         const metadata = this.#runtime.signalMetadata.eventFromEvent(this.#event, {
-            version: RepositoryStand.processManagerProducedVersion(sequence),
+            version: version.number,
         });
         return create(EventSchema, {
             id: metadata.id,
             message: AnyMessages.pack(schema, signal),
-            context: RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId),
+            context: RepositorySignals.eventContextWithProducer(metadata.context, this.#repository, entityId, version),
         });
     }
+    /**
+     * Packs Command reactions using metadata from the source Event.
+     *
+     * @param produced Domain Command messages from handlers.
+     * @returns Frozen Command envelope list.
+     */
     #bindProducedCommands(produced) {
         return Object.freeze(produced.map((signal) => {
             const typeName = EntityInvocation.messageTypeName(signal);
@@ -1303,11 +2034,22 @@ class ProcessManagerEventExecution {
             });
         }));
     }
+    /**
+     * Publishes each produced Command in handler order.
+     *
+     * @param commands Bound Commands to publish.
+     * @returns Completion after all Commands are published.
+     */
     async #postCommands(commands) {
         for (const command of commands) {
             await this.#runtime.publisher.publishCommand(command);
         }
     }
+    /**
+     * Schedules publication of produced Events.
+     *
+     * @param events Bound Events to publish.
+     */
     #postEvents(events) {
         for (const event of events) {
             // spine-log-boundary: server.process_manager_event_follow_up
@@ -1319,6 +2061,15 @@ class ProcessManagerEventExecution {
  * Internal repository identity operations.
  */
 const RepositoryIdentity = {
+    /**
+     * Creates a frozen identity snapshot from validated Entity metadata.
+     *
+     * @typeParam EntityType Concrete Entity constructor represented by the snapshot.
+     * @param entityType Entity constructor.
+     * @param entityFamily Aggregate, Projection, or Process Manager family.
+     * @param metadata Descriptor-derived state metadata.
+     * @returns Copy-safe repository identity snapshot.
+     */
     createRepositorySnapshot(entityType, entityFamily, metadata) {
         const metadataCopy = RepositoryIdentity.cloneEntityMetadata(metadata);
         return Object.freeze({
@@ -1330,6 +2081,13 @@ const RepositoryIdentity = {
             idField: RepositoryIdentity.cloneFieldMetadata(metadataCopy.idField),
         });
     },
+    /**
+     * Copies a repository identity snapshot and its mutable metadata fields.
+     *
+     * @typeParam EntityType Concrete Entity constructor in the snapshot.
+     * @param snapshot Identity snapshot to copy.
+     * @returns Frozen copy of the snapshot.
+     */
     cloneRepositorySnapshot(snapshot) {
         const metadata = RepositoryIdentity.cloneEntityMetadata(snapshot.metadata);
         return Object.freeze({
@@ -1341,9 +2099,21 @@ const RepositoryIdentity = {
             idField: RepositoryIdentity.cloneFieldMetadata(metadata.idField),
         });
     },
+    /**
+     * Checks that repository options are a non-null object.
+     *
+     * @param options Value supplied as repository options.
+     * @returns Whether the value can expose option properties.
+     */
     isRepositoryOptionsObject(options) {
         return typeof options === "object" && options !== null;
     },
+    /**
+     * Reads the Entity constructor option and reports inaccessible properties.
+     *
+     * @param options Repository options object.
+     * @returns Supplied Entity constructor value.
+     */
     readEntityTypeOption(options) {
         try {
             return options.entityType;
@@ -1353,6 +2123,14 @@ const RepositoryIdentity = {
                 "extending Aggregate, Projection, or ProcessManager.");
         }
     },
+    /**
+     * Reads the state schema option and reports inaccessible properties.
+     *
+     * @param options Repository options object.
+     * @param entityTypeDisplayName Constructor name for diagnostics.
+     * @param entityFamily Resolved Entity family for diagnostics.
+     * @returns Supplied state schema value.
+     */
     readRepositorySchemaOption(options, entityTypeDisplayName, entityFamily) {
         try {
             return options.schema;
@@ -1362,6 +2140,12 @@ const RepositoryIdentity = {
                 "the supplied state schema could not be read.");
         }
     },
+    /**
+     * Checks whether a value is a native class constructor.
+     *
+     * @param entityType Candidate Entity constructor.
+     * @returns Whether the value has class syntax.
+     */
     isClassConstructor(entityType) {
         if (typeof entityType !== "function") {
             return false;
@@ -1375,8 +2159,10 @@ const RepositoryIdentity = {
         }
     },
     /**
-     * Resolves the runtime family of a repository-owned entity constructor.
+     * Resolves the runtime family of a repository Entity constructor.
      *
+     * @param entityType Candidate Entity constructor.
+     * @returns Its supported family, or `undefined`.
      * @internal
      */
     resolveRepositoryEntityFamily(entityType) {
@@ -1395,6 +2181,14 @@ const RepositoryIdentity = {
         }
         return undefined;
     },
+    /**
+     * Checks constructor and prototype inheritance against an Entity family.
+     *
+     * @param entityType Candidate constructor.
+     * @param familyConstructor Aggregate, Projection, or Process Manager constructor.
+     * @param familyPrototype Prototype for the same family.
+     * @returns Whether both inheritance paths match.
+     */
     hasEntityFamilyInheritance(entityType, familyConstructor, familyPrototype) {
         try {
             return (Object.prototype.isPrototypeOf.call(familyConstructor, entityType) &&
@@ -1404,6 +2198,12 @@ const RepositoryIdentity = {
             return false;
         }
     },
+    /**
+     * Reads a safe diagnostic name from an Entity constructor.
+     *
+     * @param entityType Constructor value to describe.
+     * @returns Its name, or an anonymous placeholder.
+     */
     entityTypeName(entityType) {
         if ((typeof entityType !== "object" && typeof entityType !== "function") ||
             entityType === null) {
@@ -1412,6 +2212,13 @@ const RepositoryIdentity = {
         const name = RepositoryIdentity.safeStringProperty(entityType, "name");
         return typeof name === "string" && name.length > 0 ? name : "(anonymous)";
     },
+    /**
+     * Reads one string property without propagating accessor errors.
+     *
+     * @param value Object to inspect.
+     * @param propertyName Property to read.
+     * @returns String value when readable, otherwise `undefined`.
+     */
     safeStringProperty(value, propertyName) {
         try {
             const property = value[propertyName];
@@ -1421,6 +2228,15 @@ const RepositoryIdentity = {
             return undefined;
         }
     },
+    /**
+     * Describes a generated state schema and wraps invalid metadata errors.
+     *
+     * @typeParam Schema Concrete generated state schema.
+     * @param entityTypeDisplayName Constructor name for diagnostics.
+     * @param entityFamily Resolved Entity family for diagnostics.
+     * @param schema Generated state schema to inspect.
+     * @returns Descriptor-derived Entity metadata.
+     */
     describeRepositoryEntityMetadata(entityTypeDisplayName, entityFamily, schema) {
         try {
             return describeEntityMetadata(schema);
@@ -1430,6 +2246,13 @@ const RepositoryIdentity = {
                 "the supplied state schema does not expose supported entity metadata.");
         }
     },
+    /**
+     * Copies descriptor-derived Entity metadata and nested field descriptions.
+     *
+     * @typeParam Schema Generated state schema represented by the metadata.
+     * @param metadata Entity metadata to copy.
+     * @returns Frozen metadata copy.
+     */
     cloneEntityMetadata(metadata) {
         const idField = RepositoryIdentity.cloneFieldMetadata(metadata.idField);
         const firstFieldRoutingHint = Object.freeze({
@@ -1452,6 +2275,12 @@ const RepositoryIdentity = {
             setOnceFields: Object.freeze(metadata.setOnceFields.map((field) => RepositoryIdentity.cloneFieldMetadata(field))),
         });
     },
+    /**
+     * Copies one descriptor field description for an identity snapshot.
+     *
+     * @param field Descriptor field to copy.
+     * @returns Frozen field description.
+     */
     cloneFieldMetadata(field) {
         return Object.freeze({
             descriptor: field.descriptor,
@@ -1467,11 +2296,12 @@ Object.freeze(RepositoryIdentity);
  * Internal entity invocation operations.
  */
 const EntityInvocation = {
-    isEventEnvelope(signal) {
-        return (typeof signal === "object" &&
-            signal !== null &&
-            signal.$typeName === EventSchema.typeName);
-    },
+    /**
+     * Reads a generated message's type name or rejects malformed output.
+     *
+     * @param message Handler result to inspect.
+     * @returns Its generated message type name.
+     */
     messageTypeName(message) {
         const typeName = message.$typeName;
         if (typeof typeName !== "string" || typeName.length === 0) {
@@ -1479,6 +2309,16 @@ const EntityInvocation = {
         }
         return typeName;
     },
+    /**
+     * Invokes a registered Entity handler with its declared argument count.
+     *
+     * @param entity Entity instance containing the method.
+     * @param methodName Registered handler method name.
+     * @param message Decoded Command or Event message.
+     * @param parameterCount One message parameter or message plus context.
+     * @param context Handler context when declared.
+     * @returns Raw handler result.
+     */
     invokeEntityMethod(entity, methodName, message, parameterCount = 1, context) {
         const method = entity[methodName];
         if (typeof method !== "function") {
@@ -1486,16 +2326,36 @@ const EntityInvocation = {
         }
         return Reflect.apply(method, entity, parameterCount === 2 ? [message, context] : [message]);
     },
+    /**
+     * Copies a Command context or creates an empty context when absent.
+     *
+     * @param command Source Command envelope.
+     * @returns Context isolated from the source envelope.
+     */
     commandHandlerContext(command) {
         return command.context === undefined
             ? create(CommandContextSchema)
             : clone(CommandContextSchema, command.context);
     },
+    /**
+     * Copies an Event context or creates an empty context when absent.
+     *
+     * @param event Source Event envelope.
+     * @returns Context isolated from the source envelope.
+     */
     eventHandlerContext(event) {
         return event.context === undefined
             ? create(EventContextSchema)
             : clone(EventContextSchema, event.context);
     },
+    /**
+     * Unpacks a required signal message with its registered schema.
+     *
+     * @param message Packed signal payload.
+     * @param schema Registered generated message schema.
+     * @param signalKind Signal name for failure diagnostics.
+     * @returns Decoded generated message.
+     */
     unpackRequired(message, schema, signalKind) {
         const unpacked = AnyMessages.unpack(message, schema);
         if (unpacked === undefined) {
@@ -1503,6 +2363,13 @@ const EntityInvocation = {
         }
         return unpacked;
     },
+    /**
+     * Validates that a signal carries a typed message payload.
+     *
+     * @param message Optional packed signal payload.
+     * @param signalKind Signal name for failure diagnostics.
+     * @returns Payload with a nonempty type URL.
+     */
     requireSignalMessage(message, signalKind) {
         if (message === undefined || message.typeUrl === "") {
             throw new Error(`Repository ${signalKind} execution requires message.typeUrl.`);
@@ -1515,12 +2382,116 @@ Object.freeze(EntityInvocation);
  * Internal repository entities operations.
  */
 const RepositoryEntities = {
+    /**
+     * Opens Entity storage and binds diagnostic history to the restored instance.
+     *
+     * @param repository Entity repository registration.
+     * @param runtime Storage factory and tenant mode.
+     * @param tenantId Tenant identifier when multitenant.
+     * @param entityId Entity identifier.
+     * @param entity Restored Entity instance.
+     * @returns Commit storage and its Entity storage specification.
+     */
+    bindStorage(repository, runtime, tenantId, entityId, entity) {
+        const storageInput = RepositoryStorage.entityStorageInput(repository, RepositoryTenants.storageContextForTenant(runtime.context, tenantId));
+        const storage = RepositoryStorage.openRepositoryEntityStorage(repository, runtime.storageFactory, storageInput);
+        RepositoryHistoryInternals.bindEntityHistory(entity, storage, entityId, repository.stateSchema);
+        return { commits: storage.commits, events: storage.events, storageInput };
+    },
+    /**
+     * Restores an Entity from Stand or creates a fresh instance at Version zero.
+     *
+     * @param repository Entity schema and constructor registration.
+     * @param entityId Entity identifier.
+     * @param stored Prior Stand snapshot, when present.
+     * @param resetDeleted Whether rebuild replaces a deleted Projection.
+     * @returns The Entity instance for one repository dispatch.
+     */
+    instantiate(repository, entityId, stored, resetDeleted) {
+        const entityType = repository.entityType;
+        const fresh = stored === undefined || resetDeleted;
+        return new entityType({
+            id: entityId,
+            schema: repository.stateSchema,
+            state: fresh
+                ? create(repository.stateSchema, { [repository.idField.localName]: entityId })
+                : stored.state,
+            version: fresh ? create(VersionSchema) : stored.versionMessage,
+            lifecycle: resetDeleted
+                ? { archived: false, deleted: false }
+                : { archived: stored?.archived ?? false, deleted: stored?.deleted ?? false },
+        });
+    },
+    /**
+     * Builds the loaded repository Entity view from a Stand snapshot.
+     *
+     * @param entity Restored Entity instance.
+     * @param stored Prior Stand snapshot, when present.
+     * @param commits Durable commit storage.
+     * @param events Durable diagnostic Event history.
+     * @param storageInput Entity storage specification.
+     * @param schema Entity state schema.
+     * @param entityId Entity identifier.
+     * @returns The loaded Entity and prior record.
+     */
+    loaded(entity, stored, commits, events, storageInput, schema, entityId) {
+        return Object.freeze({
+            commits,
+            events,
+            current: stored === undefined
+                ? undefined
+                : EntityRecords.pack(schema, entityId, stored.state, stored.versionMessage, {
+                    archived: stored.archived,
+                    deleted: stored.deleted,
+                }),
+            entity,
+            storageInput,
+        });
+    },
+    /**
+     * Returns a defensive copy of the Version before this repository dispatch.
+     *
+     * @param current Prior stored Entity record, when one exists.
+     * @returns Prior Version, or the initial zero Version for a fresh Entity.
+     */
+    priorVersion(current) {
+        return current?.version === undefined
+            ? create(VersionSchema)
+            : clone(VersionSchema, current.version);
+    },
+    /**
+     * Reads the current state snapshot from a repository Entity.
+     *
+     * @param entity Entity instance to inspect.
+     * @returns Its current state message.
+     */
     repositoryState(entity) {
         return entity.state;
     },
+    /**
+     * Reads the current Spine Version from a repository Entity.
+     *
+     * @param entity Entity instance to inspect.
+     * @returns Its current Version snapshot.
+     */
+    repositoryVersion(entity) {
+        return entity.version;
+    },
+    /**
+     * Reads archived and deleted flags from a repository Entity.
+     *
+     * @param entity Entity instance to inspect.
+     * @returns Its current lifecycle flags.
+     */
     repositoryLifecycle(entity) {
         return entity.lifecycle;
     },
+    /**
+     * Checks whether the Entity transaction changed state or lifecycle.
+     *
+     * @param entity Entity instance to inspect.
+     * @returns Whether the Entity reports a change.
+     */
     repositoryChanged(entity) {
         return entity.changed === true;
     },
@@ -1530,9 +2501,21 @@ Object.freeze(RepositoryEntities);
  * Internal repository signals operations.
  */
 const RepositorySignals = {
+    /**
+     * Validates that a rejection type was declared by the invoked handler.
+     *
+     * @param handler Handler declaration that raised the rejection.
+     * @param rejection Rejection to validate.
+     */
     requireDeclaredRejection(handler, rejection) {
         DeclaredRejections.require(handler.methodName, HandlerMetadataValues.thrownSchemas(handler), rejection);
     },
+    /**
+     * Reads the producer version from an Event context.
+     *
+     * @param event Event carrying producer metadata.
+     * @returns Version number as a bigint.
+     */
     readEventVersion(event) {
         const number = event.context?.version?.number;
         if (number === undefined) {
@@ -1540,16 +2523,45 @@ const RepositorySignals = {
         }
         return BigInt(number);
     },
+    /**
+     * Converts an Aggregate version into the Event context int32 range.
+     *
+     * @param version Aggregate version number.
+     * @returns Version number suitable for a Protobuf Event context.
+     */
     eventVersionNumber(version) {
         if (version > 2147483647n || version < -2147483648n) {
             throw new Error("Repository aggregate execution requires versions in the protobuf int32 range.");
         }
         return Number(version);
     },
-    eventContextWithProducer(context, repository, entityId) {
+    /**
+     * Copies an Event context with the producing Entity identifier.
+     *
+     * @param context Event context to extend.
+     * @param repository Producing Entity repository.
+     * @param entityId Producing Entity identifier.
+     * @param version Full pre-dispatch producer Version, when supplied.
+     * @returns New Event context with producer metadata.
+     */
+    eventContextWithProducer(context, repository, entityId, version) {
         const producerId = EntityIds.pack(repository.stateSchema, entityId);
-        return create(EventContextSchema, { ...context, producerId });
+        return create(EventContextSchema, {
+            ...context,
+            producerId,
+            ...(version === undefined ? {} : { version: clone(VersionSchema, version) }),
+        });
     },
+    /**
+     * Builds a rejection Event and returns a best-effort publication follow-up.
+     *
+     * @param runtime Context signal and publication services.
+     * @param repository Repository of the rejected Command.
+     * @param command Command rejected by its handler.
+     * @param entityId Target Entity identifier.
+     * @param rejection Declared handler rejection.
+     * @returns Deferred rejection Event publication.
+     */
     postRejectionEvent(runtime, repository, command, entityId, rejection) {
         const metadata = runtime.signalMetadata.eventFromCommand(command, {});
         const event = create(EventSchema, {
@@ -1573,18 +2585,35 @@ const RepositorySignals = {
             }
         };
     },
+    /**
+     * Validates a nonempty Command ID for Event origin metadata.
+     *
+     * @param command Source Command envelope.
+     * @returns Its nonempty ID.
+     */
     requireCommandId(command) {
         if (command.id === undefined || command.id.uuid.trim().length === 0) {
             throw new Error("Repository aggregate execution requires command.id to bind event origins.");
         }
         return command.id;
     },
+    /**
+     * Validates a nonempty Event ID for inbox deduplication.
+     *
+     * @param event Source Event envelope.
+     * @returns Its nonempty ID.
+     */
     requireEventId(event) {
         if (event.id === undefined || event.id.value.trim().length === 0) {
             throw new Error("Repository projection inbox handoff requires event.id.");
         }
         return event.id;
     },
+    /**
+     * Creates a Protobuf timestamp for this execution instant.
+     *
+     * @returns Timestamp derived from the current clock.
+     */
     executionTimestamp() {
         const milliseconds = Date.now();
         return create(TimestampSchema, {
@@ -1597,6 +2626,19 @@ const RepositorySignals = {
  * Builds and best-effort dispatches committed entity state notifications.
  */
 class EntityStateChangePublishing {
+    /**
+     * Publishes System Events for an Entity change caused by a Command.
+     *
+     * @param runtime Context signal and publication services.
+     * @param repository Repository of the changed Entity.
+     * @param command Source Command.
+     * @param entityId Changed Entity identifier.
+     * @param oldState State before handling, when present.
+     * @param oldLifecycle Lifecycle before handling, when present.
+     * @param newState Accepted Entity state.
+     * @param lifecycle Accepted lifecycle flags.
+     * @param version Committed Entity version number.
+     */
     command(runtime, repository, command, entityId, oldState, oldLifecycle, newState, lifecycle, version) {
         this.#publish(runtime, () => runtime.signalMetadata.eventFromCommand(command, {
             version,
@@ -1605,6 +2647,19 @@ class EntityStateChangePublishing {
             typeUrl: command.message?.typeUrl ?? "",
         }, { repository, entityId, oldState, oldLifecycle, newState, lifecycle, version });
     }
+    /**
+     * Publishes System Events for an Entity change caused by an Event.
+     *
+     * @param runtime Context signal and publication services.
+     * @param repository Repository of the changed Entity.
+     * @param source Source Event.
+     * @param entityId Changed Entity identifier.
+     * @param oldState State before handling, when present.
+     * @param oldLifecycle Lifecycle before handling, when present.
+     * @param newState Accepted Entity state.
+     * @param lifecycle Accepted lifecycle flags.
+     * @param version Committed Entity version number.
+     */
     event(runtime, repository, source, entityId, oldState, oldLifecycle, newState, lifecycle, version) {
         this.#publish(runtime, () => runtime.signalMetadata.eventFromEvent(source, {
             version,
@@ -1613,6 +2668,14 @@ class EntityStateChangePublishing {
             typeUrl: source.message?.typeUrl ?? "",
         }, { repository, entityId, oldState, oldLifecycle, newState, lifecycle, version });
     }
+    /**
+     * Packs and publishes each System Event describing the accepted change.
+     *
+     * @param runtime Context signal and publication services.
+     * @param metadataFor Creates Event metadata from the source signal.
+     * @param origin Source signal identifier and type URL.
+     * @param change Accepted Entity transition.
+     */
     #publish(runtime, metadataFor, origin, change) {
         const drafts = this.#drafts(origin, change);
         drafts.forEach((draft) => {
@@ -1626,12 +2689,26 @@ class EntityStateChangePublishing {
             this.#post(runtime, event);
         });
     }
+    /**
+     * Creates state and lifecycle System Events for a committed change.
+     *
+     * @param origin Source signal identifier and type URL.
+     * @param change Accepted Entity transition.
+     * @returns Event drafts for the changed state or lifecycle.
+     */
     #drafts(origin, change) {
         const fields = this.#fields(origin, change);
         const archive = this.#archiveDraft(fields, change);
         const deletion = this.#deleteDraft(fields, change);
         return [...this.#stateDrafts(fields, change), archive, deletion].filter((draft) => draft !== undefined);
     }
+    /**
+     * Packs fields shared by Entity state and lifecycle diagnostics.
+     *
+     * @param origin Source signal identifier and type URL.
+     * @param change Accepted Entity transition.
+     * @returns Shared Entity, signal, state, and version fields.
+     */
     #fields(origin, change) {
         const entity = create(MessageIdSchema, {
             id: this.#packEntityId(change.repository, change.entityId),
@@ -1644,6 +2721,13 @@ class EntityStateChangePublishing {
             version: create(VersionSchema, { number: change.version }),
         };
     }
+    /**
+     * Creates state Event drafts from prior and next state.
+     *
+     * @param fields Shared System Event fields.
+     * @param change Accepted Entity transition.
+     * @returns Zero, one, or two state Event drafts.
+     */
     #stateDrafts(fields, change) {
         const drafts = [];
         if (change.oldState === undefined) {
@@ -1661,6 +2745,13 @@ class EntityStateChangePublishing {
         }
         return drafts;
     }
+    /**
+     * Builds an EntityStateChanged payload draft.
+     *
+     * @param fields Shared System Event fields.
+     * @param change Accepted Entity transition.
+     * @returns Draft that receives the envelope timestamp later.
+     */
     #stateChangedDraft(fields, change) {
         return {
             schema: EntityLog.EntityStateChangedSchema,
@@ -1678,6 +2769,13 @@ class EntityStateChangePublishing {
             }),
         };
     }
+    /**
+     * Creates an archive or unarchive Event when that flag changed.
+     *
+     * @param fields Shared System Event fields.
+     * @param change Accepted Entity transition.
+     * @returns Lifecycle Event draft, or `undefined`.
+     */
     #archiveDraft(fields, change) {
         const previous = change.oldLifecycle ?? { archived: false, deleted: false };
         if (previous.archived === change.lifecycle.archived)
@@ -1704,6 +2802,13 @@ class EntityStateChangePublishing {
                 }),
             };
     }
+    /**
+     * Creates a deletion or restoration Event when that flag changed.
+     *
+     * @param fields Shared System Event fields.
+     * @param change Accepted Entity transition.
+     * @returns Lifecycle Event draft, or `undefined`.
+     */
     #deleteDraft(fields, change) {
         const previous = change.oldLifecycle ?? { archived: false, deleted: false };
         if (previous.deleted === change.lifecycle.deleted)
@@ -1731,6 +2836,12 @@ class EntityStateChangePublishing {
                 }),
             };
     }
+    /**
+     * Schedules best-effort System Event publication and reports failure.
+     *
+     * @param runtime Context publication services.
+     * @param event Packed System Event to publish.
+     */
     #post(runtime, event) {
         try {
             // spine-log-boundary: server.repository_system_follow_up
@@ -1740,12 +2851,26 @@ class EntityStateChangePublishing {
             runtime.publisher.reportFailure("system-event", event, error);
         }
     }
+    /**
+     * Compares serialized state messages for a meaningful state change.
+     *
+     * @param schema Generated state schema.
+     * @param left State before handling.
+     * @param right State after handling.
+     * @returns Whether their serialized bytes match.
+     */
     #sameState(schema, left, right) {
         const leftBytes = toBinary(schema, left);
         const rightBytes = toBinary(schema, right);
         return (leftBytes.length === rightBytes.length &&
             leftBytes.every((value, index) => value === rightBytes[index]));
     }
+    /**
+     * Maps a repository Entity family to the System Event kind enum.
+     *
+     * @param kind Repository Entity family.
+     * @returns Matching Protobuf Entity kind.
+     */
     #kind(kind) {
         return kind === "aggregate"
             ? EntityOption_Kind.AGGREGATE
@@ -1753,6 +2878,13 @@ class EntityStateChangePublishing {
                 ? EntityOption_Kind.PROJECTION
                 : EntityOption_Kind.PROCESS_MANAGER;
     }
+    /**
+     * Packs an Entity identifier for System Event metadata.
+     *
+     * @param repository Repository carrying the ID schema.
+     * @param entityId Changed Entity identifier.
+     * @returns Packed identifier.
+     */
     #packEntityId(repository, entityId) {
         return EntityIds.pack(repository.stateSchema, entityId);
     }
@@ -1762,6 +2894,14 @@ const EntityStateChangePublisher = Object.freeze(new EntityStateChangePublishing
  * Builds and best-effort dispatches accepted handler diagnostics.
  */
 class HandlerDispatchPublishing {
+    /**
+     * Publishes a best-effort CommandDispatchedToHandler diagnostic.
+     *
+     * @param runtime Context signal and publication services.
+     * @param repository Repository receiving the Command.
+     * @param command Source Command.
+     * @param entityId Target Entity identifier.
+     */
     command(runtime, repository, command, entityId) {
         try {
             const context = runtime.signalMetadata.eventContext({
@@ -1778,12 +2918,37 @@ class HandlerDispatchPublishing {
             runtime.publisher.reportFailure("event", create(EventSchema), error);
         }
     }
+    /**
+     * Publishes a best-effort EventDispatchedToSubscriber diagnostic.
+     *
+     * @param runtime Context signal and publication services.
+     * @param repository Repository receiving the Event.
+     * @param event Source Event.
+     * @param entityId Target Entity identifier.
+     */
     subscriber(runtime, repository, event, entityId) {
         this.#publishEvent(runtime, repository, event, entityId, EntityLog.EventDispatchedToSubscriberSchema);
     }
+    /**
+     * Publishes a best-effort EventDispatchedToReactor diagnostic.
+     *
+     * @param runtime Context signal and publication services.
+     * @param repository Repository receiving the Event.
+     * @param event Source Event.
+     * @param entityId Target Entity identifier.
+     */
     reactor(runtime, repository, event, entityId) {
         this.#publishEvent(runtime, repository, event, entityId, EntityLog.EventDispatchedToReactorSchema);
     }
+    /**
+     * Builds and publishes one subscriber or reactor dispatch diagnostic.
+     *
+     * @param runtime Context signal and publication services.
+     * @param repository Repository receiving the Event.
+     * @param event Source Event.
+     * @param entityId Target Entity identifier.
+     * @param schema Diagnostic message schema to emit.
+     */
     #publishEvent(runtime, repository, event, entityId, schema) {
         try {
             const context = runtime.signalMetadata.eventContext({
@@ -1800,6 +2965,15 @@ class HandlerDispatchPublishing {
             runtime.publisher.reportFailure("event", create(EventSchema), error);
         }
     }
+    /**
+     * Packs a Command dispatch diagnostic with target and source metadata.
+     *
+     * @param repository Repository receiving the Command.
+     * @param command Source Command.
+     * @param entityId Target Entity identifier.
+     * @param whenDispatched Dispatch timestamp, when available.
+     * @returns Command dispatch diagnostic message.
+     */
     #message(repository, command, entityId, whenDispatched) {
         return create(EntityLog.CommandDispatchedToHandlerSchema, {
             receiver: create(MessageIdSchema, {
@@ -1813,6 +2987,13 @@ class HandlerDispatchPublishing {
             }),
         });
     }
+    /**
+     * Registers and schedules a System Event diagnostic for publication.
+     *
+     * @param runtime Context publication services.
+     * @param schema Diagnostic message schema.
+     * @param event Packed diagnostic Event.
+     */
     #post(runtime, schema, event) {
         try {
             runtime.registerSystemEventSchema(schema);
@@ -1823,9 +3004,26 @@ class HandlerDispatchPublishing {
             runtime.publisher.reportFailure("system-event", event, error);
         }
     }
+    /**
+     * Packs a target Entity identifier for dispatch diagnostics.
+     *
+     * @param repository Repository carrying the ID schema.
+     * @param entityId Target Entity identifier.
+     * @returns Packed identifier.
+     */
     #packEntityId(repository, entityId) {
         return EntityIds.pack(repository.stateSchema, entityId);
     }
+    /**
+     * Packs a subscriber or reactor dispatch diagnostic message.
+     *
+     * @param schema Diagnostic message schema to emit.
+     * @param repository Repository receiving the Event.
+     * @param event Source Event.
+     * @param entityId Target Entity identifier.
+     * @param whenDispatched Dispatch timestamp, when available.
+     * @returns Matching subscriber or reactor diagnostic message.
+     */
     #eventMessage(schema, repository, event, entityId, whenDispatched) {
         const fields = {
             receiver: create(MessageIdSchema, {
@@ -1849,6 +3047,14 @@ Object.freeze(RepositorySignals);
  * Internal repository stand operations.
  */
 const RepositoryStand = {
+    /**
+     * Builds tenant, Version, and lifecycle options for a Stand update.
+     *
+     * @param tenantId Tenant receiving the update, when present.
+     * @param version Committed Spine Version, when present.
+     * @param lifecycle Accepted archived and deleted flags.
+     * @returns Frozen Stand update options.
+     */
     standUpdateOptions(tenantId, version, lifecycle) {
         return Object.freeze({
             ...(tenantId === undefined ? {} : { tenantId }),
@@ -1856,22 +3062,25 @@ const RepositoryStand = {
             lifecycle,
         });
     },
-    projectionVersion(version) {
-        return typeof version === "bigint" ? Number(version) : (version?.number ?? 0);
-    },
-    processManagerVersion(entity) {
-        const version = entity.version;
-        return typeof version === "number" ? version + 1 : 1;
-    },
-    processManagerProducedVersion(sequence) {
-        return sequence;
-    },
+    /**
+     * Maps one Event position to its Process Manager producer version.
+     *
+     * @param sequence One-based position among produced Events.
+     * @returns Producer sequence number for Event metadata.
+     */
 };
 Object.freeze(RepositoryStand);
 /**
  * Internal repository tenants operations.
  */
 const RepositoryTenants = {
+    /**
+     * Builds tenant-aware storage context for Entity inbox delivery.
+     *
+     * @param context Bounded context storage mode.
+     * @param tenantId Delivery tenant when multitenant.
+     * @returns Storage context for durable Entity inbox rows.
+     */
     entityInboxDeliveryContext(context, tenantId) {
         if (!context.multitenant) {
             return Object.freeze({ name: context.name, multitenant: false });
@@ -1886,6 +3095,13 @@ const RepositoryTenants = {
             tenantId: RepositoryTenants.require(tid),
         });
     },
+    /**
+     * Builds tenant-aware storage context for Projection inbox delivery.
+     *
+     * @param context Bounded context storage mode.
+     * @param tenantId Delivery tenant when multitenant.
+     * @returns Storage context for durable Projection inbox rows.
+     */
     projectionDeliveryContext(context, tenantId) {
         if (!context.multitenant) {
             return Object.freeze({ name: context.name, multitenant: false });
@@ -1900,6 +3116,13 @@ const RepositoryTenants = {
             tenantId: RepositoryTenants.require(tid),
         });
     },
+    /**
+     * Validates an Event tenant before Projection inbox handoff.
+     *
+     * @param context Bounded context storage mode.
+     * @param event Event entering Projection delivery.
+     * @returns Validated tenant, or `undefined` for single-tenant contexts.
+     */
     requireProjectionTenant(context, event) {
         if (!context.multitenant) {
             return undefined;
@@ -1910,6 +3133,13 @@ const RepositoryTenants = {
         }
         return RepositoryTenants.require(tenantId);
     },
+    /**
+     * Validates an Event tenant before Process Manager inbox handoff.
+     *
+     * @param context Bounded context storage mode.
+     * @param event Event entering Process Manager delivery.
+     * @returns Validated tenant, or `undefined` for single-tenant contexts.
+     */
     requirePmEventTenant(context, event) {
         if (!context.multitenant) {
             return undefined;
@@ -1920,6 +3150,13 @@ const RepositoryTenants = {
         }
         return RepositoryTenants.require(tenantId);
     },
+    /**
+     * Validates a Command tenant before Entity inbox handoff.
+     *
+     * @param context Bounded context storage mode.
+     * @param command Command entering Entity delivery.
+     * @returns Validated tenant, or `undefined` for single-tenant contexts.
+     */
     requireCommandTenant(context, command) {
         if (!context.multitenant) {
             return undefined;
@@ -1930,6 +3167,13 @@ const RepositoryTenants = {
         }
         return RepositoryTenants.require(tenantId);
     },
+    /**
+     * Builds storage context from a Command actor tenant.
+     *
+     * @param context Bounded context storage mode.
+     * @param command Command entering repository execution.
+     * @returns Tenant-aware storage context.
+     */
     storageContextForCommand(context, command) {
         if (!context.multitenant) {
             return Object.freeze({ name: context.name, multitenant: false });
@@ -1943,6 +3187,13 @@ const RepositoryTenants = {
             tenantId: RepositoryTenants.require(tenantId),
         });
     },
+    /**
+     * Builds storage context from an Event origin tenant.
+     *
+     * @param context Bounded context storage mode.
+     * @param event Event entering repository execution.
+     * @returns Tenant-aware storage context.
+     */
     storageContextForEvent(context, event) {
         if (!context.multitenant) {
             return Object.freeze({ name: context.name, multitenant: false });
@@ -1956,6 +3207,13 @@ const RepositoryTenants = {
             tenantId: RepositoryTenants.require(tenantId),
         });
     },
+    /**
+     * Builds storage context from an explicit tenant value.
+     *
+     * @param context Bounded context storage mode.
+     * @param tenantId Tenant to select when multitenant.
+     * @returns Tenant-aware storage context.
+     */
     storageContextForTenant(context, tenantId) {
         if (!context.multitenant)
             return Object.freeze({ name: context.name, multitenant: false });
@@ -1967,9 +3225,22 @@ const RepositoryTenants = {
             tenantId: RepositoryTenants.require(tenantId),
         });
     },
+    /**
+     * Reads a copied tenant identifier from Command actor metadata.
+     *
+     * @param command Source Command.
+     * @returns Tenant identifier when present.
+     */
     readCommandTenant(command) {
         return RepositoryTenants.tenantValue(command.context?.actorContext?.tenantId);
     },
+    /**
+     * Reads a tenant for a Stand Event update when available.
+     *
+     * @param context Bounded context storage mode.
+     * @param event Source Event.
+     * @returns Stand tenant options.
+     */
     standTenantOptions(context, event) {
         if (!context.multitenant) {
             return {};
@@ -1977,6 +3248,13 @@ const RepositoryTenants = {
         const tenantId = RepositoryTenants.readEventTenant(event);
         return tenantId === undefined ? {} : { tenantId };
     },
+    /**
+     * Reads a tenant for a Stand Command update when available.
+     *
+     * @param context Bounded context storage mode.
+     * @param command Source Command.
+     * @returns Stand tenant options.
+     */
     commandStandOptions(context, command) {
         if (!context.multitenant) {
             return {};
@@ -1984,6 +3262,12 @@ const RepositoryTenants = {
         const tenantId = RepositoryTenants.readCommandTenant(command);
         return tenantId === undefined ? {} : { tenantId };
     },
+    /**
+     * Reads a copied tenant identifier from Event origin metadata.
+     *
+     * @param event Source Event.
+     * @returns Tenant identifier when present.
+     */
     readEventTenant(event) {
         switch (event.context?.origin.case) {
             case "importContext":
@@ -1994,12 +3278,31 @@ const RepositoryTenants = {
                 return undefined;
         }
     },
+    /**
+     * Copies a tenant identifier when provided.
+     *
+     * @param tenantId Tenant identifier to isolate from its source.
+     * @returns Copied tenant, or `undefined`.
+     */
     tenantValue(tenantId) {
         return tenantId === undefined ? undefined : clone(TenantIdSchema, tenantId);
     },
+    /**
+     * Validates and copies a tenant identifier through the storage boundary.
+     *
+     * @param tenantId Tenant identifier to validate.
+     * @returns Validated tenant identifier.
+     */
     require(tenantId) {
         return TenantBoundary.from(tenantId).tenantId;
     },
+    /**
+     * Compares normalized tenant storage keys.
+     *
+     * @param left First tenant identifier.
+     * @param right Second tenant identifier.
+     * @returns Whether both identifiers select the same tenant.
+     */
     equal(left, right) {
         return TenantBoundary.from(left).key === TenantBoundary.from(right).key;
     },
@@ -2009,6 +3312,27 @@ Object.freeze(RepositoryTenants);
  * Internal repository handlers operations.
  */
 const RepositoryHandlers = {
+    /**
+     * Rejects outputs not declared by the invoked handler, even if a sibling declares them.
+     *
+     * @param handler Invoked handler declaration.
+     * @param signals Returned domain messages to validate.
+     */
+    requireDeclaredOutputs(handler, signals) {
+        const schemas = HandlerMetadataValues.returnedSchemas(handler);
+        for (const signal of signals) {
+            const typeName = EntityInvocation.messageTypeName(signal);
+            if (!schemas.some((schema) => schema.typeName === typeName)) {
+                throw new Error(`Handler "${handler.methodName}" returned undeclared message "${typeName}".`);
+            }
+        }
+    },
+    /**
+     * Normalizes one or many handler metadata blocks to a frozen list.
+     *
+     * @param handlersOption Configured handler metadata.
+     * @returns Frozen handler metadata list.
+     */
     normalizeHandlers(handlersOption) {
         if (handlersOption === undefined) {
             return Object.freeze([]);
@@ -2018,17 +3342,28 @@ const RepositoryHandlers = {
         }
         return Object.freeze([handlersOption]);
     },
+    /**
+     * Groups Event-to-Command reactions by source Event type.
+     *
+     * @param handlers Entity handler metadata blocks.
+     * @returns Reactions indexed by Event type name.
+     */
     createCommandReactionMap(handlers) {
         const byEvent = new Map();
         const registry = new HandlerMetadataRegistry(handlers);
         for (const entry of registry.findHandlersByKind("command-reaction")) {
-            if (RepositoryHandlers.handlerEmittedSchemas(entry.handler).length === 0) {
-                continue;
-            }
             RepositoryHandlers.pushMapValue(byEvent, entry.handler.messageFullTypeName, entry);
         }
         return byEvent;
     },
+    /**
+     * Builds Event field filters for handlers grouped by Event type.
+     *
+     * @typeParam Value Handler registration carrying schema and filter metadata.
+     * @param byEvent Handler registrations indexed by Event type.
+     * @param stringifiers Field conversion registry for message-valued filters.
+     * @returns Compiled filter plans by Event type.
+     */
     createEventFilterPlans(byEvent, stringifiers) {
         const plans = new Map();
         for (const [eventType, values] of byEvent) {
@@ -2040,21 +3375,62 @@ const RepositoryHandlers = {
         }
         return plans;
     },
+    /**
+     * Finds handlers for domestic or external Event origin.
+     *
+     * @typeParam Value Handler registration with origin metadata.
+     * @param values Candidate handler registrations.
+     * @param external Whether the source Event is external.
+     * @returns Frozen matching registration list.
+     */
     forOrigin(values, external) {
         return Object.freeze(values.filter((value) => (value.handler.origin === "external") === external));
     },
+    /**
+     * Maps readiness-selected handlers by registered message type.
+     *
+     * @typeParam Value Handler registration returned by readiness lookup.
+     * @param schemas Registered message schemas.
+     * @param find Selects handlers for one type name.
+     * @returns Handler lists indexed by message type name.
+     */
     readinessMap(schemas, find) {
         return new Map(schemas.map((schema) => [schema.typeName, find(schema.typeName)]));
     },
+    /**
+     * Reads the declared output schemas for one handler.
+     *
+     * @param handler Command or Event handler declaration.
+     * @returns Generated schemas the handler may emit.
+     */
     handlerEmittedSchemas(handler) {
         return HandlerMetadataValues.returnedSchemas(handler);
     },
+    /**
+     * Reads the declared rejection schemas for a Command handler.
+     *
+     * @param handler Assignment or substitution declaration.
+     * @returns Generated rejection schemas the handler may throw.
+     */
     handlerThrownSchemas(handler) {
         return HandlerMetadataValues.thrownSchemas(handler);
     },
+    /**
+     * Checks whether handler metadata was supplied as a list.
+     *
+     * @param value Configured handler metadata.
+     * @returns Whether it is a handler list.
+     */
     isHandlersArray(value) {
         return Array.isArray(value);
     },
+    /**
+     * Validates handler metadata against the Entity constructor and family.
+     *
+     * @param entityType Repository Entity constructor.
+     * @param metadata Descriptor-derived state metadata.
+     * @param handlers Handler metadata blocks to validate.
+     */
     validateHandlers(entityType, metadata, handlers) {
         for (const handlersMetadata of handlers) {
             if (!HandlerMetadataValues.isAuthentic(handlersMetadata) ||
@@ -2069,6 +3445,12 @@ const RepositoryHandlers = {
             }
         }
     },
+    /**
+     * Returns unique generated schemas by type URL.
+     *
+     * @param schemas Candidate message schemas.
+     * @returns Frozen list retaining the last schema for each type URL.
+     */
     uniqueSchemas(schemas) {
         const byTypeUrl = new Map();
         for (const schema of schemas) {
@@ -2076,6 +3458,15 @@ const RepositoryHandlers = {
         }
         return Object.freeze([...byTypeUrl.values()]);
     },
+    /**
+     * Adds a value to a map entry, creating its list when absent.
+     *
+     * @typeParam Key Map key type.
+     * @typeParam Value Map value type.
+     * @param map Mutable map of value lists.
+     * @param key Entry key to update.
+     * @param value Value to append.
+     */
     pushMapValue(map, key, value) {
         const values = map.get(key);
         if (values === undefined) {
@@ -2090,6 +3481,21 @@ Object.freeze(RepositoryHandlers);
  * Internal repository routes operations.
  */
 const RepositoryRoutes = {
+    /**
+     * Builds immutable routing from an Entity constructor and its declarations.
+     *
+     * @typeParam EntityType Concrete repository Entity constructor.
+     * @param entityType Entity constructor receiving signals.
+     * @param entityFamily Aggregate, Projection, or Process Manager family.
+     * @param metadata Descriptor-derived state metadata.
+     * @param handlersOption Registered Entity handler metadata.
+     * @param producedEvents Additional Event schemas this repository may emit.
+     * @param commandRouting Captured Command route declarations.
+     * @param eventRouting Captured Event route declarations.
+     * @param stateUpdateRouting Captured state-update route declarations.
+     * @param stringifiers Field conversion registry for Event filters.
+     * @returns Immutable routing and handler selection operations.
+     */
     createRepositoryRouting(entityType, entityFamily, metadata, handlersOption, producedEvents, commandRouting, eventRouting, stateUpdateRouting, stringifiers) {
         return RepositoryRoutes.prepareRouting({
             entityType,
@@ -2103,6 +3509,13 @@ const RepositoryRoutes = {
             stringifiers,
         });
     },
+    /**
+     * Validates handler declarations and assembles routing schemas and selectors.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param input Entity metadata, handlers, and captured routes.
+     * @returns Immutable repository routing.
+     */
     prepareRouting(input) {
         const handlers = RepositoryHandlers.normalizeHandlers(input.handlersOption);
         RepositoryHandlers.validateHandlers(input.entityType, input.metadata, handlers);
@@ -2114,6 +3527,12 @@ const RepositoryRoutes = {
         const routes = RepositoryRoutes.routingMaps(schemas, input.commandRouting, input.eventRouting, input.stateUpdateRouting, input.metadata.idField);
         return RepositoryRoutes.freezeRouting(schemas, readiness, stateSubscriptions, filters, routes, input.metadata.idField);
     },
+    /**
+     * Builds Command and Event handler readiness lookups when handlers exist.
+     *
+     * @param handlers Registered Entity handler metadata.
+     * @returns Readiness lookups, or absent lookups for no handlers.
+     */
     readiness(handlers) {
         return handlers.length === 0
             ? { command: undefined, event: undefined }
@@ -2122,12 +3541,25 @@ const RepositoryRoutes = {
                 event: EventRegistrationReadiness.fromEntityHandlers(handlers),
             };
     },
+    /**
+     * Collects accepted, produced, and origin-specific message schemas.
+     *
+     * @param handlers Registered Entity handler metadata.
+     * @param producedEvents Additional Event schemas this repository may emit.
+     * @returns Schema groups used to build routes.
+     */
     routingSchemas(handlers, producedEvents) {
         const accepted = RepositoryRoutes.acceptedSchemas(handlers);
         const origins = RepositoryRoutes.originSchemas(handlers);
         const produced = RepositoryRoutes.producedSchemas(handlers, producedEvents);
         return { ...accepted, ...origins, ...produced };
     },
+    /**
+     * Collects Command, Event, and state schemas accepted by handlers.
+     *
+     * @param handlers Registered Entity handler metadata.
+     * @returns Deduplicated accepted schema groups.
+     */
     acceptedSchemas(handlers) {
         const command = RepositoryHandlers.uniqueSchemas(handlers.flatMap((handler) => [
             ...handler.commandAssignments.map((assignment) => assignment.schema),
@@ -2137,11 +3569,16 @@ const RepositoryRoutes = {
             ...handler.commandReactions.map((reaction) => reaction.schema),
             ...handler.eventSubscriptions.map((subscription) => subscription.schema),
             ...handler.eventReactions.map((reaction) => reaction.schema),
-            ...handler.eventApplications.map((application) => application.schema),
         ]));
         const state = RepositoryHandlers.uniqueSchemas(handlers.flatMap((handler) => handler.stateSubscriptions.map((subscription) => subscription.schema)));
         return { command, event, state };
     },
+    /**
+     * Groups domestic and external Event schemas declared by handlers.
+     *
+     * @param handlers Registered Entity handler metadata.
+     * @returns Origin-specific Event schema groups.
+     */
     originSchemas(handlers) {
         const schemas = (origin) => RepositoryHandlers.uniqueSchemas(handlers.flatMap((handler) => handler.handlers
             .filter((candidate) => candidate.origin === origin &&
@@ -2151,6 +3588,13 @@ const RepositoryRoutes = {
             .map((candidate) => candidate.schema)));
         return { domesticEvent: schemas("domestic"), externalEvent: schemas("external") };
     },
+    /**
+     * Collects schemas for Events and Commands handlers may produce.
+     *
+     * @param handlers Registered Entity handler metadata.
+     * @param explicitEvents Additional Event schemas configured on the repository.
+     * @returns Deduplicated produced Event and Command schema groups.
+     */
     producedSchemas(handlers, explicitEvents) {
         const producedEvent = RepositoryHandlers.uniqueSchemas([
             ...explicitEvents,
@@ -2167,6 +3611,13 @@ const RepositoryRoutes = {
         ]));
         return { producedEvent, producedCommand };
     },
+    /**
+     * Rejects state subscriptions outside Projections or to the same state type.
+     *
+     * @param entityFamily Repository Entity family.
+     * @param metadata Descriptor-derived state metadata.
+     * @param schemas Subscribed Entity state schemas.
+     */
     validateStateSchemas(entityFamily, metadata, schemas) {
         if (entityFamily !== "projection" && schemas.length > 0) {
             throw new Error("Entity state subscriptions are supported only by Projection repositories.");
@@ -2176,6 +3627,15 @@ const RepositoryRoutes = {
                 "resulting update would be routed back to the same repository.");
         }
     },
+    /**
+     * Builds Event filters for reactors, subscribers, and Command reactions.
+     *
+     * @param handlers Registered Entity handler metadata.
+     * @param eventSchemas Accepted Event schemas.
+     * @param readiness Event handler readiness lookup, when present.
+     * @param stringifiers Field conversion registry for filters.
+     * @returns Compiled Event filter groups.
+     */
     routingFilters(handlers, eventSchemas, readiness, stringifiers) {
         const commandReactionMap = RepositoryHandlers.createCommandReactionMap(handlers);
         const subscribers = RepositoryHandlers.readinessMap(eventSchemas, (typeName) => readiness?.findEventSubscribers(typeName) ?? []);
@@ -2187,6 +3647,17 @@ const RepositoryRoutes = {
             eventReactors: RepositoryHandlers.createEventFilterPlans(reactors, stringifiers),
         };
     },
+    /**
+     * Resolves captured custom routes for each accepted signal schema.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Accepted signal and state schemas.
+     * @param command Captured Command route declarations.
+     * @param event Captured Event route declarations.
+     * @param state Captured state-update route declarations.
+     * @param idField Canonical target Entity ID field.
+     * @returns Custom route maps by schema.
+     */
     routingMaps(schemas, command, event, state, idField) {
         return {
             command: RepositoryRoutes.resolveCommandRoutes(schemas.command, command),
@@ -2194,6 +3665,18 @@ const RepositoryRoutes = {
             state: RepositoryRoutes.resolveStateRoutes(schemas.state, state, idField),
         };
     },
+    /**
+     * Creates immutable schema sets, handler selectors, and signal route operations.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Accepted and produced schema groups.
+     * @param readiness Handler readiness lookups.
+     * @param stateSubscriptions State subscribers by source type.
+     * @param filters Compiled Event filter groups.
+     * @param routes Custom route maps by schema.
+     * @param idField Canonical target Entity ID field.
+     * @returns Immutable repository routing.
+     */
     freezeRouting(schemas, readiness, stateSubscriptions, filters, routes, idField) {
         return Object.freeze({
             commandSchemas: schemas.command,
@@ -2210,6 +3693,12 @@ const RepositoryRoutes = {
             ...RepositoryRoutes.routeSelectors(schemas, readiness, stateSubscriptions, filters, routes, idField),
         });
     },
+    /**
+     * Builds filter-aware selectors for Command reactions and Event handlers.
+     *
+     * @param filters Compiled Event filter groups.
+     * @returns Functions that select matching handler registrations.
+     */
     handlerSelectors(filters) {
         return {
             commandReactions: (typeName, message, external) => RepositoryRoutes.selectHandlers(filters.commandReactions, typeName, message, external),
@@ -2217,9 +3706,31 @@ const RepositoryRoutes = {
             eventSubscribers: (typeName, message, external) => RepositoryRoutes.selectHandlers(filters.eventSubscribers, typeName, message, external),
         };
     },
+    /**
+     * Finds handlers matching message fields and Event origin.
+     *
+     * @typeParam Value Handler registration with origin metadata.
+     * @param filters Compiled filter plans indexed by Event type.
+     * @param typeName Source Event type name.
+     * @param message Decoded Event message.
+     * @param external Whether the Event has external origin.
+     * @returns Matching handler registrations.
+     */
     selectHandlers(filters, typeName, message, external) {
         return RepositoryHandlers.forOrigin(filters.get(typeName)?.select(message) ?? Object.freeze([]), external);
     },
+    /**
+     * Builds Command, Event, and state-update route functions.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Accepted signal and state schemas.
+     * @param readiness Handler readiness lookups.
+     * @param stateSubscriptions State subscribers by source type.
+     * @param filters Compiled Event filter groups.
+     * @param routes Custom route maps by schema.
+     * @param idField Canonical target Entity ID field.
+     * @returns Route functions for repository dispatch.
+     */
     routeSelectors(schemas, readiness, stateSubscriptions, filters, routes, idField) {
         return {
             routeCommand: RepositoryRoutes.commandSelector(schemas, readiness, routes, idField),
@@ -2227,15 +3738,57 @@ const RepositoryRoutes = {
             routeStateUpdate: RepositoryRoutes.stateSelector(schemas, stateSubscriptions, routes, idField),
         };
     },
+    /**
+     * Builds a Command route function from readiness and custom declarations.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Accepted Command schemas.
+     * @param readiness Command handler readiness lookup.
+     * @param routes Custom route maps by schema.
+     * @param idField Canonical target Entity ID field.
+     * @returns Function that routes one Command.
+     */
     commandSelector(schemas, readiness, routes, idField) {
         return (command) => RepositoryRoutes.routeCommand(command, readiness.command, schemas.command, idField, routes.command);
     },
+    /**
+     * Builds an Event route function from readiness and custom declarations.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Accepted Event schemas.
+     * @param readiness Event handler readiness lookup.
+     * @param filters Compiled Event filter groups.
+     * @param routes Custom route maps by schema.
+     * @param idField Canonical target Entity ID field.
+     * @returns Function that routes one Event.
+     */
     eventSelector(schemas, readiness, filters, routes, idField) {
         return (event) => RepositoryRoutes.routeEvent(event, readiness.event, filters.commandReactionMap, schemas.event, idField, routes.event);
     },
+    /**
+     * Builds a state-update route function for Projection subscriptions.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Subscribed state schemas.
+     * @param subscriptions State subscribers by source type.
+     * @param routes Custom state-update routes by schema.
+     * @param idField Canonical target Entity ID field.
+     * @returns Function that routes one state-change Event.
+     */
     stateSelector(schemas, subscriptions, routes, idField) {
         return (event) => RepositoryRoutes.routeStateUpdate(event, schemas.state, subscriptions, idField, routes.state);
     },
+    /**
+     * Routes a Command to its registered assignee and target Entity ID.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param command Command envelope to route.
+     * @param readiness Command handler readiness lookup.
+     * @param schemas Accepted Command schemas.
+     * @param targetIdField Canonical target Entity ID field.
+     * @param commandRoutes Custom Command routes by schema.
+     * @returns Deferred Command route for one target.
+     */
     routeCommand(command, readiness, schemas, targetIdField, commandRoutes) {
         const message = command.message;
         if (message === undefined || message.typeUrl === "") {
@@ -2256,6 +3809,14 @@ const RepositoryRoutes = {
             invocation: "deferred",
         });
     },
+    /**
+     * Resolves custom Command routes for registered schemas.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Accepted Command schemas.
+     * @param routing Captured Command route declarations.
+     * @returns Custom Command routes by schema.
+     */
     resolveCommandRoutes(schemas, routing) {
         const routes = new Map();
         RoutingDeclarations.validate(routing, schemas, "command");
@@ -2266,6 +3827,16 @@ const RepositoryRoutes = {
         }
         return routes;
     },
+    /**
+     * Calls a custom Command route with a decoded message and context.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param route Registered custom route.
+     * @param message Packed Command payload.
+     * @param schema Registered Command schema.
+     * @param context Source Command context, when present.
+     * @returns Candidate target Entity ID.
+     */
     callCommandRoute(route, message, schema, context) {
         const unpacked = AnyMessages.unpack(message, schema);
         if (unpacked === undefined) {
@@ -2273,34 +3844,56 @@ const RepositoryRoutes = {
         }
         return route(unpacked, context ?? create(CommandContextSchema));
     },
+    /**
+     * Routes an Event to interested Entity IDs using custom or default routing.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param event Event envelope to route.
+     * @param readiness Event handler readiness lookup.
+     * @param commandReactions Command reactions by Event type.
+     * @param schemas Accepted Event schemas.
+     * @param targetIdField Canonical target Entity ID field.
+     * @param eventRoutes Custom Event routes by schema.
+     * @returns Deferred Event route with target IDs.
+     */
     routeEvent(event, readiness, commandReactions, schemas, targetIdField, eventRoutes) {
         const message = event.message;
-        if (message === undefined || message.typeUrl === "") {
+        if (message === undefined || message.typeUrl === "")
             throw new Error("Repository event routing requires event.message.typeUrl.");
-        }
         const schema = RepositoryRoutes.schemaForTypeUrl(schemas, message.typeUrl, "event");
-        const hasReceiver = (commandReactions.get(schema.typeName)?.length ?? 0) > 0 ||
-            (readiness?.findEventSubscribers(schema.typeName).length ?? 0) > 0 ||
-            (readiness?.findEventReactors(schema.typeName).length ?? 0) > 0 ||
-            (readiness?.findEventApplications(schema.typeName).length ?? 0) > 0;
-        if (!hasReceiver) {
+        if (!RepositoryRoutes.hasEventReceiver(schema.typeName, commandReactions, readiness))
             throw new Error(`Repository event routing has no receiver for "${schema.typeName}".`);
-        }
         const customRoute = eventRoutes.get(schema);
-        if (customRoute !== undefined) {
-            return Object.freeze({
-                entityIds: RepositoryRoutes.callEventRoute(customRoute, message, schema, event.context, targetIdField),
-                messageFullTypeName: schema.typeName,
-                invocation: "deferred",
-            });
-        }
-        const targetId = RepositoryRoutes.readEventEntityId(event, message, schema, targetIdField);
+        const entityIds = customRoute === undefined
+            ? [RepositoryRoutes.readEventEntityId(event, message, schema, targetIdField)]
+            : RepositoryRoutes.callEventRoute(customRoute, message, schema, event.context, targetIdField);
         return Object.freeze({
-            entityIds: Object.freeze([targetId]),
+            entityIds: Object.freeze([...entityIds]),
             messageFullTypeName: schema.typeName,
             invocation: "deferred",
         });
     },
+    /**
+     * Checks whether any registered Event receptor accepts a message type.
+     *
+     * @param typeName Full generated Event type name.
+     * @param reactions Command reactions registered by Event type.
+     * @param readiness Event receptor readiness lookup.
+     * @returns Whether at least one receptor accepts the type.
+     */
+    hasEventReceiver(typeName, reactions, readiness) {
+        return ((reactions.get(typeName)?.length ?? 0) > 0 ||
+            (readiness?.findEventSubscribers(typeName).length ?? 0) > 0 ||
+            (readiness?.findEventReactors(typeName).length ?? 0) > 0);
+    },
+    /**
+     * Resolves custom Event routes for registered schemas.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Accepted Event schemas.
+     * @param routing Captured Event route declarations.
+     * @returns Custom Event routes by schema.
+     */
     resolveEventRoutes(schemas, routing) {
         const routes = new Map();
         RoutingDeclarations.validate(routing, schemas, "event");
@@ -2311,6 +3904,12 @@ const RepositoryRoutes = {
         }
         return routes;
     },
+    /**
+     * Groups state subscribers by source Entity type name.
+     *
+     * @param handlers Registered Entity handler metadata.
+     * @returns Frozen subscriber lists indexed by state type.
+     */
     stateSubscriptions(handlers) {
         const byType = new Map();
         for (const entityHandlers of handlers) {
@@ -2325,6 +3924,15 @@ const RepositoryRoutes = {
         }
         return new Map([...byType].map(([typeName, subscriptions]) => [typeName, Object.freeze([...subscriptions])]));
     },
+    /**
+     * Resolves state-update routes and checks default ID compatibility.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param schemas Subscribed source Entity state schemas.
+     * @param routing Captured state-update route declarations.
+     * @param targetIdField Canonical Projection ID field.
+     * @returns Custom state-update routes by schema.
+     */
     resolveStateRoutes(schemas, routing, targetIdField) {
         const routes = new Map();
         RoutingDeclarations.validate(routing, schemas, "state-update");
@@ -2338,13 +3946,23 @@ const RepositoryRoutes = {
         }
         return routes;
     },
+    /**
+     * Routes a System Event state update to interested Projections.
+     *
+     * @typeParam Id Projection identifier type.
+     * @param event Entity state-change System Event.
+     * @param schemas Subscribed source state schemas.
+     * @param subscriptions State subscribers by source type.
+     * @param targetIdField Canonical Projection ID field.
+     * @param routes Custom state-update routes by schema.
+     * @returns Route and decoded state, or `undefined` when uninterested.
+     */
     routeStateUpdate(event, schemas, subscriptions, targetIdField, routes) {
         const update = RepositoryRoutes.decodeStateUpdate(event, schemas, "Repository state-update routing");
         const candidates = subscriptions.get(update?.schema.typeName ?? "") ?? [];
-        const interested = Object.freeze(candidates.filter((subscriber) => (subscriber.handler.origin === "external") === (event.context?.external === true)));
-        if (update === undefined || interested.length === 0) {
+        const interested = RepositoryRoutes.originSubscribers(candidates, event);
+        if (update === undefined || interested.length === 0)
             return undefined;
-        }
         const { schema, state } = update;
         const custom = routes.get(schema);
         const candidateIds = custom === undefined
@@ -2358,6 +3976,24 @@ const RepositoryRoutes = {
             invocation: "deferred",
         });
     },
+    /**
+     * Finds state subscribers whose origin declaration matches an Event.
+     *
+     * @param candidates Subscribers registered for one source state type.
+     * @param event State-update Event carrying the domestic or external origin.
+     * @returns Frozen matching subscriber list.
+     */
+    originSubscribers(candidates, event) {
+        return Object.freeze(candidates.filter((subscriber) => (subscriber.handler.origin === "external") === (event.context?.external === true)));
+    },
+    /**
+     * Decodes the new Entity state carried by a state-change System Event.
+     *
+     * @param event Candidate System Event.
+     * @param schemas Subscribed source state schemas.
+     * @param operation Operation name for diagnostics.
+     * @returns Decoded schema and state, or `undefined` for unrelated Events.
+     */
     decodeStateUpdate(event, schemas, operation) {
         const message = event.message;
         if (message?.typeUrl !== TypeUrls.derive(EntityLog.EntityStateChangedSchema)) {
@@ -2376,6 +4012,16 @@ const RepositoryRoutes = {
             throw new Error(`${operation} requires a readable Entity state.`);
         return Object.freeze({ schema, state });
     },
+    /**
+     * Calls a custom state-update route and validates its target IDs.
+     *
+     * @typeParam Id Projection identifier type.
+     * @param route Registered state-update route.
+     * @param state Decoded source Entity state.
+     * @param context Source Event context, when present.
+     * @param targetIdField Canonical Projection ID field.
+     * @returns Validated Projection target IDs.
+     */
     callStateUpdateRoute(route, state, context, targetIdField) {
         const candidates = route(state, context ?? create(EventContextSchema));
         if (!Array.isArray(candidates))
@@ -2391,6 +4037,17 @@ const RepositoryRoutes = {
         }
         return Object.freeze([...unique.values()]);
     },
+    /**
+     * Calls a custom Event route and validates its target IDs.
+     *
+     * @typeParam Id Repository Entity identifier type.
+     * @param route Registered custom Event route.
+     * @param message Packed Event payload.
+     * @param schema Registered Event schema.
+     * @param context Source Event context, when present.
+     * @param targetIdField Canonical target Entity ID field.
+     * @returns Validated target Entity IDs.
+     */
     callEventRoute(route, message, schema, context, targetIdField) {
         const unpacked = AnyMessages.unpack(message, schema);
         if (unpacked === undefined) {
@@ -2412,6 +4069,14 @@ const RepositoryRoutes = {
         }
         return Object.freeze([...unique.values()]);
     },
+    /**
+     * Finds a registered message schema by its type URL.
+     *
+     * @param schemas Accepted message schemas.
+     * @param typeUrl Packed message type URL.
+     * @param signalKind Signal name for diagnostics.
+     * @returns Matching generated schema.
+     */
     schemaForTypeUrl(schemas, typeUrl, signalKind) {
         const schema = schemas.find((candidate) => TypeUrls.derive(candidate) === typeUrl);
         if (schema === undefined) {
@@ -2419,6 +4084,14 @@ const RepositoryRoutes = {
         }
         return schema;
     },
+    /**
+     * Reads the default target ID from a decoded signal's first field.
+     *
+     * @param message Packed Command or Event payload.
+     * @param schema Generated payload schema.
+     * @param signalKind Signal name for validation.
+     * @returns Nonempty first-field value.
+     */
     readFirstFieldId(message, schema, signalKind) {
         const unpacked = AnyMessages.unpack(message, schema);
         const firstField = schema.fields[0];
@@ -2437,6 +4110,15 @@ const RepositoryRoutes = {
         }
         return value;
     },
+    /**
+     * Reads the first state field compatible with a Projection target ID.
+     *
+     * @param state Decoded source Entity state.
+     * @param schema Source state schema.
+     * @param targetIdField Canonical Projection ID field.
+     * @param signalKind State-update name for validation.
+     * @returns Validated Projection target ID.
+     */
     firstCompatibleId(state, schema, targetIdField, signalKind) {
         const field = schema.fields.find((candidate) => RepositoryRoutes.compatibleStateIdField(candidate, targetIdField));
         if (field === undefined)
@@ -2444,6 +4126,13 @@ const RepositoryRoutes = {
         const value = state[field.localName];
         return RepositoryRoutes.readRouteId(value, targetIdField, signalKind);
     },
+    /**
+     * Checks whether a source state field can route to the target ID type.
+     *
+     * @param field Candidate source state field.
+     * @param targetIdField Canonical target Entity ID field.
+     * @returns Whether message or primitive ID types match.
+     */
     compatibleStateIdField(field, targetIdField) {
         if (field.fieldKind === "list" || field.fieldKind === "map")
             return false;
@@ -2460,10 +4149,25 @@ const RepositoryRoutes = {
             return false;
         }
     },
+    /**
+     * Checks whether a candidate route ID is blank text.
+     *
+     * @param value Candidate identifier value.
+     * @returns Whether the value is an empty or whitespace string.
+     */
     isBlankRouteId(value) {
         const id = PrimitiveIds.readFinite(value);
         return typeof id === "string" && id.trim().length === 0;
     },
+    /**
+     * Reads a compatible producer ID or the Event payload's first-field ID.
+     *
+     * @param event Source Event envelope.
+     * @param message Packed Event payload.
+     * @param schema Generated Event schema.
+     * @param targetIdField Canonical target Entity ID field.
+     * @returns Validated target Entity ID.
+     */
     readEventEntityId(event, message, schema, targetIdField) {
         const producerId = event.context?.producerId;
         if (producerId === undefined || producerId.typeUrl.trim().length === 0) {
@@ -2475,6 +4179,13 @@ const RepositoryRoutes = {
         }
         return RepositoryRoutes.readRouteId(RepositoryRoutes.readFirstFieldId(message, schema, "event"), targetIdField, "event");
     },
+    /**
+     * Unpacks a producer ID when its type matches the target ID field.
+     *
+     * @param producerId Packed source producer identifier.
+     * @param targetIdField Canonical target Entity ID field.
+     * @returns Compatible decoded ID, or an incompatible marker.
+     */
     compatibleProducerId(producerId, targetIdField) {
         const descriptor = targetIdField.descriptor;
         if (descriptor.fieldKind === "message") {
@@ -2482,9 +4193,8 @@ const RepositoryRoutes = {
             if (producerId.typeUrl !== TypeUrls.derive(schema))
                 return { compatible: false };
             const id = Identifiers.unpack(schema, producerId);
-            if (id === undefined) {
+            if (id === undefined)
                 throw new Error("Repository event routing requires a readable compatible producer ID.");
-            }
             return { compatible: true, id };
         }
         if (descriptor.fieldKind !== "scalar") {
@@ -2503,11 +4213,16 @@ const RepositoryRoutes = {
             : type === "int32"
                 ? Identifiers.unpack("int32", producerId)
                 : Identifiers.unpack("int64", producerId);
-        if (id === undefined) {
+        if (id === undefined)
             throw new Error("Repository event routing requires a readable compatible producer ID.");
-        }
         return { compatible: true, id };
     },
+    /**
+     * Maps a supported Protobuf scalar to its primitive identifier family.
+     *
+     * @param type Protobuf scalar field type.
+     * @returns String, 32-bit integer, or 64-bit integer ID family.
+     */
     primitiveIdentifierType(type) {
         switch (type) {
             case ScalarType.STRING:
@@ -2524,6 +4239,14 @@ const RepositoryRoutes = {
                 throw new Error("Repository event routing requires a supported Entity ID type.");
         }
     },
+    /**
+     * Validates a candidate target ID against the Entity state ID field.
+     *
+     * @param value Candidate identifier.
+     * @param targetIdField Canonical target Entity ID field.
+     * @param signalKind Signal name for diagnostics.
+     * @returns Validated message or primitive identifier.
+     */
     readRouteId(value, targetIdField, signalKind) {
         const descriptor = targetIdField.descriptor;
         if (descriptor.fieldKind === "message") {
@@ -2534,6 +4257,14 @@ const RepositoryRoutes = {
         }
         throw new Error(`Repository ${signalKind} routing requires a scalar or message-valued ID.`);
     },
+    /**
+     * Validates a generated message-valued target ID.
+     *
+     * @param value Candidate identifier.
+     * @param targetSchema Generated target ID schema.
+     * @param signalKind Signal name for diagnostics.
+     * @returns Validated and encodable ID message.
+     */
     readMessageRouteId(value, targetSchema, signalKind) {
         const id = MessageIds.read(value);
         if (id === undefined) {
@@ -2556,6 +4287,14 @@ const RepositoryRoutes = {
         }
         return id;
     },
+    /**
+     * Validates a primitive target ID against a Protobuf scalar type.
+     *
+     * @param value Candidate identifier.
+     * @param targetType Canonical ID field scalar type.
+     * @param signalKind Signal name for diagnostics.
+     * @returns Compatible string, number, or bigint ID.
+     */
     readPrimitiveRouteId(value, targetType, signalKind) {
         const id = RepositoryRoutes.readCompatiblePrimitiveId(value, targetType);
         if (id === undefined) {
@@ -2563,6 +4302,13 @@ const RepositoryRoutes = {
         }
         return id;
     },
+    /**
+     * Reads a nonblank primitive ID within the target scalar's range.
+     *
+     * @param value Candidate identifier.
+     * @param targetType Canonical ID field scalar type.
+     * @returns Compatible primitive ID, or `undefined`.
+     */
     readCompatiblePrimitiveId(value, targetType) {
         switch (targetType) {
             case ScalarType.STRING:
@@ -2592,6 +4338,15 @@ Object.freeze(RepositoryRoutes);
  * Internal repository storage operations.
  */
 const RepositoryStorage = {
+    /**
+     * Opens Entity storage and an atomic commit port from a storage factory.
+     *
+     * @typeParam I Entity identifier type.
+     * @typeParam S Generated Entity state type.
+     * @param factory Provider storage factory.
+     * @param input Entity storage location and schema.
+     * @returns Storage ports closed together by one handle.
+     */
     openEntityStorage(factory, input) {
         const candidate = factory;
         if (candidate.createEntityStorage === undefined) {
@@ -2608,6 +4363,16 @@ const RepositoryStorage = {
             },
         };
     },
+    /**
+     * Returns one shared Entity storage handle per context and state type.
+     *
+     * @typeParam I Entity identifier type.
+     * @typeParam S Generated Entity state type.
+     * @param repository Repository tracking open handles.
+     * @param factory Provider storage factory.
+     * @param input Entity storage location and schema.
+     * @returns Shared Entity storage handle.
+     */
     openRepositoryEntityStorage(repository, factory, input) {
         const handle = RepositoryStorage.openEntityStorage(factory, input);
         const key = JSON.stringify({ context: input.context, state: input.sourceType.typeName });
@@ -2624,6 +4389,13 @@ const RepositoryStorage = {
         handles.set(key, handle);
         return handle;
     },
+    /**
+     * Builds Entity storage input with configured state and Event history flags.
+     *
+     * @param repository Repository Entity registration.
+     * @param context Tenant-aware storage context.
+     * @returns Entity storage description for the provider.
+     */
     entityStorageInput(repository, context) {
         const descriptor = entityStorageDescriptor(context, SpecScanner.scan(repository.entityType));
         const history = RepositoryStorage.historyConfiguration(repository);
@@ -2633,6 +4405,13 @@ const RepositoryStorage = {
             eventHistory: repository.entityFamily === "aggregate" || history.processManagerEventHistory,
         };
     },
+    /**
+     * Validates history and duplicate-dispatch options for an Entity family.
+     *
+     * @param options Repository history and guard settings.
+     * @param family Aggregate, Projection, or Process Manager family.
+     * @returns Normalized history and guard configuration.
+     */
     readHistoryConfiguration(options, family) {
         const guard = options.doubleDispatchGuard;
         const depth = guard === true
@@ -2657,22 +4436,32 @@ const RepositoryStorage = {
             dispatchGuardDepth: depth,
         };
     },
+    /**
+     * Reads history and guard settings captured for a repository.
+     *
+     * @param repository Repository to inspect.
+     * @returns Its validated configuration.
+     */
     historyConfiguration(repository) {
         const configuration = repositoryHistoryConfigurations.get(repository);
         if (configuration === undefined)
             throw new Error("Repository history configuration is unavailable.");
         return configuration;
     },
-    /**
-     * In-process bounded duplicate guard. Completion is recorded only after a successful execution;
-     * therefore provider/journal failures may be retried and separate machines remain independent.
-     */
 };
 Object.freeze(RepositoryStorage);
 /**
  * Internal repository history internals operations.
  */
 const RepositoryHistoryInternals = {
+    /**
+     * Binds state and Event history readers to one restored Entity instance.
+     *
+     * @param entity Instance receiving the history accessors.
+     * @param storage Entity storage used for reads and maintenance.
+     * @param entityId Identifier used to select history records.
+     * @param schema Schema used to unpack state records.
+     */
     bindEntityHistory(entity, storage, entityId, schema) {
         const stateCache = RepositoryHistoryInternals.createHistoryCache((depth, startingFromVersion) => storage.states.backward(entityId, depth, startingFromVersion), (record) => BigInt(EntityRecords.unpack(schema, record).versionMessage.number), { requireDescendingVersions: true });
         entityStateHistoryCaches.set(entity, stateCache);
@@ -2686,24 +4475,52 @@ const RepositoryHistoryInternals = {
         });
     },
     /**
-     * Creates a per-live-entity continuation cache that serializes a larger request behind a prior read.
+     * Creates a history cache that serializes reads and extends prior results.
      *
+     * @typeParam T State-record or Event type retained by the cache.
+     * @param load Reads a backward page, optionally continuing from a version.
+     * @param versionOf Reads the version used to continue a page.
+     * @param options State ordering and complete Event-group cache rules.
+     * @returns Read and clear operations for the new cache.
      * @internal Shared repository history-cache implementation, exercised by repository tests.
      */
     createHistoryCache(load, versionOf, options = {}) {
         return new RepositoryHistoryCache(load, versionOf, options).api();
     },
+    /**
+     * Copies a historical state and freezes the returned message object.
+     *
+     * @param state Historical state, absent when no record matched.
+     * @returns An independent state copy, or undefined.
+     */
     cloneHistoryState(state) {
         return state === undefined ? undefined : Object.freeze(structuredClone(state));
     },
+    /**
+     * Copies historical states and freezes their outer objects and list.
+     *
+     * @param states Historical states read from storage.
+     * @returns A frozen list of independent state copies.
+     */
     freezeHistoryStates(states) {
         return Object.freeze(states.map((state) => Object.freeze(structuredClone(state))));
     },
+    /**
+     * Copies historical Events and freezes their outer objects and list.
+     *
+     * @param events Historical Events read from storage.
+     * @returns A frozen list of independent Event copies.
+     */
     freezeHistoryEvents(events) {
         return Object.freeze(events.map((event) => Object.freeze(clone(EventSchema, event))));
     },
 };
 Object.freeze(RepositoryHistoryInternals);
+/**
+ * Reuses backward history pages during the lifetime of a restored Entity.
+ *
+ * @typeParam T State-record or Event type returned by the history reader.
+ */
 class RepositoryHistoryCache {
     #load;
     #versionOf;
@@ -2715,12 +4532,24 @@ class RepositoryHistoryCache {
     #nextVersion;
     #newestVersion;
     #generation = 0;
+    /**
+     * Creates an empty cache with the supplied history paging rules.
+     *
+     * @param load Reads a backward page, optionally continuing from a version.
+     * @param versionOf Extracts the continuation version from a history entry.
+     * @param options State ordering and complete Event-group cache rules.
+     */
     constructor(load, versionOf, options) {
         this.#load = load;
         this.#versionOf = versionOf;
         this.#requireDescendingVersions = options.requireDescendingVersions ?? false;
         this.#cacheCompleteVersionGroups = options.cacheCompleteVersionGroups ?? false;
     }
+    /**
+     * Exposes bound read and clear callbacks without exposing cache fields.
+     *
+     * @returns The operations used by Entity history accessors.
+     */
     api() {
         return Object.freeze({
             read: (depth) => this.read(depth),
@@ -2729,6 +4558,9 @@ class RepositoryHistoryCache {
             },
         });
     }
+    /**
+     * Clears cached entries and prevents pending reads from restoring stale pages.
+     */
     clear() {
         this.#generation += 1;
         this.#entries = Object.freeze([]);
@@ -2736,6 +4568,12 @@ class RepositoryHistoryCache {
         this.#nextVersion = undefined;
         this.#newestVersion = undefined;
     }
+    /**
+     * Reads up to the requested number of entries, extending cached history as needed.
+     *
+     * @param depth Maximum number of entries to return, newest first.
+     * @returns Cached and newly loaded entries, limited to the requested depth.
+     */
     async read(depth) {
         await this.#continuation;
         if (this.#isSatisfied(depth))
@@ -2751,9 +4589,21 @@ class RepositoryHistoryCache {
         await next;
         return result ?? this.#entries.slice(0, depth);
     }
+    /**
+     * Checks whether cached entries or known exhaustion satisfy a read.
+     *
+     * @param depth Requested number of entries.
+     * @returns True when another storage read is unnecessary.
+     */
     #isSatisfied(depth) {
         return this.#entries.length >= depth || this.#exhausted;
     }
+    /**
+     * Loads the missing entries using the configured continuation rule.
+     *
+     * @param depth Total number of entries requested by the caller.
+     * @returns A result containing uncached partial groups, or undefined to use the cache.
+     */
     async #extend(depth) {
         const generation = this.#generation;
         const requested = Math.max(1, depth - this.#entries.length);
@@ -2761,6 +4611,14 @@ class RepositoryHistoryCache {
             ? this.#extendCompleteGroups(depth, requested, generation)
             : this.#extendVersioned(depth, requested, generation);
     }
+    /**
+     * Loads an extra entry so a partial terminal version group is not cached.
+     *
+     * @param depth Total number of entries requested by the caller.
+     * @param requested Number of missing entries, excluding the look-ahead entry.
+     * @param generation Cache generation at the start of this read.
+     * @returns Requested entries, or undefined if the cache was cleared during loading.
+     */
     async #extendCompleteGroups(depth, requested, generation) {
         const loaded = await this.#load(requested + 1, this.#nextVersion);
         if (generation !== this.#generation)
@@ -2771,6 +4629,13 @@ class RepositoryHistoryCache {
         this.#exhausted = loaded.length < requested + 1;
         return Object.freeze(combined.slice(0, depth));
     }
+    /**
+     * Removes a terminal version group when the page may contain only part of it.
+     *
+     * @param loaded Page including the look-ahead entry when available.
+     * @param requested Number requested before adding the look-ahead entry.
+     * @returns Entries whose version groups are complete in this page.
+     */
     #completeGroups(loaded, requested) {
         const terminal = loaded.at(-1);
         const terminalVersion = terminal === undefined ? undefined : this.#versionOf(terminal);
@@ -2779,6 +4644,14 @@ class RepositoryHistoryCache {
             : loaded.findIndex((entry) => this.#versionOf(entry) === terminalVersion);
         return loaded.slice(0, Math.max(0, length));
     }
+    /**
+     * Loads more version-ordered history, refreshing or clearing invalid continuations.
+     *
+     * @param depth Total number of entries requested by the caller.
+     * @param requested Number of missing entries to load.
+     * @param generation Cache generation at the start of this read.
+     * @returns Undefined because accepted entries are read from the updated cache.
+     */
     async #extendVersioned(depth, requested, generation) {
         const loaded = await this.#load(requested, this.#nextVersion);
         if (generation !== this.#generation)
@@ -2799,6 +4672,12 @@ class RepositoryHistoryCache {
         this.#exhausted = loaded.length < requested;
         return undefined;
     }
+    /**
+     * Checks strict descending versions when required for state history.
+     *
+     * @param loaded Page to inspect for repeated or increasing versions.
+     * @returns True when two readable adjacent versions violate the ordering rule.
+     */
     #hasInvalidPage(loaded) {
         if (!this.#requireDescendingVersions)
             return false;
@@ -2810,12 +4689,24 @@ class RepositoryHistoryCache {
         }
         return false;
     }
+    /**
+     * Checks whether a continuation page is newer than the newest cached entry.
+     *
+     * @param latest First version in the loaded page, if readable.
+     * @returns True when the cache must restart from the newest history.
+     */
     #hasNewerPage(latest) {
         return (this.#newestVersion !== undefined &&
             latest !== undefined &&
             latest > this.#newestVersion &&
             this.#nextVersion !== undefined);
     }
+    /**
+     * Checks that a state-history continuation starts below the oldest cached version.
+     *
+     * @param latest First version in the loaded page, if readable.
+     * @returns True when the continuation overlaps or precedes the cached boundary.
+     */
     #hasInvalidContinuation(latest) {
         const oldest = this.#entries.at(-1);
         const oldestVersion = oldest === undefined ? undefined : this.#versionOf(oldest);
@@ -2824,6 +4715,13 @@ class RepositoryHistoryCache {
             latest !== undefined &&
             latest >= oldestVersion);
     }
+    /**
+     * Reads history again from the newest entry after detecting a newer page.
+     *
+     * @param depth Maximum number of entries to reload.
+     * @param generation Cache generation before this refresh clears the cache.
+     * @returns Undefined because accepted entries are stored in the cache.
+     */
     async #refresh(depth, generation) {
         this.clear();
         const refreshed = await this.#load(depth);
@@ -2836,6 +4734,11 @@ class RepositoryHistoryCache {
         this.#exhausted = refreshed.length < depth;
         return undefined;
     }
+    /**
+     * Adds an accepted page and records its oldest readable version.
+     *
+     * @param loaded Entries to add in storage order.
+     */
     #append(loaded) {
         this.#entries = Object.freeze([...this.#entries, ...loaded]);
         const last = loaded.at(-1);
@@ -2843,9 +4746,19 @@ class RepositoryHistoryCache {
     }
 }
 /**
- * Internal dispatch guards operations.
+ * Serializes guarded Event delivery and remembers recent completed dispatches.
  */
 const DispatchGuards = {
+    /**
+     * Dispatches an Event with duplicate checks when the repository enables them.
+     *
+     * @param repository Repository receiving the Event.
+     * @param runtime Storage and tenant context for the dispatch.
+     * @param event Event being delivered.
+     * @param entityId Target Entity identifier.
+     * @param dispatch Operation to run unless a completed delivery is found.
+     * @returns Completion of the dispatch or duplicate check.
+     */
     async guardedEntityEventDispatch(repository, runtime, event, entityId, dispatch) {
         const depth = RepositoryStorage.historyConfiguration(repository).dispatchGuardDepth;
         const eventId = event.id?.value;
@@ -2860,6 +4773,21 @@ const DispatchGuards = {
         guard.active += 1;
         return DispatchGuards.scheduleDispatch(repository, runtime, event, entityId, eventId, journalEventId, depth, guard, guards, dispatch);
     },
+    /**
+     * Queues a guarded dispatch after earlier work for the same Entity.
+     *
+     * @param repository Repository receiving the Event.
+     * @param runtime Storage and tenant context for the dispatch.
+     * @param event Event being delivered.
+     * @param entityId Target Entity identifier.
+     * @param eventId Original Event identifier used by the in-memory check.
+     * @param journalEventId Target-specific identifier used by stored diagnostic Events.
+     * @param depth Maximum completed identifiers and inactive Entity queues to retain.
+     * @param guard Queue and recent completion records for this Entity.
+     * @param guards Repository's collection of Entity queues.
+     * @param dispatch Operation to run unless a completed delivery is found.
+     * @returns Completion of this queued operation, retaining its failure for the caller.
+     */
     scheduleDispatch(repository, runtime, event, entityId, eventId, journalEventId, depth, guard, guards, dispatch) {
         const next = guard.chain.then(() => DispatchGuards.dispatchOnce(repository, runtime, event, entityId, eventId, journalEventId, depth, guard, dispatch));
         // spine-log-boundary: server.repository_dispatch_guard
@@ -2871,6 +4799,13 @@ const DispatchGuards = {
         });
         return next;
     },
+    /**
+     * Gets or creates the serialized dispatch queue for one Entity key.
+     *
+     * @param repository Repository whose queues are being accessed.
+     * @param key Canonical target Entity key.
+     * @returns The Entity queue and the repository collection containing it.
+     */
     guardLane(repository, key) {
         let guards = repositoryDispatchGuards.get(repository);
         if (guards === undefined) {
@@ -2884,6 +4819,20 @@ const DispatchGuards = {
         }
         return { guard, guards };
     },
+    /**
+     * Dispatches an Event unless memory or retained diagnostic Events show completion.
+     *
+     * @param repository Repository receiving the Event.
+     * @param runtime Storage and tenant context for the dispatch.
+     * @param event Event being delivered.
+     * @param entityId Target Entity identifier.
+     * @param eventId Original identifier used for recent in-memory completions.
+     * @param journalEventId Target-specific identifier to find in storage.
+     * @param depth Maximum retained Events to inspect and completions to remember.
+     * @param guard Recent completion records for this Entity.
+     * @param dispatch Operation to run when neither check finds a completed delivery.
+     * @returns Completion of the duplicate check and any required dispatch.
+     */
     async dispatchOnce(repository, runtime, event, entityId, eventId, journalEventId, depth, guard, dispatch) {
         if (guard.completed.has(eventId))
             return;
@@ -2902,6 +4851,13 @@ const DispatchGuards = {
         await dispatch();
         DispatchGuards.rememberGuardCompletion(guard, eventId, depth);
     },
+    /**
+     * Records a successful delivery and discards the oldest excess identifiers.
+     *
+     * @param guard Recent completion records for this Entity.
+     * @param eventId Identifier of the completed Event.
+     * @param depth Maximum number of identifiers to retain.
+     */
     rememberGuardCompletion(guard, eventId, depth) {
         if (!guard.completed.has(eventId)) {
             guard.completed.add(eventId);
@@ -2913,12 +4869,24 @@ const DispatchGuards = {
                 guard.completed.delete(expired);
         }
     },
+    /**
+     * Updates the queue list to place this Entity at its most recently used end.
+     *
+     * @param guards Repository collection of Entity queues.
+     * @param key Canonical key of the queue being used.
+     */
     touchGuardLane(guards, key) {
         const index = guards.order.indexOf(key);
         if (index >= 0)
             guards.order.splice(index, 1);
         guards.order.push(key);
     },
+    /**
+     * Removes least-recently-used inactive queues beyond the configured limit.
+     *
+     * @param guards Repository collection of Entity queues.
+     * @param depth Maximum queue count when enough queues are inactive.
+     */
     trimGuardLanes(guards, depth) {
         while (guards.order.length > depth) {
             const index = guards.order.findIndex((key) => guards.lanes.get(key)?.active === 0);
@@ -2930,6 +4898,14 @@ const DispatchGuards = {
             guards.lanes.delete(key);
         }
     },
+    /**
+     * Copies an Event with a target-specific identifier for duplicate checking.
+     *
+     * @param repository Repository supplying the target identifier descriptor.
+     * @param event Source Event, returned unchanged if it has no identifier.
+     * @param entityId Target Entity identifier.
+     * @returns An Event suitable for this target's diagnostic history.
+     */
     guardedJournalEvent(repository, event, entityId) {
         const sourceId = event.id?.value;
         if (sourceId === undefined)
@@ -2941,18 +4917,39 @@ const DispatchGuards = {
             }),
         });
     },
+    /**
+     * Creates an identifier from the original Event identifier and encoded target key.
+     *
+     * @param sourceId Original Event identifier.
+     * @param entityKey Canonical target Entity key.
+     * @returns The target-specific diagnostic Event identifier.
+     */
     guardedJournalEventId(sourceId, entityKey) {
         return `${sourceId}.guard.${encodeURIComponent(entityKey)}`;
     },
+    /**
+     * Encodes an Entity identifier using its repository descriptor and Inbox key format.
+     *
+     * @param repository Repository supplying the identifier descriptor.
+     * @param id Entity identifier to encode.
+     * @returns A stable key for dispatch queues and diagnostic Event identifiers.
+     */
     canonicalEntityIdKey(repository, id) {
         return InboxTargets.key(InboxMessages.inboxTargetId(id, repository.idField));
     },
 };
 Object.freeze(DispatchGuards);
 /**
- * Internal inbox messages operations.
+ * Packs target identifiers and reads typed signals from stored Inbox messages.
  */
 const InboxMessages = {
+    /**
+     * Packs an Entity identifier into the Inbox target representation.
+     *
+     * @param entityId Message, string, or integer Entity identifier.
+     * @param idField Descriptor identifying the Entity's ID field.
+     * @returns The packed target identifier.
+     */
     inboxTargetId(entityId, idField) {
         if (idField.descriptor.fieldKind === "message") {
             return Identifiers.pack(idField.descriptor.message, entityId);
@@ -2965,6 +4962,13 @@ const InboxMessages = {
             return Identifiers.pack("int64", entityId);
         throw new Error("Repository Entity Inbox handoff requires a supported target ID.");
     },
+    /**
+     * Unpacks and validates a stored Inbox target against the repository's ID field.
+     *
+     * @param targetId Packed target identifier stored with the Inbox message.
+     * @param idField Descriptor identifying the expected ID type.
+     * @returns The identifier used to restore the target Entity.
+     */
     targetEntityId(targetId, idField) {
         const descriptor = idField.descriptor;
         let entityId;
@@ -2993,6 +4997,12 @@ const InboxMessages = {
         }
         return RepositoryRoutes.readRouteId(entityId, idField, "command");
     },
+    /**
+     * Reads a Command from an Inbox message labeled for command handling.
+     *
+     * @param message Stored Inbox message to validate and unpack.
+     * @returns The stored Command envelope.
+     */
     readInboxCommand(message) {
         if (message.label !== "HANDLE_COMMAND") {
             throw new Error(`Entity Inbox replay does not handle "${message.label}" messages.`);
@@ -3003,12 +5013,33 @@ const InboxMessages = {
         }
         return command;
     },
+    /**
+     * Reads an Event labeled for a Process Manager reaction.
+     *
+     * @param message Stored Inbox message to validate and unpack.
+     * @returns The stored Event envelope.
+     */
     readPmInboxEvent(message) {
         return InboxMessages.readStoredEvent(message, "REACT_UPON_EVENT", "Entity Inbox replay", "Entity Inbox replay requires a readable stored event.");
     },
+    /**
+     * Reads an Event labeled for a Projection update.
+     *
+     * @param message Stored Inbox message to validate and unpack.
+     * @returns The stored Event envelope.
+     */
     readProjectionInboxEvent(message) {
         return InboxMessages.readStoredEvent(message, "UPDATE_SUBSCRIBER", "Projection inbox replay", "Projection inbox replay requires a readable stored event.");
     },
+    /**
+     * Validates an Inbox operation label and decodes its stored Event bytes.
+     *
+     * @param message Stored Inbox message to inspect.
+     * @param expectedLabel Operation label required by the caller.
+     * @param replayName Human-readable operation name used in label errors.
+     * @param unreadableMessage Error text used when Event decoding fails.
+     * @returns The stored Event envelope.
+     */
     readStoredEvent(message, expectedLabel, replayName, unreadableMessage) {
         if (message.label !== expectedLabel) {
             throw new Error(`${replayName} does not handle "${message.label}" messages.`);
@@ -3028,9 +5059,18 @@ const InboxMessages = {
 };
 Object.freeze(InboxMessages);
 /**
- * Internal inbox replay operations.
+ * Validates and dispatches stored Inbox signals to their recorded Entity targets.
  */
 const InboxReplay = {
+    /**
+     * Dispatches a stored Aggregate Command after checking its tenant and payload.
+     *
+     * @param repository Aggregate repository receiving the Command.
+     * @param routing Registered handlers and message schemas.
+     * @param message Stored Inbox message with the recorded target.
+     * @param deliveryTenantId Tenant selected by delivery in a multitenant context.
+     * @returns Any follow-up work that must wait for Inbox completion.
+     */
     async replayAggregateCommand(repository, routing, message, deliveryTenantId) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined) {
@@ -3045,6 +5085,15 @@ const InboxReplay = {
         const route = InboxReplay.replayCommandRoute(repository, routing, message, command);
         return await new AggregateCommandExecution(repository, routing, runtime, command).run(route);
     },
+    /**
+     * Routes Process Manager Command or Event replay by its stored operation label.
+     *
+     * @param repository Process Manager repository receiving the signal.
+     * @param routing Registered handlers and message schemas.
+     * @param message Stored Inbox message with the recorded target.
+     * @param deliveryTenantId Tenant selected by delivery in a multitenant context.
+     * @returns Any Command follow-up work that must wait for Inbox completion.
+     */
     async replayPmInbox(repository, routing, message, deliveryTenantId) {
         if (message.label === "HANDLE_COMMAND") {
             return await InboxReplay.replayProcessManagerCommand(repository, routing, message, deliveryTenantId);
@@ -3055,6 +5104,15 @@ const InboxReplay = {
         }
         throw new Error(`Entity Inbox replay does not handle "${message.label}" messages.`);
     },
+    /**
+     * Dispatches a stored Process Manager Command after tenant and payload validation.
+     *
+     * @param repository Process Manager repository receiving the Command.
+     * @param routing Registered handlers and message schemas.
+     * @param message Stored Inbox message with the recorded target.
+     * @param deliveryTenantId Tenant selected by delivery in a multitenant context.
+     * @returns Any follow-up work that must wait for Inbox completion.
+     */
     async replayProcessManagerCommand(repository, routing, message, deliveryTenantId) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined) {
@@ -3066,6 +5124,15 @@ const InboxReplay = {
         const route = InboxReplay.replayCommandRoute(repository, routing, message, command);
         return await new ProcessManagerCommandExecution(repository, routing, runtime, command).run(route);
     },
+    /**
+     * Dispatches a validated Event to the Process Manager target recorded in its Inbox.
+     *
+     * @param repository Process Manager repository receiving the Event.
+     * @param routing Registered handlers and message schemas.
+     * @param message Stored Inbox message with the recorded target.
+     * @param deliveryTenantId Tenant selected by delivery in a multitenant context.
+     * @returns Completion of dispatch to the recorded target.
+     */
     async replayProcessManagerEvent(repository, routing, message, deliveryTenantId) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined) {
@@ -3078,6 +5145,15 @@ const InboxReplay = {
         const [entityId] = route.entityIds;
         await new ProcessManagerEventExecution(repository, routing, runtime, event).runTarget(entityId, route);
     },
+    /**
+     * Dispatches a validated Event to the Projection target recorded in its Inbox.
+     *
+     * @param repository Projection repository receiving the Event.
+     * @param routing Registered subscribers and message schemas.
+     * @param message Stored Inbox message with the recorded target.
+     * @param deliveryTenantId Tenant selected by delivery in a multitenant context.
+     * @returns Completion of dispatch to the recorded target.
+     */
     async replayProjectionEvent(repository, routing, message, deliveryTenantId) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined) {
@@ -3090,6 +5166,15 @@ const InboxReplay = {
         const [entityId] = route.entityIds;
         await new ProjectionEventExecution(repository, routing, runtime, event).runTarget(entityId, route);
     },
+    /**
+     * Routes a Projection Inbox message to domain Event or Entity-state update replay.
+     *
+     * @param repository Projection repository receiving the update.
+     * @param routing Registered subscribers and message schemas.
+     * @param message Stored Projection Inbox message.
+     * @param deliveryTenantId Tenant selected by delivery in a multitenant context.
+     * @returns Completion of the selected replay operation.
+     */
     async replayProjectionMessage(repository, routing, message, deliveryTenantId) {
         const event = InboxMessages.readProjectionInboxEvent(message);
         if (event.message?.typeUrl === TypeUrls.derive(EntityLog.EntityStateChangedSchema)) {
@@ -3098,6 +5183,16 @@ const InboxReplay = {
         }
         await InboxReplay.replayProjectionEvent(repository, routing, message, deliveryTenantId);
     },
+    /**
+     * Dispatches an Entity-state update to the Projection target recorded in its Inbox.
+     *
+     * @param repository Projection repository receiving the state update.
+     * @param routing Registered state subscribers and schemas.
+     * @param message Stored Inbox message with the recorded target.
+     * @param event Event envelope carrying the Entity-state update.
+     * @param deliveryTenantId Tenant selected by delivery in a multitenant context.
+     * @returns Completion of state-subscriber dispatch to the recorded target.
+     */
     async replayProjectionStateUpdate(repository, routing, message, event, deliveryTenantId) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined)
@@ -3108,6 +5203,12 @@ const InboxReplay = {
         const subscribers = route.subscribers;
         await ProjectionEventExecution.runStateTarget(repository, routing, runtime, event, entityId, route, subscribers);
     },
+    /**
+     * Validates a stored Command against its schema and implicit identifier requirements.
+     *
+     * @param routing Registered Command schemas.
+     * @param command Envelope whose payload must remain valid on replay.
+     */
     validateReplayedCommandPayload(routing, command) {
         const commandMessage = EntityInvocation.requireSignalMessage(command.message, "command");
         const commandSchema = RepositoryRoutes.schemaForTypeUrl(routing.commandSchemas, commandMessage.typeUrl, "command");
@@ -3129,6 +5230,13 @@ const InboxReplay = {
             throw new CommandValidationError(implicitId.error);
         }
     },
+    /**
+     * Unpacks and validates a stored Event against its registered schema.
+     *
+     * @param routing Registered Event schemas.
+     * @param event Envelope whose payload must remain valid on replay.
+     * @param invalidPayloadMessage Error text used when the payload cannot be unpacked.
+     */
     validateReplayedEventPayload(routing, event, invalidPayloadMessage = "Projection inbox replay requires a readable event payload.") {
         const eventMessage = EntityInvocation.requireSignalMessage(event.message, "event");
         const eventSchema = RepositoryRoutes.schemaForTypeUrl(routing.eventSchemas, eventMessage.typeUrl, "event");
@@ -3138,6 +5246,13 @@ const InboxReplay = {
         }
         Validate.check(eventSchema, payload);
     },
+    /**
+     * Checks that a replayed Command's tenant matches its delivery tenant.
+     *
+     * @param context Context name and tenant mode; single-tenant contexts need no check.
+     * @param deliveryTenantId Tenant selected by Inbox delivery.
+     * @param command Stored Command containing the original actor context.
+     */
     validateReplayTenant(context, deliveryTenantId, command) {
         if (!context.multitenant) {
             return;
@@ -3153,6 +5268,13 @@ const InboxReplay = {
             throw new Error("Entity Inbox replay stored command tenant does not match.");
         }
     },
+    /**
+     * Checks that a replayed Projection Event's tenant matches its delivery tenant.
+     *
+     * @param context Context name and tenant mode; single-tenant contexts need no check.
+     * @param deliveryTenantId Tenant selected by Inbox delivery.
+     * @param event Stored Event containing the original tenant metadata.
+     */
     validateProjectionReplayTenant(context, deliveryTenantId, event) {
         if (!context.multitenant) {
             return;
@@ -3168,6 +5290,13 @@ const InboxReplay = {
             throw new Error("Projection inbox replay stored event tenant does not match.");
         }
     },
+    /**
+     * Checks that a replayed Process Manager Event's tenant matches its delivery tenant.
+     *
+     * @param context Context name and tenant mode; single-tenant contexts need no check.
+     * @param deliveryTenantId Tenant selected by Inbox delivery.
+     * @param event Stored Event containing the original tenant metadata.
+     */
     validatePmReplayTenant(context, deliveryTenantId, event) {
         if (!context.multitenant) {
             return;
@@ -3183,6 +5312,15 @@ const InboxReplay = {
             throw new Error("Entity Inbox replay stored event tenant does not match.");
         }
     },
+    /**
+     * Restores a Command route from the stored target instead of running routing again.
+     *
+     * @param repository Repository whose Entity type must match the stored target.
+     * @param routing Registered Command schemas.
+     * @param message Inbox message recording the target type and identifier.
+     * @param command Stored Command used to identify the registered handler schema.
+     * @returns A deferred route to the recorded Entity identifier.
+     */
     replayCommandRoute(repository, routing, message, command) {
         const expectedTargetTypeUrl = TypeUrls.derive(repository.stateSchema);
         if (message.inboxId.targetTypeUrl !== expectedTargetTypeUrl) {
@@ -3196,6 +5334,16 @@ const InboxReplay = {
             invocation: "deferred",
         });
     },
+    /**
+     * Restores a single-target Event route from a stored Inbox message.
+     *
+     * @param repository Repository whose Entity type must match the stored target.
+     * @param routing Registered Event schemas.
+     * @param message Inbox message recording the target type and identifier.
+     * @param event Stored Event used to identify the registered handler schema.
+     * @param replayName Operation name used when reporting a target-type mismatch.
+     * @returns A deferred route containing exactly the recorded target identifier.
+     */
     replayEventRoute(repository, routing, message, event, replayName) {
         const expectedTargetTypeUrl = TypeUrls.derive(repository.stateSchema);
         if (message.inboxId.targetTypeUrl !== expectedTargetTypeUrl) {
@@ -3211,6 +5359,15 @@ const InboxReplay = {
             invocation: "deferred",
         });
     },
+    /**
+     * Restores a Projection state-update route and its origin-compatible subscribers.
+     *
+     * @param repository Repository whose Entity type must match the stored target.
+     * @param routing Registered state schemas and subscribers.
+     * @param message Inbox message recording the Projection target.
+     * @param event Stored Entity-state update envelope.
+     * @returns A deferred route with the unpacked state and matching subscribers.
+     */
     replayStateUpdateRoute(repository, routing, message, event) {
         const expectedTargetTypeUrl = TypeUrls.derive(repository.stateSchema);
         if (message.inboxId.targetTypeUrl !== expectedTargetTypeUrl) {
@@ -3228,19 +5385,36 @@ const InboxReplay = {
             entityIds,
             messageFullTypeName: schema.typeName,
             state,
-            subscribers: Object.freeze((() => {
-                const candidates = routing.stateSubscriptions.get(schema.typeName) ?? [];
-                return candidates.filter((subscriber) => (subscriber.handler.origin === "external") === (event.context?.external === true));
-            })()),
+            subscribers: InboxReplay.stateSubscribers(routing, schema, event),
             invocation: "deferred",
         });
     },
+    /**
+     * Finds stored state subscribers matching the Event's origin.
+     *
+     * @param routing Registered state subscriptions.
+     * @param schema Decoded state schema.
+     * @param event Stored state-update Event.
+     * @returns Frozen origin-compatible subscriber list.
+     */
+    stateSubscribers(routing, schema, event) {
+        const candidates = routing.stateSubscriptions.get(schema.typeName) ?? [];
+        return Object.freeze(candidates.filter((subscriber) => (subscriber.handler.origin === "external") === (event.context?.external === true)));
+    },
 };
 Object.freeze(InboxReplay);
 /**
- * Internal inbox handoff operations.
+ * Records routed signals in the appropriate Entity or Projection Inbox.
  */
 const InboxHandoff = {
+    /**
+     * Routes a Command and submits it to the target Entity's Inbox.
+     *
+     * @param repository Repository supplying the Command route and Entity type.
+     * @param runtime Inbox, storage, tenant mode, and delivery strategy.
+     * @param command Command envelope to retain and deliver.
+     * @returns Completion of Inbox receipt and its selected delivery operation.
+     */
     async handoffEntityCommand(repository, runtime, command) {
         const route = repository.routeCommand(command);
         const commandId = RepositorySignals.requireCommandId(command);
@@ -3264,6 +5438,15 @@ const InboxHandoff = {
             keepUntil,
         }, deliveryTenantId);
     },
+    /**
+     * Delivers an Event to one Projection target with the duplicate-retention deadline.
+     *
+     * @param repository Repository supplying the Projection type and ID descriptor.
+     * @param runtime Projection Inbox, storage, and tenant mode.
+     * @param event Event envelope to retain and deliver.
+     * @param entityId Routed Projection identifier.
+     * @returns Completion of Inbox receipt and delivery.
+     */
     async handoffProjectionEvent(repository, runtime, event, entityId) {
         const eventId = RepositorySignals.requireEventId(event);
         const whenReceived = new Date();
@@ -3286,6 +5469,15 @@ const InboxHandoff = {
             keepUntil,
         }, deliveryTenantId);
     },
+    /**
+     * Delivers an Event to one Process Manager target using its Entity Inbox.
+     *
+     * @param repository Repository supplying the Process Manager type and ID descriptor.
+     * @param runtime Entity Inbox, storage, tenant mode, and delivery strategy.
+     * @param event Event envelope to retain and deliver.
+     * @param entityId Routed Process Manager identifier.
+     * @returns Completion of Inbox receipt and its selected delivery operation.
+     */
     async handoffPmEvent(repository, runtime, event, entityId) {
         const eventId = RepositorySignals.requireEventId(event);
         const whenReceived = new Date();
@@ -3298,6 +5490,15 @@ const InboxHandoff = {
         });
         await runtime.entityInbox.receive(delivery, InboxHandoff.pmEventInboxInput(repository, eventId.value, event, entityId, keepUntil), deliveryTenantId);
     },
+    /**
+     * Delivers an Event to all routed Process Manager targets through batch receipt.
+     *
+     * @param repository Repository supplying the Process Manager type and ID descriptor.
+     * @param runtime Entity Inbox, storage, tenant mode, and delivery strategy.
+     * @param event Event envelope shared by the target deliveries.
+     * @param entityIds Routed Process Manager identifiers.
+     * @returns Completion of batch receipt and its selected delivery operation.
+     */
     async handoffPmEvents(repository, runtime, event, entityIds) {
         const eventId = RepositorySignals.requireEventId(event);
         const whenReceived = new Date();
@@ -3311,6 +5512,16 @@ const InboxHandoff = {
         const inputs = entityIds.map((entityId) => InboxHandoff.pmEventInboxInput(repository, eventId.value, event, entityId, keepUntil));
         await runtime.entityInbox.receiveAll(delivery, inputs, deliveryTenantId);
     },
+    /**
+     * Builds a pending Process Manager Event delivery for a single target.
+     *
+     * @param repository Repository supplying the target type and ID descriptor.
+     * @param signalId Identifier of the original Event.
+     * @param event Event envelope to pack without repeating validation.
+     * @param entityId Routed Process Manager identifier.
+     * @param keepUntil Duplicate-retention deadline for this receipt.
+     * @returns Input for Entity Inbox receipt.
+     */
     pmEventInboxInput(repository, signalId, event, entityId, keepUntil) {
         return {
             inboxId: {
@@ -3327,9 +5538,16 @@ const InboxHandoff = {
 };
 Object.freeze(InboxHandoff);
 /**
- * Internal repository dispatch operations.
+ * Connects bus dispatchers and Inbox replay to repository execution.
  */
 const RepositoryDispatch = {
+    /**
+     * Creates the bus dispatchers supported by the repository's registered handlers.
+     *
+     * @param repository Repository providing Command and Event routes.
+     * @param routing Registered handlers, schemas, and state-update routes.
+     * @returns Command, Event, and system-Event dispatchers where applicable.
+     */
     createRepositoryDispatchers(repository, routing) {
         const acceptedEventRoutes = new WeakMap();
         const acceptedStateRoutes = new WeakMap();
@@ -3339,6 +5557,13 @@ const RepositoryDispatch = {
             systemEvent: RepositoryDispatch.stateDispatcher(repository, routing, acceptedStateRoutes),
         });
     },
+    /**
+     * Creates a Command dispatcher when the repository accepts Commands.
+     *
+     * @param repository Repository providing Command routes.
+     * @param routing Registered Command handlers and schemas.
+     * @returns The dispatcher, or undefined when no Command schema is registered.
+     */
     commandDispatcher(repository, routing) {
         return routing.commandSchemas.length === 0
             ? undefined
@@ -3347,6 +5572,14 @@ const RepositoryDispatch = {
                 dispatch: (command) => RepositoryDispatch.dispatchRepositoryCommand(repository, routing, command),
             });
     },
+    /**
+     * Creates an Event dispatcher that preserves routes computed during acceptance.
+     *
+     * @param repository Repository providing Event routes.
+     * @param routing Registered domestic and external Event handlers and schemas.
+     * @param accepted Cache of routes between Event acceptance and dispatch.
+     * @returns The dispatcher, or undefined when no Event schema is registered.
+     */
     eventDispatcher(repository, routing, accepted) {
         if (routing.eventSchemas.length === 0)
             return undefined;
@@ -3365,6 +5598,14 @@ const RepositoryDispatch = {
         });
         return EventDispatcherOriginSchemas.define(dispatcher, routing.domesticEventSchemas, routing.externalEventSchemas);
     },
+    /**
+     * Creates a system-Event dispatcher for registered Entity-state subscriptions.
+     *
+     * @param repository Repository receiving state updates.
+     * @param routing State schemas, subscribers, and origin-aware routing.
+     * @param accepted Cached accepted routes; null records an ignored update.
+     * @returns The dispatcher, or undefined when no state schema is registered.
+     */
     stateDispatcher(repository, routing, accepted) {
         if (routing.stateSchemas.length === 0)
             return undefined;
@@ -3381,6 +5622,15 @@ const RepositoryDispatch = {
         });
         return EventDispatcherOriginSchemas.define(dispatcher, hasOrigin("domestic") ? [schema] : [], hasOrigin("external") ? [schema] : []);
     },
+    /**
+     * Dispatches a cached state-update route unless acceptance ignored the update.
+     *
+     * @param repository Repository receiving the state update.
+     * @param routing State-update routes and subscribers.
+     * @param event System Event carrying the state update.
+     * @param accepted Cache populated during acceptance and cleared for this Event.
+     * @returns Completion of dispatch, or immediate completion for an ignored update.
+     */
     dispatchAcceptedState(repository, routing, event, accepted) {
         const route = accepted.get(event);
         accepted.delete(event);
@@ -3388,6 +5638,13 @@ const RepositoryDispatch = {
             ? Promise.resolve()
             : RepositoryDispatch.dispatchRepositoryStateUpdate(repository, routing, event, route);
     },
+    /**
+     * Creates replay access for an Aggregate or Process Manager with signal handlers.
+     *
+     * @param repository Repository providing signal routes and Entity identity.
+     * @param routing Registered handlers and message schemas.
+     * @returns The Inbox target and supported operation labels, when applicable.
+     */
     createEntityInboxTarget(repository, routing) {
         if ((repository.entityFamily !== "aggregate" && repository.entityFamily !== "process-manager") ||
             (routing.commandSchemas.length === 0 && routing.eventSchemas.length === 0)) {
@@ -3406,6 +5663,13 @@ const RepositoryDispatch = {
                 : InboxReplay.replayPmInbox(repository, routing, message, deliveryTenantId),
         });
     },
+    /**
+     * Creates replay access for a Projection with Event or state subscribers.
+     *
+     * @param repository Repository providing Projection identity and Event routes.
+     * @param routing Registered Event and state subscribers.
+     * @returns The Projection Inbox target, when applicable.
+     */
     createProjectionInboxTarget(repository, routing) {
         if (repository.entityFamily !== "projection" ||
             (routing.eventSchemas.length === 0 && routing.stateSchemas.length === 0)) {
@@ -3416,6 +5680,13 @@ const RepositoryDispatch = {
             replay: (message, deliveryTenantId) => InboxReplay.replayProjectionMessage(repository, routing, message, deliveryTenantId),
         });
     },
+    /**
+     * Creates direct Projection dispatch for ordinary delivery or rebuilding.
+     *
+     * @param repository Repository providing Projection identity and Event routes.
+     * @param routing Registered Projection subscribers and schemas.
+     * @returns A callback that validates routing only when no runtime is bound.
+     */
     createProjectionDirectDispatch(repository, routing) {
         return (event, rebuild) => {
             const runtime = repositoryRuntimes.get(repository);
@@ -3426,6 +5697,15 @@ const RepositoryDispatch = {
             return new ProjectionEventExecution(repository, routing, runtime, event, rebuild).runDirect();
         };
     },
+    /**
+     * Routes an Event to the execution path for the repository's Entity family.
+     *
+     * @param repository Repository providing Entity identity and Event routes.
+     * @param routing Registered Event handlers and schemas.
+     * @param event Event envelope to dispatch.
+     * @param acceptedRoute Previously accepted route, if available.
+     * @returns Completion of routing or runtime dispatch when a runtime is bound.
+     */
     async dispatchRepositoryEvent(repository, routing, event, acceptedRoute) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined) {
@@ -3446,12 +5726,31 @@ const RepositoryDispatch = {
                 return;
         }
     },
+    /**
+     * Dispatches an Event to each routed Aggregate with its configured duplicate guard.
+     *
+     * @param repository Aggregate repository receiving the Event.
+     * @param routing Registered Aggregate Event handlers and schemas.
+     * @param runtime Bound storage, publisher, and tenant context.
+     * @param event Event envelope to dispatch.
+     * @param route Accepted route listing target Aggregate identifiers.
+     * @returns Completion of all target dispatches in route order.
+     */
     async dispatchAggregateEvent(repository, routing, runtime, event, route) {
         const execution = new AggregateEventExecution(repository, routing, runtime, event);
         for (const entityId of route.entityIds) {
             await DispatchGuards.guardedEntityEventDispatch(repository, runtime, event, entityId, () => execution.runTarget(entityId, route));
         }
     },
+    /**
+     * Delivers a routed Entity-state update to each target Projection Inbox.
+     *
+     * @param repository Projection repository receiving the update.
+     * @param routing Registered state schemas and subscribers.
+     * @param event System Event carrying the state update.
+     * @param acceptedRoute Previously accepted state-update route, if available.
+     * @returns Completion of routing and any required Inbox receipts.
+     */
     async dispatchRepositoryStateUpdate(repository, routing, event, acceptedRoute) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined) {
@@ -3466,6 +5765,14 @@ const RepositoryDispatch = {
             await InboxHandoff.handoffProjectionEvent(repository, runtime, event, entityId);
         }
     },
+    /**
+     * Delivers Commands for Aggregates and Process Managers through their Entity Inboxes.
+     *
+     * @param repository Repository providing Command routes and Entity identity.
+     * @param routing Registered Command handler metadata.
+     * @param command Command envelope to dispatch.
+     * @returns Completion of Inbox receipt, or routing validation without a bound runtime.
+     */
     async dispatchRepositoryCommand(repository, routing, command) {
         const runtime = repositoryRuntimes.get(repository);
         if (runtime === undefined) {
@@ -3492,7 +5799,7 @@ const repositoryHistory = {
     /**
      * Creates a cache that extends a repository history only when a caller requests more entries.
      *
-     * @typeParam Entry - The history entry type.
+     * @typeParam Entry The history entry type.
      * @param load Loads entries before an optional continuation version.
      * @param versionOf Reads the optional version carried by an entry.
      * @param options Selects strictly descending-version and complete-group behavior.