@spine-event-engine/server 2.0.0-snapshot.25 → 2.0.0-snapshot.28

package/REFERENCE.md

@@ -168,7 +168,7 @@ phase without implying that every Entity model has been prepared.
 awaits both model preparation and the first subscription reconciliation by
 default. Each option can be set to `false` independently. A deferred phase runs
 before the first valid Command, Event, query, subscription operation, or Inbox
-replay for the receiving context; lazy multitenant preparation selects only that
+delivery for the receiving context; lazy multitenant preparation selects only that
 input's currently registered tenant. A failed lazy attempt rejects its current
 input and can be retried by a later input. Monitoring requires the shared
 subscription registry, so `startSubscriptionMonitoring: true` prepares that
@@ -208,20 +208,33 @@ 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.
 
-`tenantIndex` selects a live application membership directory. When omitted,
-the environment uses its storage factory's native catalog where available, or
-a transient in-memory index for a custom factory without a catalog. The
-transient index lasts only for this environment instance. `contains()` checks
-membership without preparing storage; `keep()` makes a registration visible to
-later reads and may reject for a read-only catalog. PostgreSQL and MySQL
-catalogs expose only configured tenant entries: `keep()` is idempotent for
-those entries and rejects unknown IDs. A dynamic SQL tenant resolver does not
-register or enumerate tenants. Single-tenant contexts do not insert a synthetic
-member into this directory.
+`tenantIndex` is optional and defaults to `SINGLE_TENANT`, a marker that creates
+no directory and never consults a provider catalog. The environment getter
+returns `TenantIndexSetting`, either that marker or an application-supplied
+`TenantIndex`. Narrow against the marker before calling `contains()`, `keep()`,
+`page()`, or `all()`. A multitenant Bounded Context requires a real environment
+index before business storage opens. A single-tenant Bounded Context always returns the
+marker, including inside a multitenant environment. Provider catalogs remain
+separate storage-provider APIs and do not select application membership.
+
+`PersistentTenantIndex.create({ storageFactory, group })` opens a separate,
+storage-backed registration directory without constructing a Bounded Context or
+`ServerEnvironment`. It creates and checks supported storage structures before
+returning. Set `createMissingStructures: false` to skip preparation on creation
+and on later reads or writes. A skipped directory needs structures prepared by
+the application before data access; missing structures cause provider errors.
+Memory storage remains process-local. The injected factory remains usable after the
+index closes. `keep()` registers a complete `TenantId` atomically and retains
+the first registration time; `contains()` reads its primary key. `page()` uses
+finite keyset traversal with an abort signal and a continuation accepted only
+by that index instance. `all()` traverses the complete current directory, so
+its result can be large. Traversal does not promise a snapshot while other
+writers register tenants. Registration does not provision tenant databases or
+authorize users. The environment defaults to the explicit `SINGLE_TENANT` marker.
 
 Multitenant receiving contexts check current index membership before Command,
 Event, query, direct repository/history, and subscription work. Inbox persistence
-and later replay check separately, so removing a tenant prevents saved work from
+and later delivery check separately, so removing a tenant prevents saved work from
 restoring it. Input does not call `keep()` implicitly. A confirmed missing member
 raises `TenantUnknownError` with the complete tenant ID and context name; native
 services return `NotFound` with a structured `spine.base.Error` detail whose type
@@ -249,8 +262,8 @@ 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
+recipient. Inbox delivery uses stored target IDs without rerouting. The local
+`catchUpReadSide()` helper is unrelated to retry: it resets and dispatches stored Events through
 the whole local read side, and is not Projection catch-up.
 
 ## Message-valued Entity IDs
@@ -282,7 +295,7 @@ 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.
+field, including generated validation rules, before it is stored or delivered.
 When default routing finds a message but the Entity ID type is primitive, a
 custom route returns the intended primitive ID.
 
