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

package/README.md

@@ -44,7 +44,6 @@ Add generated entities with `BoundedContext.add(...)` and use
 `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
@@ -112,6 +111,20 @@ A failed handler leaves previous persisted state unchanged and
 suppresses produced output. An external HTTP request or other side effect may
 already have happened.
 
+Repository-backed Command and Event posting resolves after recipient Inbox
+writes. Delivery starts immediately and handles the stored row separately, so
+successful posting does not mean the handler has completed. Restart durability
+depends on the configured storage provider; custom dispatchers define their own
+completion contract. A committed Entity awaits one outgoing handoff attempt for
+handler-produced domain Commands and Events. A failed attempt is reported without
+rerunning successful source handling. Internal diagnostic publication remains
+best effort.
+
+New Inbox rows have no completion deadline. After a recipient is handled, the
+first acknowledgement marks its row delivered and keeps that row for five
+seconds as duplicate evidence. A pending row does not expire during a slow
+handler. Cleanup can remove a delivered row once its deadline has passed.
+
 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
@@ -232,14 +245,36 @@ 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.
+For a multitenant receiving Bounded Context, supply an application tenant directory and
+register each accepted tenant through its `keep(tenantId)` method before sending
+tenant-scoped work. The optional environment setting defaults to `SINGLE_TENANT`;
+that mode creates no directory or provider catalog. A multitenant Bounded Context
+requires an environment directory before assembly, even when `withTenantIndex()`
+selects another directory for that Bounded Context. In one environment, a
+single-tenant Identity Bounded Context still uses `SINGLE_TENANT` while a
+multitenant Orders Bounded Context uses the configured directory.
+Both public `tenantIndex` getters return `TenantIndexSetting`, so narrow against
+`SINGLE_TENANT` before calling directory methods. A single-tenant Bounded Context always
+returns the marker, even when its environment has a directory for other Bounded Contexts.
+Provider catalogs remain available as storage-provider APIs, but environment
+assembly does not infer membership from them.
+`PersistentTenantIndex.create({ storageFactory, group })` stores registrations
+through the selected factory. Remote providers can retain them across process
+restarts; memory storage remains process-local. Its async factory prepares supported structures by
+default; set `createMissingStructures: false` when the application prepares
+the selected record family separately before data access. Close the index after its admitted work
+finishes; it leaves the supplied storage factory open.
 Unknown tenants fail before reads or handlers run; input never registers them.
 
+The [Orders application](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/orders/README.md)
+demonstrates this setup with memory, PostgreSQL, and Datastore. Its PostgreSQL
+launch uses separate shared, Northwind, and Contoso databases, validates persisted
+membership against configured routing, and prepares supported structures before
+opening the listener. Orders focuses on tenant storage and has no sign-in UI.
+The [Fieldnotes application](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/fieldnotes/README.md)
+demonstrates browser authentication and private data in a single-tenant Bounded
+Context without a tenant index.
+
 Use `EntityQuery.all(...)` when every predicate must match and
 `EntityQuery.either(...)` when any branch may match.
 
@@ -411,6 +446,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.
 
+For a standalone Gateway, call `BrowserServer.run` with a canonical
+`backend.baseUrl` (or discovery), `origins`, `sessions`, `authorize`, `contexts`,
+`clock`, and explicit `bindings`. Supply `credentials` with a
+`BrowserCredentialReader` to select a browser auth engine. The reader and each
+`authRoutes` entry declare `csrfHeaderNames`, `credentialCookieNames`, and
+`stateCookieNames`; empty arrays state that a category is unused. The Gateway
+validates those names before it starts listening, then checks raw headers before
+calling the reader or a route. Preflight never calls the credential reader;
+permitted origins receive credentialed CORS headers covering the configured CSRF
+fields and Connect protocol headers. Connect stops waiting for a reader and
+does not forward its late result when the request is cancelled or its deadline
+passes. The reader receives no abort signal, so its underlying work may continue.
+This setup does not construct a
+`ServerEnvironment` or Bounded Context. Close the returned server at shutdown.
+
 ## Native reader admission
 
 Native authentication is configured through `ServerOptions.services.readerAdmission`.
@@ -423,7 +473,10 @@ 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)
+subscription even with the same ActorContext. The host supplies an operation
+signal before authentication and closes it after unary work or the complete
+Activate stream. A direct authenticator can return a separately captured
+`invalidated` signal for local logout and session expiry. See [native reader admission](REFERENCE.md#native-reader-admission)
 for adapter signatures, public admission, and managed application configuration.
 
 ## Limits

package/REFERENCE.md

@@ -18,6 +18,11 @@ Delivery adapters import `conditionalPickUp` from
 conditional-pickup capability for a `DeliveryWorkRegistry`; it is not part of
 the server root API and does not independently create delivery work.
 
+The same SPI exports `InboxRetention.deadline(nowMs)`. Delivery adapters use it
+when marking a row delivered; it returns a `Date` five seconds after the supplied
+application time in milliseconds. Local storage and remote delivery use this
+one deadline policy without adding a public retention setting.
+
 ## Generated handler-registry SPI
 
 Generated model modules import only their registry data types from
@@ -168,7 +173,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 +213,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 +267,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 +300,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.
 
@@ -596,9 +614,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
@@ -607,9 +625,11 @@ 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.
+`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
@@ -911,6 +931,12 @@ 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,
@@ -1110,8 +1136,8 @@ export const scopedOnCreate =
 ```
 
 `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
