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

package/README.md

@@ -1,569 +1,276 @@
 # Spine application server for Node.js
 
-This package runs a Spine bounded context in Node. It assembles entities,
-handlers, storage, command/event processing, query-side Projections,
-subscriptions, and a local Connect/gRPC-compatible server.
-
-## Route a schema or interface token
-
-Use `.route(Schema, via)` for one message or `.route(Token, via)` for a named
-message-interface family. Exact schema routes take priority, then the first
-registered matching token, then replacement/default. The [To-Do example](../../examples/todo/USER_GUIDE.md)
-uses `TaskEvent`, an assignment token, and an exact `TaskReassigned` route.
-
-For a standalone application, use `await server.run()` to let the framework
-close the server on `SIGINT` or `SIGTERM` and permanently close the environment
-after the final run-managed server retires. Embedded applications use
-`await server.start()` and close the returned server themselves; `start()`
-never closes the shared environment. Active caller-managed and run-managed
-generations are exclusive, while matching `start()` or `run()` siblings share.
-Add the
-`browser` option with exact allowed origins and your session, authorization,
-and trusted-context collaborators to serve Connect and gRPC-Web without
-application listener or CORS code.
-
-### Run complete replicas on one deployment node
-
-For a deployment node that uses several application processes, put the same
-application assembly in one ESM entry module and start it with
-`ManagedServerApplication.run()`. `processCount` is an explicit deployment
-setting. It is not inferred from CPU cores, and it has no relationship to the
-Delivery shard count chosen by the application.
+`@spine-event-engine/server` is the native Node.js runtime for a Spine bounded
+context. Use it to assemble contexts and expose native Connect/gRPC-compatible
+services. Browser hosting is deliberately a separate entry point.
 
-```ts
-import { ManagedServerApplication, type RunningServer } from "@spine-event-engine/server";
-
-declare function startCompleteApplicationReplica(endpoint: {
-  host: string;
-  port: number;
-}): Promise<RunningServer>;
-
-await ManagedServerApplication.run({
-  processCount: 4,
-  host: "0.0.0.0",
-  port: 50051,
-  moduleUrl: import.meta.url,
-  createServer: startCompleteApplicationReplica,
-});
-```
-
-`startCompleteApplicationReplica()` is application code: it configures the
-production `ServerEnvironment`, opens the application's Delivery facility,
-assembles every Bounded Context, adds them to `Server`, and starts that server
-at the supplied private endpoint. See the [To-Do replica assembly](../../examples/todo/src/multi-process-replica.ts) for a concrete implementation.
+> **Experimental prerelease.** Install an exact snapshot while this API evolves:
+> Snapshot releases may remove earlier prerelease import paths.
 
-When another host owns process signals, use the same options with `start()`
-and close the returned handle from that host:
+## Install and prerequisites
 