@@ -585,9 +598,8 @@ await context.commandBus().post(
 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
-`build()` with their compiled package root.
+Application builds emit the record to `generated/spine-metadata.js` and import
+`generated/spine-bootstrap.js` before `build()` selects registered classes.
 
 One `@Where({ eventField, equals })` equality filter may narrow an event- or
 rejection-consuming `@Subscribe`, `@React`, or `@Command` handler after type
@@ -597,9 +609,9 @@ 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.
-Ordinary Aggregate, Process Manager, and Projection Inbox replay sends persisted
-accepted work through the normal handler path, so those handler effects must be
-replay-safe. An accepted Agent interaction is recorded by its receipt and is
+Ordinary Aggregate, Process Manager, and Projection Inbox delivery sends persisted
+accepted work through the normal handler path. Handler effects must tolerate
+redelivery after an uncertain acknowledgement. An accepted Agent interaction is recorded by its receipt and is
 never re-executed after interruption.
 
 ## Context assembly and entities
@@ -608,12 +620,14 @@ Create a context with `BoundedContext.singleTenant(name)` or
 `BoundedContext.multitenant(name)`. Names are immutable. Use
 `ServerEnvironment.when(type).use({ storageFactory: factory })` before explicit
 environment setup to supply record/event storage to all contexts.
-`withTenantIndex(index)` selects a different live membership directory for one
-context; `context.tenantIndex` and `ServerEnvironment.instance().tenantIndex`
-return the configured objects. Closing a context does not close either index.
-`withGeneratedRegistryRoot(root)` enables framework discovery of the generated
-handler registry for classes registered with `add(EntityClass)`;
-`build()` asynchronously performs that discovery and assembly, including
+`withTenantIndex(index)` selects a different live membership directory for a
+multitenant Bounded Context after its environment has a real index. The Bounded Context getter
+returns its captured selection; single-tenant Bounded Contexts return `SINGLE_TENANT`.
+Both getters have type `TenantIndexSetting` and require narrowing before index
+methods. Closing a Bounded Context does not close the configured directory.
+The application imports its generated `spine-bootstrap.js` before registering
+classes with `add(EntityClass)`; `build()` then selects passive descriptions
+by exact constructor and performs assembly, including
 explicit `Repository` registration. Await it before using the context. A built context contains `CommandBus`,
 `EventBus`, `Stand`, repositories, and its storage lifecycle.
 Trusted server-side code can call `context.getRepository(EntityClass)` to obtain
@@ -631,13 +645,12 @@ registry shapes with an instruction to regenerate.
 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
+added to a server). Its physical `StorageGroup` derives from the logical Bounded Context name, so two contexts using one factory keep distinct definitions. An injected `StorageSubscriptionRegistry` takes an explicit group as its third constructor argument and prepares its captured factory and context. 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
+`SubscriptionService` streams are live notifications. Each subscriber receives its admitted filtered updates in order, but there is no replay, exactly-once, or cluster-wide completeness guarantee. A standalone Server defaults to the
 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
@@ -645,7 +658,12 @@ 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
+before it is eligible for normal requests. The Coordinator resolves the same
+`subscriptionQueueCapacity` before binding its HTTP/2 listener. Its activation
+ACK is separate from the update queue, which reserves one active DATA update
+plus the configured waiting count for each logical subscriber. Overflow closes
+that subscriber's relay and aborts its child streams.
+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
@@ -678,12 +696,21 @@ 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
+delete. `create(subscription, reader?)` 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.
+content and the same reader binding. A different definition or binding with the
+same ID throws `StandConflictError`. `activate(id, reader?)` returns `activated`,
+`active`, `missing`, `expired`, or `denied`. `delete(id, reader?)` returns `deleted`,
+`missing`, or `denied`. Blank IDs or topics and malformed durable records fail closed.
+
+Service requests always supply the admitted principal ID or an explicit anonymous
+binding. When supplied, the registry checks the binding again after every failed
+compare-and-set, before changing a reread record. The omitted argument is for
+trusted internal lifecycle work; it is not a way to admit an unauthenticated RPC.
+Reader identity is stored atomically with the subscription definition and phase.
+Attributes, authority facts, and credentials are not part of the stored identity.
+A missing legacy binding is not anonymous and cannot be claimed by a caller;
+the client must create a new subscription.
 
 Entries and nested subscriptions returned by create, activate, get, and
 snapshot are clone-safe views. Protobuf byte arrays remain mutable runtime