@@ -1263,11 +1289,14 @@ transport responses independently.
 
 Configure app-node admission at `ServerOptions.services.readerAdmission`:
 
-- `direct.authenticate({ service, method, value, headers, peer })` authenticates
-  a direct native request. It returns verified `{ principal, authorityFacts }`,
-  an empty object for deliberate public access, or `undefined` to deny access.
+- `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.
+  `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)`
@@ -1294,6 +1323,69 @@ 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
@@ -1305,6 +1397,11 @@ For `BrowserServer` from `@spine-event-engine/server/browser`, origins must be u
 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
@@ -1324,7 +1421,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
@@ -1335,10 +1433,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.
 
@@ -1381,11 +1487,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`
@@ -1402,7 +1518,14 @@ the Entity transaction commit, and before acknowledgement. These checks stop a w
 after it detects that another worker has taken the shard. They do not make
 delivery and handler storage part of one distributed transaction.
 
-`keepUntil` is the optional deduplication-protection deadline, not a second
+New Inbox receipts have no `keepUntil`. The first successful local acknowledgement
+stores `DELIVERED` and a deadline five seconds after that transition in one
+compare-and-set. A repeated acknowledgement returns the first stored
+deadline. The worker passes that stored completion to delivery observers. This
+timing applies to Aggregate, Process Manager, and Projection delivery through
+the local Inbox.
+
+`keepUntil` is the deduplication-protection deadline on a delivered row, not a second
 retention setting. A delivered row is cleanup-eligible when that deadline is
 absent or elapsed (`keepUntil <= now`). Delivery skips per-record mutation checks
 and deletion attempts for rows whose deadline is still in the future. Cleanup
@@ -1419,7 +1542,7 @@ retryable, non-delivered, and still-protected rows are skipped by cleanup. There
 is no additional retention configuration, timer, or scheduler.
 
 Configure one Delivery strategy for the environment before setup. It maps
-targets to shards across all contexts; the default is one shard. For example:
+targets to shards across all Bounded Contexts; the default is one shard. For example:
 
 ```ts
 import {
@@ -1436,12 +1559,111 @@ await ServerEnvironment.instance().completeSetup();
 const context = await BoundedContext.singleTenant("Tasks").build();
 ```
 
-Aggregate commands and Process Manager or Agent commands/events derive their target shard
-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.
+Aggregates, Process Managers, Agents, and Projections derive their Inbox shard
+from this same strategy. Projection Events and Entity-state subscriptions use
+the routed Projection ID and Projection state type, just as other receivers use
+their receiving Entity identity. The framework stores the envelope before
+invoking the handler. Startup notifications cover every configured shard, and
+stored rows are checked against the current strategy before dispatch.
+
+### Receiver-specific shard policies
+
+`DeliveryStrategy.shardFor(targetId, targetType)` receives the packed receiver
+ID and the type URL of its Entity state. `targetType` is neither the signal type
+nor the TypeScript class name. Routing selects recipients first; the strategy
+then selects a shard for each routed recipient.
+
+For example, the Orders application can reserve two of eight shards for its
+`OrderSummary` and `SalesSummary` Projections. Other receiver types use the first
+six shards. Place this strategy in the Orders source directory:
+
+<!-- docs-snippet-path: examples/orders/src/orders-environment.ts -->
+
+```ts
+import type { Any } from "@bufbuild/protobuf/wkt";
+import { TypeUrls } from "@spine-event-engine/core";
+import {
+  ShardIndex,
+  UniformAcrossAllShards,
+  type DeliveryStrategy,
+} from "@spine-event-engine/server";
+import {
+  OrderSummarySchema,
+  SalesSummarySchema,
+} from "../generated/spine/examples/orders/read_models_pb.js";
+
+/**
+ * Reserves two of eight shards for the selected Orders Projections.
+ */
+class OrdersDeliveryStrategy implements DeliveryStrategy {
+  /**
+   * Number of shards in the shared set.
+   */
+  readonly shardCount = 8;
+
+  readonly #business = UniformAcrossAllShards.forNumber(6);
+
+  readonly #views = UniformAcrossAllShards.forNumber(2);
+
+  readonly #viewTypes = new Set([
+    TypeUrls.derive(OrderSummarySchema),
+    TypeUrls.derive(SalesSummarySchema),
+  ]);
+
+  /**
+   * Selects a shard in the receiver's configured range.
+   *
+   * @param targetId Packed receiving Entity identifier.
+   * @param targetType Receiving Entity state type URL.
+   * @returns A shard in the common eight-shard set.
+   */
+  shardFor(targetId: Any, targetType: string): ShardIndex {
+    if (this.#viewTypes.has(targetType)) {
+      const local = this.#views.shardFor(targetId, targetType);
+      return new ShardIndex(6 + local.index, this.shardCount);
+    }
+    const local = this.#business.shardFor(targetId, targetType);
+    return new ShardIndex(local.index, this.shardCount);
+  }
+}
+```
+
+Set `deliveryStrategy: new OrdersDeliveryStrategy()` in the existing
+`ServerEnvironment.when(...).use({...})` call before resolving the environment.
+For Orders, that call is in `configureOrdersEnvironment()`. Preserve its storage
+and tenant settings. Select the profile actually used by the process: configuring
+`Local` does not configure a process whose `NODE_ENV` is `production`.
+
+The resulting shard sets are:
+
+```text
+Other receivers                 -> 0/8, 1/8, 2/8, 3/8, 4/8, 5/8
+OrderSummary and SalesSummary   -> 6/8, 7/8
+```
 
