@spine-event-engine/server 2.0.0-snapshot.25 → 2.0.0-snapshot.28

package/dist/context/bounded-context.js

@@ -11,10 +11,6 @@
  * or implied. See the License for the specific language governing permissions and limitations under
  * the License.
  */
-import { constants as fsConstants } from "node:fs";
-import { access, realpath } from "node:fs/promises";
-import { isAbsolute, relative, resolve, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
 import { clone, create, getOption, hasOption } from "@bufbuild/protobuf";
 import { freezeRegistry, isAiModel, registryOptions } from "@spine-event-engine/ai/spi/runtime";
 import { TypeUrls } from "@spine-event-engine/core";
@@ -28,18 +24,20 @@ import { DeliveryReadiness } from "./local-inbox-handoff.js";
 import { LocalEntityInbox } from "./entity-inbox.js";
 import { LocalProjectionInbox } from "./projection-handoff.js";
 import { TenantAdmissions } from "./tenant-unknown-error.js";
+import { SINGLE_TENANT } from "./tenant-index.js";
 import { AgentExecutionCapacity, } from "../agent/agent-execution-capacity.js";
 import { AgentAcceptanceReceipts, agentAcceptanceReceiptGroup, agentAcceptanceReceiptSpec, } from "../agent/agent-acceptance-receipts.js";
 import { Repository, repositoryAccess, } from "../repository/repository.js";
-import { GeneratedRegistryDiscovery } from "../handler/generated-registry-discovery.js";
+import { SpineMetadataInventory } from "../handler/spine-metadata-inventory.js";
 import { HandlerRegistryIngestor, } from "../handler/generated-handler-registry.js";
 import { AbstractAssignee, AbstractCommander, AbstractEventReactor, AbstractEventSubscriber, } from "../handler/standalone.js";
 import { HandlerMetadataRegistry, } from "../handler/handler-metadata.js";
 import { SignalMetadata } from "../runtime/signal-metadata.js";
 import { runtimeAccess } from "../runtime/runtime.js";
 import { Stand, standAccess } from "../stand/stand.js";
+import { ReadSideFilter } from "../stand/read-side-filter.js";
 import { SubscriptionRuntime, subscriptionRuntimeAccess } from "../stand/subscription-runtime.js";
-import { StorageSubscriptionRegistry, subscriptionRecordSpec, } from "../stand/subscription-registry.js";
+import { StorageSubscriptionRegistry, subscriptionRecordGroup, } from "../stand/subscription-registry.js";
 import { IntegrationBroker } from "../integration/integration-broker.js";
 import { ServerEnvironment, serverEnvironmentAccess } from "../server/server-environment.js";
 import { SignalPublisher } from "../runtime/signal-publisher.js";
@@ -100,11 +98,8 @@ export class DuplicateEntityStateException extends Error {
 const frameworkConstructionToken = Object.freeze({
     frameworkConstructionToken: true,
 });
-const generatedRegistryFile = "generated/handler/generated-handler-registry.js";
 const errorDetailLimit = 500;
-const moduleSchemeRe = /^[A-Za-z][A-Za-z\d+.-]*:/;
 const internalStoragePrefix = "__spine/";
-const generatedRegistryLoadAttempts = new Map();
 const eventSubscribers = new WeakMap();
 const contextSystemPairings = new WeakMap();
 const contextTenantIndexes = new WeakMap();
@@ -158,7 +153,7 @@ export class BoundedContext {
     #agentReceipts;
     #agentController = new AbortController();
     #agentReservations = new Set();
-    #activeReplays = new Set();
+    #activeDeliveries = new Set();
     #activePreparations = new Set();
     #tenantPreparations = new Map();
     #preparationController = new AbortController();
@@ -232,7 +227,7 @@ export class BoundedContext {
         eventBusAccess.bindEnvironment(this.#eventBus, this.#environment);
         eventBusAccess.bindEnvironment(this.#systemEventBus, this.#environment);
         commandBusAccess.setAdmission(this.#commandBus, (command) => this.#admitTenant(command.context?.actorContext?.tenantId));
-        eventBusAccess.setAdmission(this.#eventBus, (event) => this.#admitTenant(ContextParts.readReplayTenant(event)));
+        eventBusAccess.setAdmission(this.#eventBus, (event) => this.#admitTenant(ContextParts.readCatchUpTenant(event)));
         standAccess.setAdmission(this.#stand, (tenantId) => this.#admitTenant(tenantId));
         standAccess.setPublicAdmission(this.#stand, () => {
             if (closingContexts.has(this) && !runtimeAccess.isRunningAdmittedWork(this.#environment))
@@ -265,11 +260,12 @@ export class BoundedContext {
      * @returns Shared preparation completion.
      */
     #prepareShared(mode) {
-        if (!(this.#subscriptionRuntime.registry() instanceof StorageSubscriptionRegistry))
+        const registry = this.#subscriptionRuntime.registry();
+        if (!(registry instanceof StorageSubscriptionRegistry))
             return Promise.resolve();
         if (this.#sharedPreparation !== undefined)
             return this.#sharedPreparation;
-        const attempt = this.#trackPreparation(() => StoragePreparations.for(this.#storageFactory).prepareRecord(ContextParts.createSubscriptionStorageContext(this.#snapshot.spec), subscriptionRecordSpec, undefined, mode));
+        const attempt = this.#trackPreparation(() => registry.prepare(mode));
         this.#sharedPreparation = attempt;
         void attempt.catch(() => {
             if (this.#sharedPreparation === attempt)
@@ -379,10 +375,13 @@ export class BoundedContext {
     async #prepareCurrentTenants(mode) {
         if (!this.isMultitenant)
             return this.#requiredPrepare(() => this.#prepareTenant(undefined, mode));
+        const index = this.tenantIndex;
+        if (index === SINGLE_TENANT)
+            throw new Error("Multitenant preparation requires a tenant index.");
         let after;
         do {
             serverEnvironmentAccess.requireAvailable(this.#environment);
-            const page = await this.tenantIndex.page({
+            const page = await index.page({
                 count: 64,
                 signal: this.#preparationController.signal,
                 ...(after === undefined ? {} : { after }),
@@ -390,7 +389,7 @@ export class BoundedContext {
             serverEnvironmentAccess.requireAvailable(this.#environment);
             for (const id of page.ids) {
                 serverEnvironmentAccess.requireAvailable(this.#environment);
-                await TenantAdmissions.require(this.tenantIndex, this.name.value, true, id);
+                await TenantAdmissions.require(index, this.name.value, true, id);
                 serverEnvironmentAccess.requireAvailable(this.#environment);
                 await this.#requiredPrepare(() => this.#prepareTenant(id, mode));
             }
@@ -473,8 +472,8 @@ export class BoundedContext {
     /**
      * Creates tenant-aware Inboxes and their shared readiness signal.
      *
-     * @param tenantIndex Effective membership index for this context.
-     * @returns Inboxes, tenant index, and readiness signal.
+     * @param tenantIndex Captured marker or directory for this Bounded Context.
+     * @returns Inboxes, tenant setting, and readiness signal.
      */
     #createDelivery(tenantIndex) {
         const deliveryReadiness = this.#createReadiness();
@@ -482,8 +481,8 @@ export class BoundedContext {
         const entityInbox = new LocalEntityInbox(this.#snapshot.name.value, deliveryReadiness, onAdmit, this.#environment.delivery.strategy);
         const projectionInbox = new LocalProjectionInbox(this.#snapshot.name.value, deliveryReadiness, onAdmit);
         deliveryReadiness.configureDirect((message, tenantId) => message.label === "UPDATE_SUBSCRIBER"
-            ? projectionInbox.replay(message, tenantId)
-            : entityInbox.replay(message, tenantId));
+            ? projectionInbox.deliver(message, tenantId)
+            : entityInbox.deliver(message, tenantId));
         return { deliveryReadiness, tenantIndex, entityInbox, projectionInbox };
     }
     /**
@@ -523,10 +522,14 @@ export class BoundedContext {
                 this.#beginClose();
             },
             drain: () => this.#drainWork(),
-            trackReplay: (onReplay) => this.#trackReplay(onReplay),
+            trackDelivery: (onDelivery) => this.#trackDelivery(onDelivery),
         });
         contextDeliveryDescriptors.set(this, ContextParts.createDeliveryDescriptor(this.#entityInbox, this.#projectionInbox));
     }
+    /**
+     * Prepares repository registrations, reserves their state types, and commits their Stand and
+     * inbox targets; rolls back uncommitted storage preparation on failure.
+     */
     #registerRepositories(repositories) {
         const preparedRepositories = this.#prepareRepositories(repositories);
         try {
@@ -566,6 +569,10 @@ export class BoundedContext {
                 throw new DuplicateEntityStateException(stateType, prior.name.value, this.name.value);
         }
     }
+    /**
+     * Builds prepared repository registrations using this context’s storage and delivery services,
+     * cleaning earlier preparations if a later one fails.
+     */
     #prepareRepositories(repositories) {
         const registration = this.#repositoryRegistration();
         const preparedRepositories = [];
@@ -641,6 +648,10 @@ export class BoundedContext {
             ...(tenantId === undefined ? {} : { tenantId }),
         });
     }
+    /**
+     * Closes storage for repositories that were prepared but not committed, then rethrows the
+     * registration error with cleanup failures aggregated.
+     */
     #failRegistration(error, preparedRepositories) {
         const uncommitted = preparedRepositories.filter(({ repository }) => !this.#repositoryViews.has(repository));
         const closeErrors = ContextParts.closePreparedRepositories(uncommitted);
@@ -692,9 +703,10 @@ export class BoundedContext {
         return this.#snapshot.tenantMode === "multitenant";
     }
     /**
-     * Returns the live index configured for this Bounded Context.
+     * Returns the captured tenant setting for this Bounded Context.
      *
-     * @returns The effective configured index.
+     * @returns SINGLE_TENANT in single mode, even when the environment has an index;
+     * otherwise the effective directory. Narrow before calling index methods.
      */
     get tenantIndex() {
         return ContextParts.requireTenantIndex(this);
@@ -774,17 +786,16 @@ export class BoundedContext {
         throw new Error("Entity constructor is not registered in this Bounded Context.");
     }
     /**
-     * Clears and locally replays every registered Projection from already-stored events.
+     * Clears registered Projection state and processes already-stored Events locally.
      *
-     * Despite its legacy name, this method is not Projection catch-up. It is a
-     * process-local maintenance helper and provides no Projection targeting,
+     * This process-local maintenance helper provides no Projection targeting,
      * historical starting point, durable operation identity, progress,
      * historical/live coordination, restart, resumption, or multi-node work.
      *
      * Supported boundary:
      * - projection subscribers only;
      * - already-stored events only;
-     * - clear then replay, with no event re-append;
+     * - clear then dispatch stored Events, with no event re-append;
      * - single-tenant contexts reject `tenantId`;
      * - multitenant contexts require the exact non-blank `tenantId`;
      * - process-local sequential execution on the same EventBus runtime queue as
@@ -796,11 +807,15 @@ export class BoundedContext {
      * - durable live-traffic catch-up orchestration across processes.
      *
      * @param options Selects the tenant slice to rebuild.
-     * @returns Resolves to replay and clear counts for the selected slice.
+     * @returns Dispatch and clear counts for the selected slice.
      */
     async catchUpReadSide(options = {}) {
         return eventBusAccess.runExclusive(this.#eventBus, () => this.#catchUpReadSideOnce(options));
     }
+    /**
+     * Clears registered Projection state for the selected tenant slice, reads stored events,
+     * validates each Event’s tenant, and dispatches stored Events sequentially.
+     */
     async #catchUpReadSideOnce(options) {
         const storageContext = ContextParts.catchUpStorageContext(this.#snapshot.spec, options);
         const tenantOptions = ContextParts.catchUpStandOptions(storageContext);
@@ -808,7 +823,7 @@ export class BoundedContext {
         const clearTargets = ContextParts.projectionStateClearTargets(projections);
         const clearedStateTypes = [];
         let clearedEntityCount = 0;
-        let replayedEventCount = 0;
+        let processedEventCount = 0;
         for (const target of clearTargets) {
             clearedEntityCount += await this.#stand.clear(target.schema, tenantOptions);
             clearedStateTypes.push(target.typeUrl);
@@ -816,15 +831,15 @@ export class BoundedContext {
         const events = await ContextParts.readStoredEvents(storageContext, this.#storageFactory);
         for (const event of events) {
             try {
-                ContextParts.validateReplayTenant(storageContext, event);
-                replayedEventCount += await ContextParts.dispatchStoredProjectionEvent(projections, event, true);
+                ContextParts.validateCatchUpTenant(storageContext, event);
+                processedEventCount += await ContextParts.dispatchStoredProjectionEvent(projections, event, true);
             }
             catch (error) {
-                throw ContextParts.catchUpReplayError(event, error);
+                throw ContextParts.catchUpDispatchError(event, error);
             }
         }
         return Object.freeze({
-            replayedEventCount,
+            processedEventCount,
             clearedEntityCount,
             clearedStateTypes: Object.freeze(clearedStateTypes),
         });
@@ -891,13 +906,12 @@ export class BoundedContext {
         ContextParts.clearContextMetadata(this);
     }
     /**
-     * Settles entered replay, local follow-ups, and reserved Agent turns.
+     * Settles entered deliveries, outgoing handoffs, and reserved Agent turns.
      * @param errors Collects independent close failures.
      */
     async #drainAdmittedContextWork(errors) {
         await this.#closePart(() => Promise.allSettled([...this.#activePreparations]).then(() => undefined), errors);
-        await this.#closePart(() => Promise.allSettled([...this.#activeReplays]).then(() => undefined), errors);
-        await this.#closePart(() => this.#entityInbox.whenFollowUpsIdle(), errors);
+        await this.#closePart(() => Promise.allSettled([...this.#activeDeliveries]).then(() => undefined), errors);
         await this.#closePart(() => Promise.allSettled([...this.#agentReservations]).then(() => undefined), errors);
     }
     /**
@@ -932,15 +946,15 @@ export class BoundedContext {
         }
     }
     /**
-     * Registers an entered shared replay through its complete follow-up callback.
-     * @param onReplay Complete replay callback.
-     * @returns Completion of the captured callback.
+     * Registers an entered Inbox delivery through recipient processing and outgoing handoff.
+     * @param onDelivery Delivers the stored message.
+     * @returns Completion after the delivery callback returns.
      */
-    #trackReplay(onReplay) {
-        const replay = Promise.resolve().then(onReplay);
-        this.#activeReplays.add(replay);
-        void replay.then(() => this.#activeReplays.delete(replay), () => this.#activeReplays.delete(replay));
-        return replay;
+    #trackDelivery(onDelivery) {
+        const delivery = Promise.resolve().then(onDelivery);
+        this.#activeDeliveries.add(delivery);
+        void delivery.then(() => this.#activeDeliveries.delete(delivery), () => this.#activeDeliveries.delete(delivery));
+        return delivery;
     }
     /**
      * Calls a close action and collects its failure before later cleanup.
@@ -992,7 +1006,7 @@ export const boundedContextAccess = Object.freeze({
         const phase = contextClosePhases.get(context);
         if (prepare === undefined || phase === undefined)
             return Promise.reject(new TypeError("Service input requires a built context."));
-        return phase.trackReplay(async () => {
+        return phase.trackDelivery(async () => {
             await onMembership();
             await prepare(tenantId);
             await onReady?.();
@@ -1011,13 +1025,16 @@ export const boundedContextAccess = Object.freeze({
         const phase = contextClosePhases.get(context);
         if (phase === undefined)
             return Promise.reject(new TypeError("Service registry requires a built context."));
-        return phase.trackReplay(onOperation);
+        return phase.trackDelivery(onOperation);
     },
-    trackReplay(context, onReplay) {
+    /**
+     * Registers entered delivery work with the context close lifecycle.
+     */
+    trackDelivery(context, onDelivery) {
         const phase = contextClosePhases.get(context);
         if (phase === undefined)
-            return Promise.reject(new TypeError("Replay requires a built context."));
-        return phase.trackReplay(onReplay);
+            return Promise.reject(new TypeError("Delivery requires a built context."));
+        return phase.trackDelivery(onDelivery);
     },
     /**
      * Resolves a view only within the Bounded Context that issued it.
@@ -1035,18 +1052,27 @@ export const boundedContextAccess = Object.freeze({
             ? issued.repository
             : undefined;
     },
+    /**
+     * Stops new work at this Bounded Context and begins shutdown of its runtime facilities.
+     */
     beginClose(context) {
         const phase = contextClosePhases.get(context);
         if (phase === undefined)
             throw new TypeError("Close phase requires a built BoundedContext.");
         phase.begin();
     },
+    /**
+     * Waits for accepted runtime work and entered delivery operations to finish.
+     */
     drainWork(context) {
         const phase = contextClosePhases.get(context);
         if (phase === undefined)
             return Promise.reject(new TypeError("Drain requires a built BoundedContext."));
         return phase.drain();
     },
+    /**
+     * Installs the context logger on both EventBuses, the signal publisher, and subscription runtime.
+     */
     installLogger(context, logger) {
         if (!contextStorageFactories.has(context)) {
             throw new TypeError("Context logger requires a built BoundedContext instance.");
@@ -1068,6 +1094,9 @@ export const boundedContextAccess = Object.freeze({
         }
         subscriptionRuntimeAccess.installLogger(runtime, logger, context.name.value);
     },
+    /**
+     * Returns the diagnostic logger installed on this Bounded Context.
+     */
     loggerFor(context) {
         const logger = contextLoggers.get(context);
         if (logger === undefined) {
@@ -1075,11 +1104,17 @@ export const boundedContextAccess = Object.freeze({
         }
         return logger;
     },
+    /**
+     * Checks whether a value is a BoundedContextBuilder created by this module.
+     */
     isBuilder(value) {
         return (typeof value === "object" &&
             value !== null &&
             builderBuilds.has(value));
     },
+    /**
+     * Builds the supplied context builder and completes its configured initialization.
+     */
     build(builder) {
         const build = builderBuilds.get(builder);
         if (build === undefined) {
@@ -1087,6 +1122,9 @@ export const boundedContextAccess = Object.freeze({
         }
         return build();
     },
+    /**
+     * Attaches a subscriber to the context domain EventBus for the requested event type.
+     */
     subscribeToEvent(context, typeUrl, subscriber) {
         const subscribe = eventSubscribers.get(context);
         if (subscribe === undefined) {
@@ -1094,6 +1132,9 @@ export const boundedContextAccess = Object.freeze({
         }
         return subscribe(typeUrl, subscriber);
     },
+    /**
+     * Posts a framework System Event through the context System EventBus.
+     */
     postSystemEvent(context, event) {
         const post = systemEventPosters.get(context);
         if (post === undefined) {
@@ -1101,12 +1142,18 @@ export const boundedContextAccess = Object.freeze({
         }
         return post(event);
     },
+    /**
+     * Posts an external domain Event through the context EventBus.
+     */
     postExternalEvent(context, event) {
         const imported = clone(EventSchema, event);
         imported.context = clone(EventContextSchema, imported.context ?? create(EventContextSchema));
         imported.context.external = true;
         return context.eventBus().post(imported);
     },
+    /**
+     * Subscribes to events produced by this context and forwards matching signals to the supplied observer.
+     */
     observeProducedSignals(context, observer) {
         const publisher = contextSignalPublishers.get(context);
         if (publisher === undefined) {
@@ -1114,12 +1161,21 @@ export const boundedContextAccess = Object.freeze({
         }
         return publisher.observe(observer);
     },
+    /**
+     * Returns the domain/System specification pairing captured when the context was built.
+     */
     systemPairing(context) {
         return ContextParts.cloneSystemPairing(ContextParts.requireSystemPairing(context));
     },
+    /**
+     * Returns the captured marker or directory for this Bounded Context.
+     */
     tenantIndex(context) {
         return ContextParts.requireTenantIndex(context);
     },
+    /**
+     * Returns the storage factory captured for repository and Stand operations in this context.
+     */
     storageFactory(context) {
         const storageFactory = contextStorageFactories.get(context);
         if (storageFactory === undefined) {
@@ -1127,6 +1183,9 @@ export const boundedContextAccess = Object.freeze({
         }
         return storageFactory;
     },
+    /**
+     * Returns the persistent or in-memory registry used to store Stand subscription definitions.
+     */
     subscriptionRegistry(context) {
         const runtime = contextSubscriptionRuntimes.get(context);
         if (runtime === undefined) {
@@ -1134,13 +1193,24 @@ export const boundedContextAccess = Object.freeze({
         }
         return runtime.registry();
     },
-    consumeSubscription(context, id, onUpdate) {
+    /**
+     * Consumes a registered Stand subscription update and returns its managed delivery handle.
+     */
+    consumeSubscription(context, id, onUpdate, onInvalidated, expected) {
         const runtime = contextSubscriptionRuntimes.get(context);
         if (runtime === undefined) {
             throw new TypeError("Subscription consumption requires a built BoundedContext instance.");
         }
-        return runtime.consume(id, onUpdate);
+        return runtime.consume(id, (update) => {
+            onUpdate({
+                update,
+                filter: (facts) => standAccess.filterSubscription(context.stand(), update, facts),
+            });
+        }, onInvalidated, expected);
     },
+    /**
+     * Returns the context delivery descriptor used to route Entity and Projection inbox work.
+     */
     delivery(context) {
         const descriptor = contextDeliveryDescriptors.get(context);
         if (descriptor === undefined) {
@@ -1161,12 +1231,12 @@ export class BoundedContextBuilder {
     #eventReceivers = [];
     #repositories = new Set();
     #entityTypes = new Set();
+    #readFilters = new Set();
     #generatedRepositoryOptions = new Map();
     #aiRegistry;
     #tenantIndex;
     #subscriptionRegistry;
     #persistSystemEvents = false;
-    #generatedRegistryRoot;
     /**
      * Registers the framework-only construction hook for this module.
      */
@@ -1217,6 +1287,15 @@ export class BoundedContextBuilder {
     isMultitenant() {
         return this.#specSnapshot.multitenant;
     }
+    /**
+     * Adds an outward read policy to this Bounded Context.
+     * @param filter Policy applied before Server-level outward policies.
+     * @returns This builder for further configuration.
+     */
+    addReadSideFilter(filter) {
+        this.#readFilters.add(filter);
+        return this;
+    }
     /**
      * Adds an explicitly assembled repository or an Entity class.
      *
@@ -1321,7 +1400,9 @@ export class BoundedContextBuilder {
         return this;
     }
     /**
-     * Sets a live tenant index for this Bounded Context.
+     * Sets a directory that overrides the environment index for this multitenant Bounded Context.
+     * The environment must already have a real index at build time; an override
+     * cannot enable multitenancy in a SINGLE_TENANT environment.
      *
      * @param tenantIndex Application membership index.
      * @returns This builder.
@@ -1365,16 +1446,6 @@ export class BoundedContextBuilder {
         this.#subscriptionRegistry = registry;
         return this;
     }
-    /**
-     * Sets a trusted compiled application root for generated handler metadata.
-     *
-     * @param root Names the compiled package or application root.
-     * @returns Returns this builder for further configuration.
-     */
-    withGeneratedRegistryRoot(root) {
-        this.#generatedRegistryRoot = root;
-        return this;
-    }
     /**
      * Builds a context after loading generated handlers and preparing runtime resources.
      *
@@ -1384,6 +1455,10 @@ export class BoundedContextBuilder {
     build(options = {}) {
         return this.#buildAsyncWith(options);
     }
+    /**
+     * Loads generated handlers and repositories, assembles context facilities, and completes
+     * requested initialization before publishing the context.
+     */
     async #buildAsyncWith(options = {}) {
         const environment = ServerEnvironment.instance();
         const finishBuild = serverEnvironmentAccess.beginContextBuild(environment);
@@ -1415,10 +1490,11 @@ export class BoundedContextBuilder {
      * @returns The integrated context.
      */
     async #buildAsyncReady(options, environment) {
-        const generated = await this.#loadGeneratedArtifacts([...this.#entityTypes]);
+        const tenantIndex = this.#selectTenantIndex(environment);
+        const generated = this.#loadGeneratedArtifacts([...this.#entityTypes]);
         serverEnvironmentAccess.requireAvailable(environment);
         const repositories = [...this.#repositories, ...generated.repositories];
-        const context = await this.#buildWithResources(repositories, environment.storageFactory, generated.standalone, this.#aiRegistry ?? environment.ai);
+        const context = await this.#buildWithResources(repositories, environment.storageFactory, generated.standalone, this.#aiRegistry ?? environment.ai, tenantIndex);
         try {
             await this.#integrateBuiltContext(context, options, environment);
         }
@@ -1427,6 +1503,20 @@ export class BoundedContextBuilder {
         }
         return context;
     }
+    /**
+     * Captures tenant selection before acquiring business storage.
+     *
+     * @param environment Process facilities selected for this build.
+     * @returns Marker for single mode or the effective directory for multi mode.
+     */
+    #selectTenantIndex(environment) {
+        if (!this.#specSnapshot.multitenant)
+            return SINGLE_TENANT;
+        const configured = environment.tenantIndex;
+        if (configured === SINGLE_TENANT)
+            throw new Error("Multitenant Bounded Context requires an environment tenant index.");
+        return this.#tenantIndex ?? configured;
+    }
     /**
      * Completes required integration and requested initialization before publication.
      * @param context Constructed context.
@@ -1475,20 +1565,33 @@ export class BoundedContextBuilder {
      * @param storageFactory Storage factory for the context.
      * @param standalone Generated standalone handler groups.
      * @param ai Optional AI registry.
+     * @param tenantIndex Captured marker or directory for admission.
      * @returns The assembled context.
      */
-    async #buildWithResources(repositories, storageFactory, standalone, ai) {
+    async #buildWithResources(repositories, storageFactory, standalone, ai, tenantIndex) {
         const resources = this.#subscriptionRegistry === undefined ? {} : { registry: this.#subscriptionRegistry };
         this.#subscriptionRegistry = undefined;
         const registeredRepositories = [...repositories];
         try {
-            return this.#assembleContext(registeredRepositories, storageFactory, standalone, resources, ai);
+            return this.#assembleContext(registeredRepositories, storageFactory, standalone, resources, ai, tenantIndex);
         }
         catch (error) {
             return await this.#failBuild(resources, error);
         }
     }
-    #assembleContext(repositories, storageFactory, standalone, resources, ai) {
+    /**
+     * Assembles dispatchers, buses, Stand, subscription runtime, and integration hooks, registering
+     * the completed context with its environment.
+     *
+     * @param repositories Registered repository views.
+     * @param storageFactory Provider for business records.
+     * @param standalone Generated standalone handlers.
+     * @param resources Partial resources to close if assembly fails.
+     * @param ai Selected AI registry, when configured.
+     * @param tenantIndex Captured marker or directory.
+     * @returns Assembled Bounded Context.
+     */
+    #assembleContext(repositories, storageFactory, standalone, resources, ai, tenantIndex) {
         ContextParts.preflightRepositories(repositories);
         this.#preflightAgents(repositories, storageFactory, ai);
         if (ai !== undefined)
@@ -1502,17 +1605,28 @@ export class BoundedContextBuilder {
             ...ContextParts.repositoryProducedEventSchemas(repositories),
             ...ContextParts.standaloneProducedEventSchemas(standalone),
         ]);
-        const running = this.#buildRuntime(storageFactory, buses, resources);
-        const context = this.#createContext(repositories, storageFactory, buses, running, ai);
+        const running = this.#buildRuntime(storageFactory, buses, resources, tenantIndex);
+        const context = this.#createContext(repositories, storageFactory, buses, running, tenantIndex, ai);
         resources.context = context;
         if (registerBoundedContext === undefined)
             throw new Error("Context registration is unavailable.");
         registerBoundedContext(context, repositories);
+        this.#attachIntegration(context, buses, dispatchers, standaloneEvent);
+        return context;
+    }
+    /**
+     * Registers external Event routes after Bounded Context construction.
+     *
+     * @param context Completed Bounded Context.
+     * @param buses Signal buses and System metadata.
+     * @param dispatchers Repository dispatchers.
+     * @param standaloneEvent Generated standalone Event dispatcher, when present.
+     */
+    #attachIntegration(context, buses, dispatchers, standaloneEvent) {
         ContextParts.attachIntegration(context, buses.eventBus, buses.systemSpec, ContextParts.externalEventSchemas([
             ...dispatchers.domain,
             ...(standaloneEvent === undefined ? [] : [standaloneEvent]),
         ]));
-        return context;
     }
     /**
      * Rejects missing Agent prerequisites before repository intake is installed.
@@ -1540,6 +1654,9 @@ export class BoundedContextBuilder {
                 throw new TypeError("Agent repository capabilities must be factory-created models.");
         }
     }
+    /**
+     * Collects repository and configured event recipients into domain and System dispatcher groups.
+     */
     #buildDispatchers(repositories) {
         const event = [
             ...ContextParts.repositoryEventDispatchers(repositories),
@@ -1553,6 +1670,9 @@ export class BoundedContextBuilder {
             ],
         };
     }
+    /**
+     * Creates command, domain Event, and System Event buses plus their stores and signal publisher.
+     */
     #buildBuses(repositories, storageFactory, dispatchers, resources) {
         const commandBus = new CommandBus([
             ...this.#commandDispatchers,
@@ -1577,6 +1697,9 @@ export class BoundedContextBuilder {
             systemSpec: system.spec,
         };
     }
+    /**
+     * Creates the System context store, EventBus, and Stand, then registers System event dispatchers.
+     */
     #buildSystemBuses(storageFactory, dispatchers, resources) {
         const systemSpec = ContextParts.createSystemSpec(this.#specSnapshot, this.#persistSystemEvents);
         const systemEventStore = systemSpec.storesEvents
@@ -1600,6 +1723,10 @@ export class BoundedContextBuilder {
             spec: systemSpec,
         };
     }
+    /**
+     * Matches generated standalone handlers to configured instances and registers their dispatchers
+     * on the appropriate buses.
+     */
     #installStandalone(standalone, buses) {
         ContextParts.assertUniqueCommandReceptors(standalone);
         const runtime = standalone.length === 0
@@ -1616,34 +1743,60 @@ export class BoundedContextBuilder {
             buses.systemEventBus.register(state);
         return event;
     }
-    #buildRuntime(storageFactory, buses, resources) {
-        const stand = this.#buildStand(storageFactory);
+    /**
+     * Creates the context Stand, subscription registry, and runtime that observes domain and System events.
+     *
+     * @param storageFactory Provider for business records.
+     * @param buses Assembled signal buses.
+     * @param resources Partial resources to close if assembly fails.
+     * @param tenantIndex Captured marker or directory.
+     * @returns Assembled Stand and subscription runtime.
+     */
+    #buildRuntime(storageFactory, buses, resources, tenantIndex) {
+        const stand = this.#buildStand(storageFactory, tenantIndex);
         resources.stand = stand;
         const registry = resources.registry ??
-            new StorageSubscriptionRegistry(ContextParts.createSubscriptionStorageContext(this.#specSnapshot), storageFactory);
+            new StorageSubscriptionRegistry(ContextParts.createSubscriptionStorageContext(this.#specSnapshot), storageFactory, subscriptionRecordGroup(this.#specSnapshot.name.value));
         resources.registry = registry;
         const runtime = new SubscriptionRuntime(stand, buses.systemStand, buses.eventBus, buses.systemEventBus, registry);
         resources.runtime = runtime;
         return { stand, registry, runtime };
     }
     /**
-     * Builds the context Stand with a captured live membership directory.
+     * Builds the Bounded Context Stand with captured tenant admission.
      *
      * @param storageFactory Provider used for Entity records.
+     * @param tenantIndex Captured marker or directory.
      * @returns Direct read-side Stand.
      */
-    #buildStand(storageFactory) {
-        const tenantIndex = this.#tenantIndex ?? ServerEnvironment.instance().tenantIndex;
+    #buildStand(storageFactory, tenantIndex) {
         const stand = new Stand({
             context: ContextParts.createStorageMode(this.#specSnapshot),
             storageFactory,
         });
+        if (this.#readFilters.size > 0)
+            standAccess.installReadFilters(stand, [...this.#readFilters]);
         standAccess.setAdmission(stand, (tenantId) => TenantAdmissions.require(tenantIndex, this.#specSnapshot.name.value, this.#specSnapshot.multitenant, tenantId));
         return stand;
     }
-    #createContext(repositories, storageFactory, buses, running, ai) {
-        return ContextParts.createBoundedContext(this.#specSnapshot, storageFactory, repositories, ServerEnvironment.instance().delivery.strategy, buses, running, ai, this.#tenantIndex ?? ServerEnvironment.instance().tenantIndex);
+    /**
+     * Constructs the immutable BoundedContext using assembled buses, runtime parts, environment
+     * delivery strategy, and tenant setting.
+     *
+     * @param repositories Registered repository views.
+     * @param storageFactory Provider for business records.
+     * @param buses Assembled signal buses.
+     * @param running Prepared Stand and subscription runtime.
+     * @param tenantIndex Captured marker or directory.
+     * @param ai Selected AI registry, when configured.
+     * @returns Immutable Bounded Context.
+     */
+    #createContext(repositories, storageFactory, buses, running, tenantIndex, ai) {
+        return ContextParts.createBoundedContext(this.#specSnapshot, storageFactory, repositories, ServerEnvironment.instance().delivery.strategy, buses, running, ai, tenantIndex);
     }
+    /**
+     * Closes partial context resources after assembly fails and aggregates cleanup errors with the original failure.
+     */
     async #failBuild(resources, error) {
         const cleanupErrors = [];
         if (resources.context !== undefined) {
@@ -1675,28 +1828,27 @@ export class BoundedContextBuilder {
         }
         throw error;
     }
-    async #loadGeneratedArtifacts(entityTypes) {
+    /**
+     * Selects generated metadata for configured Entity and standalone handler types and creates
+     * repository views and handler groups.
+     */
+    #loadGeneratedArtifacts(entityTypes) {
         if (entityTypes.length === 0 && this.#standaloneInstances().length === 0) {
             return Object.freeze({ repositories: Object.freeze([]), standalone: Object.freeze([]) });
         }
-        const root = ContextParts.requireGeneratedRegistryRoot(this.#generatedRegistryRoot);
-        const discovery = new GeneratedRegistryDiscovery();
-        const registryModule = await ContextParts.trustedGeneratedRegistryModule(root);
-        const registryKey = registryModule.href;
-        const registries = (await discovery
-            .load({
-            modules: [registryModule],
-            ...ContextParts.generatedRegistryCacheBust(registryKey),
-        })
-            .catch((error) => {
-            ContextParts.recordGeneratedRegistryFailure(registryKey);
-            throw error;
-        }));
+        const selected = [
+            ...entityTypes,
+            ...this.#standaloneInstances().map((instance) => instance.constructor),
+        ];
+        const registries = [SpineMetadataInventory.select(selected)];
         const metadata = ContextParts.ingestGeneratedRegistries(registries);
         const repositories = Object.freeze(entityTypes.map((entityType) => ContextParts.createGeneratedRepository(entityType, registries, metadata, this.#generatedRepositoryOptions.get(entityType))));
         const standalone = Object.freeze(registries.flatMap((registry) => registry.receivers.filter((receiver) => receiver.receiverKind === "standalone")));
         return Object.freeze({ repositories, standalone });
     }
+    /**
+     * Returns a frozen list of configured standalone assignee, commander, and event-receiver instances.
+     */
     #standaloneInstances() {
         return Object.freeze([...this.#assignees, ...this.#commanders, ...this.#eventReceivers]);
     }
@@ -1775,28 +1927,28 @@ export class ContextSpec {
 }
 const registeredRepositories = new WeakMap();
 /**
- * Reports failure while redispatching a stored event during read-side replay.
+ * Reports failure while dispatching a stored Event during read-side catch-up.
  */
-class CatchUpReplayError extends Error {
-    code = "READ_SIDE_CATCH_UP_REPLAY_FAILED";
+class CatchUpDispatchError extends Error {
+    code = "READ_SIDE_CATCH_UP_DISPATCH_FAILED";
     eventId;
     detail;
     /**
-     * Creates a replay error tied to the stored event that failed.
+     * Creates a catch-up error tied to the stored Event that failed.
      *
      * @param eventId Identifies the stored event.
      * @param detail Contains the bounded cause name and message.
      */
     constructor(eventId, detail) {
         super(`Read-side catch-up failed for stored event "${eventId}".`);
-        this.name = "ReadCatchUpReplayError";
+        this.name = "ReadSideCatchUpDispatchError";
         this.eventId = eventId;
         this.detail = detail;
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
 /**
- * Assembles private bounded-context lifecycle and replay details.
+ * Assembles private bounded-context lifecycle and catch-up details.
  */
 const ContextParts = Object.freeze({
     /**
@@ -1941,11 +2093,11 @@ const ContextParts = Object.freeze({
      * @param buses Prepared domain and System buses.
      * @param running Prepared Stand and subscription runtime.
      * @param ai Effective AI registry when Agent repositories are present.
-     * @param tenantIndex Effective live membership index.
+     * @param tenantIndex Captured marker or directory.
      * @returns Constructed bounded context.
      */
     createBoundedContext(specSnapshot, storageFactory, repositories, deliveryStrategy, buses, running, ai, tenantIndex) {
-        return constructBoundedContext({
+        const context = constructBoundedContext({
             snapshot: ContextParts.snapshotFor(specSnapshot),
             commandBus: buses.commandBus,
             eventBus: buses.eventBus,
@@ -1956,12 +2108,14 @@ const ContextParts = Object.freeze({
             subscriptionRuntime: running.runtime,
             systemSpec: buses.systemSpec,
             storageFactory,
-            tenantIndex: tenantIndex ?? ServerEnvironment.instance().tenantIndex,
+            tenantIndex,
             repositories,
             deliveryStrategy,
             ...(ai === undefined ? {} : { ai }),
             token: frameworkConstructionToken,
         });
+        standAccess.bindProducingContext(running.stand, context);
+        return context;
     },
     /**
      * Captures public context identity from the build specification.
@@ -2229,7 +2383,7 @@ const ContextParts = Object.freeze({
      * @param event Imported event to validate.
      */
     validateImportedTenant(context, event) {
-        const tenantId = ContextParts.readReplayTenant(event);
+        const tenantId = ContextParts.readCatchUpTenant(event);
         if (!context.isMultitenant) {
             if (tenantId !== undefined) {
                 throw new Error(`Single-tenant context "${context.name.value}" does not accept tenantId.`);
@@ -2284,10 +2438,10 @@ const ContextParts = Object.freeze({
         return pairing;
     },
     /**
-     * Reads the tenant index recorded for a built context.
+     * Reads the marker or directory recorded for a built Bounded Context.
      *
-     * @param context Context to inspect.
-     * @returns Tenant index; throws if unavailable.
+     * @param context Bounded Context to inspect.
+     * @returns Captured marker or directory; throws if unavailable.
      */
     requireTenantIndex(context) {
         const tenantIndex = contextTenantIndexes.get(context);
@@ -2318,151 +2472,6 @@ const ContextParts = Object.freeze({
             throw new TypeError(`${operation} requires a Repository instance. Use an entity class only with build().`);
         }
     },
-    /**
-     * Validates that a root exists when generated metadata must be loaded.
-     *
-     * @param root Configured registry location.
-     * @returns Configured root; throws when absent.
-     */
-    requireGeneratedRegistryRoot(root) {
-        if (root !== undefined) {
-            return root;
-        }
-        throw new Error("BoundedContextBuilder.build() requires withGeneratedRegistryRoot(root) " +
-            "when assembling entity classes from generated metadata.");
-    },
-    /**
-     * Resolves the generated registry module and verifies it stays beneath the configured root.
-     *
-     * @param root Configured filesystem path or file URL.
-     * @returns Registry module file URL.
-     */
-    async trustedGeneratedRegistryModule(root) {
-        const trustedRoot = await ContextParts.canonicalGeneratedRegistryRoot(root);
-        const registryPath = resolve(trustedRoot, generatedRegistryFile);
-        const canonicalRegistryPath = await ContextParts.canonicalReadableRegistryPath(registryPath);
-        if (ContextParts.resolvesOutsideRoot(trustedRoot, canonicalRegistryPath)) {
-            throw new Error(`Generated handler registry module "${canonicalRegistryPath}" must resolve within ` +
-                `the configured generated registry root "${trustedRoot}".`);
-        }
-        return pathToFileURL(canonicalRegistryPath);
-    },
-    /**
-     * Resolves a generated registry root to its canonical filesystem path.
-     *
-     * @param root Configured path or file URL.
-     * @returns Canonical directory path.
-     */
-    async canonicalGeneratedRegistryRoot(root) {
-        const rootPath = ContextParts.generatedRegistryRootPath(root);
-        try {
-            return await realpath(rootPath);
-        }
-        catch (error) {
-            throw new Error(`Generated registry root "${rootPath}" must be an existing readable directory.`, { cause: error });
-        }
-    },
-    /**
-     * Converts a registry root path or file URL to an absolute filesystem path.
-     *
-     * @param root Configured path or file URL.
-     * @returns Absolute filesystem path.
-     */
-    generatedRegistryRootPath(root) {
-        if (root instanceof URL) {
-            return ContextParts.fileUrlPath(root, "Generated registry root");
-        }
-        if (ContextParts.isUrlLike(root)) {
-            return ContextParts.fileUrlPath(ContextParts.parseRootUrl(root), "Generated registry root");
-        }
-        return resolve(root);
-    },
-    /**
-     * Validates a file URL and converts it to an absolute filesystem path.
-     *
-     * @param url File URL to convert.
-     * @param label Label used in validation errors.
-     * @returns Filesystem path.
-     */
-    fileUrlPath(url, label) {
-        if (url.protocol !== "file:") {
-            throw new Error(`${label} "${url.href}" must use the file: URL scheme.`);
-        }
-        if (url.search.length > 0 || url.hash.length > 0) {
-            throw new Error(`${label} "${url.href}" must not include a query or hash.`);
-        }
-        return resolve(fileURLToPath(url));
-    },
-    /**
-     * Parses a generated registry root string as a URL.
-     *
-     * @param root Registry root string.
-     * @returns Parsed URL.
-     */
-    parseRootUrl(root) {
-        try {
-            return new URL(root);
-        }
-        catch (error) {
-            throw new Error(`Generated registry root "${root}" is not a valid URL.`, { cause: error });
-        }
-    },
-    /**
-     * Checks strings for a URL scheme, excluding Windows drive paths.
-     *
-     * @param value String to inspect.
-     * @returns True when the string has a URL scheme.
-     */
-    isUrlLike(value) {
-        return moduleSchemeRe.test(value) && !/^[A-Za-z]:[\\/]/.test(value);
-    },
-    /**
-     * Verifies registry-module readability and resolves its canonical path.
-     *
-     * @param registryPath Registry module filesystem path.
-     * @returns Canonical readable path.
-     */
-    async canonicalReadableRegistryPath(registryPath) {
-        try {
-            await access(registryPath, fsConstants.R_OK);
-            return await realpath(registryPath);
-        }
-        catch (error) {
-            throw new Error(`Generated handler registry module "${registryPath}" must exist and be readable.`, { cause: error });
-        }
-    },
-    /**
-     * Checks whether a canonical path escapes a canonical root.
-     *
-     * @param canonicalRoot Root directory.
-     * @param canonicalPath Candidate path.
-     * @returns True when the candidate escapes the root.
-     */
-    resolvesOutsideRoot(canonicalRoot, canonicalPath) {
-        const relativePath = relative(canonicalRoot, canonicalPath);
-        return (relativePath.startsWith("..") ||
-            relativePath === ".." ||
-            relativePath.split(sep).includes("..") ||
-            isAbsolute(relativePath));
-    },
-    /**
-     * Creates a cache-bust query after a prior registry load failure.
-     *
-     * @param registryKey Canonical registry identifier.
-     * @returns Retry query, or an empty object on the first attempt.
-     */
-    generatedRegistryCacheBust(registryKey) {
-        const attempt = generatedRegistryLoadAttempts.get(registryKey) ?? 0;
-        return attempt === 0 ? {} : { cacheBust: `retry-${attempt.toString()}` };
-    },
-    /**
-     * Records another failed load for a registry.
-     *
-     * @param registryKey Canonical registry identifier.
-     */
-    recordGeneratedRegistryFailure(registryKey) {
-        generatedRegistryLoadAttempts.set(registryKey, (generatedRegistryLoadAttempts.get(registryKey) ?? 0) + 1);
-    },
     /**
      * Loads generated handler registries into a metadata registry.
      *
@@ -2758,9 +2767,9 @@ const ContextParts = Object.freeze({
     createDeliveryDescriptor(entityInbox, projections) {
         return Object.freeze({
             endpoints: () => Object.freeze([...entityInbox.endpoints(), ...projections.endpoints()]),
-            replay: (message, tenantId) => message.label === "UPDATE_SUBSCRIBER"
-                ? projections.replay(message, tenantId)
-                : entityInbox.replay(message, tenantId),
+            deliver: (message, tenantId) => message.label === "UPDATE_SUBSCRIBER"
+                ? projections.deliver(message, tenantId)
+                : entityInbox.deliver(message, tenantId),
         });
     },
     /**
@@ -3031,12 +3040,12 @@ const ContextParts = Object.freeze({
      * @param context Catch-up storage context.
      * @param event Stored event to validate.
      */
-    validateReplayTenant(context, event) {
+    validateCatchUpTenant(context, event) {
         if (!context.multitenant) {
             return;
         }
         const expectedTenantId = context.tenantId;
-        const envelopeTenantId = ContextParts.readReplayTenant(event);
+        const envelopeTenantId = ContextParts.readCatchUpTenant(event);
         if (envelopeTenantId === undefined) {
             throw new Error("Read-side catch-up requires stored event envelope tenant.");
         }
@@ -3050,7 +3059,7 @@ const ContextParts = Object.freeze({
      * @param event Event whose origin is inspected.
      * @returns Cloned tenant ID when present.
      */
-    readReplayTenant(event) {
+    readCatchUpTenant(event) {
         switch (event.context?.origin.case) {
             case "importContext":
                 return ContextParts.tenantIdValue(event.context.origin.value.tenantId);
@@ -3092,14 +3101,14 @@ const ContextParts = Object.freeze({
         return matching.length > 0 ? 1 : 0;
     },
     /**
-     * Creates a replay error with the event ID and bounded cause details.
+     * Creates a catch-up error with the Event ID and bounded cause details.
      *
      * @param event Event that failed.
-     * @param cause Thrown replay cause.
-     * @returns Replay error.
+     * @param cause Thrown catch-up cause.
+     * @returns Catch-up error.
      */
-    catchUpReplayError(event, cause) {
-        return new CatchUpReplayError(event.id?.value ?? "(missing)", ContextParts.catchUpReplayDetail(cause));
+    catchUpDispatchError(event, cause) {
+        return new CatchUpDispatchError(event.id?.value ?? "(missing)", ContextParts.catchUpDispatchDetail(cause));
     },
     /**
      * Returns an error string truncated to a maximum length.
@@ -3117,7 +3126,7 @@ const ContextParts = Object.freeze({
      * @param error Thrown value.
      * @returns Immutable bounded details.
      */
-    catchUpReplayDetail(error) {
+    catchUpDispatchDetail(error) {
         if (error instanceof Error) {
             return Object.freeze({
                 name: ContextParts.boundedErrorString(error.name, errorDetailLimit) || "Error",
@@ -3160,9 +3169,15 @@ const ContextParts = Object.freeze({
  * @internal
  */
 export const boundedContextIntegrationAccess = Object.freeze({
+    /**
+     * Publishes an imported Event through the context’s import path.
+     */
     publishImported(context, event) {
         return ContextParts.publishImported(context, event);
     },
+    /**
+     * Signals that standalone context integration is ready.
+     */
     ready(context) {
         return ContextParts.integrationReady(context);
     },