@@ -840,6 +867,11 @@ The scope is explicit: pass `{}` in a single-tenant Bounded Context or
 `{ tenantId }` in a multitenant Bounded Context. Reads use indexed storage
 without restoring an Agent. The application bridge must authorize access;
 actor metadata does not grant read permission.
+For a trusted in-process caller, the scope can also include detached
+`actorContext`, a verified `reader` with principal and authority facts, and a
+`signal`. Read-side filters receive those facts for that history call; omitting
+`reader` leaves principal and authority facts absent. The bridge supplies
+verified facts explicitly and cannot derive them from `actorContext`.
 
 If a selected model's `authorizeUse` callback explicitly returns `false`
 before the handler, the turn records one `AgentInvocationTerminated` System
@@ -849,10 +881,15 @@ may correlate this fact with the original source through paged Agent history.
 
 ## 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`.
+`CommandBus` checks the nonempty Command ID, nondefault message and context,
+and declared payload constraints before admission or dispatcher code runs.
+Annotated packed messages use generated Proto modules registered in the process.
+`SpineServices` reports invalid Commands in an error Ack with type
+`spine.core.CommandValidationError`, numeric `INVALID_COMMAND` code, and a
+packed `spine.validation.ValidationError`. Unsupported Commands use the same
+enum type and numeric `UNSUPPORTED_COMMAND` code.
+Technical validator failures use a sanitized `COMMAND_POST_ERROR` Ack without
+constraint details; they are distinct from invalid Command input.
 Entity transition validation failures that escape service processing map to
 `COMMAND_STATE_TRANSITION_VALIDATION_FAILED` with the same detail type. Managed
 reception of ordinary Entity work sends post-handler transition rejection to `DeliveryMonitor`;
@@ -871,6 +908,8 @@ 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.
+Each EventBus validates the Event envelope and domain payload before admission,
+storage, or delivery.
 `persistSystemEvents()` enables the paired System Context's separate storage.
 Bounded Contexts with Agents must enable it. For other Bounded Contexts it is optional; without
 it, the bus validates, dispatches and notifies without appending. Schemas may come from an external dispatcher or
@@ -887,9 +926,213 @@ 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.
 