-```ts
-import { ManagedServerApplication, type RunningServer } from "@spine-event-engine/server";
-
-declare function startCompleteApplicationReplica(endpoint: {
-  host: string;
-  port: number;
-}): Promise<RunningServer>;
-
-const managed = await ManagedServerApplication.start({
-  processCount: 4,
-  host: "0.0.0.0",
-  port: 50051,
-  moduleUrl: import.meta.url,
-  createServer: startCompleteApplicationReplica,
-});
-
-await managed.close();
+```bash
+pnpm add @spine-event-engine/server@snapshot
 ```
 
-The parent starts four separate children. Each child runs this same entry
-module, assembles the complete application, opens its own loopback listener,
-and completes its local readiness work before it is admitted. `run()` first
-waits for every configured child. Afterwards it stays ready while at least one
-child is ready; replacements continue while it is degraded, and it becomes
-unready if no child remains ready. A crashed child is replaced with bounded
-exponential delay; surviving children keep serving.
-The parent listens at the configured `host` and required nonzero `port` and
-forwards generated unary Command and Query gRPC calls to one READY child.
-The Coordinator fans each Gateway-owned logical subscription to the complete
-replicas and merges their updates. Each child observes the application's
-configured remote/shared Delivery facility directly; the parent does not proxy
-Delivery. Application assembly must select the Delivery facility and shard
-strategy appropriate to the deployment. The framework does not infer or
-certify their provenance, and managed process count neither detects CPU cores
-nor changes Delivery shard selection.
-
-Children progress `STARTING → SYNCHRONIZING → READY`. During synchronization,
-retained definitions are recreated and active streams attach before unary or
-Delivery admission; inactive definitions do not block readiness. Shutdown
-progresses `READY → DRAINING → CLOSED`: new unary and shard admission stops,
-active Delivery work may finish while subscription relays remain connected,
-then the child closes. The small parent/child channel carries only these
-lifecycle facts, including an opaque subscription-installation acknowledgement.
-It never carries Commands, Events, queries, subscription definitions or
-updates, or Delivery notifications. `ManagedServerApplication.run()` owns
-`SIGINT` and `SIGTERM` cleanup for its children. An embedding host uses
-`ManagedServerApplication.start()` instead and closes the returned managed
-handle itself; `start()` installs no process-signal handlers. Child listener
-topology remains private. Use direct `Server.run()` for one explicit local
-process or browser-oriented hosting.
-
-For detailed contracts intended for coding agents, see the
-[REFERENCE.md documentation for agents](REFERENCE.md).
-
-## 💡 Why use it?
-
-- ✅ Builds bounded contexts with Aggregates, Process Managers, and query-side
-  Projections.
-- ✅ Validates commands before application handlers run.
-- ✅ Exposes Command, Query, and Subscription services over native gRPC.
-- ✅ Optionally exposes authenticated Connect and gRPC-Web browser access.
-- ✅ Manages readiness, rollback, process signals, and ordered shutdown.
-
-## 🧭 Understand the two event paths
-
-Each domain bounded context has an internal paired System Context. Domain events
-go to the domain `EventBus` and are durably appended to the domain `EventStore`.
-System events, such as committed entity-state notifications, go only to the
-System Context's `EventBus`; they never enter the domain EventStore. By default
-system events are forgotten after validation and notification. Call
-`persistSystemEvents()` when the application needs a separate optional System
-Context event store.
-
-Enable that option while assembling the context, before `build()` or
-`buildAsync()`:
-
-```ts
-import { BoundedContext } from "@spine-event-engine/server";
-
-const context = BoundedContext.singleTenant("Tasks").persistSystemEvents().build();
-await context.close();
-```
+Use Node.js in ESM mode. Before adding entities, generate your application
+model and handler registry with `@spine-event-engine/proto-tools`. The small
+example below has no entity handlers, so it is useful for proving that native
+assembly, listener startup, and cleanup work locally.
 
-`Stand` is the read side: it serves queries from current entity state. Exposed
-domain-event subscriptions observe domain events on the domain `EventBus`.
-Entity subscriptions observe `EntityStateChanged` on the paired System Context
-`EventBus` and turn those notifications into updates. A subscription is best
-effort, so clients use a query for initial state and recovery after reconnect
-or a possible gap.
+## First native server
 
-## 🧱 Build a bounded context
+Build one context, start a loopback listener on an ephemeral port, and close
+the returned running server. `start()` installs no signal handlers, which makes
+this shape appropriate for tests and hosts that manage shutdown themselves.
 
-Start with an explicit tenant mode. Register entity classes after their Proto
-model and generated handler registry are available.
+<!-- docs-snippet-path: packages/server/test/server/server-environment.test.ts -->
 
 ```ts
