@spine-event-engine/server 2.0.0-snapshot.24 → 2.0.0-snapshot.26

package/README.md

@@ -14,7 +14,8 @@ pnpm add @spine-event-engine/server@snapshot
 ```
 
 Use Node.js in ESM mode. Before adding entities, generate your application
-model and handler registry with `@spine-event-engine/proto-tools`. The small
+model and handler metadata with `@spine-event-engine/proto-tools`, then import
+`generated/spine-bootstrap.js` before assembly. The small
 example below has no entity handlers, so it is useful for proving that native
 assembly, listener startup, and cleanup work locally.
 
@@ -27,9 +28,10 @@ this shape appropriate for tests and hosts that manage shutdown themselves.
 <!-- docs-snippet-path: packages/server/test/server/server-environment.test.ts -->
 
 ```ts
-import { BoundedContext, Server } from "@spine-event-engine/server";
+import { BoundedContext, Server, ServerEnvironment } from "@spine-event-engine/server";
 
-const context = BoundedContext.singleTenant("Tasks").build();
+await ServerEnvironment.instance().completeSetup();
+const context = await BoundedContext.singleTenant("Tasks").build();
 const running = await new Server({ contexts: [context], port: 0 }).start();
 try {
   // Native Command, Query, and Subscription services are now listening.
@@ -39,10 +41,29 @@ try {
 ```
 
 Add generated entities with `BoundedContext.add(...)` and use
-`buildAsync()` when framework-generated repository discovery is needed. A
+`build()` to assemble the context and load generated repositories when configured. A
 context is single-tenant or multitenant by construction; select that mode
 before registering application handlers and storage.
 
+`build()` prepares the current model storage and awaits the first subscription
+registry pass. Set `createStorageStructures: false` or
+`startSubscriptionMonitoring: false` in `build({...})` to defer either phase
+independently until the first valid input. Complete environment setup explicitly
+before building, even when both phases are deferred.
+Starting monitoring still prepares its shared subscription registry when model
+structure creation is deferred; it does not prepare every tenant's Entity storage structures.
+An eager required-phase failure stops accepting new input and triggers environment
+cleanup. A lazy first-input failure rejects that input and can be retried.
+After build, `context.runtime.createStorageStructures(...tenantIds)` explicitly
+creates declared structures; `checkStructureCompatibility(...tenantIds)` checks
+them without creating structures. With no IDs, a multitenant context traverses
+its current tenant index in pages; a single-tenant context prepares its neutral
+destination. `startSubscriptionMonitoring()` starts the initial registry pass
+without preparing every tenant's Entity structures. The environment offers the
+same operations across completed, open contexts, selecting matching multitenant
+contexts for explicit IDs. Database-backed providers require an existing
+database; these operations do not provision one or register tenants.
+
 ## Give an Entity an application service
 
 Spine normally constructs an Entity with its ID, state, version, and lifecycle
@@ -58,15 +79,17 @@ 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),
-  });
+const builder = BoundedContext.singleTenant("Assignments").add(TaskAssignment, {
+  // Forward Spine's options and add the service required by the constructor.
+  onCreate: (options) => new TaskAssignment(options, weights),
+});
 ```
 
-Call `builder.buildAsync()` to assemble the context. The callback runs for each
+The application's `src/index.js` imports its generated `spine-bootstrap.js`
+before assembly, so `add(TaskAssignment)` finds the passive metadata for that
+exact class.
+
+Await `builder.build()` 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
@@ -182,11 +205,40 @@ Bounded 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.
 
+Application queries use generated `_queries.proto` request/response companions.
+Pass concrete `AppQueryHandler<Q, R>` instances in `ServerOptions.appQueries`;
+generated metadata alone never enables a route. On direct app-node ingress,
+`QueryService.Execute` validates the wire envelope and Q before dispatch.
+Native and browser Gateways forward Execute to the app node; `ClientRequest.query(generatedQ)`
+returns the wire `Response` and zero or one decoded paired results. Application code calls
+`server.query(generatedQ, executionContext)` and receives the paired generated R.
+The trusted execution context supplies the current `actorContext`, optional
+verified principal and authority facts, and an optional cancellation signal.
+For a Process Manager or Agent, inject a Server-bound query function through the
+repository's `onCreate` callback and use `currentActorContext` only inside an
+active handler. That actor metadata does not prove authentication. Source reads
+from an application query use registered query-visible Entity routes and enforce
+the destination's tenant membership; a handler that performs no source read has
+no destination tenant to check. Direct calls do not run Server output filters.
+
+The [typed callback example](REFERENCE.md#services-reads-and-lifecycle) shows
+the repository `onCreate` injection and active handler call. The actor/tenant
+snapshot supplies no verified principal or provider facts; the
+[scoped integration test](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/server/test/entity/process-manager-querying.test.ts) shows
+the complete repository setup.
+
 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.
+For a multitenant receiving context, explicitly register each accepted tenant
+through `context.tenantIndex.keep(tenantId)` or the configured directory.
+Provider-backed indexes may only confirm existing membership: fixed SQL catalogs
+cannot add tenants, and the Datastore index requires native namespace metadata.
+Use an application-managed `TenantIndex` to register tenants before provider
+data exists or to add tenants dynamically.
+Unknown tenants fail before reads or handlers run; input never registers them.
 
 Use `EntityQuery.all(...)` when every predicate must match and
 `EntityQuery.either(...)` when any branch may match.
@@ -201,7 +253,7 @@ state are declared in Proto and its handlers use generated registration.
 
 An Agent can read its recorded interactions and emitted domain Events through
 its repository. See the [Agent execution reference](REFERENCE.md#agent-execution)
-for history methods, paging, and recovery behavior.
+for history methods, paging, and live execution behavior.
 
 Declare the Agent ID and state in Proto, with `option (entity).kind = ENTITY;`
 on the state. The [Support example](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/README.md) includes
@@ -271,16 +323,16 @@ class SupportDraftAgent extends Agent<SupportTicketId, typeof SupportDraftStateS
 <!-- prettier-ignore-end -->
 
 Configure the registry outside the Entity. The Bounded Context requires persisted System
-Events, and the Agent registration supplies its code revision and permitted
-capabilities. The [example Bounded Context factory](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/src/index.ts)
-assembles these settings with the generated handler registry. A server-wide
-`withAi()` default can be supplied when building Bounded Contexts through `Server`;
-Bounded Context configuration can provide its registry directly.
+Events, and the Agent registration supplies its permitted capabilities. The
+[example Bounded Context factory](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/src/index.ts)
+assembles these settings with generated passive handler metadata. Supply the AI registry
+through `ServerEnvironment.when(type).use({ ai: registry })` as a default, or
+`BoundedContextBuilder.withAi(registry)` for one Bounded Context.
 
 Posting a Command awaits acceptance. Model work and the resulting domain Event
 arrive asynchronously afterward. The handling operation can await a model without
 keeping a database transaction open. See the [Agent execution reference](REFERENCE.md#agent-execution)
-for defaults, recovery and retained history.
+for defaults and retained history.
 
 ## Native lifecycle and routing
 
@@ -337,7 +389,7 @@ 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.
 
-## Browser gateway migration
+## Browser gateway setup
 
 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
@@ -359,6 +411,21 @@ 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.
 
+## Native reader admission
+
+Native authentication is configured through `ServerOptions.services.readerAdmission`.
+Use `direct` to authenticate native callers or `forwarded` to verify reader
+assertions from an authenticated gateway. For browser forwarding, supply the
+corresponding issuer as `BrowserServerOptions.forwardingProof`. Configure both
+ends; the backend does not trust an actor ID or incoming identity header by
+itself. With neither admission adapter configured, the native server remains
+public and supplies no authenticated principal or authority facts.
+
+Subscription activation and cancellation also check the admitted principal
+against the stored reader binding. A different principal cannot reuse a
+subscription even with the same ActorContext. See [native reader admission](REFERENCE.md#native-reader-admission)
+for adapter signatures, public admission, and managed application configuration.
+
 ## Limits
 
 This package does not create an identity provider, browser session store,