+Native QueryService accepts `BytesValue` equality and range operands for annotated scalar `bytes`
+columns and permits ascending or descending byte ordering. The shared evaluator uses unsigned
+lexicographic comparison, including shorter equal prefixes first. This TypeScript query capability
+does not assert JVM JDBC byte-range compatibility. `QUERY_SERVICE_MAX_RESULTS` from core is the
+current capacity of 1,000 returned and evaluated records for one native read, not a collection-size limit.
+
+`ServerOptions.appQueries` selects concrete generated `AppQueryHandler<Q, R>`
+instances by exact constructor metadata before listening. Duplicate Q routes
+or missing metadata fail startup. On direct app-node ingress,
+`QueryService.Execute` validates a complete AppQuery envelope and Q, then
+returns one packed paired R. Native and browser Gateways and managed Coordinators
+forward Execute to an app node; `ClientRequest.query(generatedQ)` decodes its paired R.
+The internal
+`Server.query(generatedQ, executionContext)` accepts a generated Q and returns
+its paired generated R, using a detached request and the effective actor,
+verified reader facts, and cancellation signal supplied by the current
+framework invocation. `ProcessManager.currentActorContext` and
+`Agent.currentActorContext` expose only the current signal's detached actor and
+tenant during a handler; neither establishes a verified principal. Constructor
+injection can bind the query function to a Server. Scoped Entity reads require
+query/full visibility and destination tenant membership. Direct calls do not
+cross the Server's gRPC output-filter boundary.
+
+`ReadSideFilter<typeof MessageSchema>` declares a typed policy for a registered
+Proto message. Its protected constructor takes the generated schema and optional
+`{ nested: true }`; `filter(message, context)` receives a detached mutable value
+and may return the same type or `null` to remove that occurrence. The context
+separates actor metadata from verified reader facts and identifies the current
+operation, plus a detached containing message and field for nested calls.
+Read-only packed bytes remain available to Buf decoding through a detached
+`value.slice()` passed to `fromBinary`.
+Call `addReadSideFilter(filter)` on a `BoundedContextBuilder` before `build()` to apply it to that
+Bounded Context's outward Entity reads and retained histories. Pass `readSideFilters`
+to `new Server(...)` to apply policies to Entity Query and App Query results
+leaving that Server over gRPC. The same instance can be installed in both
+places; each boundary invokes it once. Direct `Server.query()` runs BC source
+policies but does not cross the Server output boundary. An Entity root returned
+as `null` is omitted without another storage read; an App Query root returned
+as `null` produces OK with zero outer `AppQueryResponse.message` entries. A
+non-null response whose child field is absent remains one response entry.
+History removals retain the
+original continuation. Retained storage, hydration, and replay remain raw.
+Direct Stand and retained-history callbacks identify the producing Bounded
+Context. Protected history called from a handler carries its current signal
+actor; an out-of-handler diagnostic read has no actor or authenticated reader.
+Native SubscriptionService delivery filters already matched Entity states and
+Event payloads through the producing Bounded Context policy and then the
+Server policy. The `subscription` operation includes the original Topic and
+admitted subscription; its context carries the current verified reader facts,
+effective tenant, actor metadata, producing Bounded Context, and cancellation
+signal. Removing a state emits `no_longer_matching` with its original Entity
+ID; removing every Event payload suppresses that data batch. ACKs and existing
+removal controls remain unchanged. Policy failures end only that reader stream
+with a sanitized technical status.
+
+The operation describes the call that produced the value. `query` includes the
+actual Query and, during an App Query child read, the enclosing AppQuery. `app-query`
+identifies the final application result. `direct` identifies either a typed
+Stand state read by type URL and Entity ID, a caller-supplied RecordQuery, or a
+normalized query plan. `history` distinguishes an Entity state-at timestamp,
+Entity state/Event history depth, and an Agent view with its page request and
+optional cursor. Direct callers supply actor metadata, verified reader facts,
+and cancellation separately; they cannot override the operation.
+Direct subscription delivery uses `kind: "direct"` with
+`operation.subscription.typeUrl`, distinct from a one-off Stand read's
+`operation.read`.
+
+This filter uses the generated Project state and can be installed on the Bounded
+Context builder that contains its Repository:
+
+<!-- docs-snippet-path: packages/server/test/server/app-query-execution.test.ts -->
+
+```ts
+import {
+  type BoundedContextBuilder,
+  ReadSideFilter,
+  type ReadSideContext,
+} from "@spine-event-engine/server";
+import {
+  type ProjectOverviewState,
+  ProjectOverviewStateSchema,
+} from "../../test-fixtures/generated/repository-routing/project_states_pb.js";
+
+/**
+ * Replaces a project name in all ordinary Entity Query results.
+ */
+class PublicProjectName extends ReadSideFilter<typeof ProjectOverviewStateSchema> {
+  /**
+   * Registers the filter for project overview state.
+   */
+  constructor() {
+    super(ProjectOverviewStateSchema);
+  }
+
+  /**
+   * Replaces the name only for ordinary Entity Query responses.
+   *
+   * @param state Project overview returned by the read side.
+   * @param context Describes the read operation and verified reader.
+   * @returns The project overview with its name replaced for ordinary Entity Queries.
+   */
+  filter(state: ProjectOverviewState, context: ReadSideContext): ProjectOverviewState {
+    if (context.operation.kind === "query") state.name = "Public project";
+    return state;
+  }
+}
+
+const projectPolicy = new PublicProjectName();
+
+/**
+ * Registers the project name policy in its supplying Bounded Context.
+ *
+ * @param builder Configures the project Bounded Context.
+ * @returns The builder with the read policy installed.
+ */
+function installProjectPolicy(builder: BoundedContextBuilder): BoundedContextBuilder {
+  return builder.addReadSideFilter(projectPolicy);
+}
+```
+
+The repository `onCreate` callback can inject `(q, context) => server.query(q, context)`
+into a Process Manager or Agent. Within an active handler, pass a generated Q
+with `{ actorContext: this.currentActorContext }`; the actor/tenant snapshot
+does not supply 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) includes
+the full callback and handler invocation.
+
+This example uses the generated Project query and the current Process Manager
+scope; pass `scopedOnCreate(server)` as the repository's `onCreate` callback.
+Ordinary generation and bootstrap register the decorated handler description:
+
+<!-- docs-snippet-path: packages/server/test/entity/process-manager-querying.test.ts -->
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import {
+  Assign,
+  ProcessManager,
+  type EntityOptions,
+  type Server,
+  type ServerQueryExecutionContext,
+} from "@spine-event-engine/server";
+import { ProcessManagerStateSchema } from "../../test-fixtures/generated/entity-metadata/visibility_pb.js";
+import { ProjectIdSchema } from "../../test-fixtures/generated/repository-routing/project_identifiers_pb.js";
+import {
+  type ProjectCreated as ProjectionEvent,
+  ProjectCreatedSchema as ProjectionEventSchema,
+} from "../../test-fixtures/generated/repository-routing/project_events_pb.js";
+import { type CreateReviewProject } from "../../test-fixtures/generated/validation-refusal/project_commands_pb.js";
+import {
+  type GetProjectOverview_Query,
+  type GetProjectOverview_Response,
+} from "../../test-fixtures/generated/repository-routing/project_queries_pb.js";
+import { GetProjectOverview } from "../../test-fixtures/generated/repository-routing/project_queries_app_query.js";
+
+/**
+ * Runs a typed App Query from an active Process Manager handler.
+ */
+class ScopedAppQueryManager extends ProcessManager<string, typeof ProcessManagerStateSchema> {
+  /**
+   * Captures the scoped query callback supplied during repository construction.
+   *
+   * @param options Configures this Process Manager instance.
+   * @param ask Executes a generated App Query with trusted handler context.
+   */
+  constructor(
+    options: EntityOptions<string, typeof ProcessManagerStateSchema>,
+    private readonly ask: (
+      query: GetProjectOverview_Query,
+      context: ServerQueryExecutionContext,
+    ) => Promise<GetProjectOverview_Response>,
+  ) {
+    super(options);
+  }
+
+  /**
+   * Reads the current project overview while handling the creation Command.
+   *
+   * @param command Project creation request being assigned.
+   * @returns Event carrying the selected overview name.
+   */
+  @Assign
+  async assign(command: CreateReviewProject): Promise<ProjectionEvent> {
+    const result = await this.ask(
+      create(GetProjectOverview.querySchema, {
+        project: create(ProjectIdSchema, { value: command.id }),
+      }),
+      { actorContext: this.currentActorContext },
+    );
+    return create(ProjectionEventSchema, {
+      id: command.id,
+      name: result.project?.name ?? "",
+    });
+  }
+}
+
+/**
+ * Injects the Server's typed App Query route into new Process Manager instances.
+ */
+export const scopedOnCreate =
+  (server: Server) => (options: EntityOptions<string, typeof ProcessManagerStateSchema>) =>
+    new ScopedAppQueryManager(options, (q, context) => server.query(q, context));
+```
+
 `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