-// docs-snippet-path: packages/server/test/context/bounded-context.test.ts
-import { BoundedContext } from "@spine-event-engine/server";
-
-const context = await BoundedContext.singleTenant("Tasks").buildAsync();
-await context.close();
+import { BoundedContext, Server } from "@spine-event-engine/server";
+
+const context = BoundedContext.singleTenant("Tasks").build();
+const running = await new Server({ contexts: [context], port: 0 }).start();
+try {
+  // Native Command, Query, and Subscription services are now listening.
+} finally {
+  await running.close();
+}
 ```
 
-Use `withStorageFactory()` to choose storage. Use
-`withGeneratedRegistryRoot()` for framework-generated repository assembly, or
-register explicitly assembled repositories with `add()`. `buildAsync()` is the
-normal choice for an application that uses generated handlers.
+Add generated entities with `BoundedContext.add(...)` and use
+`buildAsync()` when framework-generated repository discovery is needed. A
+context is single-tenant or multitenant by construction; select that mode
+before registering application handlers and storage.
 
-### Keep Stand subscription definitions
+## Give an Entity an application service
 
-Stand subscription definitions use your context storage by default. One
-`spine.client.SubscriptionRecord` is stored for each explicit subscription ID.
-Pending definitions expire if they are not activated; reconciliation is
-best-effort at a ten-second interval, so subscription updates are not complete
-delivery and clients re-query after reconnects or gaps.
+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:
 
-The storage record exposes the physical columns `status` and
-`when_activation_expires`. Cleanup asks the provider for 26 pending records,
-ordered by `when_activation_expires` and then ID. It deletes at most 25 expired
-records and reports more work only when the observed 26th record is expired.
-
-For an application-specific registry, provide one complete implementation.
-The built context closes it.
+<!-- docs-snippet-path: examples/projects/test/topology.test.ts -->
 
 ```ts
-import { BoundedContext, type StandSubscriptionRegistry } from "@spine-event-engine/server";
-
-declare const registry: StandSubscriptionRegistry;
-
-const context = BoundedContext.singleTenant("Tasks").withSubscriptionRegistry(registry).build();
+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),
+  });
 ```
 
-`InMemorySubscriptionRegistry` is useful in local development and tests. When a
-context using it is attached to a production `ServerEnvironment`, it emits one
-warning naming the context because definitions disappear on restart; startup
-still continues.
-
-### Managed subscription fan-out
-
-`SubscriptionService` remains a best-effort live stream: it has no replay or
-completeness promise. In standalone mode, its default registry is persistent.
-In managed complete-replica mode, the framework owns every child `Server` and
-requires each actual Bounded Context registry to be exactly an
-`InMemorySubscriptionRegistry`; persistent and custom registries are rejected
-and the assembled child is closed before READY.
-
-The Gateway alone owns durable logical subscription bindings. It rehydrates
-them after restart, while its Coordinator fans a definition out to READY
-replicas, merges their live updates, and propagates cancellation. Definition
-payloads never cross parent/child IPC. Late or replacement replicas first
-synchronize retained definitions and only then become eligible for ordinary
-traffic. Real-process event and Delivery handoff verification is documented
-separately from this server configuration guide.
-
-### Follow one definition from creation to cleanup
-
-The registry stores a definition first, then makes it active. Applications use
-the generated `SubscriptionId` throughout the lifecycle. `get()` and
-`snapshot()` return cloned values, so treat them as observations rather than
-mutable working objects. Their Protobuf byte arrays remain mutable, but do not
-alias stored or caller bytes.
+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
+usual result directly or through exactly one built-in `Promise<T>` layer. Its
+transaction remains open until that promise settles. Nested `Promise<Promise<T>>`
+results and structural or imported thenable lookalikes are rejected during handler
+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:
+
+<!-- docs-snippet-path: examples/todo/src/index.ts -->
 
 ```ts
