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

package/README.md

@@ -82,10 +82,12 @@ for the exact contract.
 
 An `@Assign`, `@Command`, `@React`, or `@Subscribe` handler may return its
 usual result directly or through exactly one built-in `Promise<T>` layer. Its
-transaction remains open until that promise settles. Nested `Promise<Promise<T>>`
+in-memory Entity draft remains active until that promise settles. Nested `Promise<Promise<T>>`
 results and structural or imported thenable lookalikes are rejected during handler
-analysis. Rejection rolls back framework state and suppresses produced output; it
-cannot roll back an external HTTP request or other side effect.
+analysis. Storage writes happen in separate short operations after the handler succeeds.
+A failed handler leaves previous persisted state unchanged and
+suppresses produced output. An external HTTP request or other side effect may
+already have happened.
 
 Handler return declarations can use native unions for one of several results,
 or fixed tuples for several ordered results. For example,
@@ -129,7 +131,11 @@ class TaskAssignee {
 Place the primary handler decorator first for readability. Reversing the two
 decorators has the same behavior.
 
-Process Managers, but not Aggregates, have protected read-only `select()` during a handler:
+Process Managers have protected read-only `select()` during a handler. Agents use
+the generated `select(query).read()` form with the same actor, tenant, and
+1,000-state limits. Aggregates do not expose handler-scoped queries.
+
+For Process Manager's schema-and-columns query form:
 
 ```ts
 import { EntityQuery, type EntityColumn } from "@spine-event-engine/core";
@@ -167,11 +173,11 @@ These reads are eventually consistent. `limit()` may not exceed 1,000, and
 `all()` can be expensive for a large read model; prefer a targeted, ordered,
 bounded query.
 
-The Entity type identifies its context among those registered with the same
+The Entity type identifies its Bounded Context among those registered with the same
 `Server`. For example, an order process can query a product in a catalogue
-context without naming that context. An Entity in another context must allow
+Bounded Context without naming that Bounded Context. An Entity in another Bounded Context must allow
 queries (`query` or `full` visibility). Registering the same Entity type in two
-contexts causes a startup error.
+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.
@@ -185,6 +191,97 @@ for the complete tenant rules and empty-result behavior.
 Use `EntityQuery.all(...)` when every predicate must match and
 `EntityQuery.either(...)` when any branch may match.
 
+## Draft with an Agent
+
+An Agent is a stateful Entity that can ask a model for help while handling a
+Command or Event. For example, a support Agent drafts a reply from ticket facts
+and emits an Event for a person to review. It keeps provider credentials out of
+the handler and records the model interaction. Like other Entities, its ID and
+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.
+
+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
+complete [domain Protos](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/proto/spine/examples/support/states.proto),
+[a model definition](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/src/model.ts), and
+[an Agent implementation](https://github.com/SpineEventEngine/spine-ts/blob/master/examples/support/src/index.ts).
+
+The handler invokes a typed model operation, updates its draft only on success,
+and emits a domain outcome. This abbreviated declaration uses the example's
+actual generated messages:
+
+<!-- prettier-ignore-start -->
+
+<!-- docs-snippet-path: examples/support/src/index.ts -->
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { Agent, Assign } from "@spine-event-engine/server";
+import type { DraftSupportReply } from "../generated/spine/examples/support/commands_pb.js";
+import {
+    SupportReplySuggestedSchema,
+    SupportReplyFailedSchema,
+    type SupportReplySuggested,
+    type SupportReplyFailed,
+} from "../generated/spine/examples/support/events_pb.js";
+import { SupportDraftStateSchema } from "../generated/spine/examples/support/states_pb.js";
+import type { SupportTicketId } from "../generated/spine/examples/support/types_pb.js";
+import { draftSupportReply } from "./model.js";
+
+/** Proposes support replies for a person's review. */
+class SupportDraftAgent extends Agent<SupportTicketId, typeof SupportDraftStateSchema> {
+    /**
+     * Drafts a reply from the submitted ticket facts.
+     *
+     * @param command Ticket facts and an explicit conversation.
+     * @returns The proposed reply or a recorded failure outcome.
+     */
+    @Assign
+    async draft(command: DraftSupportReply): Promise<SupportReplySuggested | SupportReplyFailed> {
+        if (command.conversation === undefined || command.request === undefined)
+            throw new TypeError("A draft requires ticket facts and a conversation.");
+        const result = await this.ai.invoke(draftSupportReply, {
+            call: "draft-support-reply",
+            conversation: command.conversation,
+            input: command,
+        });
+        const outcome = {
+            id: this.id,
+            request: command.request,
+            conversation: command.conversation,
+            operation: result.operationId,
+        };
+        if (!result.ok) return create(SupportReplyFailedSchema, outcome);
+        this.update((state) =>
+            Object.assign(state, {
+                id: this.id,
+                request: command.request,
+                conversation: command.conversation,
+                reply: result.value,
+            }),
+        );
+        return create(SupportReplySuggestedSchema, { ...outcome, reply: result.value });
+    }
+}
+```
+
+<!-- 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.
+
+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.
+
 ## Native lifecycle and routing
 
 `Server.run()` is the standalone process form: it handles `SIGINT`/`SIGTERM`

package/REFERENCE.md

@@ -1,7 +1,6 @@
 # @spine-event-engine/server reference
 
-This reference gives application developers and coding agents the detailed
-server contracts. For an introduction and examples, start with the
+This reference gives coding agents the detailed server contracts. For an introduction and examples, start with the
 [server README](README.md).
 
 ## Testing entry point
@@ -238,11 +237,13 @@ route registration API.
 
 Handlers may return their established result directly or through exactly one built-in `Promise<T>`.
 Nested promises and structural or imported thenable lookalikes are rejected during handler analysis.
-The entity transaction remains open until that promise settles; rejection rolls
-back framework state and suppresses produced output, but cannot undo external
-side effects. Process Managers may use their protected read-only query surface
-for eventually consistent Entity state during a handler. Aggregates must not
-use these reads for invariants.
+The in-memory Entity draft remains active until that promise settles. Storage
+writes use separate short operations after the handler succeeds; a rejected
+handler leaves no partial persisted state or produced signals, but cannot undo
+external side effects. Process Managers may use their protected read-only query
+surface for eventually consistent Entity state during a handler. Agents expose
+the generated `select(query).read()` form under the same handler scope and
+limits. Aggregates must not use these reads for invariants.
 
 `select(schema, columns)` supports `byId`, typed `where`, `orderBy`,
 `limit`, `read`, `findById`, and `all`. A Process Manager query returns at most
@@ -329,10 +330,11 @@ A command-input `@Command` method is a command substitution receptor: it is
 the one effective receptor for that Command type (instead of an `@Assign`),
 commits its Entity state before its one-or-more returned Commands are detached
 for in-process produced-command enqueue, and receives an optional `CommandContext`.
-Only Process Manager repositories support `@Command` handlers. Aggregate and
-Projection repositories reject command-input substitutions and event- or
+Process Manager and Agent repositories support `@Command` handlers. Aggregate
+and Projection repositories reject command-input substitutions and event- or
 rejection-input command reactions during generated metadata ingestion and
-repository construction.
+repository construction. Agents reject `@Subscribe`, including Entity-state
+Apply handlers, at generation and runtime registration.
 Event- and rejection-input `@Command` methods remain Event- or
 rejection-to-command reactions on Event Bus.
 
@@ -542,6 +544,11 @@ handler registry for classes registered with `add(EntityClass)`;
 `buildAsync()` performs that discovery and assembly. `build()` remains for
 explicit `Repository` registration. A built context contains `CommandBus`,
 `EventBus`, `Stand`, repositories, and its storage lifecycle.
+Trusted server-side code can call `context.getRepository(EntityClass)` to obtain
+the already registered repository for that exact constructor. The lookup does
+not create a repository or read Entity state; an absent class or closing
+Bounded Context fails explicitly. Application code must authorize users before
+exposing repository reads through a client bridge.
 
 Generated writer output is an unversioned receiver collection and records
 command substitutions explicitly. The ingestor rejects retired versioned
@@ -615,8 +622,10 @@ configuration and Datastore custom record storage registered for
 `SubscriptionRecord` are used by the registry. The registry uses one
 record-storage handle, while the context closes the registry.
 
-`Entity` is the state base class. `Aggregate`, `Projection`, and
-`ProcessManager` identify the three entity families. Handler decorators are
+`Entity` is the state base class. `Aggregate`, `Projection`,
+`ProcessManager`, and `Agent` identify the four entity families. Agent state
+declares canonical Proto kind `ENTITY` and uses the same Spine `Version`.
+Handler decorators are
 `@Assign`, `@Command`, `@React`, and `@Subscribe`. A command-accepting
 handler uses `@Throws(GeneratedRejection)` to declare its possible domain
 rejections. Write the primary handler decorator first and `@Throws` immediately
@@ -633,6 +642,173 @@ zero. A dispatch that produces Events or changes state or lifecycle advances it
 once; no-op and rejected dispatches do not. Repositories restore and persist the
 full Version, including its timestamp, across current state, history, and Stand.
 
+## Agent execution
+
+Agents extend `Agent<Id, typeof StateSchema>`. The state declares Proto kind
+`ENTITY`; IDs, state, Version, validation and routing use the normal Entity
+contracts. Agents accept `@Assign`, `@React` and `@Command`, including declared
+rejections as inputs. They reject `@Subscribe` and Entity-state Apply handlers.
+The Agent runs only after an accepted signal. A model response or timer cannot
+start a new autonomous Entity loop.
+
+### Configuration
+
+Register a factory-created `AiRegistry`, enable `persistSystemEvents()`, and
+configure `agentCodeRevision` plus `ai.models` for each Agent repository. Use
+an empty `models` array when that Agent has no model calls. Readiness requires
+indexed Agent history and execution storage from the selected provider.
+The [Support Bounded Context](../../examples/support/src/index.ts) uses generated
+registration with these options.
+
+Configuration has these scopes:
+
+| Scope           | Setting                                  | Effect                                                                   |
+| --------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
+| Server          | `Server.withAi(registry)`                | Default registry for Bounded Context builders assembled by that server.  |
+| Bounded Context | `BoundedContextBuilder.withAi(registry)` | Explicit registry replacing the server default for that Bounded Context. |
+| Repository      | `ai.defaultModels`                       | Generation and decision defaults before the registry's defaults.         |
+| Repository      | `ai.allowedModels`                       | Deployment references the Agent may use.                                 |
+| Repository      | `ai.resolveModel`                        | Optional accepted-source choice before the Agent handler.                |
+| Repository      | `ai.authorizeSelection`                  | Authorizes explicit choices and staged preference changes.               |
+| Repository      | `ai.invocationLimits`                    | Limits that can narrow the registry's whole-signal limits.               |
+| Instance        | `this.ai.select(kind, ref)`              | A saved preference applied to later accepted signals.                    |
+
+A prebuilt Bounded Context already has its registry; adding it to a server does not
+reconfigure it. An instance preference takes precedence over its repository
+default, which takes precedence over the effective registry default. Passing
+`undefined` to `select` restores inheritance. Selection must satisfy the
+repository policy and `authorizeSelection` callback; it cannot extend the
+repository's allowed deployments. The current signal keeps its original selection.
+
+`resolveModel(kind, scope, sourceMessage, control)` can choose a registered
+deployment from a detached copy of the original accepted Command or Event
+payload. A concrete result overrides preference and default precedence for that
+signal; `undefined` preserves it. This allows an Agent without a configured
+default to start after a deployment is appended to the bound registry. The
+runtime checks repository allowlists, capabilities and `authorizeSelection`
+before saving the selection and connection identity. A saved selection is reused
+on continuation. Resolver and authorization callbacks receive linked cancellation
+and the smaller of the invocation deadline and registry hook timeout. An
+effective `this.ai.select()` change, including reset to inheritance, is
+authorized before the Entity transition and preference Events commit; a no-op
+change skips that callback.
+
+Model registrations resolve a credential-free connection identity and authorize
+use for the original actor, tenant, Agent and source signal. Connection callbacks
+can obtain an API key, refreshed token, cloud credential or local model handle
+through application code. The optional adapter supplies a guarded fetch function
+for provider construction. Spine does not implement a provider's login flow.
+See [adapter configuration](../ai-vercel-ax/README.md).
+
+### Acceptance and completion
+
+Before acknowledging Agent intake, the runtime saves the original signal,
+recipient, selected handlers and code/schema/policy revisions. The scheduler
+processes one accepted signal at a time per Agent instance, under a provider
+claim. Different instances can run concurrently within configured limits.
+Bounded Contexts using the same registry object share its capacity within the process.
+Signals beyond the bounded in-memory waiting queue remain durably pending.
+Waiting before a fresh execution starts precedes its deadline. Once execution
+starts, recovery continues with the saved deadline and counts. The same deadline
+bounds an awaited application handler. Expiry or Bounded Context shutdown ends that wait
+and prevents late handler results from changing Entity state or emitting signals;
+it cannot stop arbitrary application JavaScript or undo external effects.
+
+Newly accepted work supplies its repository and tenant to prompt discovery.
+Periodic discovery reads tenant pages and constructs repository scopes as they
+are needed. It retains at most one page of 16 tenants, four periodic scan scopes,
+and 64 scopes awaiting a prompt scan. A turn requests at most one tenant page
+and reads at most four pending-work pages. It does not load the complete tenant
+catalog or retain a scan position for every tenant.
+
+A sweep finishes before another begins. The next starts no earlier than five
+seconds after the preceding sweep started, measured by `Time`; longer sweeps
+restart after completion. This lets discovery reach tenants near the end of a
+large catalog and find later admissions on the next sweep. Periodic scans keep
+their turn during new arrivals, including while execution capacity is full.
+A pending catalog request does not block prompt scans of known scopes.
+
+Bounded Context shutdown stops waiting for discovery reads even if a provider ignores
+cancellation. Late results cannot submit work or restart scanning. Built-in
+adapters use their available cancellation and timeout controls; detaching the
+scheduler does not guarantee cancellation of an already issued native request.
+
+The signal's matching handlers share one Entity draft. Each handler can await
+`this.ai.invoke()` through the protected Spine facade. Calls in one handler must
+be sequential and finish before it returns. Requests, results and
+validation failures are saved as the operation progresses. The final accepted
+state, Version, history and outgoing Command obligations are committed under the
+same execution claim. Emitted domain Events enter immutable Agent history but are
+not stored as delivery obligations. A no-op still completes its execution record. Waiting for
+a provider does not hold a database transaction open.
+
+Recovery compares the registered handler, schema and policy with accepted work.
+A saved named call can reuse its result; changing that call's input or prepared
+request is a mismatch, not a new attempt. Domain code should derive its decisions
+from accepted signals and recorded reads. Arbitrary external effects performed
+by handler code are outside the model/tool journal.
+
+After completion, emitted domain Events are handed once to the Bounded Context's
+normal EventBus. The Agent does not track Event recipients, retry a failed handoff,
+or replay Event delivery after restart. Immutable Agent history remains readable
+independently of EventBus delivery. Saved outgoing Commands retain their original
+IDs and recipient bindings for recovery without rerunning the producing handler
+or model. Generated repository and standalone Command receivers provide the
+required binding metadata; matching raw custom Command dispatchers without it
+are rejected.
+
+### Retained history
+
+Every Agent records conversations, System Events and its emitted domain Events.
+The paired System Context EventStore also keeps System Events. Agent history
+reads use dedicated repository indexes for that instance and tenant, rather than
+scanning the Bounded Context-wide stores. Memory storage lasts for the process; choose a
+persistent provider when records must survive process termination.
+
+| Protected method               | Returned `HistoryPage.items`                                                   |
+| ------------------------------ | ------------------------------------------------------------------------------ |
+| `fullHistory(request)`         | `AgentHistoryEntry` oneof: conversation record, System Event, or domain Event. |
+| `conversationHistory(request)` | `ConversationRecord` for the required `conversation` ID.                       |
+| `systemEventHistory(request)`  | Original System Event envelopes.                                               |
+| `domainEventHistory(request)`  | Original domain Event envelopes emitted by this Agent.                         |
+
+All methods return newest entries first. A request supplies positive `pageSize`
+and an optional opaque cursor; `nextCursor` continues toward older entries.
+There is no fixed 100-item or page-byte ceiling. Reads made during a handler count
+toward any configured invocation limits for recorded reads and recovery data. Ordering
+uses the full Spine `Time` timestamp, category and existing record ID. There is
+no repository-managed history counter. Cursors cannot be transferred across
+Agents, tenants, categories or conversations.
+
+Recording has no off switch, expiry policy or Agent-specific purge operation.
+Archive and logical deletion retain the history. General physical Entity deletion
+is a separate feature; this API does not introduce it. Authentication callbacks do not become conversation records. Hidden model
+reasoning is not part of the audit API. The records describe the supplied
+requests, received supported content, tool calls and admitted outcomes.
+
+Use `BlackBox.readAgentHistory(AgentClass, id, request)` to inspect full
+history in an application test. `BlackBox.readSystemEvents(ids)` reads the paired
+System store by exact Event IDs. See the [testing reference](../testing/REFERENCE.md)
+and [complete support tests](../../examples/support/test/support-blackbox.test.ts).
+
+For a trusted application bridge, `context.getRepository(AgentClass)` returns
+the registered Agent `Repository`, which exposes
+`agentHistory(id, scope)` with the same four history methods and page contracts.
+The scope is explicit: pass `{}` in a single-tenant Bounded Context or
+`{ tenantId }` in a multitenant Bounded Context. The repository also exposes
+`agentExecution(id, sourceCommandOrEventId, scope)` for the exact recorded phase:
+`accepted`, `active`, `completed-pending-commands`, `completed`, or `terminated`.
+An absent record returns `undefined`; it does not establish completion. These
+reads use indexed storage without restoring an Agent. The application bridge
+must authorize access before calling either method; actor metadata does not
+grant read permission.
+
+If a selected model's `authorizeUse` callback explicitly returns `false` at
+Agent claim time, the execution becomes `terminated` with one
+`AgentInvocationTerminated` System Event carrying `MODEL_USE_DENIED`. No Agent
+handler runs and no application-domain result Event is emitted. Callback
+exceptions and infrastructure failures remain distinct from this denial.
+
 ## Signals, validation, and rejection behavior
 
 `CommandBus` validates every accepted command from Proto validation options
@@ -646,18 +822,18 @@ UUIDs; fixed IDs belong only to existing source envelopes retained through the
 normal origin chain.
 
 An application handler throws a generated core `RejectionThrowable` for a
-domain rejection declared with `@Throws`. The repository rolls back state,
-version, lifecycle, and output; it schedules the typed rejection event independently. Command service
+domain rejection declared with `@Throws`. The repository discards the unaccepted
+draft and output, retaining the previous state, Version and lifecycle; it schedules the typed rejection event independently. Command service
 acknowledgement remains an accepted `Ack`. Rejection-event posting can be
 unobserved by inactive, full, or closed subscriptions and a posting failure is
 an internal diagnostic, not a retry guarantee.
 
 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. System
-event persistence is optional: `persistSystemEvents()` enables the paired
-System Context's separate storage; otherwise the bus validates, dispatches,
-and notifies without appending. Schemas may come from an external dispatcher or
+System Context `EventBus`, so they never enter the domain EventStore.
+`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
 a registered internal repository producer. A producer-only schema is not
 thereby an external dispatch route.
 
@@ -681,6 +857,21 @@ a starting time, and has no durable operation identity, progress, Inbox
 catch-up delivery, restart, resumption, or historical/live coordination. It is
 not JVM-equivalent Projection catch-up.
 
+Event Topics accept `include_all` or equality filters on the complete
+`context.past_message` Origin. The filter value must be a valid packed
+`spine.core.Origin`; other Event field paths, operators, ID filters, empty
+filter trees, and malformed values are rejected. Existing composite-filter
+limits apply. This is the immediate previous signal, not any ancestor in a
+causal chain. Tenant isolation remains independent of the filter.
+
+Origin filters use Protobuf value equality for the entire supported message,
+including actor context and grand-origin. Packed `Any` payloads retain their
+exact type URL and bytes. Expected Origins with unknown fields in their nested
+message structure are unsupported and rejected; actual Origins with such
+unknown fields cannot match. This avoids silently ignoring fields while keeping
+the same equality semantics as Spine JVM for supported filters. The same rule
+applies to direct and stored subscription definitions.
+
 Active subscription streams and queues are process-local. `Stand` serves
 authoritative queries from current state and Entity subscriptions observe
 committed `EntityStateChanged` messages on the paired System Context EventBus,
@@ -706,7 +897,8 @@ group of complete server replicas when the framework handles process shutdown.
 and installs no process signal handlers; that host closes the returned handle.
 Both require a positive safe-integer
 `processCount` and an ESM `moduleUrl`; it never derives a process count from
-the machine. Its optional `host` and required nonzero `port` bind the public
+the machine. Its optional `host` and required `port` (zero selects an OS-assigned
+port) bind the public
 Coordinator listener. Every child executes that same module and calls the
 module's `createServer({ host: "127.0.0.1", port: 0 })`. The child reports its
 actual loopback endpoint only after its local readiness gates settle. The parent
@@ -725,11 +917,24 @@ inspect CPU availability and does not constrain the application's independently
 chosen `DeliveryStrategy` or shard count. Direct `Server.run()` and browser
 hosting remain independent of managed Node deployment.
 
+Managed close drains Delivery before cancelling subscription relays. Child listeners
+remain available through relay cancellation, and final child close follows relay
+cleanup. A failed cleanup phase can be retried. Private child acknowledgement
+and process reaping retain their finite process-control graces. A permanently
+blocked application effect can keep explicit close pending.
+
 If no child is READY, Command and Query return gRPC `UNAVAILABLE`. The
 Coordinator does not enter application intake and does not retry the selected
 call on a sibling child. Subscription fan-out follows current READY members;
 later and replacement members attach the retained subscription before managed
 admission.
+Each native child sends a response-only successful activation ACK after its
+listener attaches. The Coordinator waits for every required child ACK before
+emitting one ACK with the logical public subscription ID and Topic; a child
+failure before readiness cancels admitted siblings. Business updates do not
+serve as readiness signals, and later joining children do not emit another
+logical ACK. An ACK confirms attachment, not durable replay or delivery of
+future updates.
 
 `ServerOptions` is native-only: it configures contexts, resources, services,
 and the native listener. It has no `browser` option and the root package does
@@ -844,12 +1049,15 @@ absent or elapsed (`keepUntil <= now`). Delivery skips per-record mutation check
 and deletion attempts for rows whose deadline is still in the future. Cleanup
 and retained-row duplicate recognition use the same applicable clock. Eligible
 rows still receive final time and shard checks before deletion.
-Direct local storage atomically verifies ownership and
-the exact delivered snapshot during removal. A remote adapter may instead read
-and compare the snapshot before sending a separate best-effort removal request;
-that sequence is not an atomic compare-and-delete guarantee. Pending, retryable,
-non-delivered, and still-protected rows remain. There is no additional retention
-configuration, timer, or scheduler.
+Direct local storage checks the supplied delivered status and deadline again,
+then deletes by ID while the operation is active. It does not re-read the stored
+row or compare its snapshot, and the shard session is not checked again after
+deletion. A row changed between the checks and deletion can therefore be
+removed. Cancellation stops subsequent cleanup attempts; deletions already
+completed remain. The remote adapter sends a separate bounded removal request,
+without an atomic compare-and-delete guarantee from this client. Pending,
+retryable, non-delivered, and still-protected rows are skipped by cleanup. There
+is no additional retention configuration, timer, or scheduler.
 
 `BoundedContextBuilder.withDeliveryStrategy(strategy)` snapshots a validated
 immutable strategy for its Entity Inbox; the default is one shard. For example,
@@ -863,7 +1071,7 @@ const context = BoundedContext.singleTenant("Tasks")
   .build();
 ```
 
-Aggregate commands and Process Manager commands/events derive their target shard
+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. Local intake can directly drain the persisted Inbox in the
 current request path. Attached `ServerEnvironment` ports acknowledge admission
@@ -878,6 +1086,11 @@ before source client/storage. `DeliverySource` is not configured on
 durable supervisor state, topology failover, exactly-once effects, or automatic
 retry of unknown remote mutations.
 
+Direct `DeliverySupervisor.close({ graceMs })` stops new admission and source
+activity. Its `graceMs` defaults to 30,000 ms and bounds active-work grace and
+release cleanup separately. After those waits, close may still await entered
+work that has not settled; it is not a hard total close deadline.
+
 Each Inbox read is bounded to one page. That bound does not limit the total
 pending work: an active drain continues from the last row read until that scan
 ends. It restarts from the beginning only if the completed scan delivered
@@ -898,11 +1111,39 @@ the remote server.
 `DeliveryMonitor` is an instantiable, customizable policy seam exposing
 asynchronous continuation, start/completion, failed-reception, pickup-failure,
 and already-picked hooks.
-`FailedReception` supplies only `markDelivered()` and one immediate
-`repeatDispatching()` action; the framework adds no attempt history, timer,
-backoff, quarantine, dead-letter, receipt, marker, or scheduler policy. A failed
-durable acknowledgement keeps that row pending, blocks later rows for its
-target during the run, and does not prevent independent targets from running.
+`FailedReception` supplies `markDelivered()` and immediate
+`repeatDispatching()` actions for failed processing. The default marks a failed
+reception delivered; independent targets continue. A custom monitor may repeat
+the dispatch and is consulted again if that attempt fails. Monitor and selected
+action errors propagate. A successful handler followed by a failed acknowledgement
+retries acknowledgement up to three times without deliberately rerunning the
+handler. Exhausted acknowledgement leaves the row pending and does not call the
+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
+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
+marker policy. The supervisor rescans pending shards every 10 seconds by default;
+the stale-session threshold is separately 60 seconds.
+After a failed finite run, release-generated remote observations of that shard
+are held locally until the next periodic rescan, preventing an immediate
+self-triggered retry loop. Explicit notifications remain admissible. A newly
+enqueued remote row on that shard may wait for the next rescan; other shards
+continue, and other processes may each attempt the failed row before applying
+local suppression. This timing is not a delivery deadline.
+
+`BoundedContext.close()` stops external admission, drains accepted framework
+work, and then closes buses, subscriptions, Stands, and repository bindings.
+Cleanup failures are aggregated and may be retried. A committed Entity Event,
+reactor or Process Manager Event, and System Event receives one first-publication
+attempt; a contained failure is logged and does not schedule publication again.
+Persisted System Events use a separate fixed storage group. Command acceptance
+alone does not promise recipient completion. Processing retries for Inbox rows
+and acknowledgement recovery remain separate Delivery behavior.
 
 `Environment` resolves the Node `local` or `production` profile once from
 `NODE_ENV`. `ServerEnvironment` resolves configured facilities once for that

package/dist/agent/agent-admission.d.ts

@@ -0,0 +1,80 @@
+import type { Any } from "@bufbuild/protobuf/wkt";
+import type { ActorContext, Command, Event } from "@spine-event-engine/proto";
+import { type AgentAcceptedInvocation, type AgentHandlerBinding } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { RegisteredHandlerMetadata } from "../handler/handler-metadata.js";
+import type { InboxMessage } from "../delivery/inbox.js";
+/**
+ * Complete source and selected bindings at one durable Inbox handoff.
+ */
+export interface AgentAdmissionInput {
+    /**
+     * Generated Agent state type.
+     */
+    readonly stateType: string;
+    /**
+     * Canonical storage key of the typed recipient.
+     */
+    readonly agentKey: string;
+    /**
+     * Original typed recipient from the persisted Inbox row.
+     */
+    readonly recipientId: Any;
+    /**
+     * Original Command or Event envelope.
+     */
+    readonly signal: {
+        readonly kind: "command";
+        readonly value: Command;
+    } | {
+        readonly kind: "event";
+        readonly value: Event;
+    };
+    /**
+     * Actor selected from the original envelope.
+     */
+    readonly actor: ActorContext;
+    /**
+     * Original durable Inbox receipt and order.
+     */
+    readonly inbox: InboxMessage;
+    /**
+     * Every matching handler in actual execution order.
+     */
+    readonly handlers: readonly RegisteredHandlerMetadata[];
+    /**
+     * Application build revision supplied by Agent registration.
+     */
+    readonly codeRevision: string;
+    /**
+     * Descriptor digest of accepted generated schemas.
+     */
+    readonly schemaRevision: string;
+    /**
+     * Digest of effective AI policy and configuration.
+     */
+    readonly policyRevision: string;
+}
+interface AgentAdmissionAccess {
+    /**
+     * Copies the exact accepted recipient and selected bindings for durable admission.
+     *
+     * @param input Routed Inbox work and registration revisions.
+     * @returns Immutable accepted invocation content.
+     */
+    create(input: AgentAdmissionInput): AgentAcceptedInvocation;
+    /**
+     * Compares every persisted handler-binding field with current registration.
+     *
+     * @param accepted Binding saved with the original invocation.
+     * @param registered Current generated handler metadata.
+     * @param ordinal Expected position in the accepted handler order.
+     * @returns Whether current registration exactly matches the saved binding.
+     */
+    matchesHandler(accepted: AgentHandlerBinding, registered: RegisteredHandlerMetadata, ordinal: number): boolean;
+}
+/**
+ * Materializes provider admission without running application handlers.
+ */
+export declare const AgentAdmission: AgentAdmissionAccess;
+export {};
+//# sourceMappingURL=agent-admission.d.ts.map

package/dist/agent/agent-admission.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-admission.d.ts","sourceRoot":"","sources":["../../src/agent/agent-admission.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAC9E,OAAO,EAYL,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EAEzB,MAAM,+EAA+E,CAAC;AACvF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAChF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC;IAE1B;;OAEG;IACH,QAAQ,CAAC,MAAM,EACX;QAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;KAAE,GACrD;QAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC;IAEtD;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,yBAAyB,EAAE,CAAC;IAExD;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,UAAU,oBAAoB;IAC5B;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,uBAAuB,CAAC;IAE5D;;;;;;;OAOG;IACH,cAAc,CACZ,QAAQ,EAAE,mBAAmB,EAC7B,UAAU,EAAE,yBAAyB,EACrC,OAAO,EAAE,MAAM,GACd,OAAO,CAAC;CACZ;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,oBA4C3B,CAAC"}