@spine-event-engine/server 2.0.0-snapshot.11

package/REFERENCE.md

@@ -0,0 +1,760 @@
+# @spine-event-engine/server reference
+
+This reference describes the public server contracts for coding agents.
+
+## Testing entry point
+
+`@spine-event-engine/server/testing` is for framework-package tests and controlled
+in-process fixtures. It exposes test reset and integration-frame helpers; managed-host
+internals remain repository-only fixture code. This entrypoint is deliberately outside
+the end-user root API and may change with test infrastructure rather than normal server
+compatibility guarantees.
+
+## Delivery SPI
+
+Delivery adapters import `conditionalPickUp` from
+`@spine-event-engine/server/spi/delivery`. It registers or looks up an optional
+conditional-pickup capability for a `DeliveryWorkRegistry`; it is not part of
+the server root API and does not independently create delivery work.
+
+## Generated handler-registry SPI
+
+Generated model modules import only their registry data types from
+`@spine-event-engine/server/spi/handler-registry`. The stable contract is the
+unversioned `GeneratedHandlerRegistry` receiver collection, receiver records,
+handler records, kinds, arity, and optional `where` data. The subpath has no
+runtime values. Server-side ingestion, validation errors, and their error codes
+are implementation details; generated code must not depend on them. Retired
+versioned registries are rejected and must be regenerated.
+
+## Standalone handlers
+
+Generated standalone handlers extend `AbstractAssignee`, `AbstractCommander`,
+`AbstractEventReactor`, or `AbstractEventSubscriber`. Register instances with
+`addAssignee()`, `addCommandDispatcher()`, or `addEventDispatcher()` as their
+role requires, then use `buildAsync()` to load generated receiver metadata and
+match the exact constructor. Assignees consume Commands and produce Events;
+commanders consume Commands, Events, or rejections and produce Commands;
+reactors consume Events or rejections and may produce Events; subscribers
+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.
+
+## 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.
+
+The status exchange announces `BoundedContextOnline`; observing a foreign
+announcement resends the local complete wanted-event document. The
+configuration exchange treats each `ExternalEventsWanted` as a complete
+replacement, installs producer publication on the first requester, avoids
+duplicate unchanged broadcasts, and removes publication after the last
+withdrawal. The event exchange uses one logical channel per event message type
+and retains the original Event ID and complete Event. Self-origin and paired
+domain/System Context messages are ignored.
+
+`External<T>` is exported as a transparent type alias (`type External<T> = T`)
+and has no runtime value or brand. The build-time handler analyzer recognizes
+the canonical server declaration only when it is the direct first receptor
+parameter. Missing markers mean `domestic`; a valid marker means `external`.
+External commands are rejected, while external event/rejection handlers and
+the supported state-subscription path are filtered by `EventContext.external`.
+Repository selection applies the filter per handler, including mixed-origin
+repositories. This is also the loop rule: domestic publication and origin
+filtering prevent self-origin and paired-context traffic; no hop count, origin
+ledger, Inbox, retry, replay, deduplication, cursor, fencing, or election is
+added.
+
+Incoming broker frames must contain a valid `ExternalMessage` wrapper and a
+complete `Event`. The server unpacks and validates the event, obtains the
+tenant from its explicit event origin, validates that tenant at the existing
+boundary, copies only `EventContext.external = true`, and posts the ordinary
+domain `EventBus`, whose admitted schemas are the destination's authority for
+incoming payload decoding. Unknown or malformed received payloads are logged safely,
+dropped, and do not stop the broker loop. Zero-byte control messages are valid
+where the Proto contract permits an empty payload.
+
+Malformed, unknown-schema, or undecodable received events emit the fixed ERROR
+message `Dropped corrupt external event.` with safe `contextName`, `eventType`,
+`operation: external-event-intake`, and
+`reasonCode: corrupt_external_event`; the callback resolves, the event is
+dropped, and later valid events continue. Application intake failures after a
+valid decode remain observable.
+
+Context readiness includes broker open. Close gates new EventBus intake before
+awaiting transport work, broadcasts an empty wanted document, detaches domestic
+publishers and external subscribers, drains accepted work, and closes acquired
+channels. Failed cleanup remains retryable and concurrent close callers share
+one attempt.
+
+`ThirdPartyContext` is the sole public third-party import API. Its
+`singleTenant()` form forbids an actor tenant; `multitenant()` requires one.
+`emittedEvent(event, actor)` accepts a registered generated Protobuf message used as an event
+payload and `ActorContext` (or a
+`UserId` in the single-tenant form), preserves actor identity and timestamp,
+and publishes through its hidden context. An unknown local schema throws; a
+valid event with no interested external receptor is simply not delivered.
+
+## Server environment facilities
+
+`ServerEnvironment.instance()` is a process-wide singleton. Production
+resolution requires storage and the complete application schema registry:
+
+```ts
+import { EnvironmentType, ServerEnvironment } from "@spine-event-engine/server";
+import type { TypeRegistryLookup } from "@spine-event-engine/core";
+import type { StorageFactory } from "@spine-event-engine/storage";
+
+declare const storageFactory: StorageFactory;
+declare const typeRegistry: TypeRegistryLookup;
+
+ServerEnvironment.when(EnvironmentType.Production).use({
+  storageFactory,
+  typeRegistry,
+});
+```
+
+`storageFactory` supplies records and events. `typeRegistry` is the complete
+application schema universe used by `ThirdPartyContext` to encode outgoing
+imported events. An optional `integrationChannelFactory` overrides the
+process-wide private
+integration message channel factory. When it is absent, all local bounded
+contexts share one in-memory factory, including in production. Local and test
+environments default storage in memory and use the core registry only as a
+fallback; those defaults are not production configuration.
+
+To override the default channel factory, add
+`integrationChannelFactory: customFactory` to the same settings object.
+
+## 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
+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.
+
+## Message-valued Entity IDs
+
+The first state field determines the Entity ID type. It can be a primitive or
+a generated Protobuf message; for a message ID, all declared fields form the
+identifier. Nested and composite IDs are supported.
+
+```proto
+message ShipmentId {
+  spine.core.UserId owner = 1;
+  int32 number = 2;
+}
+
+message Shipment {
+  ShipmentId id = 1;
+  string status = 2;
+}
+```
+
+The root `MessageId` type accepts generated messages such as `CommandId`:
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { type MessageId } from "@spine-event-engine/server";
+import { CommandIdSchema } from "@spine-event-engine/proto";
+
+const id: MessageId = create(CommandIdSchema, { uuid: "shipment-7" });
+```
+
+Admission validates a message ID against the schema declared by the state
+field, including generated validation rules, before it is stored or replayed.
+When default routing finds a message but the Entity ID type is primitive, a
+custom route returns the intended primitive ID.
+
+Without a custom route, Command routing uses the Command's declared first
+field. Event routing uses a compatible producer ID when available and otherwise
+uses the Event's declared first field. State-update routing selects the first
+state field compatible with the Entity ID.
+
+## Handler routing and operations
+
+Generated handler metadata routes a command, event, or state update by its
+exact generated message type. A declared default route is considered only when
+there is no exact route. This is TypeScript routing; it does not consume
+`(is).java_type` or `(every_is).java_type`, and it has no decorator-based
+route registration API.
+
+Handlers may return their established result directly or through exactly one built-in `Promise<T>`.
+Nested promises and structural or imported thenable lookalikes are rejected during handler analysis.
+The entity transaction remains open until that promise settles; rejection rolls
+back framework state and suppresses produced output, but cannot undo external
+side effects. Process Managers may use their protected read-only query surface
+for eventually consistent projection state during a handler. Aggregates must
+not use projection reads for invariants.
+
+`select(schema, columns)` supports `byId`, typed `where`, `mask`, `orderBy`,
+`limit`, `read`, `findById`, and `all`. A Process Manager query returns at most
+1,000 states. `all()` is a convenience and can be costly on a large Projection;
+prefer an ID-targeted or ordered bounded query.
+
+Use `EntityQuery.all(...)` to require every predicate and `EntityQuery.either(...)`
+to accept any branch. Query execution inherits the active handler's actor and
+tenant; the protected read-only facade has no tenant override.
+
+```ts
+import type { Message } from "@bufbuild/protobuf";
+import type { GenMessage } from "@bufbuild/protobuf/codegenv2";
+import { EntityQuery, type EntityColumn } from "@spine-event-engine/core";
+import { ProcessManager } from "@spine-event-engine/server";
+
+type RequestView = Message<"RequestView"> & {
+  id: string;
+  status: string;
+  createdAt: number;
+};
+
+declare const RequestViewSchema: GenMessage<RequestView>;
+declare const RequestViewColumns: {
+  readonly status: EntityColumn<typeof RequestViewSchema, "status", string, "equal">;
+  readonly createdAt: EntityColumn<
+    typeof RequestViewSchema,
+    "createdAt",
+    number,
+    "equal" | "greaterThan"
+  >;
+};
+
+abstract class RequestCoordinator extends ProcessManager<string, typeof RequestViewSchema> {
+  protected async pendingRequests(requestId: string): Promise<void> {
+    const matching = await this.select(RequestViewSchema, RequestViewColumns)
+      .where(EntityQuery.eq(RequestViewColumns.status, "pending"))
+      .orderBy(RequestViewColumns.createdAt, "asc")
+      .limit(10)
+      .read();
+    const one = await this.select(RequestViewSchema, RequestViewColumns).findById(requestId);
+    const everyVisible = await this.select(RequestViewSchema, RequestViewColumns).all();
+    void [matching, one, everyVisible];
+  }
+}
+```
+
+`all()` remains capped at 1,000 states but may still be costly; use `findById()`
+or an ordered bounded `read()` where possible.
+
+A command-input `@Command` method is a command substitution receptor: it is
+the one effective receptor for that Command type (instead of an `@Assign`),
+commits its Entity state before its one-or-more returned Commands are detached
+for in-process produced-command enqueue, and receives an optional `CommandContext`.
+Only Process Manager repositories support `@Command` handlers. Aggregate and
+Projection repositories reject command-input substitutions and event- or
+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.
+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
+produced commands drain during context close. A contained child failure is diagnosed,
+but does not retroactively fail an already accepted source command or durably
+retry that child.
+
+For a generated Process Manager, a command-input handler uses distinct domain
+Command input and output types, and the generated registry supplies those
+schemas. This self-contained example explicitly ingests the unversioned data that an
+application build normally emits, then assembles a repository from it; it does
+not claim that its fixture discovers a registry artifact automatically:
+
+<!-- docs-snippet-path: packages/server-blackbox-tests/test/project-event-routing.test.ts -->
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { SignalEnvelopes } from "@spine-event-engine/core";
+import {
+  CommandContextSchema,
+  CommandIdSchema,
+  type CommandContext,
+} from "@spine-event-engine/proto";
+import {
+  BoundedContext,
+  Command,
+  type EntityHandlersMetadata,
+  HandlerRegistryIngestor,
+  ProcessManager,
+  Repository,
+} from "@spine-event-engine/server";
+import type { GeneratedHandlerRegistry } from "@spine-event-engine/server/spi/handler-registry";
+
+import {
+  ApproveProjectSchema,
+  ScheduleProjectSchema,
+  type ApproveProject,
+  type ScheduleProject,
+} from "../generated/spine/server/testing/project_commands_pb.js";
+import {
+  CoordinationStateSchema,
+  OrganizationIdSchema,
+  ProjectIdSchema,
+  type ProjectId,
+} from "../generated/spine/server/testing/project_workflow_pb.js";
+
+class ApprovalCoordinator extends ProcessManager<
+  ProjectId,
+  typeof CoordinationStateSchema,
+  number
+> {
+  @Command
+  approve(command: ApproveProject, context: CommandContext): ScheduleProject {
+    this.update((draft) => Object.assign(draft, { id: this.id, projectName: command.status }));
+    return create(ScheduleProjectSchema, { project: command.project, status: command.status });
+  }
+}
+
+const project = create(ProjectIdSchema, {
+  organization: create(OrganizationIdSchema, { code: "org-a" }),
+  number: 1,
+});
+const registry: GeneratedHandlerRegistry = {
+  receivers: [
+    {
+      receiverKind: "entity",
+      receiverType: ApprovalCoordinator,
+      stateSchema: CoordinationStateSchema,
+      handlers: [
+        {
+          kind: "command-substitution",
+          methodName: "approve",
+          input: { schema: ApproveProjectSchema, origin: "domestic" },
+          outcomes: { returned: [ScheduleProjectSchema], thrown: [] },
+          parameterCount: 2,
+        },
+      ],
+    },
+  ],
+};
+const [handlers] = new HandlerRegistryIngestor().ingest(registry);
+if (handlers === undefined) throw new Error("Generated Process Manager metadata is missing.");
+const repository = new Repository({
+  entityType: ApprovalCoordinator,
+  schema: CoordinationStateSchema,
+  handlers: handlers as EntityHandlersMetadata<ApprovalCoordinator, typeof CoordinationStateSchema>,
+});
+const context = BoundedContext.singleTenant("Projects").add(repository).build();
+await context.commandBus().post(
+  SignalEnvelopes.command({
+    context: create(CommandContextSchema),
+    schema: ApproveProjectSchema,
+    message: create(ApproveProjectSchema, { project, status: "approved" }),
+  }),
+);
+```
+
+The generated record declares `ApproveProjectSchema` as the input and
+`ScheduleProjectSchema` as the emitted Command schema; registry ingestion, not
+manual decorator materialization, constructs the output-bearing metadata.
+Application builds emit the record to
+`generated/handler/generated-handler-registry.js`; those applications use
+`buildAsync()` with their compiled package root.
+
+One `@Where({ eventField, equals })` equality filter may narrow an event- or
+rejection-consuming `@Subscribe`, `@React`, or `@Command` handler after type
+routing. `eventField` and `equals` are typed string literals; invalid or
+repeated declarations fail closed. It is not an alternative routing mechanism.
+
+Configure logging through `ServerEnvironment` when assembling the server. The
+server installs that logger into its runtime components, where warnings and
+failures carry operation context. Durable facts belong in events or storage.
+Entity Inbox replay sends persisted accepted work through the normal handler
+path, so handler effects must be replay-safe.
+
+## Context assembly and entities
+
+Create a context with `BoundedContext.singleTenant(name)` or
+`BoundedContext.multitenant(name)`. Names are immutable. Use
+`withStorageFactory(factory)` to supply record/event storage.
+`withGeneratedRegistryRoot(root)` enables framework discovery of the generated
+handler registry for classes registered with `add(EntityClass)`;
+`buildAsync()` performs that discovery and assembly. `build()` remains for
+explicit `Repository` registration. A built context contains `CommandBus`,
+`EventBus`, `Stand`, repositories, and its storage lifecycle.
+
+Generated writer output is an unversioned receiver collection and records
+command substitutions explicitly. The ingestor rejects retired versioned
+registry shapes with an instruction to regenerate.
+
+### Stand subscription registry
+
+Each built context also has one `StandSubscriptionRegistry`. By default the
+builder creates a storage-backed registry from the resolved context
+`StorageFactory` (including the `ServerEnvironment` factory used for a builder
+added to a server). It stores one `spine.client.SubscriptionRecord` under each
+explicit `SubscriptionId`. A complete custom implementation can instead be
+supplied with `withSubscriptionRegistry(registry)`; responsibility transfers to
+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
+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
+Gateway-only. The Coordinator fans each logical definition to ready children,
+merges updates, propagates cancellation, and carries no subscription payload on
+parent/child IPC. A late or replacement child synchronizes retained definitions
+before it is eligible for normal requests. Active definitions attach their
+child streams before admission; subscribed but inactive definitions do not
+block readiness. Each child observes application-configured remote/shared
+Delivery directly. During DRAINING, new unary and shard admission stops while
+active Delivery and its subscription updates finish before child close. The
+application configures the Delivery facility and selects the shard strategy;
+managed mode does not infer or certify configuration provenance.
+
+Create records begin `pending` and expire after 30 seconds unless activated.
+Active records have no framework TTL. Cancellation physically deletes the
+definition; no tombstone remains. A stored definition is at most 1 MiB
+(1,048,576 bytes). Its physical provider columns are `status` and
+`when_activation_expires`. `cleanup()` asks the provider for 26 pending rows
+ordered by `when_activation_expires` then ID, validates that finite result,
+deletes at most 25 expired definitions, and reports `more` only when its
+observed 26th row is expired. Cleanup can run idempotently on every node.
+
+Context close drains and closes Stand before its registry, then closes tenant,
+repository, and storage resources; it attempts every close and reports
+aggregate failures. An in-memory registry reports `persistent === false`.
+Attaching such a context to a production `ServerEnvironment` emits one
+context-name-only warning without failing startup; Local environments do not
+warn.
+
+Creation writes the pending record only when that ID is absent. Activation
+replaces that pending record only when it remains unchanged. Cancellation and
+expiry cleanup delete the observed record only when it remains unchanged. Each
+node reconciles its local snapshot immediately after context assembly and then
+every ten seconds. Physical deletion detaches the local observer after its next
+completed cycle. This is best-effort per-node convergence, not a
+cluster-completeness, replay, ordering, gap-repair, or exactly-once guarantee.
+
+The registry accepts only a generated `SubscriptionId` for activate, get, and
+delete. `create(subscription)` returns `{ kind: "created", entry }` or
+`{ kind: "existing", entry }`; the latter requires byte-equivalent canonical
+content and a different definition with the same ID throws `StandConflictError`.
+`activate(id)` returns `activated`, `active`, `missing`, or `expired`.
+`delete(id)` returns `deleted` or `missing`. Blank IDs or topics and malformed
+durable records fail closed.
+
+Entries and nested subscriptions returned by create, activate, get, and
+snapshot are clone-safe views. Protobuf byte arrays remain mutable runtime
+views but are cloned so they never alias caller storage. Snapshots are ordered
+by identifier. A durable provider must implement atomic compare-and-set for
+`SubscriptionRecord`; construction rejects a provider that cannot. MySQL table
+configuration and Datastore custom record storage registered for
+`SubscriptionRecord` are used by the registry. The registry uses one
+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
+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
+normal and rejection outcomes before context assembly, so clients may subscribe
+to a declared rejection even when no server handler consumes it. Throwing an
+undeclared generated rejection is a technical handler failure. In a transactional
+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.
+
+## Signals, validation, and rejection behavior
+
+`CommandBus` validates every accepted command from Proto validation options
+before dispatcher or repository handler code runs. It raises the framework's
+command-validation failure, which `SpineServices` maps to
+`COMMAND_VALIDATION_ERROR` with a packed `spine.validation.ValidationError`.
+Entity transition validation failures map to
+`COMMAND_STATE_TRANSITION_VALIDATION_FAILED` with the same detail type.
+Framework-created runtime command and event metadata uses fresh Node secure
+UUIDs; fixed IDs belong only to existing source envelopes retained through the
+normal origin chain.
+
+An application handler throws a generated core `RejectionThrowable` for a
+domain rejection declared with `@Throws`. The repository rolls back state,
+version, lifecycle, and output; it schedules the typed rejection event independently. Command service
+acknowledgement remains an accepted `Ack`. Rejection-event posting can be
+unobserved by inactive, full, or closed subscriptions and a posting failure is
+an internal diagnostic, not a retry guarantee.
+
+Every domain context has an internal paired System Context. Domain events use
+the domain `EventBus` and domain `EventStore`. System events use only the
+System Context `EventBus`, so they never enter the domain EventStore. System
+event persistence is optional: `persistSystemEvents()` enables the paired
+System Context's separate storage; otherwise the bus validates, dispatches,
+and notifies without appending. Schemas may come from an external dispatcher or
+a registered internal repository producer. A producer-only schema is not
+thereby an external dispatch route.
+
+## Services, reads, and lifecycle
+
+`SpineServices({ contexts }).register(router)` registers the JVM-compatible
+CommandService, QueryService, and SubscriptionService contracts. `Server`
+opens the local Node HTTP/2 listener; default host is `127.0.0.1`. Set
+`readMaxBytes` and `writeMaxBytes` only to integers 1–4294967295; defaults are 4194304. `RunningServer.close()` stops intake, closes sessions, waits for active
+work to stop using dependencies, then closes contexts. Caller-managed `start()`
+does not close global process facilities; close `ServerEnvironment.instance()`
+separately when used. The final run-managed `run()` close closes its environment.
+
+`Stand` registers entity state for point/list reads, updates current state, and
+offers in-process subscriptions. The legacy-named local reset/replay helper
+`catchUpReadSide(options?)` clears every registered Projection state and replays
+the whole stored event history through matching Projection subscribers; it does
+not append events. Single-tenant contexts reject a tenant option; multitenant
+contexts require one. It cannot target a Projection repository, entity IDs, or
+a starting time, and has no durable operation identity, progress, Inbox
+catch-up delivery, restart, resumption, or historical/live coordination. It is
+not JVM-equivalent Projection catch-up.
+
+Active subscription streams and queues are process-local. `Stand` serves
+authoritative queries from current state and Entity subscriptions observe
+committed `EntityStateChanged` messages on the paired System Context EventBus,
+so a direct Stand write alone does not produce a subscription update. Consumer
+callback failures are isolated from post-commit observation and other
+consumers. The package does not guarantee cluster-complete observations,
+subscription replay, event-gap repair, or exactly-once effects.
+
+### Native and managed hosting
+
+`Server.start()` installs no process signal handlers, never closes its
+environment, and shares only a caller-managed active generation. `Server.run()`
+coalesces concurrent calls on one builder, shares a run-managed generation with
+other `run()` servers, and rejects mixed admission before listener open. The
+coordinator uses one `SIGINT`/`SIGTERM` listener pair, closes servers in reverse
+successful-start order, retains failed final environment closure for later
+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
+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
+the machine. Its optional `host` and required nonzero `port` bind the public
+Coordinator listener. Every child executes that same module and calls the
+module's `createServer({ host: "127.0.0.1", port: 0 })`. The child reports its
+actual loopback endpoint only after its local readiness gates settle. The parent
+initially waits until every configured child is ready. Afterwards it is ready
+while at least one child is ready; it remains alive and keeps replacing while
+degraded, and reports unready if no child is ready. It replaces an unexpected
+child exit after a bounded exponential delay (250 ms initially, capped at 30 s;
+reset after 60 s READY). It does not restart a child being closed. Restart
+values are optional `restart` settings and must be positive safe integers;
+concurrent starts default to `min(4, processCount)`. `run()` parent `SIGINT`
+and `SIGTERM` use the same shared child-close path; `start()` leaves those
+signals to its caller. This private lifecycle channel
+does not transport application signals. The Coordinator forwards generated
+Command and Query unary calls once to a READY child; process count does not
+inspect CPU availability and does not constrain the application's independently
+chosen `DeliveryStrategy` or shard count. Direct `Server.run()` and browser
+hosting remain independent of managed Node deployment.
+
+If no child is READY, Command and Query return gRPC `UNAVAILABLE`. The
+Coordinator does not enter application intake and does not retry the selected
+call on a sibling child. Subscription fan-out follows current READY members;
+later and replacement members attach the retained subscription before managed
+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).
+
+Browser unary gateway admission has a fixed 1 MiB (1,048,576-byte) request
+limit. A larger unary gateway request is rejected with `ResourceExhausted`.
+This is an additional boundary: `readMaxBytes` still limits the Connect or
+gRPC-Web transport message accepted by the public listener, so the effective
+inbound limit is the stricter applicable limit. `writeMaxBytes` limits public
+transport responses independently.
+
+For `BrowserServer` from `@spine-event-engine/server/browser`, origins must be unique canonical HTTP(S) origins with no path, query,
+fragment, or trailing slash. Requests without an allowed exact `Origin` receive
+403 before RPC handling. Allowed responses include credentialed exact-origin
+CORS, `Vary: Origin`, protocol request headers, and exposed gRPC status headers.
+
+Supplying `browser.backend.baseUrl` selects standalone mode. It is one canonical
+HTTP(S) origin for a Spine TS or JVM backend; the gateway never closes
+that backend. Every standalone mode, including local development and tests,
+requires explicit subscription bindings; production additionally requires an
+application type registry and named durable bindings. `ResolveContext` stays in the gateway;
+Post, Read, Subscribe, Activate, and Cancel use the same authenticated policy,
+context-replacement, and native descriptors before reaching the backend.
+
+`browser.backend.baseUrls` is exclusive with `baseUrl` and configures a
+non-empty ordered unique static node set. Unary calls use bounded round-robin
+without retry; native streams fan out best-effort. Durable bindings retain only
+logical definitions, not topology. Clients
+re-query authoritative state after duplicate updates or generic loss notices.
+
+`browser.authRoutes` is deliberately a bounded callback seam, not a router.
+Each registration has one exact `GET` or `POST` canonical path, one method per
+path, exact canonical origins, finite request bytes, and a finite timeout. A
+missing Origin is rejected unless that route explicitly permits it for an OAuth
+callback. Unknown paths, method/origin failures, body overflow, timeout, and
+handler failure return fixed 404, 405, 403, 413, 504, and 500 responses without
+calling application code on rejected input. The 404 unknown-path result applies
+only after framework Origin admission. Auth admission is bounded to 64 active
+requests by default or a configured positive `maxActiveAuthRequests`; excess
+requests receive 503 before handler invocation and capacity returns when work
+settles. The route deadline covers body intake, handler work, and response
+transfer. Response bodies use `writeMaxBytes`; overflow returns 413 before any
+application status or headers are committed. Listener close ultimately aborts
+an active request through its disconnect signal.
+
+With `cookies`, `OpaqueSessionCookies` performs strict bearer-first or
+CSRF-protected cookie extraction. A strict rejection becomes an unusable
+credential and never falls back to permissive header parsing. Without cookies,
+the host accepts exactly one non-whitespace bearer token. Credentials and raw
+transport metadata do not reach the private backend. The application-supplied
+context resolver replaces caller actor and tenant facts before forwarding.
+
+Browser close stops new listener intake, closes subscription admission and
+bindings so active streams settle, awaits listener closure, then closes the
+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
+`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
+`publicAccess: true`, cannot supply bindings, and uses process-local bindings
+managed by the framework. The durable registry receives an explicit application
+namespace, storage factory, identifier source, and cleanup callback. It closes
+only its independently opened record-storage handle, not the application
+storage factory or a Spine JVM/TS backend. It stores canonical public
+Subscription definitions, never backend envelopes or membership topology, and
+never returns private native data through public subscription responses.
+
+The durable registry preserves one approved `GatewayAuthenticatedSubscription`
+per public subscription through a process restart. It validates the record ID,
+full Subscription, and expiry before use. The trusted Actor and Tenant remain
+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,
+updates are not replayed, and the registry provides neither exactly-once
+delivery, global update ordering, nor cluster-complete notification delivery.
+
+## Delivery and environment
+
+`Inbox`, `InboxStorage`, `ShardIndex`, and `ShardedWorkRegistry` provide the
+local durable-row abstraction. Read limits are 1–1000; work leases are
+1000–2147483647 ms. Framework replay supports command handling, projection
+updates, and process-manager reactions. Callbacks are at-least-once/replay-safe:
+lost renewal can prevent stale finalization but cannot undo a callback already
+run. The package exposes no general raw worker callback API.
+
+Shard ownership is the only delivery exclusion mechanism and excludes
+concurrent delivery within that shard. Pending and delivered `InboxMessage`
+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.
+
+`keepUntil` is the optional deduplication-protection deadline, not a second
+retention setting. A delivered row is cleanup-eligible when that deadline is
+absent or elapsed. Under current shard ownership, environment delivery performs
+one bounded cleanup page, plus at most one continuation after a full protected
+page makes no removal. Direct local storage atomically verifies ownership and
+the exact delivered snapshot during removal. A remote adapter may instead read
+and compare the snapshot before sending a separate best-effort removal request;
+that sequence is not an atomic compare-and-delete guarantee. Pending, retryable,
+non-delivered, and still-protected rows remain. There is no additional retention
+configuration, timer, or scheduler.
+
+`BoundedContextBuilder.withDeliveryStrategy(strategy)` snapshots a validated
+immutable strategy for its Entity Inbox; the default is one shard. For example,
+use the public builder chain:
+
+```ts
+import { BoundedContext, UniformAcrossAllShards } from "@spine-event-engine/server";
+
+const context = BoundedContext.singleTenant("Tasks")
+  .withDeliveryStrategy(UniformAcrossAllShards.forNumber(3))
+  .build();
+```
+
+Aggregate commands and Process Manager commands/events derive their target shard
+internally and persist their envelope in the target Entity Inbox before any
+handler runs. Delivery is never a post-request callback: local and remote
+handler runs. Local intake can directly drain the persisted Inbox in the
+current request path. Attached `ServerEnvironment` ports acknowledge admission
+and delivery workers replay it through the same path. Projection rows remain
+separate.
+
+`DeliveryBuilder` constructs a controlled `Delivery`; `DeliverySupervisor`
+receives `{ source, delivery, onMessage }`, manages bounded shard notifications
+from that structural source, and must start after endpoints are ready and close
+before source client/storage. `DeliverySource` is not configured on
+`DeliveryBuilder`. The supervisor does not promise
+durable supervisor state, topology failover, exactly-once effects, or automatic
+retry of unknown remote mutations.
+
+Each Inbox read is bounded to one page. That bound does not limit the total
+pending work: an active drain can advance to another page while it retains the
+shard. Delivery compares pending rows with delivered rows in the current page
+and a process-local cache of the 1,000 most recent deliveries, then removes
+duplicates. The 30-second Inbox deduplication window controls how long delivered
+rows remain available as duplicate evidence; it is not a replay-retention
+period. Persisted accepted rows follow their delivery lifecycle and may be
+replayed according to that lifecycle after the deduplication window has elapsed.
+
+`DeliveryMonitor` is an instantiable, customizable policy seam exposing
+asynchronous continuation, start/completion, failed-reception, pickup-failure,
+and already-picked hooks.
+`FailedReception` supplies only `markDelivered()` and one immediate
+`repeatDispatching()` action; the framework adds no attempt history, timer,
+backoff, quarantine, dead-letter, receipt, marker, or scheduler policy. A failed
+durable acknowledgement keeps that row pending, blocks later rows for its
+target during the run, and does not prevent independent targets from running.
+
+`Environment` resolves the Node `local` or `production` profile once from
+`NODE_ENV`. `ServerEnvironment` resolves configured facilities once for that
+profile and exposes its `storageFactory`, optional `delivery`, optional
+`tracerFactory`, `nodeId`, and `close()` lifecycle. Applications do
+not manage internal server attachments through this public API. Neither API
+authenticates requests or supplies a production scheduler, remote topology,
+storage adapter, or deployment policy.
+
+`ServerEnvironmentDelivery` extends the existing closeable facility shape with
+`open()` plus generic `inbox` and `workRegistry` ports. After readiness, the
+environment supplies those ports to both existing delivery paths: direct finite
+`Delivery` construction and the supervisor's `DeliveryBuilder`. The environment
+invokes `open()` once before attachment admission and coalesces concurrent
+callers; rejection admits no attachment and a later attempt retries open. A
+close-only local delivery remains source-compatible. After attachments retire,
+environment close runs delivery, tracer, then storage and preserves retry
+checkpoints for failed phases.
+
+`ServerEnvironmentDelivery.source` is optional. When present, its Admin source
+is used by the environment supervisor for remote snapshots and
+shard-update hints; when absent, the existing local source remains the fallback.
+Applications configure and close only the delivery facility through the
+environment: attachment supervisors and their source reads belong to that facility.
+
+## Signal identity and Aggregate semantics
+
+Projection handlers cannot use `@Assign`; explicit metadata rejects that unsupported
+handler shape. Framework-created child Commands and Events receive fresh IDs. Existing
+Command or Event envelopes retain their IDs through transport and storage, including
+when returned or passed as envelopes. Aggregate domain Events use the loaded pre-dispatch
+version, while persisted Aggregate state advances to the next version. History caching accepts descending retained
+versions with gaps, while continuing to reject equal or newer continuations.
+
+# Dynamic unary discovery
+
+`BrowserServerOptions.discovery` from `@spine-event-engine/server/browser` may supply changing complete application-node snapshots alongside fixed `backend` configuration. Both unary routing and native subscription streams use the same current membership. Empty membership retains durable definitions and later nodes reactivate them; a new backend-dependent subscription is unavailable until a node exists.