@spine-event-engine/server 2.0.0-snapshot.24 → 2.0.0-snapshot.26

package/dist/server/server-environment.js

@@ -12,14 +12,20 @@
  * the License.
  */
 import { InMemoryStorageFactory } from "@spine-event-engine/storage";
+import { TenantBoundary } from "@spine-event-engine/storage/provider";
 import { LogLayer, StructuredTransport } from "loglayer";
 import { InMemoryTransportFactory } from "@spine-event-engine/transport";
 import { spineCoreRegistry } from "@spine-event-engine/core";
-import { RetryableCloseGroup } from "./retryable-close.js";
-import { emitServerWarning } from "./server-log.js";
+import { CloseErrors, RetryableCloseGroup } from "./retryable-close.js";
+import { Delivery as CoreDelivery } from "../delivery/delivery.js";
+import { deliveryControls, deliveryStrategyAccess } from "../delivery/delivery-builder.js";
+import { DeliverySupervisor, deliverySupervisorAccess } from "../delivery/delivery-supervisor.js";
+import { deliveryTenant } from "../delivery/delivery-tenant.js";
+import { emitServerInfo, emitServerWarning } from "./server-log.js";
+import { managedDeliveryGate } from "./managed-delivery-gate.js";
 import { boundedContextAccess } from "../context/bounded-context.js";
-import { EnvironmentDeliveryWorker } from "./environment-delivery-worker.js";
-import { EnvironmentAttachments, } from "./environment-attachment.js";
+import { TenantIndexes } from "../context/tenant-index.js";
+import { TenantUnknownError } from "../context/tenant-unknown-error.js";
 import { Environment, EnvironmentTests, EnvironmentType } from "./environment.js";
 const configuredSettings = new Map();
 let resolvedEnvironment;
