@spine-event-engine/server 2.0.0-snapshot.14 → 2.0.0-snapshot.16

package/dist/context/bounded-context.js

@@ -116,7 +116,7 @@ export class BoundedContext {
         constructBoundedContext = (snapshot, commandBus, eventBus, systemEventBus, publisher, stand, systemStand, runtime, systemSpec, storageFactory, repositories, deliveryStrategy, token) => new BoundedContext(snapshot, commandBus, eventBus, systemEventBus, publisher, stand, systemStand, runtime, systemSpec, storageFactory, repositories, deliveryStrategy, token);
     }
     /**
-     * Creates a framework-owned bounded context.
+     * Creates a Bounded Context from its prepared framework services.
      *
      * @param snapshot Contains the immutable context metadata.
      * @param commandBus Dispatches commands accepted by this context.
@@ -125,7 +125,7 @@ export class BoundedContext {
      * @param publisher Publishes signals produced by context handlers.
      * @param stand Stores read-side state for this context.
      * @param systemStand Stores read-side state for the paired System Context.
-     * @param subscriptionRuntime Coordinates pair-owned subscription delivery.
+     * @param subscriptionRuntime Coordinates subscriptions for the paired contexts.
      * @param systemSpec Contains paired System Context metadata.
      * @param storageFactory Creates context storage.
      * @param repositories Lists repositories to register.
@@ -303,7 +303,7 @@ export class BoundedContext {
         return ContextParts.cloneContextSnapshot(this.#snapshot);
     }
     /**
-     * Returns the command endpoint owned by this context.
+     * Returns this context's command endpoint.
      *
      * @returns Returns the context command endpoint.
      */
@@ -311,7 +311,7 @@ export class BoundedContext {
         return this.#commandEndpoint;
     }
     /**
-     * Returns the event endpoint owned by this context.
+     * Returns this context's event endpoint.
      *
      * @returns Returns the context event endpoint.
      */
@@ -319,7 +319,7 @@ export class BoundedContext {
         return this.#eventEndpoint;
     }
     /**
-     * Returns the context-owned read-side Stand.
+     * Returns the Stand that stores this context's read-side state.
      *
      * @returns Returns the read-side state store.
      */