-import { create } from "@bufbuild/protobuf";
-import { InMemorySubscriptionRegistry } from "@spine-event-engine/server";
-import { SubscriptionIdSchema, SubscriptionSchema } from "@spine-event-engine/proto/client";
-
-const registry = new InMemorySubscriptionRegistry();
-const id = create(SubscriptionIdSchema, { value: "daily-report" });
-const definition = create(SubscriptionSchema, {
-  id,
-  topic: { id: { value: "reports.daily" } },
-});
-
-await registry.create(definition); // pending for up to 30 seconds
-await registry.activate(id); // active definitions do not expire
-const current = await registry.get(id); // one isolated snapshot
-const all = await registry.snapshot(); // complete, identifier-sorted copies
-if (current !== undefined) await registry.delete(id);
-await registry.cleanup(); // removes at most 25 expired pending entries
-await registry.close();
-
-void all;
+import { Assign, Throws } from "@spine-event-engine/server";
+import type { CompleteTask } from "../generated/spine/examples/todo/task_commands_pb.js";
+import type { TaskCompleted } from "../generated/spine/examples/todo/task_events_pb.js";
+import { TaskAlreadyDone } from "../generated/spine/examples/todo/task_rejections.js";
+
+class TaskAssignee {
+  @Assign
+  @Throws(TaskAlreadyDone)
+  completeTask(command: CompleteTask): TaskCompleted {
+    throw TaskAlreadyDone.create({ id: command.id });
+  }
+}
 ```
 
-The built-in durable registry requires record storage with atomic
-compare-and-set. Context construction fails fast when the selected storage
-provider cannot supply that capability; it never silently falls back to memory.
+Place the primary handler decorator first for readability. Reversing the two
+decorators has the same behavior.
 
-Provider configuration for `SubscriptionRecord` applies to these definitions.
-For example, a MySQL factory can assign `SubscriptionRecordSchema` to a chosen
-table, and a Datastore factory can provide storage for that same schema. The
-registry uses the configured provider when the context is built.
-
-An aggregate receives a generated command type in an `@Assign` method. The
-generator discovers this method and writes the registry used by `buildAsync()`;
-run `spine-proto handlers` after changing it.
+Process Managers, but not Aggregates, have protected read-only `select()` during a handler:
 
 ```ts
