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

package/README.md

@@ -43,6 +43,41 @@ Add generated entities with `BoundedContext.add(...)` and use
 context is single-tenant or multitenant by construction; select that mode
 before registering application handlers and storage.
 
+## Give an Entity an application service
+
+Spine normally constructs an Entity with its ID, state, version, and lifecycle
+options. If your constructor also needs a service, supply `onCreate` when
+registering the class. For example, the Projects application's Process Manager
+uses an assignment-weight service:
+
+<!-- docs-snippet-path: examples/projects/test/topology.test.ts -->
+
+```ts
+import { BoundedContext } from "@spine-event-engine/server";
+import { TaskAssignment, type AssignmentWeightService } from "../src/index.js";
+
+// Create shared services before starting the context.
+const weights: AssignmentWeightService = { weightFor: () => 2 };
+const builder = BoundedContext.singleTenant("Assignments")
+  .withGeneratedRegistryRoot(new URL("..", import.meta.url))
+  .add(TaskAssignment, {
+    // Forward Spine's options and add the service required by the constructor.
+    onCreate: (options) => new TaskAssignment(options, weights),
+  });
+```
+
+Call `builder.buildAsync()` to assemble the context. The callback runs for each
+fresh or restored Entity object, not just once per ID. It also works for
+Aggregates and Projections, including Projection rebuilds. Return a fresh
+instance synchronously and pass the supplied options unchanged. Application
+services are not persisted; the application manages their initialization and
+shutdown. Constructors that need only `EntityOptions` require no callback.
+
+Explicit repositories accept `onCreate` in their options too. See the
+[guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/USER_GUIDE.md#give-an-entity-an-application-service) for the
+full story and the [reference](REFERENCE.md#entity-constructor-dependencies)
+for the exact contract.
+
 ## Async handlers and Process Manager queries
 
 An `@Assign`, `@Command`, `@React`, or `@Subscribe` handler may return its
@@ -52,6 +87,24 @@ results and structural or imported thenable lookalikes are rejected during handl
 analysis. Rejection rolls back framework state and suppresses produced output; it
 cannot roll back an external HTTP request or other side effect.
 
+Handler return declarations can use native unions for one of several results,
+or fixed tuples for several ordered results. For example,
+`CreateAccessGrant | ExtendAccessGrant` selects one Command, while
+`readonly [AccessGrantCreated, AccessRequestCompleted?]` returns an Event and
+possibly a second Event. Each actual result must be declared by that handler.
+Arrays and local/imported aliases of these concrete message types are supported
+too. `@Assign` returns Events, `@Command` returns Commands, `@React` returns
+Events or `undefined`, and `@Subscribe` declares `void` or `Promise<void>`.
+Event/rejection-input `@Command` also permits `undefined`, alone or alongside
+concrete Command types. Only subscriptions accept `void`; required empty
+results and unexpected returned values fail before Entity commit or publication.
+See the [return-type guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/USER_GUIDE.md#choose-what-a-handler-returns)
+for examples, optional results, and the restrictions for each decorator.
+
+Every Entity's `version` is the generated Spine `Version`; the framework
+advances it once when a successful dispatch produces Events or changes state or
+lifecycle, not for a no-op.
+
 Declare each domain rejection a command handler may throw. This registers the
 rejection before the server starts, so a client can subscribe even when no
 server handler consumes that rejection:

package/REFERENCE.md

@@ -1,6 +1,8 @@
 # @spine-event-engine/server reference
 
-This reference describes the public server contracts for coding agents.
+This reference gives application developers and coding agents the detailed
+server contracts. For an introduction and examples, start with the
+[server README](README.md).
 
 ## Testing entry point
 
@@ -40,14 +42,49 @@ consume Events, rejections, or Entity states and produce no signal. State
 subscribers use the System Event Bus. Produced signals are published in-process
 on a best-effort basis; this is not an exactly-once contract.
 
+## Entity constructor dependencies
+
+Supply `onCreate` when an Entity constructor needs an application service:
+`new Repository({ entityType, schema, onCreate })` for an explicit repository,
+or `.add(EntityClass, { onCreate })` when Spine creates the repository. The
+callback receives `EntityOptions` with the registered class's exact identifier
+and state-schema types. Its result must be an instance of that class.
+
+`onCreate` is required when the class cannot be constructed with framework
+options alone. It is optional for constructors that need only `EntityOptions`, or
+constructors whose additional parameters are optional or have defaults.
+
+For each new object, the callback must synchronously return a fresh instance
+and pass the supplied options unchanged to its constructor. Those options
+contain the ID, schema, state, Spine `Version`, and lifecycle flags. The same
+callback runs when restoring a stored Aggregate, Projection, or Process Manager,
+and when creating a Projection during a rebuild. It is not a once-per-ID hook.
+Queries that read stored state without constructing an Entity do not call it.
+
+Construct and initialize shared services before building the context. Keep
+network calls and other business work in handlers, not in `onCreate`. A thrown
+construction error fails that dispatch before its handler runs; it is not a
+domain rejection. An asynchronous callback or a result of the wrong class is
+rejected. Services are neither serialized nor closed by Spine; close them in
+application shutdown after closing the context.
+
+Spine still connects Entity history and Process Manager queries. A constructor
+callback does not receive the current actor or tenant. Pass these to a service
+from the handler when needed. Queries made through the Process Manager still
+use the handler's context. Services are passed directly; no dependency container
+is required, and the storage format is unchanged.
+
+See the [Entity dependency guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/USER_GUIDE.md#give-an-entity-an-application-service)
+and the [Projects example](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/projects/README.md).
+
 ## Integration broker and event origin
 
 Each `BoundedContext` creates and closes exactly one private integration broker.
 The broker has distinct status, configuration, and event exchanges. Event
 export is requested-only: a context installs a domestic publisher only for
 event types requested by another context, and withdrawal removes only that
-requester's interest. The broker does not enforce ownership; the supported
-shape is many consumers and one domain producer per event type at a time.
+requester's interest. Each event type should have one producing domain and may
+have many consumers; the broker does not enforce that producer restriction.
 
 The status exchange announces `BoundedContextOnline`; observing a foreign
 announcement resends the local complete wanted-event document. The
@@ -133,9 +170,9 @@ To override the default channel factory, add
 
 ## Routing lifecycle
 
-Event, command, and state-update routing accepts exact schemas and nominal
-message-interface tokens. It selects exact, first registered matching token,
-then replacement/default. The route runs once at accepted admission; its
+Event, command, and state-update routing accepts exact schemas and generated
+message-interface tokens. It selects an exact schema first, then the first
+matching token, then the replacement or default route. The route runs when the message is accepted; its
 validated typed targets are stored and reused for retries. The legacy-named
 local `catchUpReadSide()` helper is unrelated to retry: it resets and replays
 the whole local read side, and is not Projection catch-up.
@@ -253,6 +290,92 @@ rejection-input command reactions during generated metadata ingestion and
 repository construction.
 Event- and rejection-input `@Command` methods remain Event- or
 rejection-to-command reactions on Event Bus.
+
+### Handler return types
+
+Use a TypeScript union such as `CreateAccessGrant | ExtendAccessGrant` to return
+one of several Commands. A tuple such as
+`readonly [AccessGrantCreated, AccessRequestCompleted?]` returns multiple Events
+in order, with the second optional. Either declaration may have one outer
+`Promise` layer. Generated metadata lists every possible schema; runtime checks
+each result against the invoked handler's list. A whole result may be absent
+for `@React` and Event/rejection-input `@Command`, using a generated signal type
+unioned with `undefined`. A reaction that never emits can declare `undefined`
+alone or `Promise<undefined>`. Either reaction kind may also return an empty
+typed array. Command-input `@Command` and `@Assign` require nonempty results.
+`@Subscribe` declares `void` or `Promise<void>` and produces no signals.
+`@Throws` declares thrown rejections separately from normal results.
+
+Only subscriptions accept `void`. An absent reaction result or optional tuple
+entry uses `undefined`, never `null`. The framework validates all returned
+values before committing Entity changes or publishing outputs. An invalid
+subscription result fails even if it is an empty array. A valid no-output
+reaction still saves its Entity state changes.
+
+Other supported forms are `T[]`, `readonly T[]`, `Array<T>`, `ReadonlyArray<T>`,
+named tuple entries, union alternatives inside tuple entries, and local or
+imported aliases resolving to concrete generated messages. Only one flat
+collection level is supported. Rest tuples, nested collections, nested promises,
+custom thenables, framework envelopes, and unresolved/`any`/`unknown` result
+branches are rejected. TypeScript enforces tuple structure; the runtime checks
+declared message types, required nonempty results, and result order, not tuple
+arity or positional schema constraints. See the
+[user guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/USER_GUIDE.md#choose-what-a-handler-returns) for a compact
+return-type table and examples.
+
+These independent examples use generated review-workflow messages. The Commander
+chooses whether to start or schedule a review. The reactor example shows a
+different workflow: record a started review and optionally schedule a follow-up.
+They illustrate return declarations, not two handlers to register together.
+
+<!-- docs-snippet-path: packages/server/test/runtime/standalone-handler-runtime.test.ts -->
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import {
+  AbstractCommander,
+  AbstractEventReactor,
+  Command,
+  React,
+} from "@spine-event-engine/server";
+import {
+  StartReviewSchema,
+  ScheduleReviewSchema,
+  type StartReview,
+  type ScheduleReview,
+} from "../../test-fixtures/generated/handler-registry/commands_pb.js";
+import {
+  ReviewStartedSchema,
+  ReviewFollowUpScheduledSchema,
+  type ReviewStarted,
+  type ReviewFollowUpScheduled,
+  type ReviewTaskAssigned,
+} from "../../test-fixtures/generated/handler-registry/events_pb.js";
+
+export class ReviewCommander extends AbstractCommander {
+  @Command
+  planReview(event: ReviewTaskAssigned): StartReview | ScheduleReview {
+    // Return one Command, choosing its type using the application's rules.
+    return event.name === "Security review"
+      ? create(ScheduleReviewSchema, { id: event.id })
+      : create(StartReviewSchema, { id: event.id });
+  }
+}
+
+export class ReviewReactor extends AbstractEventReactor {
+  @React
+  recordReview(event: ReviewTaskAssigned): readonly [ReviewStarted, ReviewFollowUpScheduled?] {
+    const started = create(ReviewStartedSchema, { id: event.id });
+    // A tuple returns ordered Events. Its optional second value may be absent.
+    if (event.name !== "Security review") return [started];
+    return [
+      started,
+      create(ReviewFollowUpScheduledSchema, { id: event.id, name: "Security follow-up" }),
+    ];
+  }
+}
+```
+
 Produced commands retain the source actor, tenant, origin, and causal lineage.
 The enqueue is post-commit best effort, not an atomic outbox or exactly-once
 delivery: a process crash between commit and enqueue can lose a child. Accepted
@@ -299,11 +422,7 @@ import {
   type ProjectId,
 } from "../generated/spine/server/testing/project_workflow_pb.js";
 
-class ApprovalCoordinator extends ProcessManager<
-  ProjectId,
-  typeof CoordinationStateSchema,
-  number
-> {
+class ApprovalCoordinator extends ProcessManager<ProjectId, typeof CoordinationStateSchema> {
   @Command
   approve(command: ApproveProject, context: CommandContext): ScheduleProject {
     this.update((draft) => Object.assign(draft, { id: this.id, projectName: command.status }));
@@ -335,7 +454,7 @@ const registry: GeneratedHandlerRegistry = {
 };
 const [handlers] = new HandlerRegistryIngestor().ingest(registry);
 if (handlers === undefined) throw new Error("Generated Process Manager metadata is missing.");
-const repository = new Repository({
+const repository = new Repository<typeof ApprovalCoordinator>({
   entityType: ApprovalCoordinator,
   schema: CoordinationStateSchema,
   handlers: handlers as EntityHandlersMetadata<ApprovalCoordinator, typeof CoordinationStateSchema>,
@@ -395,7 +514,7 @@ the builder on the first build attempt.
 
 `SubscriptionService` streams are live best-effort notifications, not replay,
 ordering, or completeness contracts. A standalone Server defaults to the
-persistent registry. In a managed complete-replica cohort, the framework starts
+persistent registry. In a group of managed server replicas, the framework starts
 and closes each child Server and accepts only every context's actual
 `InMemorySubscriptionRegistry`; a persistent or custom registry is rejected
 and the assembled child is closed before READY. Durable logical bindings remain
@@ -453,7 +572,7 @@ record-storage handle, while the context closes the registry.
 
 `Entity` is the state base class. `Aggregate`, `Projection`, and
 `ProcessManager` identify the three entity families. Handler decorators are
-`@Assign`, `@Command`, `@React`, `@Subscribe`, and `@Apply`. A command-accepting
+`@Assign`, `@Command`, `@React`, and `@Subscribe`. A command-accepting
 handler uses `@Throws(GeneratedRejection)` to declare its possible domain
 rejections. Write the primary handler decorator first and `@Throws` immediately
 below it; declaration order does not affect behavior. Generated metadata records
@@ -464,6 +583,10 @@ handler, `update(mutator)` changes the active draft and returns the draft;
 `tryUpdate(mutator)` validates a scratch draft and returns violations without
 applying an invalid change. Entity lifecycle and version changes are committed
 only after the transaction accepts.
+Every Entity exposes the generated Spine `Version` message, starting at number
+zero. A dispatch that produces Events or changes state or lifecycle advances it
+once; no-op and rejected dispatches do not. Repositories restore and persist the
+full Version, including its timestamp, across current state, history, and Stand.
 
 ## Signals, validation, and rejection behavior
 
@@ -533,8 +656,8 @@ signal or explicit-close retry, and sets `process.exitCode` to `1` after a
 signal-driven failure.
 
 `ManagedServerApplication.run()` is the Node-only deployment entrypoint for a
-complete-replica process cohort when the framework handles process shutdown.
-`ManagedServerApplication.start()` starts the same cohort for an embedding host
+group of complete server replicas when the framework handles process shutdown.
+`ManagedServerApplication.start()` starts the same group for an embedding host
 and installs no process signal handlers; that host closes the returned handle.
 Both require a positive safe-integer
 `processCount` and an ESM `moduleUrl`; it never derives a process count from
@@ -566,7 +689,7 @@ admission.
 `ServerOptions` is native-only: it configures contexts, resources, services,
 and the native listener. It has no `browser` option and the root package does
 not load `@spine-event-engine/auth`. Browser hosting belongs to the explicit
-`@spine-event-engine/server/browser` entry point; see the [browser/auth guide](../../docs/BROWSER_CLIENT_AUTH_EXTENSION_GUIDE.md).
+`@spine-event-engine/server/browser` entry point; see the [browser/auth guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/BROWSER_CLIENT_AUTH_EXTENSION_GUIDE.md).
 
 Browser unary gateway admission has a fixed 1 MiB (1,048,576-byte) request
 limit. A larger unary gateway request is rejected with `ResourceExhausted`.
@@ -622,7 +745,7 @@ native backend. Concurrent calls share an attempt; a failed unfinished phase
 can be retried without repeating completed native cleanup.
 
 Browser subscription bindings are separate from service subscription records.
-`BrowserAdmission` selects their ownership. Authenticated mode supplies
+`BrowserAdmission` determines who configures and manages them. Authenticated mode supplies
 `sessions` and may supply `BrowserServerOptions.bindings`; production then
 requires `DurableSubscriptionBindings` from `@spine-event-engine/server/browser` and rejects a
 missing or in-memory binding store before listener open. Public mode supplies
@@ -641,7 +764,7 @@ inside the stored Topic and are checked for Activate and Cancel. Create assigns
 the public ID directly; no quota, reservation, fingerprint, or lease is
 persisted. Cleanup remains bounded and restart-safe at the record level. It
 cleans the backend definition before deleting its record. It is not a cleaner
-lease or fence: this direct store supports one Gateway process. Active streams do not resume,
+lock between Gateway processes: this store supports one Gateway process. Active streams do not resume,
 updates are not replayed, and the registry provides neither exactly-once
 delivery, global update ordering, nor cluster-complete notification delivery.
 
@@ -660,10 +783,10 @@ rows are direct records; a delivered row is the deduplication fact. A handler
 effect and the exact pending-to-delivered compare-and-set are not one
 transaction, so a lost acknowledgement can redeliver after restart. Downstream
 signal handling must be idempotent. A customized `DeliveryWorkRegistry`
-implements `validateOwnership()` so delivery can validate before dispatch, at
-repository commit time, and before acknowledgement. Validation is a fence
-against an observed takeover, not a distributed transaction with handler
-storage.
+implements `validateOwnership()` so delivery can validate before dispatch, before
+the Entity transaction commit, and before acknowledgement. These checks stop a worker
+after it detects that another worker has taken the shard. They do not make
+delivery and handler storage part of one distributed transaction.
 
 `keepUntil` is the optional deduplication-protection deadline, not a second
 retention setting. A delivered row is cleanup-eligible when that deadline is

package/dist/context/bounded-context.d.ts

@@ -118,10 +118,10 @@ export interface ContextDeliveryDescriptor {
      */
     onReady(onReady: OnDeliveryReady): () => void;
     /**
-     * Updates readiness ownership to use configured delivery routes.
+     * Routes readiness notifications through the configured delivery routes.
      *
      * @param scopes Lists routes that may receive buffered readiness.
-     * @param onReady Observes readiness after routed ownership begins.
+     * @param onReady Observes readiness after routing changes.
      * @param options Allows an empty route set when `allowEmpty` is true.
      * @returns A promise that resolves after the readiness transition completes.
      */
@@ -141,7 +141,7 @@ export interface CommandEndpoint {
      */
     acceptedCommandTypes(): readonly string[];
     /**
-     * Posts a command into the context-owned command bus.
+     * Posts a command to this context's command bus.
      *
      * @param command Contains the command to dispatch.
      * @returns A promise that settles after queued command dispatch completes and may reject.
@@ -159,7 +159,7 @@ export interface EventEndpoint {
      */
     acceptedEventTypes(): readonly string[];
     /**
-     * Posts an event into the context-owned event bus.
+     * Posts an event to this context's event bus.
      *
      * @param event Contains the event to dispatch.
      * @returns A promise that settles after persistence and dispatch complete and may reject.
@@ -218,24 +218,116 @@ interface FrameworkConstructionToken {
     readonly frameworkConstructionToken: true;
 }
 interface BoundedContextAccess {
+    /**
+     * Checks whether a value is a builder created by this module.
+     *
+     * @param value Value to check.
+     * @returns True for a registered builder.
+     */
     isBuilder(value: unknown): value is BoundedContextBuilder;
+    /**
+     * Builds a registered context builder with supplied default storage.
+     *
+     * @param builder Registered builder to build.
+     * @param defaultStorageFactory Storage used when the builder has none.
+     * @returns Promise resolving to a bounded context.
+     */
     build(builder: BoundedContextBuilder, defaultStorageFactory: StorageFactory): Promise<BoundedContext>;
+    /**
+     * Subscribes to a public event type on a built context.
+     *
+     * @param context Built context to observe.
+     * @param typeUrl Public event type URL.
+     * @param subscriber Event subscriber to register.
+     * @returns Cancellable event subscription.
+     */
     subscribeToEvent(context: BoundedContext, typeUrl: string, subscriber: EventSubscriber): EventSubscription;
+    /**
+     * Posts a framework System event through the context publisher.
+     *
+     * @param context Target bounded context.
+     * @param event System event to post.
+     * @returns Promise settling after publication.
+     */
     postSystemEvent(context: BoundedContext, event: Event): Promise<void>;
+    /**
+     * Marks a copied event as external and posts it through the context endpoint.
+     *
+     * @param context Target bounded context.
+     * @param event External event to post.
+     * @returns Event dispatch promise.
+     */
     postExternalEvent(context: BoundedContext, event: Event): Promise<void>;
+    /**
+     * Observes commands and events published by the context.
+     *
+     * @param context Context whose signals are observed.
+     * @param observer Callbacks for produced commands and events.
+     * @returns Handle whose close operation removes the observer.
+     */
     observeProducedSignals(context: BoundedContext, observer: {
         readonly onCommand?: (command: Readonly<Command>) => void;
         readonly onEvent?: (event: Readonly<Event>) => void;
     }): {
         readonly close: () => void;
     };
+    /**
+     * Returns a copy-safe snapshot of paired domain and System specifications.
+     *
+     * @param context Context whose pairing is read.
+     * @returns Paired specification snapshot.
+     */
     systemPairing(context: BoundedContext): SystemPairingSnapshot;
+    /**
+     * Returns the context tenant index.
+     *
+     * @param context Context whose index is read.
+     * @returns Tenant index for the built context.
+     */
     tenantIndex(context: BoundedContext): TenantIndex;
+    /**
+     * Returns the storage factory configured for a built context.
+     *
+     * @param context Context whose storage factory is read.
+     * @returns Configured storage factory.
+     */
     storageFactory(context: BoundedContext): StorageFactory;
+    /**
+     * Returns the context's Stand subscription registry.
+     *
+     * @param context Context whose registry is read.
+     * @returns Stand subscription registry.
+     */
     subscriptionRegistry(context: BoundedContext): StandSubscriptionRegistry;
+    /**
+     * Processes a registered Stand subscription and forwards each update.
+     *
+     * @param context Context containing the subscription.
+     * @param id Registered subscription ID.
+     * @param onUpdate Callback receiving updates.
+     * @returns Promise resolving to the subscription handle.
+     */
     consumeSubscription(context: BoundedContext, id: string, onUpdate: (update: import("@spine-event-engine/proto/client").SubscriptionUpdate) => void): Promise<import("../stand/stand.js").StandSubscription>;
+    /**
+     * Sets a logger on context buses and subscription runtime.
+     *
+     * @param context Context receiving the logger.
+     * @param logger Logging layer to install.
+     */
     installLogger(context: BoundedContext, logger: ILogLayer): void;
+    /**
+     * Returns the logger installed on a built context.
+     *
+     * @param context Context whose logger is read.
+     * @returns Installed logging layer.
+     */
     loggerFor(context: BoundedContext): ILogLayer;
+    /**
+     * Returns the delivery descriptor for a built context.
+     *
+     * @param context Context whose descriptor is read.
+     * @returns Delivery descriptor.
+     */
     delivery(context: BoundedContext): ContextDeliveryDescriptor;
 }
 /**
@@ -244,7 +336,7 @@ interface BoundedContextAccess {
 export declare class BoundedContext {
     #private;
     /**
-     * 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.
@@ -253,7 +345,7 @@ export declare 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.
@@ -306,19 +398,19 @@ export declare class BoundedContext {
      */
     get snapshot(): BoundedContextSnapshot;
     /**
-     * Returns the command endpoint owned by this context.
+     * Returns this context's command endpoint.
      *
      * @returns Returns the context command endpoint.
      */
     commandBus(): CommandEndpoint;
     /**
-     * Returns the event endpoint owned by this context.
+     * Returns this context's event endpoint.
      *
      * @returns Returns the context event endpoint.
      */
     eventBus(): 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.
      */
@@ -356,14 +448,14 @@ export declare class BoundedContext {
      */
     catchUpReadSide(options?: ReadCatchUpOptions): Promise<ReadCatchUpResult>;
     /**
-     * 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(): Promise<void>;
 }
@@ -372,18 +464,25 @@ export declare class BoundedContext {
  */
 export declare const boundedContextAccess: BoundedContextAccess;
 /**
- * Customizes a repository assembled from an Entity class and generated handlers.
+ * Configures routing and Entity construction for a generated repository.
+ *
+ * `onCreate` passes the framework's Entity options to an application constructor callback.
+ * It is required when the Entity class has additional required constructor arguments.
  *
- * @typeParam EntityType - The Entity class added to a Bounded Context builder.
+ * @typeParam EntityType The Entity class added to a Bounded Context builder.
  */
-export type GeneratedRepositoryOptions<EntityType extends RepositoryEntityType & ConcreteRepositoryEntityType<EntityType>> = Readonly<Pick<RepositoryOptions<EntityType>, "commandRouting" | "eventRouting" | "stateUpdateRouting" | "stringifierRegistry">>;
+export type GeneratedRepositoryOptions<EntityType extends RepositoryEntityType & ConcreteRepositoryEntityType<EntityType>> = Readonly<Pick<RepositoryOptions<EntityType>, "commandRouting" | "eventRouting" | "stateUpdateRouting" | "stringifierRegistry">> & (RepositoryOptions<EntityType> extends {
+    readonly onCreate: infer Callback;
+} ? {
+    readonly onCreate: Callback;
+} : Pick<RepositoryOptions<EntityType>, "onCreate">);
 /**
  * Assembles a {@link BoundedContext} from repositories and dispatchers.
  */
 export declare class BoundedContextBuilder {
     #private;
     /**
-     * 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.
@@ -416,6 +515,7 @@ export declare class BoundedContextBuilder {
     /**
      * Adds an explicitly assembled repository.
      *
+     * @typeParam EntityType Concrete Entity class represented by the repository.
      * @param entry The repository to register.
      * @returns This builder for further configuration.
      */
@@ -423,14 +523,19 @@ export declare class BoundedContextBuilder {
     /**
      * Adds an Entity class whose repository is assembled from generated handlers.
      *
+     * @typeParam EntityType Concrete Entity class represented by this entry.
      * @param entry The Entity class to register.
-     * @param options Optional custom routing and field mappings for its generated repository.
+     * @param options Routing and constructor callback for its generated repository. The callback
+     * is required when the Entity constructor needs additional application arguments.
      * @returns This builder for further configuration.
      */
-    add<EntityType extends RepositoryEntityType & ConcreteRepositoryEntityType<EntityType>>(entry: EntityType, options?: GeneratedRepositoryOptions<EntityType>): this;
+    add<EntityType extends RepositoryEntityType & ConcreteRepositoryEntityType<EntityType>>(entry: EntityType, ...options: GeneratedRepositoryOptions<EntityType> extends {
+        readonly onCreate: object;
+    } ? [options: GeneratedRepositoryOptions<EntityType>] : [options?: GeneratedRepositoryOptions<EntityType>]): this;
     /**
      * 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.
      */
@@ -504,7 +609,7 @@ export declare class BoundedContextBuilder {
      */
     withSubscriptionRegistry(registry: StandSubscriptionRegistry): 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.
@@ -534,6 +639,12 @@ export declare class BoundedContextBuilder {
      * @returns Resolves to the built context.
      */
     buildAsync(): Promise<BoundedContext>;
+    /**
+     * Creates the domain EventStore using this context's storage mode.
+     *
+     * @param storageFactory Storage provider for event records.
+     * @returns Domain EventStore.
+     */
     private createEventStore;
 }
 /**
@@ -542,7 +653,7 @@ export declare class BoundedContextBuilder {
 export declare class ContextSpec {
     #private;
     /**
-     * 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.