@@ -391,14 +391,14 @@ export class BoundedContext {
         });
     }
     /**
-     * Closes context-owned buses, Stand, and repository storage/runtime bindings.
+     * Closes this context's buses, Stand, and repository storage and runtime bindings.
      *
      * Close is idempotent and returns the same close outcome on repeated calls.
-     * The context attempts every owned close hook; when any hook fails, the
+     * The context attempts every close hook; when any hook fails, the
      * returned promise rejects with an `AggregateError` after the remaining hooks
      * have also been attempted.
      *
-     * @returns A promise that settles after all owned resources close.
+     * @returns A promise that settles after all resources close.
      */
     close() {
         closingContexts.add(this);
@@ -570,7 +570,7 @@ export class BoundedContextBuilder {
         constructBoundedContextBuilder = (snapshot, token) => new BoundedContextBuilder(snapshot, token);
     }
     /**
-     * Creates a framework-owned context builder.
+     * Creates a builder from a prepared context specification.
      *
      * @param specSnapshot Contains the initial context specification.
      * @param token Proves framework-controlled construction.
@@ -616,6 +616,7 @@ export class BoundedContextBuilder {
     /**
      * Adds an explicitly assembled repository or an Entity class.
      *
+     * @typeParam EntityType Concrete Entity class represented by this entry.
      * @param entry The repository or Entity class to register.
      * @param options Optional settings used only when an Entity class is supplied.
      * @returns This builder for further configuration.
@@ -638,6 +639,7 @@ export class BoundedContextBuilder {
     /**
      * Removes a repository from the context registration list.
      *
+     * @typeParam EntityType Concrete Entity class represented by the repository.
      * @param repository Identifies the repository to remove.
      * @returns Returns this builder for further configuration.
      */
@@ -748,7 +750,7 @@ export class BoundedContextBuilder {
         return this;
     }
     /**
-     * Sets the target-to-shard strategy for the context-owned Entity Inbox.
+     * Sets how Entity Inbox targets are assigned to shards.
      *
      * @param strategy Selects the durable shard for Aggregate and Process Manager targets.
      * @returns Returns this builder for further configuration.
@@ -972,6 +974,12 @@ export class BoundedContextBuilder {
     #standaloneInstances() {
         return Object.freeze([...this.#assignees, ...this.#commanders, ...this.#eventReceivers]);
     }
+    /**
+     * Creates the domain EventStore using this context's storage mode.
+     *
+     * @param storageFactory Storage provider for event records.
+     * @returns Domain EventStore.
+     */
     createEventStore(storageFactory) {
         return new EventStore(ContextParts.createStorageMode(this.#specSnapshot), storageFactory);
     }
@@ -988,7 +996,7 @@ export class ContextSpec {
         constructContextSpec = (snapshot, token) => new ContextSpec(snapshot, token);
     }
     /**
-     * Creates a framework-owned context specification.
+     * Creates a context specification from prepared values.
      *
      * @param snapshot Contains immutable specification values.
      * @param token Proves framework-controlled construction.
@@ -1040,10 +1048,19 @@ export class ContextSpec {
     }
 }
 const registeredRepositories = new WeakMap();
+/**
+ * Reports failure while redispatching a stored event during read-side replay.
+ */
 class CatchUpReplayError extends Error {
     code = "READ_SIDE_CATCH_UP_REPLAY_FAILED";
     eventId;
     detail;
+    /**
+     * Creates a replay 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";
@@ -1056,6 +1073,11 @@ class CatchUpReplayError extends Error {
  * Assembles private bounded-context lifecycle and replay details.
  */
 const ContextParts = Object.freeze({
+    /**
+     * Rejects duplicate command receptors in generated standalone groups.
+     *
+     * @param receivers Generated groups to validate.
+     */
     assertUniqueCommandReceptors(receivers) {
         const receptorByType = new Map();
         for (const receiver of receivers) {
@@ -1070,6 +1092,14 @@ const ContextParts = Object.freeze({
             }
         }
     },
+    /**
+     * Matches generated standalone groups to their registered instances.
+     *
+     * @param generated Generated handler groups.
+     * @param instances Registered standalone instances.
+     * @param publisher Publisher used by bindings.
+     * @returns Frozen bindings in generated order.
+     */
     matchStandaloneHandlers(generated, instances, publisher) {
         const byConstructor = new Map();
         for (const instance of instances) {
@@ -1094,6 +1124,12 @@ const ContextParts = Object.freeze({
         }
         return Object.freeze(bindings);
     },
+    /**
+     * Calls cleanup and records any thrown error.
+     *
+     * @param onCleanup Cleanup action.
+     * @param errors Collection receiving failures.
+     */
     attemptCleanup(onCleanup, errors) {
         try {
             onCleanup();
@@ -1102,6 +1138,12 @@ const ContextParts = Object.freeze({
             errors.push(error);
         }
     },
+    /**
+     * Closes buses and stores after context assembly fails.
+     *
+     * @param resources Partially created resources.
+     * @param errors Collection receiving failures.
+     */
     cleanupBuildBuses(resources, errors) {
         ContextParts.attemptCleanup(() => {
             if (resources.commandBus !== undefined)
@@ -1120,20 +1162,61 @@ const ContextParts = Object.freeze({
                 resources.eventStore?.close();
         }, errors);
     },
+    /**
+     * Returns constituent failures from nested aggregate errors.
+     *
+     * @param errors Errors to expand.
+     * @returns Flattened error list.
+     */
     flattenErrors(errors) {
         return errors.flatMap((error) => error instanceof AggregateError ? ContextParts.flattenErrors(error.errors) : [error]);
     },
+    /**
+     * Rejects construction without the framework token.
+     *
+     * @param token Supplied token.
+     * @param message Error message for an invalid token.
+     */
     requireFrameworkConstructionToken(token, message) {
         if (token !== frameworkConstructionToken) {
             throw new TypeError(message);
         }
     },
+    /**
+     * Creates a context specification from its snapshot.
+     *
+     * @param specSnapshot Snapshot used for construction.
+     * @returns Constructed context specification.
+     */
     createContextSpec(specSnapshot) {
         return constructContextSpec(specSnapshot, frameworkConstructionToken);
     },
+    /**
+     * Creates a builder for a context snapshot.
+     *
+     * @param specSnapshot Context configuration snapshot.
+     * @returns Constructed context builder.
+     */
     createBoundedContextBuilder(specSnapshot) {
         return constructBoundedContextBuilder(specSnapshot, frameworkConstructionToken);
     },
+    /**
+     * Creates a bounded context from assembled runtime components.
+     *
+     * @param specSnapshot Context configuration.
+     * @param commandBus Command dispatch bus.
+     * @param eventBus Domain event bus.
+     * @param systemEventBus System event bus.
+     * @param publisher Signal publisher.
+     * @param stand Domain read-side Stand.
+     * @param systemStand System read-side Stand.
+     * @param runtime Subscription runtime.
+     * @param systemSpec Paired System specification.
+     * @param storageFactory Storage provider.
+     * @param repositories Registered repository views.
+     * @param deliveryStrategy Delivery sharding strategy.
+     * @returns Constructed bounded context.
+     */
     createBoundedContext(specSnapshot, commandBus, eventBus, systemEventBus, publisher, stand, systemStand, runtime, systemSpec, storageFactory, repositories, deliveryStrategy) {
         return constructBoundedContext({
             name: specSnapshot.name,
@@ -1141,18 +1224,36 @@ const ContextParts = Object.freeze({
             spec: specSnapshot,
         }, commandBus, eventBus, systemEventBus, publisher, stand, systemStand, runtime, systemSpec, storageFactory, repositories, deliveryStrategy, frameworkConstructionToken);
     },
+    /**
+     * Creates the storage mode represented by a context snapshot.
+     *
+     * @param specSnapshot Context configuration snapshot.
+     * @returns Storage mode for the context.
+     */
     createStorageMode(specSnapshot) {
         return Object.freeze({
             name: specSnapshot.name.value,
             multitenant: specSnapshot.multitenant,
         });
     },
+    /**
+     * Creates a non-tenant-scoped subscription storage context.
+     *
+     * @param specSnapshot Context configuration snapshot.
+     * @returns Subscription storage context.
+     */
     createSubscriptionStorageContext(specSnapshot) {
         return Object.freeze({
             name: `${specSnapshot.name.value}:subscriptions`,
             multitenant: false,
         });
     },
+    /**
+     * Captures the shard count and validates later shard results.
+     *
+     * @param strategy Configured delivery strategy.
+     * @returns Immutable delivery strategy snapshot.
+     */
     snapshotDeliveryStrategy(strategy) {
         if (!Number.isSafeInteger(strategy.shardCount) || strategy.shardCount <= 0) {
             throw new Error("Delivery strategy shard count must be a positive safe integer.");
@@ -1160,6 +1261,13 @@ const ContextParts = Object.freeze({
         const shardCount = strategy.shardCount;
         return Object.freeze({
             shardCount,
+            /**
+             * Returns a target shard after verifying the captured shard total.
+             *
+             * @param targetId Inbox target identifier.
+             * @param targetType Inbox target type.
+             * @returns Validated shard index.
+             */
             shardFor(targetId, targetType) {
                 const shard = strategy.shardFor(InboxTargets.clone(targetId), targetType);
                 if (shard.ofTotal !== shardCount) {
@@ -1169,6 +1277,13 @@ const ContextParts = Object.freeze({
             },
         });
     },
+    /**
+     * Creates the storage context for read-side catch-up.
+     *
+     * @param specSnapshot Context configuration.
+     * @param options Catch-up tenant options.
+     * @returns Storage context for the selected scope.
+     */
     catchUpStorageContext(specSnapshot, options) {
         if (!specSnapshot.multitenant) {
             if (options.tenantId !== undefined) {
@@ -1186,6 +1301,12 @@ const ContextParts = Object.freeze({
             tenantId: TenantBoundary.from(tenantId).tenantId,
         });
     },
+    /**
+     * Creates a bounded-context name after checking reserved names.
+     *
+     * @param value Candidate context name.
+     * @returns Immutable validated name.
+     */
     createBoundedContextName(value) {
         if (typeof value !== "string" ||
             value.trim().length === 0 ||
@@ -1194,6 +1315,13 @@ const ContextParts = Object.freeze({
         }
         return Object.freeze({ value });
     },
+    /**
+     * Creates a context snapshot with event storage enabled.
+     *
+     * @param name Context name.
+     * @param multitenant Whether tenant isolation is enabled.
+     * @returns Immutable specification snapshot.
+     */
     createSpecSnapshot(name, multitenant) {
         return Object.freeze({
             name: ContextParts.createBoundedContextName(name),
@@ -1201,9 +1329,21 @@ const ContextParts = Object.freeze({
             storesEvents: true,
         });
     },
+    /**
+     * Copies a bounded-context name into an immutable value.
+     *
+     * @param name Source context name.
+     * @returns Immutable name copy.
+     */
     cloneName(name) {
         return ContextParts.createBoundedContextName(name.value);
     },
+    /**
+     * Copies a context specification snapshot and its name.
+     *
+     * @param spec Source specification.
+     * @returns Immutable specification copy.
+     */
     cloneSpecSnapshot(spec) {
         return Object.freeze({
             name: ContextParts.cloneName(spec.name),
@@ -1211,6 +1351,12 @@ const ContextParts = Object.freeze({
             storesEvents: spec.storesEvents,
         });
     },
+    /**
+     * Copies a bounded-context snapshot and its specification.
+     *
+     * @param snapshot Source context snapshot.
+     * @returns Immutable context snapshot copy.
+     */
     cloneContextSnapshot(snapshot) {
         return Object.freeze({
             name: ContextParts.cloneName(snapshot.name),
@@ -1218,6 +1364,13 @@ const ContextParts = Object.freeze({
             spec: ContextParts.cloneSpecSnapshot(snapshot.spec),
         });
     },
+    /**
+     * Creates the System specification paired with a domain context.
+     *
+     * @param domainSpec Domain specification.
+     * @param storesEvents Whether System events are stored.
+     * @returns System context snapshot.
+     */
     createSystemSpec(domainSpec, storesEvents) {
         return Object.freeze({
             name: ContextParts.createBoundedContextName(`${domainSpec.name.value}_System`),
@@ -1225,24 +1378,49 @@ const ContextParts = Object.freeze({
             storesEvents,
         });
     },
+    /**
+     * Creates a pairing snapshot for domain and System specifications.
+     *
+     * @param snapshot Domain snapshot.
+     * @param systemSpec Paired System specification.
+     * @returns Immutable context pairing.
+     */
     createSystemPairing(snapshot, systemSpec) {
         return Object.freeze({
             domain: ContextParts.cloneContextSnapshot(snapshot),
             system: ContextParts.cloneSpecSnapshot(systemSpec),
         });
     },
+    /**
+     * Copies both specifications in a System pairing.
+     *
+     * @param pairing Pairing to copy.
+     * @returns Immutable pairing copy.
+     */
     cloneSystemPairing(pairing) {
         return Object.freeze({
             domain: ContextParts.cloneContextSnapshot(pairing.domain),
             system: ContextParts.cloneSpecSnapshot(pairing.system),
         });
     },
+    /**
+     * Lists non-internal event type URLs exposed by an event bus.
+     *
+     * @param eventBus Bus whose schemas are inspected.
+     * @returns Frozen exposed type URLs.
+     */
     exposedEventTypeUrls(eventBus) {
         return Object.freeze(eventBusAccess
             .eventSchemas(eventBus)
             .filter((schema) => !ContextParts.isInternalEventSchema(schema))
             .map((schema) => TypeUrls.derive(schema)));
     },
+    /**
+     * Collects external event schemas by type URL.
+     *
+     * @param dispatchers Dispatchers to inspect.
+     * @returns Unique frozen schemas.
+     */
     externalEventSchemas(dispatchers) {
         const schemas = new Map();
         for (const dispatcher of dispatchers) {
@@ -1252,6 +1430,14 @@ const ContextParts = Object.freeze({
         }
         return Object.freeze([...schemas.values()]);
     },
+    /**
+     * Opens the integration broker and associates context readiness.
+     *
+     * @param context Context receiving integration.
+     * @param eventBus Event bus supplied to broker.
+     * @param systemSpec Paired System specification.
+     * @param externalEventSchemas Schemas accepted from outside.
+     */
     attachIntegration(context, eventBus, systemSpec, externalEventSchemas) {
         const broker = new IntegrationBroker({
             contextName: create(BoundedContextNameSchema, { value: context.name.value }),
@@ -1274,6 +1460,13 @@ const ContextParts = Object.freeze({
         void ready.catch(() => undefined);
         contextIntegrations.set(context, { broker, ready });
     },
+    /**
+     * Posts an event after integration readiness and tenant validation.
+     *
+     * @param context Target context.
+     * @param event Event to post.
+     * @returns Promise fulfilled after posting.
+     */
     postContextEvent(context, event) {
         const buses = contextEventBuses.get(context);
         if (buses === undefined)
@@ -1285,15 +1478,34 @@ const ContextParts = Object.freeze({
             return buses[0].post(event);
         });
     },
+    /**
+     * Closes the context integration broker.
+     *
+     * @param context Context whose broker is closed.
+     * @returns Promise fulfilled after closing.
+     */
     closeIntegration(context) {
         return contextIntegrations.get(context)?.broker.close() ?? Promise.resolve();
     },
+    /**
+     * Publishes an imported event through the integration broker.
+     *
+     * @param context Context integration.
+     * @param event Imported event.
+     * @returns Promise fulfilled after publishing.
+     */
     publishImported(context, event) {
         const integration = contextIntegrations.get(context);
         if (integration === undefined)
             return Promise.reject(new Error("Context integration is unavailable."));
         return integration.ready.then(() => integration.broker.publishImported(event));
     },
+    /**
+     * Checks imported event tenant against the context tenant mode.
+     *
+     * @param context Target context.
+     * @param event Imported event to validate.
+     */
     validateImportedTenant(context, event) {
         const tenantId = ContextParts.readReplayTenant(event);
         if (!context.isMultitenant) {
@@ -1307,17 +1519,41 @@ const ContextParts = Object.freeze({
         }
         TenantBoundary.from(tenantId);
     },
+    /**
+     * Waits for the integration broker to become ready.
+     *
+     * @param context Context whose readiness is observed.
+     * @returns Readiness promise.
+     */
     integrationReady(context) {
         return contextIntegrations.get(context)?.ready ?? Promise.resolve();
     },
+    /**
+     * Checks whether a schema carries an internal or SPI marker.
+     *
+     * @param schema Event schema to inspect.
+     * @returns True when an internal marker is set.
+     */
     isInternalEventSchema(schema) {
         return ((hasOption(schema, internal_type) && getOption(schema, internal_type)) ||
             (hasOption(schema, SPI_type) && getOption(schema, SPI_type)) ||
             (hasOption(schema.file, internal_all) && getOption(schema.file, internal_all)));
     },
+    /**
+     * Converts the multitenant flag to a tenant mode.
+     *
+     * @param multitenant Context isolation flag.
+     * @returns Corresponding tenant mode.
+     */
     toTenantMode(multitenant) {
         return multitenant ? "multitenant" : "single-tenant";
     },
+    /**
+     * Reads the System pairing recorded for a built context.
+     *
+     * @param context Context to inspect.
+     * @returns Pairing snapshot; throws if unpaired.
+     */
     requireSystemPairing(context) {
         const pairing = contextSystemPairings.get(context);
         if (pairing === undefined) {
@@ -1325,6 +1561,12 @@ const ContextParts = Object.freeze({
         }
         return pairing;
     },
+    /**
+     * Reads the tenant index recorded for a built context.
+     *
+     * @param context Context to inspect.
+     * @returns Tenant index; throws if unavailable.
+     */
     requireTenantIndex(context) {
         const tenantIndex = contextTenantIndexes.get(context);
         if (tenantIndex === undefined) {
@@ -1332,16 +1574,33 @@ const ContextParts = Object.freeze({
         }
         return tenantIndex;
     },
+    /**
+     * Rejects values that are not Repository instances.
+     *
+     * @param repository Candidate value.
+     * @param operation Operation name included in the error.
+     */
     requireRepositoryInstance(repository, operation) {
         if (!repositoryAccess.hasInstance(repository)) {
             throw new TypeError(`${operation} requires a Repository instance.`);
         }
     },
+    /**
+     * Rejects values that are not Entity classes.
+     *
+     * @param entityType Candidate Entity constructor.
+     * @param operation Operation name included in the error.
+     */
     requireEntityClass(entityType, operation) {
         if (typeof entityType !== "function") {
             throw new TypeError(`${operation} requires a Repository instance. Use an entity class only with buildAsync().`);
         }
     },
+    /**
+     * Rejects synchronous assembly when classes need generated metadata.
+     *
+     * @param entityTypes Entity classes to assemble.
+     */
     rejectSyncEntityAssembly(entityTypes) {
         if (entityTypes.size === 0) {
             return;
@@ -1349,6 +1608,12 @@ const ContextParts = Object.freeze({
         throw new Error("BoundedContextBuilder.build() cannot assemble entity classes from generated metadata. " +
             "Use buildAsync().");
     },
+    /**
+     * 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;
@@ -1356,6 +1621,12 @@ const ContextParts = Object.freeze({
         throw new Error("BoundedContextBuilder.buildAsync() 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);
@@ -1366,6 +1637,12 @@ const ContextParts = Object.freeze({
         }
         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 {
@@ -1375,6 +1652,12 @@ const ContextParts = Object.freeze({
             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");
@@ -1384,6 +1667,13 @@ const ContextParts = Object.freeze({
         }
         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.`);
@@ -1393,6 +1683,12 @@ const ContextParts = Object.freeze({
         }
         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);
@@ -1401,9 +1697,21 @@ const ContextParts = Object.freeze({
             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);
@@ -1413,6 +1721,13 @@ const ContextParts = Object.freeze({
             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("..") ||
@@ -1420,13 +1735,30 @@ const ContextParts = Object.freeze({
             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.
+     *
+     * @param registries Generated registries to ingest.
+     * @returns Populated handler metadata registry.
+     */
     ingestGeneratedRegistries(registries) {
         const registry = new HandlerMetadataRegistry();
         const ingestor = new HandlerRegistryIngestor();
@@ -1435,6 +1767,15 @@ const ContextParts = Object.freeze({
         }
         return registry;
     },
+    /**
+     * Creates a repository from generated Entity handler metadata.
+     *
+     * @param entityType Entity class.
+     * @param registries Generated registries to search.
+     * @param metadata Ingested handler metadata.
+     * @param options Repository options overriding defaults.
+     * @returns Configured repository view.
+     */
     createGeneratedRepository(entityType, registries, metadata, options) {
         const generated = ContextParts.findGeneratedEntity(entityType, registries);
         const handlers = ContextParts.findGeneratedHandlers(entityType, generated, metadata);
@@ -1446,6 +1787,13 @@ const ContextParts = Object.freeze({
         }, options);
         return new Repository(repositoryOptions);
     },
+    /**
+     * Finds the generated Entity handler group for an Entity class.
+     *
+     * @param entityType Entity class to find.
+     * @param registries Generated registries to search.
+     * @returns Matching handler group; throws when absent.
+     */
     findGeneratedEntity(entityType, registries) {
         for (const registry of registries) {
             const generated = registry.receivers.find((receiver) => receiver.receiverKind === "entity" && receiver.receiverType === entityType);
@@ -1455,6 +1803,14 @@ const ContextParts = Object.freeze({
         }
         throw new Error(`Generated handler registry is missing metadata for ${entityType.name}.`);
     },
+    /**
+     * Finds handler metadata for an Entity class and state schema.
+     *
+     * @param entityType Entity class.
+     * @param generated Matching generated Entity group.
+     * @param metadata Handler metadata registry.
+     * @returns Matching handler metadata; throws when absent.
+     */
     findGeneratedHandlers(entityType, generated, metadata) {
         const matches = metadata.findByState(generated.stateSchema.typeName);
         const handlers = matches.find((candidate) => candidate.entityType === entityType);
@@ -1463,6 +1819,12 @@ const ContextParts = Object.freeze({
         }
         return handlers;
     },
+    /**
+     * Collects event schemas declared as returned or thrown handler outcomes.
+     *
+     * @param generated Generated Entity handler group.
+     * @returns Frozen unique event schemas.
+     */
     aggregateAssignedEvents(generated) {
         return ContextParts.uniqueSchemas(generated.handlers.flatMap((handler) => [
             ...(handler.kind === "command-assignment" || handler.kind === "event-reaction"
@@ -1473,6 +1835,12 @@ const ContextParts = Object.freeze({
                 : []),
         ]));
     },
+    /**
+     * Collects event schemas produced by standalone handler outcomes.
+     *
+     * @param receivers Generated standalone groups.
+     * @returns Frozen unique event schemas.
+     */
     standaloneProducedEventSchemas(receivers) {
         return ContextParts.uniqueSchemas(receivers.flatMap((receiver) => receiver.handlers.flatMap((handler) => [
             ...(handler.kind === "command-assignment" || handler.kind === "event-reaction"
@@ -1483,6 +1851,13 @@ const ContextParts = Object.freeze({
                 : []),
         ])));
     },
+    /**
+     * Returns unique schemas by Protobuf type name, preserving the last schema.
+     *
+     * @typeParam Schema Descriptor schema type retained in the result.
+     * @param schemas Schemas to deduplicate.
+     * @returns Frozen deduplicated schemas.
+     */
     uniqueSchemas(schemas) {
         const byTypeName = new Map();
         for (const schema of schemas) {
@@ -1490,6 +1865,11 @@ const ContextParts = Object.freeze({
         }
         return Object.freeze([...byTypeName.values()]);
     },
+    /**
+     * Validates repository uniqueness, registration state, and projection cycles.
+     *
+     * @param repositories Repository views to validate.
+     */
     preflightRepositories(repositories) {
         const entityTypes = new Set();
         const stateTypeNames = new Set();
@@ -1512,6 +1892,11 @@ const ContextParts = Object.freeze({
         }
         ContextParts.rejectStateCycles(repositories);
     },
+    /**
+     * Rejects cycles among repository state-subscription dependencies.
+     *
+     * @param repositories Repository views whose dependencies are checked.
+     */
     rejectStateCycles(repositories) {
         const dependencies = new Map();
         for (const repository of repositories) {
@@ -1542,30 +1927,66 @@ const ContextParts = Object.freeze({
         for (const stateType of dependencies.keys())
             visit(stateType);
     },
+    /**
+     * Collects command dispatchers configured by repositories.
+     *
+     * @param repositories Repository views to inspect.
+     * @returns Present command dispatchers.
+     */
     repositoryCommandDispatchers(repositories) {
         return repositories.flatMap((repository) => {
             const dispatcher = repositoryAccess.commandDispatcher(repository);
             return dispatcher === undefined ? [] : [dispatcher];
         });
     },
+    /**
+     * Collects event dispatchers configured by repositories.
+     *
+     * @param repositories Repository views to inspect.
+     * @returns Present event dispatchers.
+     */
     repositoryEventDispatchers(repositories) {
         return repositories.flatMap((repository) => {
             const dispatcher = repositoryAccess.eventDispatcher(repository);
             return dispatcher === undefined ? [] : [dispatcher];
         });
     },
+    /**
+     * Collects System event dispatchers configured by repositories.
+     *
+     * @param repositories Repository views to inspect.
+     * @returns Present System event dispatchers.
+     */
     repositorySystemEventDispatchers(repositories) {
         return repositories.flatMap((repository) => {
             const dispatcher = repositoryAccess.systemEventDispatcher(repository);
             return dispatcher === undefined ? [] : [dispatcher];
         });
     },
+    /**
+     * Returns event dispatchers excluding System routes.
+     *
+     * @param dispatchers Event dispatchers to filter.
+     * @returns Frozen domain event dispatchers.
+     */
     domainEventDispatchers(dispatchers) {
         return Object.freeze(dispatchers.filter((dispatcher) => !ContextParts.isSystemEventDispatcher(dispatcher)));
     },
+    /**
+     * Returns System event dispatchers.
+     *
+     * @param dispatchers Event dispatchers to filter.
+     * @returns Frozen System event dispatchers.
+     */
     systemEventDispatchers(dispatchers) {
         return Object.freeze(dispatchers.filter((dispatcher) => ContextParts.isSystemEventDispatcher(dispatcher)));
     },
+    /**
+     * Checks a dispatcher's event family and rejects mixed families.
+     *
+     * @param dispatcher Dispatcher to inspect.
+     * @returns True when its schemas are System event schemas.
+     */
     isSystemEventDispatcher(dispatcher) {
         const schemas = [...dispatcher.messageSchemas()];
         const systemSchemas = schemas.filter((schema) => schema.typeName.startsWith("spine.system."));
@@ -1574,6 +1995,12 @@ const ContextParts = Object.freeze({
         }
         return systemSchemas.length > 0;
     },
+    /**
+     * Collects repository-produced event schemas by type URL.
+     *
+     * @param repositories Repository views to inspect.
+     * @returns Frozen unique event schemas.
+     */
     repositoryProducedEventSchemas(repositories) {
         const schemas = new Map();
         for (const repository of repositories) {
@@ -1583,10 +2010,21 @@ const ContextParts = Object.freeze({
         }
         return Object.freeze([...schemas.values()]);
     },
+    /**
+     * Clears metadata for a failed context build and closes its tenant index.
+     *
+     * @param context Context whose build failed.
+     * @param tenantIndex Tenant index to close.
+     */
     cleanupFailedContext(context, tenantIndex) {
         ContextParts.clearContextMetadata(context);
         tenantIndex.close();
     },
+    /**
+     * Removes runtime metadata associated with a context.
+     *
+     * @param context Context whose WeakMap metadata is removed.
+     */
     clearContextMetadata(context) {
         const buses = contextEventBuses.get(context);
         if (buses !== undefined) {
@@ -1608,48 +2046,72 @@ const ContextParts = Object.freeze({
         eventSubscribers.delete(context);
         systemEventPosters.delete(context);
     },
+    /**
+     * Creates delivery operations from the context inboxes and readiness state.
+     *
+     * @param context Built context snapshot.
+     * @param storageFactory Context storage provider.
+     * @param tenantIndex Tenant index for startup scopes.
+     * @param entityInbox Registered Entity inbox.
+     * @param projections Projection inbox.
+     * @param readiness Delivery readiness coordinator.
+     * @returns Delivery descriptor.
+     */
     createDeliveryDescriptor(context, storageFactory, tenantIndex, entityInbox, projections, readiness) {
         return Object.freeze({
             storageFactory,
-            async startupScopes() {
-                if (tenantIndex.tenantMode === "single-tenant") {
-                    return Object.freeze([Object.freeze({})]);
-                }
-                return Object.freeze((await tenantIndex.all()).map((tenantId) => Object.freeze({ tenantId })));
-            },
-            storageContext(scope) {
-                if (context.tenantMode === "single-tenant") {
-                    if (scope.tenantId !== undefined) {
-                        throw new Error(`Single-tenant context "${context.name.value}" does not accept tenantId.`);
-                    }
-                    return Object.freeze({ name: context.name.value, multitenant: false });
-                }
-                const tenantId = scope.tenantId;
-                if (tenantId === undefined) {
-                    throw new Error(`Multitenant context "${context.name.value}" requires tenantId.`);
-                }
-                return Object.freeze({
-                    name: context.name.value,
-                    multitenant: true,
-                    tenantId: TenantBoundary.from(tenantId).tenantId,
-                });
-            },
-            endpoints() {
-                return Object.freeze([...entityInbox.endpoints(), ...projections.endpoints()]);
-            },
-            replay(message, tenantId) {
-                return message.label === "UPDATE_SUBSCRIBER"
-                    ? projections.replay(message, tenantId)
-                    : entityInbox.replay(message, tenantId);
-            },
-            onReady(onReady) {
-                return readiness.onReady(onReady);
-            },
-            transition(scopes, onReady, options) {
-                return readiness.transition(scopes, onReady, options);
-            },
+            startupScopes: () => ContextParts.deliveryStartupScopes(tenantIndex),
+            storageContext: (scope) => ContextParts.deliveryStorageContext(context, scope),
+            endpoints: () => Object.freeze([...entityInbox.endpoints(), ...projections.endpoints()]),
+            replay: (message, tenantId) => message.label === "UPDATE_SUBSCRIBER"
+                ? projections.replay(message, tenantId)
+                : entityInbox.replay(message, tenantId),
+            onReady: (onReady) => readiness.onReady(onReady),
+            transition: (scopes, onReady, options) => readiness.transition(scopes, onReady, options),
+        });
+    },
+    /**
+     * Lists delivery startup scopes, one per tenant in multitenant contexts.
+     *
+     * @param tenantIndex Tenant index supplying configured scopes.
+     * @returns Frozen startup scope list.
+     */
+    async deliveryStartupScopes(tenantIndex) {
+        if (tenantIndex.tenantMode === "single-tenant") {
+            return Object.freeze([Object.freeze({})]);
+        }
+        return Object.freeze((await tenantIndex.all()).map((tenantId) => Object.freeze({ tenantId })));
+    },
+    /**
+     * Creates tenant-validated storage context for a delivery scope.
+     *
+     * @param context Built context snapshot.
+     * @param scope Selected startup scope.
+     * @returns Storage context for the selected tenant.
+     */
+    deliveryStorageContext(context, scope) {
+        if (context.tenantMode === "single-tenant") {
+            if (scope.tenantId !== undefined) {
+                throw new Error(`Single-tenant context "${context.name.value}" does not accept tenantId.`);
+            }
+            return Object.freeze({ name: context.name.value, multitenant: false });
+        }
+        const tenantId = scope.tenantId;
+        if (tenantId === undefined) {
+            throw new Error(`Multitenant context "${context.name.value}" requires tenantId.`);
+        }
+        return Object.freeze({
+            name: context.name.value,
+            multitenant: true,
+            tenantId: TenantBoundary.from(tenantId).tenantId,
         });
     },
+    /**
+     * Closes prepared repositories and collects close failures.
+     *
+     * @param preparedRepositories Prepared repository resources to close.
+     * @returns Collected close errors.
+     */
     closePreparedRepositories(preparedRepositories) {
         const errors = [];
         for (const preparedRepository of preparedRepositories) {
@@ -1662,6 +2124,13 @@ const ContextParts = Object.freeze({
         }
         return errors;
     },
+    /**
+     * Calls one asynchronous context close action and records failures.
+     *
+     * @param close Close operation.
+     * @param errors Failure collection.
+     * @returns Promise fulfilled after the close attempt is recorded.
+     */
     async closeContextPart(close, errors) {
         try {
             await close();
@@ -1670,6 +2139,15 @@ const ContextParts = Object.freeze({
             ContextParts.collectCloseError(error, errors);
         }
     },
+    /**
+     * Waits until accepted command, event, System event, and signal work drains.
+     *
+     * @param commandBus Command bus.
+     * @param eventBus Domain event bus.
+     * @param systemEventBus System event bus.
+     * @param publisher Signal publisher.
+     * @returns Promise fulfilled when accepted work stabilizes.
+     */
     async drainContextWork(commandBus, eventBus, systemEventBus, publisher) {
         let observedCommandWork = -1;
         let observedEventWork = -1;
@@ -1686,6 +2164,12 @@ const ContextParts = Object.freeze({
             eventBusAccess.acceptedWorkCount(eventBus) !== observedEventWork ||
             eventBusAccess.acceptedWorkCount(systemEventBus) !== observedSystemEventWork);
     },
+    /**
+     * Adds an error or aggregate causes to the close error collection.
+     *
+     * @param error Close failure.
+     * @param errors Failure collection.
+     */
     collectCloseError(error, errors) {
         if (error instanceof AggregateError) {
             const causes = error.errors;
@@ -1696,6 +2180,13 @@ const ContextParts = Object.freeze({
         }
         errors.push(error);
     },
+    /**
+     * Binds a repository to context runtime services and supplies commit and close operations.
+     *
+     * @param repository Repository to prepare.
+     * @param registration Context services and schemas.
+     * @returns Prepared repository.
+     */
     prepareRepositoryForContext(repository, registration) {
         ContextParts.requireRepositoryInstance(repository, "BoundedContext repository registration");
         const snapshot = ContextParts.repositorySnapshot(repository);
@@ -1726,6 +2217,12 @@ const ContextParts = Object.freeze({
             },
         };
     },
+    /**
+     * Captures repository metadata needed for context registration.
+     *
+     * @param repository Repository to inspect.
+     * @returns Frozen registration snapshot.
+     */
     repositorySnapshot(repository) {
         const snapshot = repositoryAccess.snapshot(repository);
         return Object.freeze({
@@ -1738,6 +2235,11 @@ const ContextParts = Object.freeze({
             snapshot,
         });
     },
+    /**
+     * Rejects a repository already registered with a bounded context.
+     *
+     * @param repository Repository to check.
+     */
     rejectRegisteredRepository(repository) {
         const snapshot = ContextParts.repositorySnapshot(repository);
         const registration = registeredRepositories.get(repository);
@@ -1746,9 +2248,21 @@ const ContextParts = Object.freeze({
                 `"${registration.name.value}".`);
         }
     },
+    /**
+     * Creates storage record columns from Entity metadata.
+     *
+     * @param snapshot Registration snapshot supplying fields.
+     * @returns Record columns.
+     */
     repositoryColumns(snapshot) {
         return snapshot.metadata.columns.map((field) => new RecordColumn(field.name, ColumnTypes.fromField(field.descriptor), (record) => ContextParts.readRecordField(record, field.localName)));
     },
+    /**
+     * Creates an immutable repository view from a registration snapshot.
+     *
+     * @param snapshot Registration snapshot.
+     * @returns Immutable repository view.
+     */
     createRepositoryView(snapshot) {
         return Object.freeze({
             entityType: snapshot.entityType,
@@ -1760,6 +2274,12 @@ const ContextParts = Object.freeze({
             snapshot: snapshot.snapshot,
         });
     },
+    /**
+     * Builds dispatch descriptors for Projection repositories with event handlers.
+     *
+     * @param repositories Repository views to inspect.
+     * @returns Frozen Projection dispatch descriptors.
+     */
     projectionDispatchers(repositories) {
         const projections = [];
         for (const repository of repositories) {
@@ -1778,6 +2298,12 @@ const ContextParts = Object.freeze({
         }
         return Object.freeze(projections);
     },
+    /**
+     * Collects unique Projection state schemas for clearing.
+     *
+     * @param projections Projection dispatch descriptors.
+     * @returns Frozen unique clear targets.
+     */
     projectionStateClearTargets(projections) {
         const unique = new Map();
         for (const projection of projections) {
@@ -1790,6 +2316,13 @@ const ContextParts = Object.freeze({
         }
         return Object.freeze([...unique.values()]);
     },
+    /**
+     * Reads stored events in deterministic timestamp, producer, version, and ID order.
+     *
+     * @param context Event-store storage context.
+     * @param storageFactory Event storage provider.
+     * @returns Stored events in deterministic order.
+     */
     async readStoredEvents(context, storageFactory) {
         const eventStore = new EventStore(context, storageFactory);
         try {
@@ -1806,12 +2339,24 @@ const ContextParts = Object.freeze({
             eventStore.close();
         }
     },
+    /**
+     * Builds Stand options for the catch-up tenant scope.
+     *
+     * @param context Catch-up storage context.
+     * @returns Options with a cloned tenant ID when multitenant.
+     */
     catchUpStandOptions(context) {
         if (!context.multitenant) {
             return {};
         }
         return Object.freeze({ tenantId: clone(TenantIdSchema, context.tenantId) });
     },
+    /**
+     * Verifies a stored event envelope belongs to the catch-up tenant.
+     *
+     * @param context Catch-up storage context.
+     * @param event Stored event to validate.
+     */
     validateReplayTenant(context, event) {
         if (!context.multitenant) {
             return;
@@ -1825,6 +2370,12 @@ const ContextParts = Object.freeze({
             throw new Error("Read-side catch-up stored event envelope tenant does not match.");
         }
     },
+    /**
+     * Reads the tenant ID from an event import or past-message origin.
+     *
+     * @param event Event whose origin is inspected.
+     * @returns Cloned tenant ID when present.
+     */
     readReplayTenant(event) {
         switch (event.context?.origin.case) {
             case "importContext":
@@ -1835,9 +2386,23 @@ const ContextParts = Object.freeze({
                 return undefined;
         }
     },
+    /**
+     * Copies a tenant ID when present.
+     *
+     * @param tenantId Optional tenant ID.
+     * @returns Cloned tenant ID or undefined.
+     */
     tenantIdValue(tenantId) {
         return tenantId === undefined ? undefined : clone(TenantIdSchema, tenantId);
     },
+    /**
+     * Dispatches a stored event to matching Projection handlers and direct updates.
+     *
+     * @param projections Projection dispatch descriptors.
+     * @param event Stored event.
+     * @param rebuild Whether direct dispatch is a rebuild.
+     * @returns One when a Projection matched, otherwise zero.
+     */
     async dispatchStoredProjectionEvent(projections, event, rebuild) {
         const typeUrl = event.message?.typeUrl;
         if (typeUrl === undefined || typeUrl === "") {
@@ -1852,12 +2417,32 @@ const ContextParts = Object.freeze({
         }
         return matching.length > 0 ? 1 : 0;
     },
+    /**
+     * Creates a replay error with the event ID and bounded cause details.
+     *
+     * @param event Event that failed.
+     * @param cause Thrown replay cause.
+     * @returns Replay error.
+     */
     catchUpReplayError(event, cause) {
         return new CatchUpReplayError(event.id?.value ?? "(missing)", ContextParts.catchUpReplayDetail(cause));
     },
+    /**
+     * Returns an error string truncated to a maximum length.
+     *
+     * @param value String to bound.
+     * @param limit Maximum character count.
+     * @returns Bounded string.
+     */
     boundedErrorString(value, limit) {
         return value.length <= limit ? value : `${value.slice(0, limit - 3)}...`;
     },
+    /**
+     * Converts a thrown value to bounded error name and message details.
+     *
+     * @param error Thrown value.
+     * @returns Immutable bounded details.
+     */
     catchUpReplayDetail(error) {
         if (error instanceof Error) {
             return Object.freeze({
@@ -1870,6 +2455,13 @@ const ContextParts = Object.freeze({
             message: ContextParts.boundedErrorString(String(error), errorDetailLimit),
         });
     },
+    /**
+     * Reads and requires the Entity ID field from a stored record.
+     *
+     * @param record Protobuf record.
+     * @param snapshot Repository metadata identifying the ID field.
+     * @returns ID field value; throws when missing.
+     */
     readRecordId(record, snapshot) {
         const value = ContextParts.readRecordField(record, snapshot.idField.localName);
         if (value === undefined || value === null) {
@@ -1877,6 +2469,13 @@ const ContextParts = Object.freeze({
         }
         return value;
     },
+    /**
+     * Reads a field from a Protobuf record by descriptor local name.
+     *
+     * @param record Record message.
+     * @param localName Descriptor local field name.
+     * @returns Field value.
+     */
     readRecordField(record, localName) {
         return record[localName];
     },