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

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,172 @@ 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 original outgoing envelopes are committed under the
+same execution claim. 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, delivery uses the saved outgoing envelopes and recipient
+bindings. The producing handler and model are not rerun to deliver them.
+Downstream delivery is at least once: a recipient or standalone callback may be
+called again with the same envelope. Application effects must account for that.
+Generated repository and standalone receivers have the required binding metadata.
+Matching raw custom dispatchers without that metadata are rejected for Agent
+output; unrelated dispatchers and ordinary non-Agent posting keep their usual
+behavior.
+
+### 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-delivery`, `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 +821,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.
 
@@ -822,6 +997,11 @@ updates, and process-manager reactions. Callbacks are at-least-once/replay-safe:
 lost renewal can prevent stale finalization but cannot undo a callback already
 run. The package exposes no general raw worker callback API.
 
+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`
+with the same Timestamp contract.
+
 Shard ownership is the only delivery exclusion mechanism and excludes
 concurrent delivery within that shard. Pending and delivered `InboxMessage`
 rows are direct records; a delivered row is the deduplication fact. A handler
@@ -858,7 +1038,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

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"}

package/dist/agent/agent-admission.js

@@ -0,0 +1,127 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { create, equals } from "@bufbuild/protobuf";
+import { AgentAcceptedInvocationSchema, AgentCodeRevisionSchema, AgentExecutionScopeSchema, AgentHandlerBindingSchema, AgentHandlerKind, AgentHandlerOrigin, AgentInboxOrderSchema, AgentInvocationKeySchema, AgentPolicyRevisionSchema, AgentSchemaRevisionSchema, AgentSignalKeySchema, } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+/**
+ * Materializes provider admission without running application handlers.
+ */
+export const AgentAdmission = Object.freeze({
+    matchesHandler(accepted, registered, ordinal) {
+        return equals(AgentHandlerBindingSchema, accepted, binding(registered, ordinal));
+    },
+    create(input) {
+        const sourceSignal = signalKey(input.signal);
+        const bindings = input.handlers.map((handler, ordinal) => binding(handler, ordinal));
+        if (bindings.length === 0)
+            throw new TypeError("Agent admission requires a selected handler.");
+        return create(AgentAcceptedInvocationSchema, {
+            key: create(AgentInvocationKeySchema, {
+                scope: create(AgentExecutionScopeSchema, {
+                    stateType: nonblank(input.stateType, "state type"),
+                    agentKey: nonblank(input.agentKey, "Agent key"),
+                }),
+                sourceSignal,
+            }),
+            recipientId: input.recipientId,
+            signal: input.signal.kind === "command"
+                ? { case: "command", value: input.signal.value }
+                : { case: "event", value: input.signal.value },
+            actor: input.actor,
+            order: create(AgentInboxOrderSchema, {
+                receivedAt: input.inbox.whenReceived,
+                inboxVersion: input.inbox.version,
+                sourceSignal,
+            }),
+            handlers: bindings,
+            codeRevision: create(AgentCodeRevisionSchema, {
+                value: nonblank(input.codeRevision, "code revision"),
+            }),
+            schemaRevision: create(AgentSchemaRevisionSchema, {
+                value: nonblank(input.schemaRevision, "schema revision"),
+            }),
+            policyRevision: create(AgentPolicyRevisionSchema, {
+                value: nonblank(input.policyRevision, "policy revision"),
+            }),
+        });
+    },
+});
+/**
+ * Requires the original typed signal identity before constructing its durable key.
+ *
+ * @param signal Accepted Command or Event envelope.
+ * @returns Typed source identity.
+ */
+function signalKey(signal) {
+    if (signal.kind === "command") {
+        const id = signal.value.id;
+        if (id === undefined)
+            throw new TypeError("Agent admission requires the original typed signal ID.");
+        return create(AgentSignalKeySchema, { id: { case: "command", value: id } });
+    }
+    const id = signal.value.id;
+    if (id === undefined)
+        throw new TypeError("Agent admission requires the original typed signal ID.");
+    return create(AgentSignalKeySchema, {
+        id: { case: "event", value: id },
+    });
+}
+/**
+ * Converts one generated handler identity without reinterpreting its route.
+ *
+ * @param registered Selected generated handler metadata.
+ * @param ordinal Position within this accepted signal.
+ * @returns Complete stored binding.
+ */
+function binding(registered, ordinal) {
+    const handler = registered.handler;
+    const kind = handler.kind === "command-assignment"
+        ? AgentHandlerKind.AGENT_HANDLER_COMMAND_ASSIGNMENT
+        : handler.kind === "command-reaction"
+            ? AgentHandlerKind.AGENT_HANDLER_COMMAND_REACTION
+            : handler.kind === "event-reaction"
+                ? AgentHandlerKind.AGENT_HANDLER_EVENT_REACTION
+                : undefined;
+    if (kind === undefined)
+        throw new TypeError("Agent admission selected an unsupported handler.");
+    return create(AgentHandlerBindingSchema, {
+        ordinal,
+        receiverType: registered.entity.schema.typeName,
+        methodName: handler.methodName,
+        kind,
+        signalType: handler.messageFullTypeName,
+        origin: handler.origin === "external"
+            ? AgentHandlerOrigin.AGENT_HANDLER_EXTERNAL
+            : AgentHandlerOrigin.AGENT_HANDLER_DOMESTIC,
+        parameterCount: handler.parameterCount,
+        ...(handler.where === undefined
+            ? {}
+            : {
+                whereEventField: handler.where.eventField,
+                whereEquals: handler.where.equals,
+            }),
+    });
+}
+/**
+ * Requires a nonblank serialized identity or revision.
+ *
+ * @param value Text to validate.
+ * @param label Diagnostic field name.
+ * @returns Original checked text.
+ */
+function nonblank(value, label) {
+    if (value.trim() === "")
+        throw new TypeError(`Agent admission requires ${label}.`);
+    return value;
+}
+//# sourceMappingURL=agent-admission.js.map

package/dist/agent/agent-admission.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-admission.js","sourceRoot":"","sources":["../../src/agent/agent-admission.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAGpD,OAAO,EACL,6BAA6B,EAC7B,uBAAuB,EACvB,yBAAyB,EACzB,yBAAyB,EACzB,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,wBAAwB,EACxB,yBAAyB,EACzB,yBAAyB,EACzB,oBAAoB,GAIrB,MAAM,+EAA+E,CAAC;AAqFvF;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAyB,MAAM,CAAC,MAAM,CAAC;IAChE,cAAc,CACZ,QAA6B,EAC7B,UAAqC,EACrC,OAAe;QAEf,OAAO,MAAM,CAAC,yBAAyB,EAAE,QAAQ,EAAE,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC,CAAC;IACnF,CAAC;IAED,MAAM,CAAC,KAA0B;QAC/B,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC7C,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACrF,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;QAC/F,OAAO,MAAM,CAAC,6BAA6B,EAAE;YAC3C,GAAG,EAAE,MAAM,CAAC,wBAAwB,EAAE;gBACpC,KAAK,EAAE,MAAM,CAAC,yBAAyB,EAAE;oBACvC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,EAAE,YAAY,CAAC;oBAClD,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC;iBAChD,CAAC;gBACF,YAAY;aACb,CAAC;YACF,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,MAAM,EACJ,KAAK,CAAC,MAAM,CAAC,IAAI,KAAK,SAAS;gBAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE;gBAChD,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE;YAClD,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,KAAK,EAAE,MAAM,CAAC,qBAAqB,EAAE;gBACnC,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY;gBACpC,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,OAAO;gBACjC,YAAY;aACb,CAAC;YACF,QAAQ,EAAE,QAAQ;YAClB,YAAY,EAAE,MAAM,CAAC,uBAAuB,EAAE;gBAC5C,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY,EAAE,eAAe,CAAC;aACrD,CAAC;YACF,cAAc,EAAE,MAAM,CAAC,yBAAyB,EAAE;gBAChD,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,cAAc,EAAE,iBAAiB,CAAC;aACzD,CAAC;YACF,cAAc,EAAE,MAAM,CAAC,yBAAyB,EAAE;gBAChD,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,cAAc,EAAE,iBAAiB,CAAC;aACzD,CAAC;SACH,CAAC,CAAC;IACL,CAAC;CACF,CAAC,CAAC;AAEH;;;;;GAKG;AACH,SAAS,SAAS,CAAC,MAAqC;IACtD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC9B,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,IAAI,EAAE,KAAK,SAAS;YAClB,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;QAChF,OAAO,MAAM,CAAC,oBAAoB,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IAC3B,IAAI,EAAE,KAAK,SAAS;QAClB,MAAM,IAAI,SAAS,CAAC,wDAAwD,CAAC,CAAC;IAChF,OAAO,MAAM,CAAC,oBAAoB,EAAE;QAClC,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE;KACjC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,OAAO,CAAC,UAAqC,EAAE,OAAe;IACrE,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;IACnC,MAAM,IAAI,GACR,OAAO,CAAC,IAAI,KAAK,oBAAoB;QACnC,CAAC,CAAC,gBAAgB,CAAC,gCAAgC;QACnD,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,kBAAkB;YACnC,CAAC,CAAC,gBAAgB,CAAC,8BAA8B;YACjD,CAAC,CAAC,OAAO,CAAC,IAAI,KAAK,gBAAgB;gBACjC,CAAC,CAAC,gBAAgB,CAAC,4BAA4B;gBAC/C,CAAC,CAAC,SAAS,CAAC;IACpB,IAAI,IAAI,KAAK,SAAS;QAAE,MAAM,IAAI,SAAS,CAAC,kDAAkD,CAAC,CAAC;IAChG,OAAO,MAAM,CAAC,yBAAyB,EAAE;QACvC,OAAO;QACP,YAAY,EAAE,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,QAAQ;QAC/C,UAAU,EAAE,OAAO,CAAC,UAAU;QAC9B,IAAI;QACJ,UAAU,EAAE,OAAO,CAAC,mBAAmB;QACvC,MAAM,EACJ,OAAO,CAAC,MAAM,KAAK,UAAU;YAC3B,CAAC,CAAC,kBAAkB,CAAC,sBAAsB;YAC3C,CAAC,CAAC,kBAAkB,CAAC,sBAAsB;QAC/C,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS;YAC7B,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC;gBACE,eAAe,EAAE,OAAO,CAAC,KAAK,CAAC,UAAU;gBACzC,WAAW,EAAE,OAAO,CAAC,KAAK,CAAC,MAAM;aAClC,CAAC;KACP,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,SAAS,QAAQ,CAAC,KAAa,EAAE,KAAa;IAC5C,IAAI,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,MAAM,IAAI,SAAS,CAAC,4BAA4B,KAAK,GAAG,CAAC,CAAC;IACnF,OAAO,KAAK,CAAC;AACf,CAAC"}