+offers in-process subscriptions. The local read-side reset helper
+`catchUpReadSide(options?)` clears every registered Projection state and dispatches
 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
@@ -917,8 +1160,57 @@ 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.
+consumers. Native subscription updates enter the existing bounded delivery
+queue before asynchronous read policies run; a full queue closes that stream.
+For a surviving Event, policy replaces only its domain payload and retains the original envelope.
+Direct `Stand.subscribe(schema, { next, error }, options)` applies only its
+producing Bounded Context's read policies, independently for each local
+subscriber. `next` receives either `{ kind: "state", state, previousState? }`
+or `{ kind: "removal", noLongerMatching: true }`; both retain the original type
+URL, Entity ID, version, and tenant metadata. A removed prior state is omitted
+from a surviving current state. `error` receives one terminal local policy,
+callback, or capacity fault. There is no raw callback overload. Options accept
+trusted `reader` facts, `actorContext` metadata, tenant, and cancellation;
+`ServerEnvironmentSettings.subscriptionQueueCapacity` sets the waiting count
+for direct and server-served subscriptions. Configure it before constructing
+the Stand or Bounded Context. It defaults to 100 waiting updates in addition to
+one active update; zero allows the active update with no waiting updates. Filter calls
+and `next` completion are sequential per subscriber. Overflow closes only that
+subscriber, clears waiting updates, invalidates the active result, and reports
+`StandSubscriptionCapacityError`; committed writes and other subscribers
+continue. Unsubscribe, cancellation, and Stand close invalidate outstanding
+results without waiting for a nonsettling policy. A producer does not await
+asynchronous policy or observer completion, although CPU-heavy synchronous
+policy work still runs on the producer's Node event loop.
+Direct subscribers do not cross a Server output-filter boundary. The package
+does not guarantee cluster-complete observations, subscription replay,
+event-gap repair, or exactly-once effects.
+
+This typed local observer handles visible states, removals, and terminal faults.
+Configure `subscriptionQueueCapacity: 250` through `ServerEnvironment.when(...).use(...)`
+before creating the Stand to allow 250 waiting updates beyond the active one:
+
+<!-- docs-snippet-path: packages/server/test/stand/stand-direct-subscription.test.ts -->
+
+```ts
+import { type Stand, type StandSubscription } from "@spine-event-engine/server";
+import { ProjectOverviewStateSchema } from "../../test-fixtures/generated/repository-routing/project_states_pb.js";
+
+export function observeProjects(
+  stand: Stand,
+  onState: (name: string) => void,
+  onRemoval: (id: unknown) => void,
+  onError: (error: Error) => void,
+): StandSubscription {
+  return stand.subscribe(ProjectOverviewStateSchema, {
+    next(update) {
+      if (update.kind === "state") onState(update.state.name);
+      else onRemoval(update.id);
+    },
+    error: onError,
+  });
+}
+```
 
 ### Native and managed hosting
 