@@ -41,6 +47,18 @@ export class ServerEnvironment {
      * Storage facility selected for server assembly, including server-added context builders.
      */
     storageFactory;
+    /**
+     * Waiting updates per subscription beyond one active update.
+     */
+    subscriptionQueueCapacity;
+    /**
+     * Live default tenant membership index.
+     */
+    tenantIndex;
+    /**
+     * Default AI registry selected for Bounded Context assembly, when configured.
+     */
+    ai;
     /**
      * Message-channel factory selected for private bounded-context integration.
      *
@@ -54,45 +72,92 @@ export class ServerEnvironment {
      */
     typeRegistry;
     /**
-     * Optional closeable delivery owner selected for this environment.
+     * Optional closeable remote delivery facility selected for this environment.
      */
-    delivery;
+    #remoteDelivery;
+    /**
+     * Returns the actual shared Delivery after explicit environment setup.
+     * @returns The one public Delivery facade for this environment.
+     */
+    get delivery() {
+        if (this.#publicDelivery === undefined)
+            throw new Error("ServerEnvironment.completeSetup() must finish before Delivery use.");
+        return this.#publicDelivery;
+    }
     /**
      * Optional tracing factory selected for this environment.
      */
     tracerFactory;
     #ownedCloseables;
     #closeGroup;
+    #deliveryCloseGroup;
+    #deliveryStrategy;
+    #delivery;
+    #publicDelivery;
+    #supervisor;
+    #supervisorStart;
     #close;
     #deliveryOpen;
     #deliveryOpened = false;
+    #closing = false;
+    #fatal;
+    /**
+     * Initializes resolved environment facilities.
+     *
+     * @param environment Selected process environment.
+     * @param settings Resolved facilities and settings.
+     */
     constructor(environment, settings) {
         this.environment = environment;
         this.nodeId = crypto.randomUUID();
         this.storageFactory = settings.storageFactory;
+        this.subscriptionQueueCapacity = settings.subscriptionQueueCapacity;
+        this.tenantIndex = settings.tenantIndex ?? TenantIndexes.fromFactory(settings.storageFactory);
+        this.ai = settings.ai;
         this.integrationChannelFactory = settings.integrationChannelFactory;
         this.typeRegistry = settings.typeRegistry;
-        this.delivery = settings.delivery;
+        this.#remoteDelivery = settings.delivery;
+        this.#deliveryStrategy = settings.deliveryStrategy;
         this.tracerFactory = settings.tracerFactory;
-        environmentLoggers.set(this, settings.logger);
-        this.#ownedCloseables = ServerEnvironmentValues.facilitiesToClose(settings);
-        warnedVolatileRegistries.set(this, new WeakSet());
+        this.#registerRuntimeHooks(settings.logger);
+        this.#deliveryCloseGroup = new RetryableCloseGroup([
+            { close: () => this.#supervisor?.close() },
+            { close: () => this.#delivery?.close() },
+            this.#remoteDelivery,
+        ], "Environment Delivery close failed.");
+        this.#ownedCloseables = ServerEnvironmentValues.facilitiesToClose(settings, this.#deliveryCloseGroup);
         this.#closeGroup = new RetryableCloseGroup(this.#ownedCloseables, "ServerEnvironment close failed.");
-        environmentAttachments.set(this, new EnvironmentAttachments({
-            logger: ServerEnvironmentValues.loggerFor(this),
-            createWorker: () => {
-                const ports = ServerEnvironmentValues.ports(this.delivery);
-                return new EnvironmentDeliveryWorker({
-                    ...(ports === undefined ? {} : { ports }),
-                    nodeId: this.nodeId,
-                });
-            },
-            deliveryPorts: () => ServerEnvironmentValues.ports(this.delivery),
-        }));
-        deliveryOpeners.set(this, () => this.#openDelivery());
-        testAttachmentsInstallable.add(this);
         Object.freeze(this);
     }
+    /**
+     * Registers package-local callbacks for this environment's runtime.
+     * @param logger Receives diagnostics from these callbacks.
+     */
+    #registerRuntimeHooks(logger) {
+        environmentLoggers.set(this, logger);
+        environmentContexts.set(this, new EnvironmentContextRegistrations());
+        startupControls.set(this, {
+            fail: (cause) => {
+                this.#failStartup(cause);
+            },
+            awaitFailure: () => this.#awaitStartupFailure(),
+            available: () => {
+                if (this.#closing)
+                    throw new Error("ServerEnvironment is closed.");
+            },
+            failed: () => this.#fatal !== undefined,
+            recordCleanup: (error) => {
+                if (this.#fatal !== undefined)
+                    CloseErrors.collect(error, this.#fatal.cleanupErrors);
+            },
+        });
+        warnedVolatileRegistries.set(this, new WeakSet());
+        supervisorStarters.set(this, () => this.#startSupervisor());
+        deliveryNotifiers.set(this, (shard) => {
+            this.#notifyDelivery(shard);
+        });
+        deliveryIdlers.set(this, () => this.#whenDeliveryIdle());
+    }
     /**
      * Sets facilities for an environment type before first resolution.
      *
@@ -101,6 +166,9 @@ export class ServerEnvironment {
      */
     static when(type) {
         return Object.freeze({
+            /**
+             * Stores settings for this environment type unless reset or singleton resolution has started.
+             */
             use(settings) {
                 if (resetInProgress !== undefined) {
                     throw new Error("ServerEnvironment reset is in progress.");
@@ -123,6 +191,9 @@ export class ServerEnvironment {
         }
         return (resolvedEnvironment ??= this.#resolve());
     }
+    /**
+     * Resolves the current Environment and its configured or default facilities into the process-wide ServerEnvironment.
+     */
     static #resolve() {
         const environment = Environment.instance();
         const configured = configuredSettings.get(environment.type);
@@ -131,19 +202,165 @@ export class ServerEnvironment {
         return new ServerEnvironment(environment, facilities);
     }
     /**
-     * Closes this environment after all attached servers retire.
+     * Checks shared storage and initializes transport and Delivery before context startup.
      *
-     * Admission permanently closes the environment and prevents reuse. If it is
-     * in use, closure rejects without owned-facility teardown. Failed facility
-     * closes are retryable and already closed facilities are not closed again.
+     * @returns The coalesced setup attempt for this environment lifetime.
+     */
+    completeSetup() {
+        if (this.#closing)
+            return Promise.reject(new Error("ServerEnvironment is closed."));
+        const current = environmentSetups.get(this);
+        if (current !== undefined)
+            return current;
+        const started = this.#completeSetup();
+        environmentSetups.set(this, started);
+        return started;
+    }
+    /**
+     * Creates declared structures for the completed open contexts in this environment.
+     * Explicit IDs select matching multitenant contexts through their effective indexes.
+     * Database-backed providers require an existing database; this method does not
+     * provision one or register tenants.
+     * @param tenantIds Optional complete tenant identities; absence includes single-tenant
+     * contexts and pages current multitenant indexes.
+     * @returns Completion after participating contexts are prepared.
+     */
+    createStorageStructures(...tenantIds) {
+        return this.#prepareContexts("create", tenantIds);
+    }
+    /**
+     * Checks existing structures without authorizing creation.
+     * Explicit IDs select matching multitenant contexts through their effective indexes.
+     * The operation does not provision databases or register tenants.
+     * @param tenantIds Optional complete tenant identities; absence includes single-tenant
+     * contexts and pages current multitenant indexes.
+     * @returns Completion after participating contexts pass read-only checks.
+     */
+    checkStructureCompatibility(...tenantIds) {
+        return this.#prepareContexts("check", tenantIds);
+    }
+    /**
+     * Prevalidates selected tenant membership before starting provider work.
+     * @param contexts Captured completed context references.
+     * @param tenantIds Explicit complete tenant identities.
+     * @returns Participating contexts and their selected tenants.
+     */
+    async #selectedContexts(contexts, tenantIds) {
+        const selected = new Map();
+        const boundaries = new Map();
+        for (const id of tenantIds) {
+            const boundary = TenantBoundary.from(id);
+            boundaries.set(boundary.key, boundary);
+        }
+        for (const boundary of boundaries.values()) {
+            let found = false;
+            for (const context of contexts) {
+                serverEnvironmentAccess.requireAvailable(this);
+                if (!context.isMultitenant)
+                    continue;
+                const present = await context.tenantIndex.contains(boundary.tenantId);
+                serverEnvironmentAccess.requireAvailable(this);
+                if (!present)
+                    continue;
+                const ids = selected.get(context) ?? [];
+                ids.push(boundary.tenantId);
+                selected.set(context, ids);
+                found = true;
+            }
+            if (!found)
+                throw new TenantUnknownError(boundary.tenantId, "ServerEnvironment");
+        }
+        return selected;
+    }
+    /**
+     * Prepares captured contexts after complete explicit-ID validation.
+     * @param mode Creation or read-only check.
+     * @param tenantIds Optional complete tenant identities.
+     * @returns Completion after every participating context settles.
+     */
+    async #prepareContexts(mode, tenantIds) {
+        serverEnvironmentAccess.requireAvailable(this);
+        const captured = tenantIds.map((id) => TenantBoundary.from(id).tenantId);
+        const contexts = serverEnvironmentAccess
+            .openContexts(this)
+            .filter((context) => !boundedContextAccess.isClosing(context));
+        if (contexts.length === 0)
+            throw new Error("ServerEnvironment has no completed Bounded Context to prepare.");
+        const selection = Promise.withResolvers();
+        const admitted = contexts.map((context) => boundedContextAccess.admitServiceRegistryOperation(context, async () => {
+            const selected = await selection.promise;
+            const ids = selected?.get(context);
+            if (selected !== undefined && ids === undefined)
+                return;
+            await boundedContextAccess.prepareExplicit(context, mode, ids ?? []);
+        }));
+        if (captured.length === 0)
+            selection.resolve(undefined);
+        else
+            void this.#selectedContexts(contexts, captured).then(selection.resolve, selection.reject);
+        const results = await Promise.allSettled(admitted);
+        if (serverEnvironmentAccess.hasStartupFailure(this))
+            return serverEnvironmentAccess.awaitStartupFailure(this);
+        const failure = results.find((result) => result.status === "rejected");
+        if (failure?.status === "rejected")
+            throw failure.reason;
+    }
+    /**
+     * Opens configured facilities, validates shared storage, and initializes shared Delivery before context startup.
+     */
+    async #completeSetup() {
+        try {
+            if (typeof this.integrationChannelFactory.initialize !== "function")
+                throw new TypeError("TransportFactory.initialize is required.");
+            await this.storageFactory.checkConnection();
+            emitServerInfo(ServerEnvironmentValues.loggerFor(this), "Environment storage connection checked.", { operation: "server.setup_storage" });
+            await this.integrationChannelFactory.initialize();
+            emitServerInfo(ServerEnvironmentValues.loggerFor(this), "Environment transport initialized.", { operation: "server.setup_transport" });
+            await this.#openDelivery();
+            if (this.#closing)
+                throw new Error("ServerEnvironment closed during setup.");
+            emitServerInfo(ServerEnvironmentValues.loggerFor(this), "Environment Delivery initialized.", {
+                operation: "server.setup_delivery",
+            });
+        }
+        catch (error) {
+            this.#closing = true;
+            const cleanup = await Promise.allSettled([this.#closeGroup.close()]);
+            const failures = cleanup.flatMap((result) => {
+                if (result.status !== "rejected")
+                    return [];
+                return result.reason instanceof AggregateError
+                    ? result.reason.errors
+                    : [result.reason];
+            });
+            if (failures.length)
+                throw new AggregateError([error, ...failures], "Environment setup failed.");
+            throw error;
+        }
+    }
+    /**
+     * Closes this environment after all Bounded Contexts close.
      *
-     * @returns A promise that settles after the environment and owned facilities close.
+     * A healthy environment with active contexts rejects without teardown. After
+     * required startup failure, this joins automatic cleanup and rejects with the
+     * original cause and any cleanup failures. Successful closure prevents reuse;
+     * failed facility closes during an ordinary close remain retryable.
      *
+     * @returns Completion after facilities close or a rejection reporting failures.
      */
     close() {
-        testAttachmentsInstallable.delete(this);
-        this.#close ??= this.#attachments()
-            .admitPermanentClose()
+        if (this.#fatal !== undefined)
+            return this.#awaitStartupFailure();
+        if (EnvironmentContextRegistrations.forEnvironment(this).active)
+            return Promise.reject(new Error("Cannot close ServerEnvironment with active Bounded Contexts."));
+        this.#closing = true;
+        this.#delivery?.beginClose();
+        this.#close ??= Promise.resolve()
+            .then(async () => {
+            const setup = environmentSetups.get(this);
+            if (setup !== undefined)
+                await Promise.allSettled([setup]);
+        })
             .then(() => this.#closeGroup.close())
             .catch((error) => {
             this.#close = undefined;
@@ -151,16 +368,86 @@ export class ServerEnvironment {
         });
         return this.#close;
     }
+    /**
+     * Fences a failed required startup phase and starts one automatic cleanup.
+     * @param cause Original required-phase failure.
+     */
+    #failStartup(cause) {
+        if (this.#fatal !== undefined) {
+            this.#fatal.originals.push(cause);
+            return;
+        }
+        this.#closing = true;
+        const contexts = EnvironmentContextRegistrations.forEnvironment(this);
+        const cleanupErrors = [];
+        const cleanup = Promise.resolve().then(() => this.#cleanupStartup(contexts, cleanupErrors));
+        this.#fatal = { originals: [cause], cleanupErrors, cleanup };
+        for (const context of contexts.allContexts()) {
+            try {
+                boundedContextAccess.beginClose(context);
+            }
+            catch (error) {
+                CloseErrors.collect(error, cleanupErrors);
+            }
+        }
+        this.#delivery?.beginStartupDrain();
+    }
+    /**
+     * Waits for local rollbacks, then closes contexts and shared facilities.
+     * @param contexts Context registrations for this environment.
+     * @param cleanupErrors Mutable cleanup failures.
+     * @returns Completion after every cleanup attempt.
+     */
+    async #cleanupStartup(contexts, cleanupErrors) {
+        const started = new Set(contexts.openContexts());
+        const observe = (context) => Promise.resolve()
+            .then(() => context.close())
+            .then(() => ({ status: "fulfilled", value: undefined }), (reason) => ({ status: "rejected", reason }));
+        const completed = [...started].map(observe);
+        await contexts.whenBuildsIdle();
+        const remaining = contexts
+            .allContexts()
+            .filter((context) => !started.has(context))
+            .map(observe);
+        for (const result of await Promise.all([...completed, ...remaining]))
+            if (result.status === "rejected")
+                CloseErrors.collect(result.reason, cleanupErrors);
+        this.#delivery?.beginClose();
+        try {
+            await this.#closeGroup.close();
+        }
+        catch (error) {
+            CloseErrors.collect(error, cleanupErrors);
+        }
+    }
+    /**
+     * Reports all original and cleanup errors after automatic cleanup settles.
+     * @returns Rejection preserving the original failure when it is the only error.
+     */
+    async #awaitStartupFailure() {
+        const fatal = this.#fatal;
+        if (fatal === undefined)
+            throw new Error("No startup failure was recorded.");
+        await fatal.cleanup;
+        const failures = [...fatal.originals, ...fatal.cleanupErrors];
+        if (failures.length === 1)
+            throw failures[0];
+        throw new AggregateError(failures, "Required environment initialization failed.");
+    }
+    /**
+     * Opens the configured delivery facility once and records successful opening for later cleanup.
+     */
     #openDelivery() {
         if (this.#deliveryOpened)
             return Promise.resolve();
         const opening = (this.#deliveryOpen ??= Promise.resolve()
-            .then(() => {
-            const delivery = ServerEnvironmentValues.openableDelivery(this.delivery);
-            if (delivery !== undefined) {
-                return delivery.open();
-            }
-            return undefined;
+            .then(async () => {
+            const remote = ServerEnvironmentValues.openableDelivery(this.#remoteDelivery);
+            if (remote !== undefined)
+                await remote.open();
+            if (this.#closing)
+                throw new Error("ServerEnvironment closed during Delivery setup.");
+            this.#constructDelivery(ServerEnvironmentValues.ports(this.#remoteDelivery));
         })
             .then(() => {
             this.#deliveryOpened = true;
@@ -172,12 +459,98 @@ export class ServerEnvironment {
         });
         return opening;
     }
-    #attachments() {
-        const attachments = environmentAttachments.get(this);
-        if (attachments === undefined) {
-            throw new Error("ServerEnvironment attachments are not available.");
+    /**
+     * Constructs the one environment Delivery after configured ports open.
+     * @param ports Open remote ports when configured.
+     */
+    #constructDelivery(ports) {
+        const delivery = new CoreDelivery({
+            context: { name: "__System_Delivery__", multitenant: false },
+            storageFactory: this.storageFactory,
+            node: this.nodeId,
+            ...(ports?.source === undefined ? { logger: ServerEnvironmentValues.loggerFor(this) } : {}),
+            ...(this.#deliveryStrategy === undefined
+                ? {}
+                : { strategy: deliveryStrategyAccess.snapshot(this.#deliveryStrategy) }),
+            ...(ports ?? {}),
+        });
+        delivery.setReplay((message) => this.#replayMessage(message), (message) => this.#acceptsMessage(message));
+        this.#delivery = delivery;
+        environmentDeliveryCores.set(this, delivery);
+        this.#publicDelivery = deliveryControls.supervised(delivery);
+        if (ports?.source !== undefined)
+            this.#installSupervisor(this.#publicDelivery, ports.source);
+    }
+    /**
+     * Checks whether a Delivery inbox message targets an Entity or Projection currently served by this environment.
+     */
+    #acceptsMessage(message) {
+        return (EnvironmentContextRegistrations.forEnvironment(this).recipient(message.inboxId.targetTypeUrl) !== undefined);
+    }
+    /**
+     * Creates the Delivery supervisor and connects inbox, work registry, and shard delivery notifications.
+     */
+    #installSupervisor(delivery, source) {
+        const supervisor = new DeliverySupervisor({
+            source,
+            delivery,
+            onMessage: (message) => this.#replayMessage(message),
+        });
+        deliverySupervisorAccess.installAdmission(supervisor, (message) => this.#acceptsMessage(message));
+        deliverySupervisorAccess.installLogger(supervisor, ServerEnvironmentValues.loggerFor(this));
+        this.#supervisor = supervisor;
+        remoteSupervisedEnvironments.add(this);
+    }
+    /**
+     * Starts the configured Delivery supervisor once and records fatal startup failures for environment cleanup.
+     */
+    #startSupervisor() {
+        const supervisor = this.#supervisor;
+        return supervisor === undefined
+            ? Promise.resolve()
+            : managedDeliveryGate.start(() => (this.#supervisorStart ??= supervisor.start()));
+    }
+    /**
+     * Notifies the supervisor that work for a shard may now be available.
+     */
+    #notifyDelivery(shard) {
+        if (this.#supervisor === undefined) {
+            this.#delivery?.wake(shard);
+            return;
+        }
+        try {
+            this.#supervisor.notify(shard);
         }
-        return attachments;
+        catch {
+            emitServerWarning(ServerEnvironmentValues.loggerFor(this), "Delivery notification failed.", {
+                operation: "delivery.notify",
+                reasonCode: "failed",
+            });
+        }
+    }
+    /**
+     * Waits until the environment’s supervised Delivery has no active work.
+     */
+    async #whenDeliveryIdle() {
+        const settled = await Promise.allSettled([
+            this.#supervisor?.whenIdle(),
+            this.#delivery?.whenIdle(),
+        ]);
+        const failures = settled.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length)
+            throw new AggregateError(failures, "Environment Delivery idle wait failed.");
+    }
+    /**
+     * Replays a persisted Delivery inbox message through the matching context recipient and signals
+     * completion or failure.
+     */
+    async #replayMessage(message) {
+        const context = EnvironmentContextRegistrations.forEnvironment(this).recipient(message.inboxId.targetTypeUrl);
+        if (context === undefined)
+            throw new Error("No open Bounded Context serves the Inbox target.");
+        await boundedContextAccess.trackReplay(context, () => boundedContextAccess.delivery(context).replay(message, deliveryTenant(message)));
     }
 }
 /**
@@ -196,8 +569,19 @@ export const ServerEnvironmentLifecycle = Object.freeze({
             return current;
         }
         const resolved = resolvedEnvironment;
+        if (resolved !== undefined && EnvironmentContextRegistrations.forEnvironment(resolved).active) {
+            return Promise.reject(new Error("Cannot reset ServerEnvironment with active Bounded Contexts."));
+        }
         const reset = Promise.resolve()
-            .then(() => resolved?.close())
+            .then(() => {
+            if (resolved !== undefined && EnvironmentContextRegistrations.forEnvironment(resolved).active) {
+                throw new Error("Cannot reset ServerEnvironment with active Bounded Contexts.");
+            }
+            if (resolved !== undefined && startupControls.get(resolved)?.failed())
+                // spine-log-boundary: server.fatal_environment_test_reset
+                return resolved.close().catch(() => undefined);
+            return resolved?.close();
+        })
             .then(() => {
             resolvedEnvironment = undefined;
             configuredSettings.clear();
@@ -210,112 +594,284 @@ export const ServerEnvironmentLifecycle = Object.freeze({
         return reset;
     },
 });
-const environmentAttachments = new WeakMap();
+const environmentSetups = new WeakMap();
+const startupControls = new WeakMap();
+const environmentDeliveryCores = new WeakMap();
+const remoteSupervisedEnvironments = new WeakSet();
 const environmentLoggers = new WeakMap();
-const deliveryOpeners = new WeakMap();
-const testAttachmentsInstallable = new WeakSet();
+const supervisorStarters = new WeakMap();
+const deliveryNotifiers = new WeakMap();
+const deliveryIdlers = new WeakMap();
 const warnedVolatileRegistries = new WeakMap();
+const environmentContexts = new WeakMap();
+/**
+ * Records live domain contexts separately from build-phase reservations.
+ */
+class EnvironmentContextRegistrations {
+    #contexts = new Set();
+    #completed = new Set();
+    #states = new Map();
+    #recipients = new Map();
+    #builds = 0;
+    #buildsIdle;
+    /**
+     * Finds the registrations attached to one resolved environment.
+     *
+     * @param environment Resolved environment.
+     * @returns Its context registrations.
+     */
+    static forEnvironment(environment) {
+        const contexts = environmentContexts.get(environment);
+        if (contexts === undefined)
+            throw new TypeError("Context registration requires an environment.");
+        return contexts;
+    }
+    /**
+     * Checks whether a full singleton reset would discard context state.
+     *
+     * @returns Whether a context or build remains active.
+     */
+    get active() {
+        return this.#builds > 0 || this.#contexts.size > 0;
+    }
+    /**
+     * Records a build until asynchronous assembly settles.
+     *
+     * @returns A callback that finishes this build exactly once.
+     */
+    beginBuild() {
+        if (this.#builds === 0)
+            this.#buildsIdle = Promise.withResolvers();
+        this.#builds++;
+        let finished = false;
+        return () => {
+            if (finished)
+                return;
+            finished = true;
+            this.#builds--;
+            if (this.#builds === 0)
+                this.#buildsIdle?.resolve(undefined);
+        };
+    }
+    /**
+     * Waits until every admitted build releases its local assembly ticket.
+     * @returns Completion when no build remains.
+     */
+    whenBuildsIdle() {
+        return this.#buildsIdle?.promise ?? Promise.resolve();
+    }
+    /**
+     * Lists constructed contexts, including incomplete registrations.
+     * @returns Snapshot of all constructed contexts.
+     */
+    allContexts() {
+        return [...this.#contexts];
+    }
+    /**
+     * Records an open or partly constructed context.
+     *
+     * @param context Context to track.
+     */
+    add(context) {
+        this.#contexts.add(context);
+    }
+    /**
+     * Marks a tracked context ready for public cleanup enumeration.
+     *
+     * @param context Context whose integration opened successfully.
+     */
+    complete(context) {
+        if (!this.#contexts.has(context))
+            throw new Error("Context completed after cleanup.");
+        this.#completed.add(context);
+        for (const endpoint of boundedContextAccess.delivery(context).endpoints())
+            this.#recipients.set(endpoint.targetTypeUrl, context);
+    }
+    /**
+     * Finds the completed context registered for a delivery target.
+     * @param typeUrl Identifies the target message type.
+     * @returns The matching context, if one completed registration.
+     */
+    recipient(typeUrl) {
+        return this.#recipients.get(typeUrl);
+    }
+    /**
+     * Registers one state type without overwriting a different context.
+     *
+     * @param context Context registering the state.
+     * @param typeUrl Full wire type URL of the state.
+     * @returns The conflicting context, if another context registered it.
+     */
+    reserve(context, typeUrl) {
+        const prior = this.#states.get(typeUrl);
+        if (prior !== undefined)
+            return prior === context ? undefined : prior;
+        this.#states.set(typeUrl, context);
+        return undefined;
+    }
+    /**
+     * Removes only registrations made by the selected context.
+     *
+     * @param context Context that completed shutdown.
+     */
+    remove(context) {
+        this.#contexts.delete(context);
+        this.#completed.delete(context);
+        this.stopRecipients(context);
+        for (const [typeUrl, registered] of this.#states) {
+            if (registered === context)
+                this.#states.delete(typeUrl);
+        }
+    }
+    /**
+     * Removes fresh delivery endpoints while retaining state reservations.
+     * @param context Context entering close.
+     */
+    stopRecipients(context) {
+        for (const [typeUrl, recipient] of this.#recipients)
+            if (recipient === context)
+                this.#recipients.delete(typeUrl);
+    }
+    /**
+     * Lists the context currently serving a state type.
+     *
+     * @param typeUrl Full wire type URL of the state.
+     * @returns Zero or one context names.
+     */
+    serving(typeUrl) {
+        const context = this.#states.get(typeUrl);
+        return context === undefined ? [] : [context.name.value];
+    }
+    /**
+     * Returns completed context references without releasing them.
+     *
+     * @returns References to integrated open contexts.
+     */
+    openContexts() {
+        return [...this.#completed];
+    }
+}
 /**
  * Provides package-only environment delivery attachment access for server lifecycle owners.
  *
  * @internal
  */
 export const serverEnvironmentAccess = Object.freeze({
-    attach(environment, options) {
-        testAttachmentsInstallable.delete(environment);
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            return Promise.reject(new TypeError("Attachment requires a ServerEnvironment instance."));
-        }
-        const openDelivery = deliveryOpeners.get(environment);
-        if (openDelivery === undefined) {
-            return Promise.reject(new TypeError("Attachment requires a ServerEnvironment instance."));
-        }
-        return openDelivery().then(() => attachments.attach(options));
+    /**
+     * Returns the initialized internal Delivery engine, failing before environment setup completes.
+     */
+    coreDelivery(environment) {
+        const core = environmentDeliveryCores.get(environment);
+        if (core === undefined)
+            throw new Error("ServerEnvironment.completeSetup() must finish before Delivery use.");
+        return core;
     },
-    failedStartPending(environment) {
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            throw new TypeError("Failed-start observation requires a ServerEnvironment instance.");
-        }
-        return attachments.failedStartPending;
+    /**
+     * Reports whether this environment uses a remote Delivery source supervised by the runtime.
+     */
+    remoteSupervised(environment) {
+        return remoteSupervisedEnvironments.has(environment);
     },
-    failedStartRetryPending(environment, error) {
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            throw new TypeError("Failed-start retry observation requires a ServerEnvironment instance.");
-        }
-        return attachments.failedStartRetryPending(error);
+    /**
+     * Waits for supervised Delivery work to become idle.
+     */
+    whenDeliveryIdle(environment) {
+        return deliveryIdlers.get(environment)?.() ?? Promise.resolve();
     },
-    retryFailedStart(environment) {
-        testAttachmentsInstallable.delete(environment);
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            return Promise.reject(new TypeError("Rollback retry requires a ServerEnvironment instance."));
-        }
-        return attachments.retryFailedStart();
+    /**
+     * Signals that the supplied shard may have Delivery work ready.
+     */
+    notifyDelivery(environment, shard) {
+        deliveryNotifiers.get(environment)?.(shard);
     },
-    detach(environment, attachment) {
-        testAttachmentsInstallable.delete(environment);
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            return Promise.reject(new TypeError("Detach requires a ServerEnvironment instance."));
-        }
-        return attachments.detach(attachment);
+    /**
+     * Requires an available environment and waits for its shared setup promise.
+     */
+    awaitSetup(environment) {
+        this.requireAvailable(environment);
+        return (environmentSetups.get(environment) ??
+            Promise.reject(new Error("Await ServerEnvironment.completeSetup() before building a Bounded Context."))).then(() => {
+            this.requireAvailable(environment);
+        });
     },
-    retryDetach(environment, attachment) {
-        testAttachmentsInstallable.delete(environment);
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            return Promise.reject(new TypeError("Detach retry requires a ServerEnvironment instance."));
-        }
-        return attachments.retryDetach(attachment);
+    /**
+     * Starts tracking an in-progress context build in the environment lifecycle registry.
+     */
+    beginContextBuild(environment) {
+        this.requireAvailable(environment);
+        return EnvironmentContextRegistrations.forEnvironment(environment).beginBuild();
     },
-    detachRetryPending(environment, attachment) {
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            throw new TypeError("Detach-retry observation requires a ServerEnvironment instance.");
-        }
-        return attachments.detachRetryPending(attachment);
+    /**
+     * Starts automatic cleanup after a required startup failure.
+     *
+     * @param environment Failed environment.
+     * @param cause Original required-phase error.
+     */
+    failStartup(environment, cause) {
+        startupControls.get(environment)?.fail(cause);
     },
-    endpointSafe(environment, attachment) {
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            throw new TypeError("Endpoint-safety observation requires a ServerEnvironment instance.");
-        }
-        return attachments.endpointSafe(attachment);
+    /**
+     * Waits for the environment’s fatal startup failure, rejecting if the environment is unknown.
+     */
+    awaitStartupFailure(environment) {
+        const control = startupControls.get(environment);
+        if (control === undefined)
+            return Promise.reject(new Error("Unknown ServerEnvironment."));
+        return control.awaitFailure();
     },
-    stopDelivery(environment) {
-        testAttachmentsInstallable.delete(environment);
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            return Promise.reject(new TypeError("Delivery stop requires a ServerEnvironment instance."));
-        }
-        return attachments.stopDelivery();
+    /**
+     * Reports whether a required environment startup phase has failed.
+     */
+    hasStartupFailure(environment) {
+        return startupControls.get(environment)?.failed() ?? false;
     },
-    retryDeliveryStop(environment) {
-        testAttachmentsInstallable.delete(environment);
-        const attachments = environmentAttachments.get(environment);
-        if (attachments === undefined) {
-            return Promise.reject(new TypeError("Delivery stop retry requires a ServerEnvironment instance."));
-        }
-        return attachments.retryDeliveryStop();
+    /**
+     * Adds an independent partial-context rollback failure to the fatal result.
+     *
+     * @param environment Failed environment.
+     * @param error Local rollback failure.
+     */
+    recordStartupCleanup(environment, error) {
+        startupControls.get(environment)?.recordCleanup(error);
     },
-    installTestAttachments(environment, createWorker) {
-        if (!environmentAttachments.has(environment)) {
-            throw new TypeError("Test attachments require a ServerEnvironment instance.");
-        }
-        if (!testAttachmentsInstallable.delete(environment)) {
-            throw new Error("Test attachments may only be installed before environment lifecycle use.");
-        }
-        environmentAttachments.set(environment, new EnvironmentAttachments({
-            logger: ServerEnvironmentValues.loggerFor(environment),
-            createWorker,
-        }));
+    /**
+     * Throws when the environment is closing or unavailable after startup failure.
+     */
+    requireAvailable(environment) {
+        startupControls.get(environment)?.available();
+    },
+    addContext: (environment, context) => {
+        serverEnvironmentAccess.requireAvailable(environment);
+        EnvironmentContextRegistrations.forEnvironment(environment).add(context);
     },
+    completeContext: async (environment, context) => {
+        serverEnvironmentAccess.requireAvailable(environment);
+        EnvironmentContextRegistrations.forEnvironment(environment).complete(context);
+        const endpoints = boundedContextAccess.delivery(context).endpoints();
+        if (endpoints.length > 0)
+            await supervisorStarters.get(environment)?.();
+        serverEnvironmentAccess.requireAvailable(environment);
+        for (const endpoint of endpoints)
+            deliveryNotifiers.get(environment)?.(endpoint.shard);
+    },
+    reserveState: (environment, context, typeUrl) => EnvironmentContextRegistrations.forEnvironment(environment).reserve(context, typeUrl),
+    stopRecipients: (environment, context) => {
+        EnvironmentContextRegistrations.forEnvironment(environment).stopRecipients(context);
+    },
+    removeContext: (environment, context) => {
+        EnvironmentContextRegistrations.forEnvironment(environment).remove(context);
+    },
+    contextsServing: (environment, typeUrl) => EnvironmentContextRegistrations.forEnvironment(environment).serving(typeUrl),
+    openContexts: (environment) => EnvironmentContextRegistrations.forEnvironment(environment).openContexts(),
+    /**
+     * Returns the logger configured for this server environment.
+     */
     loggerFor(environment) {
         return ServerEnvironmentValues.loggerFor(environment);
     },
+    /**
+     * Emits one production warning when a context uses a non-persistent subscription registry.
+     */
     warnVolatileRegistry(environment, context) {
         if (environment.environment.type !== EnvironmentType.Production)
             return;
@@ -337,12 +893,24 @@ export const serverEnvironmentAccess = Object.freeze({
  * @internal Groups private facility-assembly operations for the environment singleton.
  */
 const ServerEnvironmentValues = Object.freeze({
+    /**
+     * Returns the installed environment logger.
+     *
+     * @param environment Resolved server environment.
+     * @returns Its logger.
+     */
     loggerFor(environment) {
         const logger = environmentLoggers.get(environment);
         if (logger === undefined)
             throw new TypeError("ServerEnvironment logger is not available.");
         return logger;
     },
+    /**
+     * Gets an openable delivery facility when configured.
+     *
+     * @param delivery Configured delivery facility.
+     * @returns Openable delivery or undefined.
+     */
     openableDelivery(delivery) {
         if (delivery === undefined)
             return undefined;
@@ -356,6 +924,12 @@ const ServerEnvironmentValues = Object.freeze({
         }
         return candidate;
     },
+    /**
+     * Maps delivery to its environment ports.
+     *
+     * @param delivery Configured delivery facility.
+     * @returns Ports when delivery is openable.
+     */
     ports(delivery) {
         const remote = ServerEnvironmentValues.openableDelivery(delivery);
         if (remote === undefined)
@@ -366,14 +940,27 @@ const ServerEnvironmentValues = Object.freeze({
             ...(remote.source === undefined ? {} : { source: remote.source }),
         };
     },
-    facilitiesToClose(options) {
+    /**
+     * Lists facilities closed by the environment.
+     *
+     * @param options Resolved facilities.
+     * @param deliveryCloseGroup Closes the shared Delivery before other facilities.
+     * @returns Facilities in shutdown order.
+     */
+    facilitiesToClose(options, deliveryCloseGroup) {
         return Object.freeze([
-            ...(options.delivery === undefined ? [] : [options.delivery]),
+            deliveryCloseGroup,
             options.integrationChannelFactory,
             ...(options.tracerFactory === undefined ? [] : [options.tracerFactory]),
             options.storageFactory,
         ]);
     },
+    /**
+     * Creates a default logger when none was supplied.
+     *
+     * @param logger Optional application logger.
+     * @returns Logger child for this environment.
+     */
     logger(logger) {
         return (logger ??
             new LogLayer({
@@ -388,28 +975,30 @@ const ServerEnvironmentValues = Object.freeze({
                 }),
             })).child();
     },
+    /**
+     * Resolves configured facilities with local defaults where supported.
+     *
+     * @param type Selected environment type.
+     * @param settings Configured facilities.
+     * @returns Complete resolved facilities.
+     */
     resolveFacilities(type, settings) {
-        if (type === EnvironmentType.Production) {
-            if (settings.storageFactory === undefined) {
-                throw new Error("Production ServerEnvironment requires storageFactory.");
-            }
-            if (settings.typeRegistry === undefined) {
-                throw new Error("Production ServerEnvironment requires typeRegistry.");
-            }
-            return {
-                storageFactory: settings.storageFactory,
-                integrationChannelFactory: settings.integrationChannelFactory ?? new InMemoryTransportFactory(),
-                typeRegistry: settings.typeRegistry,
-                delivery: settings.delivery,
-                tracerFactory: settings.tracerFactory,
-                logger: ServerEnvironmentValues.logger(settings.logger),
-            };
-        }
+        const configuredCapacity = settings.subscriptionQueueCapacity;
+        if (configuredCapacity !== undefined &&
+            (!Number.isSafeInteger(configuredCapacity) || configuredCapacity < 0))
+            throw new RangeError("ServerEnvironment subscriptionQueueCapacity must be a nonnegative safe integer.");
+        const capacity = configuredCapacity ?? 100;
+        if (type === EnvironmentType.Production && settings.typeRegistry === undefined)
+            throw new Error("Production ServerEnvironment requires typeRegistry.");
         return {
+            subscriptionQueueCapacity: capacity,
             storageFactory: settings.storageFactory ?? new InMemoryStorageFactory(),
+            tenantIndex: settings.tenantIndex,
+            ai: settings.ai,
             integrationChannelFactory: settings.integrationChannelFactory ?? new InMemoryTransportFactory(),
             typeRegistry: settings.typeRegistry ?? spineCoreRegistry,
             delivery: settings.delivery,
+            deliveryStrategy: settings.deliveryStrategy,
             tracerFactory: settings.tracerFactory,
             logger: ServerEnvironmentValues.logger(settings.logger),
         };