-Local posting waits for the result of that signal's delivery attempt. For an
+Only the listed state types use the second range. Add other Projection state
+types explicitly if they should use it. To place all instances of one receiver
+type on one shard instead, return a fixed value such as `new ShardIndex(6, 8)`
+for that state type. All returned totals must equal `shardCount`: `0/1` and `0/8`
+are distinct shard identities, not aliases.
+
+Keep the mapping deterministic and identical across application processes
+sharing delivery storage. Configure it in processes hosting the receivers,
+before Bounded Context assembly. Shard count is not process count and does not
+assign a receiver to a particular process. Do not change the policy underneath
+pending rows, whose stored shard must agree with the configured strategy.
+
+The built-in uniform strategy hashes the typed ID together with the receiver
+state type. Equal IDs in different receiver types therefore do not guarantee
+co-location. A custom strategy can normalize related receiver types to the same
+hash input when their domain identifier has the same meaning. This does not make
+their separate signal deliveries transactional. The callback has no tenant ID
+or Bounded Context name parameter.
+
+### Reception and processing
+
+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.
@@ -1487,9 +1709,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
@@ -1510,8 +1732,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

package/dist/agent/agent-live-ai-runtime.d.ts

@@ -280,7 +280,7 @@ export declare class AgentLiveAiRuntime implements AgentAi {
      */
     private ticket;
     /**
-     * Completes measured response bytes without replay state.
+     * Completes measured response bytes without recorded state.
      *
      * @param attempts Physical attempt state for this invocation.
      * @param audit Retained history audit for this invocation.

package/dist/agent/agent-live-ai-runtime.js

@@ -578,7 +578,7 @@ export class AgentLiveAiRuntime {
         return ticket;
     }
     /**
-     * Completes measured response bytes without replay state.
+     * Completes measured response bytes without recorded state.
      *
      * @param attempts Physical attempt state for this invocation.
      * @param audit Retained history audit for this invocation.

package/dist/agent/agent-live-budget.d.ts

@@ -13,7 +13,7 @@ export interface AgentPhysicalTicket {
     readonly maxOutputBytes: number | undefined;
 }
 /**
- * Counts one live invocation without durable replay or unacknowledged writes.
+ * Counts one live invocation without durable restart or unacknowledged writes.
  */
 export declare class AgentLiveBudget {
     #private;

package/dist/agent/agent-live-budget.js

@@ -13,7 +13,7 @@
  */
 import { AgentLiveFault } from "./agent-live-fault.js";
 /**
- * Counts one live invocation without durable replay or unacknowledged writes.
+ * Counts one live invocation without durable restart or unacknowledged writes.
  */
 export class AgentLiveBudget {
     limits;

package/dist/agent/agent-live-read-runtime.d.ts

@@ -7,7 +7,7 @@ import type { AgentHistoryPage } from "@spine-event-engine/storage/provider";
 import type { AgentHistoryScope } from "./agent-history.js";
 import { AgentLiveBudget } from "./agent-live-budget.js";
 /**
- * Sequences live Agent reads without durable snapshots or replay.
+ * Sequences live Agent reads without durable snapshots or recorded-operation restart.
  */
 export declare class AgentLiveReadRuntime {
     #private;

package/dist/agent/agent-live-read-runtime.js

@@ -16,7 +16,7 @@ import { TypeUrls } from "@spine-event-engine/core";
 import { AgentHistoryEntrySchema } from "@spine-event-engine/proto/agent";
 import { AgentLiveBudget } from "./agent-live-budget.js";
 /**
- * Sequences live Agent reads without durable snapshots or replay.
+ * Sequences live Agent reads without durable snapshots or recorded-operation restart.
  */
 export class AgentLiveReadRuntime {
     scope;