@@ -988,10 +1280,123 @@ 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.
 
+### Native reader admission
+
+Configure app-node admission at `ServerOptions.services.readerAdmission`:
+
+- `direct.authenticate({ service, method, value, headers, peer, signal })` authenticates
+  a direct native request. It returns `{ reader, invalidated? }` with verified
+  `{ principal, authorityFacts }` in `reader`, `{ reader: {} }` for deliberate
+  public access, or `undefined` to deny access. `signal` begins before
+  authentication and ends on terminal unary or complete stream exit.
+  The request value contains canonical Proto bytes; `peer` is the Connect
+  `HandlerContext` for that invocation. `invalidated` is a separate local
+  AbortSignal captured by the host; it never enters reader facts or proofs.
+- `forwarded.verify(bytes, proof, peer)` verifies an assertion from a trusted
+  forwarding peer. It must authenticate that peer and validate the supplied
+  proof over the exact bytes. `BrowserServerOptions.forwardingProof.issue(bytes)`
+  supplies the corresponding gateway adapter.
+
+Admission completes before service validation, routing, or subscription mutation.
+Principal IDs and authority facts are copied per invocation. `principal.attributes`
+remains a string map; `authorityFacts` accepts finite JSON values, including
+arrays and nested objects. ActorContext remains separate from authentication.
+Neither the framework nor these ports promise live provider information.
+
+With no admission adapters, native requests remain public. Internal identity
+headers are still rejected without a configured verifier. With a forwarding
+verifier but no direct adapter, a request without a forwarding assertion is
+rejected as unauthenticated. An application that also permits public direct
+requests can explicitly return an empty reader from its direct adapter.
+Malformed assertions and denied authentication return `UNAUTHENTICATED`;
+unexpected adapter faults return sanitized `INTERNAL`. Explicit cancellation,
+availability, and permission statuses retain their meaning.
+
+`ManagedServerApplication` accepts `readerAdmission` for its Coordinator listener
+and `forwardingProof` for Coordinator-to-child requests. Configure the receiving
+child Servers with their verifier as well. Each hop verifies its incoming
+assertion and issues a new proof for the actual outgoing operation and payload.
+Loopback placement alone does not authenticate a forwarding peer.
+
+A standard session strategy accepts the host signal during `resolve` and
+returns an invalidation signal for local logout, its captured session deadline,
+and strategy close. A custom direct authenticator may omit invalidation, but
+then the host cannot stop an active stream on local logout or expiry. A
+successful unary request releases its operation even while the transport peer
+stays connected. Subscribe releases its operation after definition creation;
+Activate authenticates again and holds its operation through ACK and every
+update. Normal completion, host handler iterator return, cancellation, and host
+close stop the operation. Raw Connect clients must abort an explicit
+`AbortSignal` or call `SubscriptionService.Cancel` to stop remote stream work;
+returning from the client iterator alone does not signal transport cancellation.
+An active stream in another process receives no local signal.
+
+```ts
+import type { SignedSessions } from "@spine-event-engine/auth";
+import { Server, type ReaderAdmissionResult, type ServerOptions } from "@spine-event-engine/server";
+
+/**
+ * Configures direct native bearer admission with the local session strategy.
+ *
+ * @param sessions Strategy also used by the application's logout action.
+ * @param contexts Application Bounded Contexts exposed by this Server.
+ * @returns Server configured for native authentication.
+ */
+function nativeServer(
+  sessions: SignedSessions,
+  contexts: NonNullable<ServerOptions["contexts"]>,
+): Server {
+  return new Server({
+    contexts,
+    services: {
+      readerAdmission: {
+        direct: {
+          /**
+           * Resolves the bearer credential within the host operation.
+           *
+           * @param request Native peer and lifetime facts.
+           * @returns Verified reader and invalidation, or denial.
+           */
+          async authenticate(request): Promise<ReaderAdmissionResult | undefined> {
+            const authorization = request.peer.requestHeader.get("authorization");
+            const token = /^Bearer ([^\s,]+)$/i.exec(authorization ?? "")?.[1];
+            if (token === undefined) return undefined;
+            const session = await sessions.resolve(
+              { kind: "bearer", value: token },
+              request.signal,
+            );
+            if (session?.invalidated === undefined) return undefined;
+            return { reader: { principal: session.principal }, invalidated: session.invalidated };
+          },
+        },
+      },
+    },
+  });
+}
+```
+
+The admitted logout action checks `await sessions.logout(credential)` on that
+same strategy. It reports durable success only for `revoked`; `unavailable`
+and `expiryOnly` remain distinct. Application shutdown closes both Server and
+strategy. A custom authenticator still enforces its own credential and policy
+checks; a token in a header alone does not establish authority.
+
+Authenticated forwarding now requires an issuer; configure both gateway and
+receiving node when updating an existing authenticated deployment. The native
+Server root still does not load the optional auth package. The forwarding ports
+do not make a JVM endpoint understand the TS internal reader assertion.
+
+### Browser hosting
+
 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.
