@spine-event-engine/server 2.0.0-snapshot.2 → 2.0.0-snapshot.20

package/REFERENCE.md

@@ -1,6 +1,81 @@
 # @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
+
+`@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.
+
+## 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
 
@@ -8,8 +83,8 @@ 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
@@ -95,13 +170,64 @@ 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
-validated typed targets are stored and reused for retries. The legacy-named
+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. Route callbacks may
+return a value or a Promise. `CommandRouting.create(EntityClass)`,
+`EventRouting.create(EntityClass)`, and `StateUpdateRouting.create(ProjectionClass)`
+infer the receiving ID, state, and application Entity types. The selected class
+must be the same constructor registered by the repository;
+construction rejects a mismatch even when two classes share ID and state types.
+The callback's third argument exposes `findIds(query)`, `findStates(query)`, and `find(query)`
+for that repository in the signal's tenant. The read access rejects new calls
+after the route finishes. ID-only `create<Id>()` declarations remain valid.
+Direct `repository.routeCommand()` and `repository.routeEvent()` calls return
+Promises and must be awaited. Commands select exactly one ID; Events and state
+updates may select any number of distinct IDs. After validation and stable
+deduplication, routes above 1,000 recipients emit one warning and retain every
+recipient. Inbox replay uses stored target IDs without rerouting. 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
@@ -110,6 +236,291 @@ 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 Entity state during a handler. Aggregates must not
+use these reads for invariants.
+
+`select(schema, columns)` supports `byId`, typed `where`, `orderBy`,
+`limit`, `read`, `findById`, and `all`. A Process Manager query returns at most
+1,000 states and accepts at most 1,000 explicit IDs at execution. A generated
+`StateQuery.create()...build()` value also works with `this.select(query).read()`; its read
+binds the current handler actor and tenant. `all()` is a convenience and can be costly on a large read model;
+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
+effective tenant; the protected read-only facade has no tenant override.
+
+`RepositoryReadQueries<EntityType>` describes the receiving repository's typed
+`findIds`, `findStates`, and `find` reads. A read returns all matches unless the
+shared generated query sets a limit. States are detached messages; `find`
+restores application Entity instances with stored Version and lifecycle flags.
+The framework binds each read scope to the incoming signal tenant. Routing
+callbacks receive that scope as their third argument while they run.
+
+For contexts registered with one `Server`, the target Entity's type URL selects
+its context. No context name or network request is required. The Server rejects
+duplicate Entity type registrations before starting delivery recovery or
+listening, identifying the type and both contexts. Contexts used without a
+Server retain local querying; separate Servers do not share query routes.
+
+Cross-context targets must declare `query` or `full` visibility. This applies
+to any Entity family with queryable state. Unknown targets, foreign targets
+without query visibility, and tenant mismatches produce errors before storage
+reads. Existing local and public-query visibility behavior is unchanged.
+
+Single-tenant execution resolves to the built-in `SINGLE_TENANT` identity;
+omitting the wire tenant field does not create tenant-free execution. Named
+tenants can query their corresponding multitenant partition, not a single-tenant
+destination. `SINGLE_TENANT` can query a single-tenant destination or its same
+partition in a multitenant destination. The query never replaces the tenant to
+suit the target. A valid query with no matching record keeps its ordinary empty
+result (`undefined` from `findById()`). Reads remain eventually consistent.
+
+Routes are available before recovered handlers execute. Server shutdown drains
+accepted handlers across contexts before closing any target read-side; failed
+startup validation participates in context and resource cleanup.
+
+```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.
+
+### 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
+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> {
+  @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<typeof ApprovalCoordinator>({
+  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
@@ -132,6 +543,10 @@ handler registry for classes registered with `add(EntityClass)`;
 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
@@ -144,8 +559,8 @@ 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 owns
-each child Server and accepts only every context's actual
+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
 Gateway-only. The Coordinator fans each logical definition to ready children,
@@ -156,8 +571,8 @@ 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 owns Delivery facility and shard-strategy selection; managed mode
-does not infer or certify configuration provenance.
+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
@@ -202,11 +617,21 @@ 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`. In a transactional
+`@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
+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.
+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
 
@@ -216,10 +641,13 @@ 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. The repository rolls back state, version, lifecycle, and
-output; it schedules the typed rejection event independently. Command service
+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.
@@ -261,7 +689,7 @@ 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.
 
-### Standalone and browser hosting
+### 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()`
@@ -273,15 +701,15 @@ 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 owns 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
 the machine. Its optional `host` and required nonzero `port` bind the public
-Coordinator listener. Every child executes that same module and calls its own
-`createServer({ host: "127.0.0.1", port: 0 })`. The child reports its actual
-loopback endpoint only after its local readiness gates settle. The parent
+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
@@ -303,12 +731,10 @@ call on a sibling child. Subscription fan-out follows current READY members;
 later and replacement members attach the retained subscription before managed
 admission.
 
-`ServerOptions.browser` changes the public listener, not the bounded-context
-services. The native HTTP/2 backend binds to an ephemeral loopback port and is
-never returned. After it is ready, the server creates `UnaryGateway`,
-`SubscriptionGateway`, and native gateway services, then binds one HTTP/1.1
-Connect/gRPC-Web listener. A public bind failure closes subscription resources
-and the native backend; multiple rollback failures are aggregated.
+`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](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`.
@@ -317,7 +743,7 @@ 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.
 
-Browser origins must be unique canonical HTTP(S) origins with no path, query,
+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.
@@ -364,12 +790,12 @@ 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 the Server package's `DurableSubscriptionBindings` and rejects a
+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 framework-owned
-process-local bindings. The durable registry receives an explicit application
+`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
@@ -383,7 +809,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.
 
@@ -402,18 +828,23 @@ 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
-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. Each removal atomically verifies ownership and the exact
-delivered snapshot. Pending, retryable, non-delivered, and still-protected rows
-remain. There is no additional retention configuration, timer, or scheduler.
+absent or elapsed (`keepUntil <= now`). Delivery skips per-record mutation checks
+and deletion attempts for rows whose deadline is still in the future. Cleanup
+and retained-row duplicate recognition use the same applicable clock. Eligible
+rows still receive final time and shard checks before deletion.
+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,
@@ -429,7 +860,6 @@ const context = BoundedContext.singleTenant("Tasks")
 
 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
@@ -443,12 +873,22 @@ before source client/storage. `DeliverySource` is not configured on
 durable supervisor state, topology failover, exactly-once effects, or automatic
 retry of unknown remote mutations.
 
-Each drain operation is bounded to one page. That bound limits a single
-operation, not the total pending work: an active lease owner can take another
-page while its policy retains the shard. The 30-second Inbox deduplication
-window controls duplicate admission only; 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.
+Each Inbox read is bounded to one page. That bound does not limit the total
+pending work: an active drain continues from the last row read until that scan
+ends. It restarts from the beginning only if the completed scan delivered
+messages, allowing it to find work added during delivery. It finishes after a
+scan delivers nothing; it does not restart after each productive page.
+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.
+
+Direct delivery uses the configured Inbox storage clock for both retained-row
+duplicate checks and early cleanup filtering. Remote delivery uses local client
+wall-clock time for these checks and does not assume it is synchronized with
+the remote server.
 
 `DeliveryMonitor` is an instantiable, customizable policy seam exposing
 asynchronous continuation, start/completion, failed-reception, pickup-failure,
@@ -483,6 +923,15 @@ 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` 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.
+`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.