-// docs-snippet-path: examples/orders/src/index.ts
-import { create } from "@bufbuild/protobuf";
-import { Aggregate, Assign } from "@spine-event-engine/server";
-import {
-  CreateOrderSchema,
-  type CreateOrder,
-} from "../generated/spine/examples/orders/commands_pb.js";
-import { OrderSchema } from "../generated/spine/examples/orders/entities_pb.js";
-import {
-  OrderCreatedSchema,
-  type OrderCreated,
-} from "../generated/spine/examples/orders/events_pb.js";
-
-class OrderAggregate extends Aggregate<string, typeof OrderSchema> {
-  @Assign createOrder(command: CreateOrder): OrderCreated {
-    this.update((draft) =>
-      Object.assign(draft, create(OrderSchema, { id: this.id, skuId: command.skuId })),
-    );
-    return create(OrderCreatedSchema, { id: this.id, skuId: command.skuId });
+import { EntityQuery, type EntityColumn } from "@spine-event-engine/core";
+import { ProcessManager } from "@spine-event-engine/server";
+
+type RequestView = import("@bufbuild/protobuf").Message<"RequestView"> & {
+  id: string;
+  status: string;
+  createdAt: number;
+};
+declare const RequestViewSchema: import("@bufbuild/protobuf/codegenv2").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 handleRequest(requestId: string): Promise<void> {
+    const pending = 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);
+    void [pending, one];
   }
 }
 ```
 
-## 🚀 Run a standalone server
-
-`Server` exposes the supplied built contexts through the Spine command, query,
-and subscription services. Its default host is local-only.
-
-```ts
-// docs-snippet-path: packages/server/src/server/server.ts
-import { Server, type BoundedContext } from "@spine-event-engine/server";
+These reads are eventually consistent. `limit()` may not exceed 1,000, and
+`all()` can be expensive for a large read model; prefer a targeted, ordered,
+bounded query.
+
+The Entity type identifies its context among those registered with the same
+`Server`. For example, an order process can query a product in a catalogue
+context without naming that context. An Entity in another context must allow
+queries (`query` or `full` visibility). Registering the same Entity type in two
+contexts causes a startup error.
+
+The [Orders example](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/orders/README.md#cross-context-order-review)
+shows this in an Event handler and includes a runnable integration test.
+
+Queries preserve the handler's actor and effective tenant; there is no tenant
+override. Single-tenant execution uses `SINGLE_TENANT`, even when the request
+omits a tenant field. A named tenant cannot query a single-tenant context: that
+fails before reading. See the [query contract](REFERENCE.md#handler-routing-and-operations)
+for the complete tenant rules and empty-result behavior.
+
+Use `EntityQuery.all(...)` when every predicate must match and
+`EntityQuery.either(...)` when any branch may match.
+
+## Native lifecycle and routing
+
+`Server.run()` is the standalone process form: it handles `SIGINT`/`SIGTERM`
+cleanup. `Server.start()` returns a `RunningServer` for an embedding host to
+close. `ManagedServerApplication` is the Node-only complete-replica entrypoint;
+it does not infer process or Delivery-shard counts.
+
+Routes are declared by generated message schema or interface token. Exact
+schema routes take precedence. Query results from `Stand` are authoritative;
+subscriptions are live, best-effort notifications, so clients re-query after a
+reconnect or a possible gap. Configure a storage provider for durable
+application state and generated repository assembly; in-memory choices are
+for local development and tests.
+
+## Entity identifiers
+
+An Entity ID can be a primitive value or a complete generated Protobuf message.
+For a message-valued ID, the Entity state message declares that ID message as
+its first field. Every field declared by the ID message, including nested
+messages, is part of the identity.
+
+```proto
+message WorkItemId {
+  spine.core.UserId owner = 1;
+  int32 sequence = 2;
+}
 
-declare const context: BoundedContext;
-const server = new Server({ contexts: [context], port: 0 });
-const running = await server.run();
-console.log(running.baseUrl);
+message WorkItem {
+  WorkItemId id = 1;
+  string title = 2;
+}
 ```
 
-Use `run()` for a standalone process. It installs framework `SIGINT` and
-`SIGTERM` shutdown; siblings share its generation, and a failed final close is
-retryable by a later signal or `close()`. Use `start()` when another host handles
-the process lifecycle; it shares only caller-managed siblings and never closes
-the environment.
+Generated messages can have any declared identifier fields. For example,
+`CommandId` is a generated message ID:
 
 ```ts
-import { Server, type BoundedContext } from "@spine-event-engine/server";
+import { create } from "@bufbuild/protobuf";
+import { type MessageId } from "@spine-event-engine/server";
+import { CommandIdSchema } from "@spine-event-engine/proto";
 
-declare const context: BoundedContext;
-const running = await new Server({ contexts: [context], port: 8080 }).run();
-console.log(`Spine server ready at ${running.baseUrl}`);
+const id = create(CommandIdSchema, { uuid: "task-42" });
+const entityId: MessageId = id;
 ```
 
-## Delivery and subscriptions
-
-An `@Assign` command for an Aggregate or Process Manager first persists in that
-Entity's Inbox. Local intake can then directly drain the persisted work in the
-current request path. With an attached `ServerEnvironment`, delivery workers
-replay admitted Inbox work through the same path. In shared remote delivery,
-every matching node may attempt a shard, while one active lease owner performs
-one bounded drain page; later drains can have a different lease owner. A page
-bound does not cap all pending work: the owner may take later pages until the
-delivery policy releases the shard. Events and later Process Manager commands
-use the same path. See [REFERENCE.md](REFERENCE.md) for operational delivery
-details.
-
-Domain-event subscriptions observe exposed domain events on the domain
-`EventBus`. Entity subscriptions observe committed `EntityStateChanged`
-notifications on the paired System Context `EventBus`. Stand's default registry
-uses the application's `StorageFactory`; a builder may supply another
-implementation. A definition is pending for at most 30 seconds, active
-definitions have no framework TTL, and cancellation physically deletes the
-definition. Nodes reconcile their local listeners from a complete
-snapshot every 10 seconds. Active streams and queues are process-local.
-
-### Serve browser clients
-
-Add `browser` configuration to expose Connect and gRPC-Web without writing a
-listener, router, CORS middleware, or shutdown coordinator. The application
-still supplies its authorization policy and trusted actor context resolver.
-Choose exactly one admission mode:
-
-- supply `sessions` when browser callers must authenticate; or
-- set `publicAccess: true` for an intentionally public endpoint with no login
-  session.
-
-Never supply both. Public access does not manufacture a session or an expiry.
-The application policy must still authorize every operation and rebuild trusted
-actor and tenant context from request facts.
-
-For a separately hosted TS or JVM backend, set `browser.backend.baseUrl` to its
-canonical HTTP(S) origin. The gateway keeps `ResolveContext` local and forwards
-the five application RPCs only after the configured admission, authorization,
-and trusted-context rewrite. An authenticated standalone mode requires explicit
-subscription bindings: local development and tests may explicitly supply an
-in-memory binding, while production also needs a type registry and named
-`DurableSubscriptionBindings`. A public standalone mode instead owns
-process-local bindings. A Gateway restart drops those definitions, so browsers
-reconnect, query authoritative state, and subscribe again. The external backend
-remains under caller control.
-
-Use `browser.backend.baseUrls` for non-empty unique origins. Unary calls use
-round-robin without retry; native streams fan out best-effort, so clients
-re-query authoritative state after duplicate updates or a generic loss notice.
-
-Applications may add only explicit OAuth-style callbacks with `authRoutes`.
-Each route uses an exact `GET`/`POST` path, per-route origins, a safe body limit,
-and a finite timeout. This is not a general HTTP router; use it for bounded
-identity exchanges and validate OAuth state in the application handler.
-The host admits at most 64 active auth requests by default (or the configured
-positive `maxActiveAuthRequests`); excess requests receive 503 before a handler
-runs. A route timeout covers request intake, handler work, and response
-transfer. Auth response bodies are bounded by `writeMaxBytes`; an overflow
-returns 413 without copying application headers.
+At routing, the generated ID is checked against the state field's declared
+schema and its generated validation rules before durable use. When default
+routing finds a message but the Entity ID type is primitive, define a custom
+route that returns the intended primitive ID.
 
-```ts
-import {
-  DurableSubscriptionBindings,
-  Server,
-  type BoundedContext,
-} from "@spine-event-engine/server";
-
-declare const context: BoundedContext;
-declare const sessions: import("@spine-event-engine/auth").SessionResolver;
-declare const authorize: import("@spine-event-engine/auth").AuthorizationPolicy["authorize"];
-declare const contextResolver: import("@spine-event-engine/auth").ContextResolver;
-declare const clock: import("@spine-event-engine/auth").Clock;
-declare const registryStorage: import("@spine-event-engine/storage").StorageFactory;
-
-const bindings = new DurableSubscriptionBindings({
-  storageFactory: registryStorage,
-  namespace: "my-app",
-  nextId: () => crypto.randomUUID(),
-  cleanup: async () => undefined,
-});
-
-const running = await new Server({
-  contexts: [context],
-  port: 8090,
-  browser: {
-    origins: ["http://127.0.0.1:5173"],
-    sessions,
-    authorize,
-    contexts: contextResolver,
-    clock,
-    bindings,
-  },
-}).run();
-
-void running;
-```
+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.
 
-For an intentionally public browser application, replace `sessions` and
-`bindings` in the example with `publicAccess: true`. Do not supply both modes.
-Public mode uses process-local bindings and has no synthetic session expiry.
-
-In production, authenticated browser access requires
-`DurableSubscriptionBindings`. Startup rejects missing or in-memory bindings
-before opening a listener. The registry uses the storage factory that your
-application supplies and closes only the handle, so you can use a separate
-factory from application-data storage or intentionally share one. Its namespace
-separates applications sharing a provider. Combined authenticated browser mode
-may omit bindings to use an in-memory registry; authenticated standalone mode
-must always supply them explicitly.
-
-Each durable binding stores one approved `GatewayAuthenticatedSubscription`:
-its public ID, complete subscription, and expiry. The stored Topic retains the
-trusted Actor and Tenant, so Activate and Cancel must match that context.
-
-- Cancellation cleans up the backend before deleting the record; a failure
-  leaves it available for retry.
-- Request-time cleanup is finite; a maintenance loop may call
-  `purgeExpired(nowMs)`.
-- Restart rehydrates unexpired definitions. An expired definition is removed
-  only after cleanup succeeds.
-
-This is a single-Gateway persistence model. It has no multi-process
-coordination, quotas, reservations, or durable fingerprints. Configure MySQL
-with `setTableName(GatewayAuthenticatedSubscriptionSchema, table)` or Datastore
-with `useRecordStorage(GatewayAuthenticatedSubscriptionSchema, creator)`.
-
-The server validates commands before handler code runs. Invalid payloads are
-returned as `COMMAND_VALIDATION_ERROR`; invalid state transitions are returned
-as `COMMAND_STATE_TRANSITION_VALIDATION_FAILED`. Domain rejections roll back
-the entity change and are posted independently as typed rejection events.
-
-## 🔎 Read state and updates
-
-`context.stand()` provides framework-managed current entity state reads and
-in-process update subscriptions. `SpineServices` translates the standard query
-and subscription service requests for registered state routes.
+## Browser gateway migration
 
-```ts
-// docs-snippet-path: packages/server/test/context/bounded-context.test.ts
-import type { BoundedContext } from "@spine-event-engine/server";
+The server root has no browser options and does not load auth. To host a
+browser-facing Gateway, install the optional auth peer and import the browser
+entry point explicitly:
 
-declare const context: BoundedContext;
-const stand = context.stand();
-void stand;
+```bash
+pnpm add @spine-event-engine/server@snapshot @spine-event-engine/auth@snapshot
 ```
 
-Subscriptions and active queues are local-process resources. A client must
-re-query after reconnect; this package does not promise cluster-complete
-updates, event replay for subscriptions, or exactly-once observation.
-
-## 🌐 Delivery and environment
-
-`DeliveryBuilder` builds a delivery from its inbox, work registry, shard, and
-page-size choices. `DeliverySupervisor({ source, delivery, onMessage })` receives
-the separate public `DeliverySource` used to observe remote shards.
-`Environment` resolves the Node deployment profile; the singleton
-`ServerEnvironment` exposes configured storage, optional delivery/tracing
-facilities, and its process lifecycle. They do not create a production topology
-or durable scheduler for you.
-
-`DeliveryMonitor` is the customizable explicit failure-policy seam. Its hooks
-may return a value or a promise; a failed reception defaults to durable
-`markDelivered()` and continues independent targets. Applications may instead
-select one immediate `repeatDispatching()` action. The monitor adds no attempts,
-quarantine, receipts, markers, timers, backoff, dead-letter storage, or
-scheduler policy. Each delivery lifetime has an opaque `WorkerId`; graceful
-stop waits for admitted work to settle before releasing its shard session.
-
-The default Entity Inbox has one shard. Configure more shards through the public
-builder chain:
-
 ```ts
-import { BoundedContext, UniformAcrossAllShards } from "@spine-event-engine/server";
-
-const context = BoundedContext.singleTenant("Tasks")
-  .withDeliveryStrategy(UniformAcrossAllShards.forNumber(3))
-  .build();
+import { BrowserServer, DurableSubscriptionBindings } from "@spine-event-engine/server/browser";
 ```
 
-Aggregate commands and Process Manager commands/events
-derive a target shard themselves and persist before handler replay. Local delivery
-drains in the posting request; after `ServerEnvironment` supplies delivery ports,
-posting persists and acknowledges while a worker replays later. Projection delivery
-is separate.
-
-An openable `ServerEnvironmentDelivery` is opened before the first environment
-attachment is admitted, then supplies its inbox and work-registry ports to both
-the existing finite and supervisor delivery paths; a close-only local delivery
-remains supported. The environment stops attachments before closing delivery,
-tracing, and storage in that order. Use `RemoteDelivery` from
-`@spine-event-engine/delivery-client` when an application selects a remote
-delivery endpoint with direct authoritative removal.
-
-Shard ownership excludes concurrent delivery within a shard. Pending and
-delivered Inbox rows are stored directly, and delivered rows are the
-deduplication fact. Handler effects and the delivered-row compare-and-set are
-not transactional: a lost acknowledgement can redeliver after restart, so
-downstream handling must be idempotent.
-
-## ⚠️ Runtime boundaries
-
-The package is Node-only. It does not choose an identity provider, session
-database, production storage, TLS setup, or durable multi-machine delivery.
-Subscription updates are notices rather than complete history, so clients
-re-query entity state after reconnecting.
-
-## 🔗 Learn more
-
-- [End-user guide](../../docs/USER_GUIDE.md)
-- [Authentication](../auth/README.md)
-- [Node client](../client-node/README.md)
-- [Browser client](../client-web/README.md)
-- [Message Board application](../../examples/message-board/README.md)
-- [Reference for coding agents](REFERENCE.md)
-
-## Cross-context external events
-
-Every built `BoundedContext` owns one private integration broker. It publishes
-domestic events only when another context has requested them, and an imported
-event is delivered only to handlers declared with `External<T>`. The marker is
-type-only and transparent at runtime:
+`BrowserServer.open(...)` composes a browser listener around a caller-managed
+native server; `BrowserServer.run(...)` starts and manages a standalone or
+combined browser host. Supply exact allowed origins, a session or intentional
+public admission, authorization and trusted-context resolvers, finite limits,
+and backend forwarding. Authenticated durable bindings are browser-host
+infrastructure, not native `Server` state. See the [browser/auth extension guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/BROWSER_CLIENT_AUTH_EXTENSION_GUIDE.md)
+before exposing a backend to a browser.
 
-```ts
-// docs-snippet-path: examples/todo/src/index.ts
-import { Subscribe, type External } from "@spine-event-engine/server";
-import type { TaskCreated } from "../generated/spine/examples/todo/task_events_pb.js";
-
-class TaskProjection {
-  @Subscribe
-  onImported(event: External<TaskCreated>): void {
-    void event;
-  }
-}
-```
+## Limits
+
+This package does not create an identity provider, browser session store,
+authorization policy, TLS configuration, or deployment topology. It does not
+guarantee replay, gap repair, exactly-once subscription effects, or
+cluster-complete notification delivery.
+
+## Next steps
 
-`External<T>` must be the direct first receptor parameter. External commands
-are invalid; external events, rejections, and supported state subscriptions
-are valid. A context publishes only the event types requested by interested
-contexts. This requested-only export, plus domestic/external filtering, is the
-loop-prevention rule: there is no hop counter, broker Inbox, retry, replay,
-deduplication, or producer election. Delivery is best effort; many consumers
-may observe one domain producer at a time.
-
-The broker uses private `TransportFactory` message channels.
-`ServerEnvironment` owns one process-wide `InMemoryTransportFactory` by
-default for private IntegrationBroker message channels, including production.
-An application may supply `integrationChannelFactory` to override that local
-channel factory. Production resolution still requires `storageFactory` and the
-complete application `typeRegistry`; it does not fall back to in-memory storage
-or to the core-only registry. No application signal-binding setting is part of
-the environment. The channel factory is private IntegrationBroker plumbing,
-not a general runtime transport.
-
-`ThirdPartyContext.singleTenant(name)` or `.multitenant(name)` creates the
-public import facade. `emittedEvent(event, actor)` requires a generated event,
-preserves the actor tenant policy, and uses the actor timestamp (or fills one
-for a `UserId`). An unknown local event schema rejects before publication; a
-valid event with no current interested context is a successful no-op. Close the
-hidden context when imports are finished.
+- [Detailed coding-agent reference](REFERENCE.md)
+- [Authentication gateway](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/auth/README.md)
+- [Message Board application](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/message-board/app/README.md)