+RPC and auth-route preflight completes before credential extraction. The host
+allows configured CSRF headers alongside Connect and gRPC-Web protocol headers;
+actual responses, including permitted-origin terminal errors, retain exact-origin
+credentialed CORS. Callback responses cannot replace that host policy with a
+wildcard origin.
 
 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
@@ -1011,7 +1416,8 @@ re-query authoritative state after duplicate updates or generic loss notices.
 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
+callback and validates the protocol state in its handler.
+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
@@ -1022,10 +1428,18 @@ 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
+Every credential reader and auth route declares CSRF header names, primary
+credential-cookie names, and supporting state-cookie names. The host snapshots
+these declarations before startup, rejects repeated raw Authorization, Origin,
+configured CSRF headers, and selected cookies, and checks simultaneous primary
+credentials only for the active reader or selected route. Legal split Cookie
+fields and repeated unrelated cookies remain available to the reader.
+`OpaqueSessionCookies` provides a strict reader for a sealed opaque session or
+bearer credential, including CSRF checks; a primary cookie and bearer field
+together are rejected. The legacy `cookies` option cannot be combined with
+`credentials`. Without either, the host reads one valid Bearer field. A reader
+returns a credential, absence, or terminal rejection; a thrown read is terminal
+unavailability. Credentials and raw
 transport metadata do not reach the private backend. The application-supplied
 context resolver replaces caller actor and tenant facts before forwarding.
 
@@ -1050,7 +1464,11 @@ 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
+inside the stored Topic; a stable principal ID is stored beside it. Activate and
+Cancel check the newly admitted reader and Actor/Tenant before stream effects
+or record mutation. Changed authority facts do not change the principal ID.
+An explicit anonymous binding remains distinct from missing legacy identity;
+records with missing identity cannot be claimed by a caller. 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
@@ -1064,11 +1482,21 @@ delivery, global update ordering, nor cluster-complete notification delivery.
 local durable-row abstraction. Inbox and shard storage require a single-tenant
 Delivery storage context shared by all tenants; the packed signal supplies
 the dispatch tenant. 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:
+1000–2147483647 ms. Framework delivery supports command handling, projection
+updates, process-manager reactions, and Aggregate Event reactions. Callbacks must tolerate redelivery:
 lost renewal can prevent stale finalization but cannot undo a callback already
 run. The package exposes no general raw worker callback API.
 
+Repository-backed Command and Event routing awaits recipient Inbox writes and
+notifies Delivery immediately. A successful post through this routing means
+recipient Inbox writes completed; it does not wait for handler execution or row
+acknowledgement. Restart durability depends on the configured storage provider.
+Custom dispatchers define their own completion contract. After an Entity commit, the
+source delivery awaits one outgoing bus handoff attempt through recipient Inbox
+acceptance. A failed publication is reported and contained without re-executing
+a successful source Command. Entity storage, recipient Inbox writes, and source
+acknowledgement remain separate operations.
+
 Inbox reads return `InboxMessage` with a full-precision Protobuf `Timestamp` in
 `whenReceived`. `InboxMessageInput` requires a precise `Timestamp` for new
 receipts. Writes, acknowledgements, and exact removals use an `InboxMessage`
@@ -1124,7 +1552,8 @@ internally and persist their envelope in the target Entity Inbox before any
 handler runs. Projection input uses the same environment Delivery and shared
 Inbox, with its separate recipient identity.
 
-Local posting waits for the result of that signal's delivery attempt. For an
+Local repository-backed posting waits for recipient Inbox writes and scheduling,
+while handler execution and row acknowledgement continue through Delivery. For an
 Agent, successful acceptance and Inbox acknowledgement let posting finish while
 the live handler continues. If Agent execution capacity is unavailable, the input
 stays pending and the local call reports the existing command-posting error.
@@ -1170,9 +1599,9 @@ 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
+rows remain available as duplicate evidence; it is not a delivery-retention
 period. Persisted accepted rows follow their delivery lifecycle and may be
-replayed according to that lifecycle after the deduplication window has elapsed.
+redelivered 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
@@ -1193,8 +1622,8 @@ reception monitor. A custom reception action that completes normally completes
 delivery and the enclosing stage acknowledges the row. An action that rejects
 propagates its error and leaves the row `TO_DELIVER`. `markDelivered()` does not
 mean domain processing succeeded.
-Managed repository replay sends actual handler failures to the monitor while
-storage and replay infrastructure errors propagate. A direct `onMessage` callback
+Managed repository delivery sends actual handler failures to the monitor while
+storage and delivery infrastructure errors propagate. A direct `onMessage` callback
 is treated as the endpoint. Handler effects and acknowledgement are separate,
 so a crash between them may redeliver.
 The framework adds no persisted attempts, quarantine, dead-letter, receipt, or