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

package/dist/agent/agent-model-selection.d.ts

@@ -0,0 +1,129 @@
+import { type Any } from "@bufbuild/protobuf/wkt";
+import type { MessageSchema } from "@spine-event-engine/core";
+import { type AiControl, type AiRegistry, type AiScope, type ModelRef } from "@spine-event-engine/ai";
+import { backendDefinition, selectDeployment } from "@spine-event-engine/ai/spi/runtime";
+import { AiModelKind, type ModelPreference } from "@spine-event-engine/proto/agent";
+import { type TenantId } from "@spine-event-engine/proto";
+import { type AgentAcceptedInvocation, type AgentSelectedModel } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { RepositoryAiOptions } from "../repository/repository.js";
+interface AgentModelSelectionAccess {
+    /**
+     * Builds the authorization scope from immutable accepted signal facts.
+     *
+     * @param accepted Accepted original signal and recipient.
+     * @param state Generated Agent state descriptor.
+     * @param tenantId Delivery tenant, or undefined for a single-tenant Bounded Context.
+     * @returns Typed actor, Agent, tenant, and source scope.
+     */
+    scope(accepted: AgentAcceptedInvocation, state: MessageSchema, tenantId?: TenantId): AiScope;
+    /**
+     * Returns each model kind required by the repository's capabilities.
+     *
+     * @param registry Effective deployment registry.
+     * @param repository Repository models and selection policy.
+     * @param scope Authenticated accepted-invocation scope.
+     * @param preferences Claim-time per-instance selections.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param sourceMessage Detached original accepted payload when selection is required.
+     * @returns Selected, authorized deployments by available kind.
+     */
+    select(registry: AiRegistry, repository: RepositoryAiOptions, scope: AiScope, preferences: readonly ModelPreference[], signal: AbortSignal, deadlineEpochMs: number | undefined, sourceMessage?: Any): Promise<readonly AgentSelectedModel[]>;
+    /**
+     * Resolves one kind through instance, repository, and Bounded Context precedence.
+     *
+     * @param registry Effective deployment registry.
+     * @param repository Repository models and selection policy.
+     * @param scope Authenticated accepted-invocation scope.
+     * @param preferences Claim-time per-instance selections.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param kind Generation or decision kind to resolve.
+     * @param sourceMessage Detached original accepted payload when selection is required.
+     * @returns Authorized deployment and nonsecret connection identity.
+     */
+    selectKind(registry: AiRegistry, repository: RepositoryAiOptions, scope: AiScope, preferences: readonly ModelPreference[], signal: AbortSignal, deadlineEpochMs: number | undefined, kind: "generation" | "decision", sourceMessage?: Any): Promise<AgentSelectedModel>;
+    /**
+     * Resolves and copies one explicit model from the accepted payload.
+     *
+     * @param registry Effective registry and hook bound.
+     * @param repository Repository selection policy.
+     * @param scope Accepted source and actor.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param kind Generation or decision kind.
+     * @param sourceMessage Detached source supplied by the runner.
+     * @returns A validated explicit model or absence.
+     */
+    resolveOverride(registry: AiRegistry, repository: RepositoryAiOptions, scope: AiScope, signal: AbortSignal, deadlineEpochMs: number | undefined, kind: "generation" | "decision", sourceMessage?: Any): Promise<ModelRef | undefined>;
+    /**
+     * Finds and authorizes a registered deployment before identity resolution.
+     *
+     * @param registry Effective registry and hook bound.
+     * @param repository Repository selection policy.
+     * @param scope Accepted source and actor.
+     * @param preferences Claim-time per-instance selections.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param kind Generation or decision kind.
+     * @param sourceMessage Original accepted payload.
+     * @returns A registered authorized deployment.
+     */
+    deployment(registry: AiRegistry, repository: RepositoryAiOptions, scope: AiScope, preferences: readonly ModelPreference[], signal: AbortSignal, deadlineEpochMs: number | undefined, kind: "generation" | "decision", sourceMessage?: Any): Promise<ReturnType<typeof selectDeployment>>;
+    /**
+     * Checks a concrete or inherited selection with repository policy.
+     *
+     * @param registry Effective registry and hook bound.
+     * @param repository Repository selection policy.
+     * @param scope Accepted source and actor.
+     * @param reference Selected deployment or inheritance.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @returns When the selection is authorized.
+     */
+    authorizeSelection(registry: AiRegistry, repository: RepositoryAiOptions, scope: AiScope, reference: ModelRef | undefined, signal: AbortSignal, deadlineEpochMs: number | undefined): Promise<void>;
+    /**
+     * Calls a hook only while active and races its bounded cancellation.
+     *
+     * @typeParam Value Callback result.
+     * @param registry Effective registry and hook bound.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param callback Hook receiving a bounded linked control.
+     * @returns A result produced before cancellation or expiry.
+     */
+    invokeHook<Value>(registry: AiRegistry, signal: AbortSignal, deadlineEpochMs: number | undefined, callback: (control: AiControl) => Value | Promise<Value>): Promise<Value>;
+    /**
+     * Resolves and authorizes the selected backend's nonsecret identity.
+     *
+     * @param backend Factory-proven selected backend callbacks.
+     * @param scope Authenticated accepted-invocation scope.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @returns Validated connection identity for the selected backend.
+     */
+    connection(backend: ReturnType<typeof backendDefinition>, scope: AiScope, signal: AbortSignal, deadlineEpochMs: number | undefined): Promise<NonNullable<AgentSelectedModel["connection"]>>;
+    /**
+     * Converts a deployment role to its generated enum value.
+     *
+     * @param kind Registered generation or decision role.
+     * @returns Corresponding generated model kind.
+     */
+    kind(kind: "generation" | "decision"): AiModelKind;
+    /**
+     * Awaits a selection hook under cancellation and the invocation deadline.
+     *
+     * @typeParam Value Hook result type.
+     * @param work Hook result or pending callback promise.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @returns Hook value if it settles before cancellation or expiry.
+     */
+    awaitHook<Value>(work: Value | Promise<Value>, signal: AbortSignal, deadlineEpochMs: number | undefined): Promise<Value>;
+}
+/**
+ * Selects and authenticates each available model kind at execution start.
+ */
+export declare const AgentModelSelection: AgentModelSelectionAccess;
+export {};
+//# sourceMappingURL=agent-model-selection.d.ts.map

package/dist/agent/agent-model-selection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-model-selection.d.ts","sourceRoot":"","sources":["../../src/agent/agent-model-selection.ts"],"names":[],"mappings":"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"}

package/dist/agent/agent-model-selection.js

@@ -0,0 +1,342 @@
+/*
+ * 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 { clone, create } from "@bufbuild/protobuf";
+import { AnySchema } from "@bufbuild/protobuf/wkt";
+import { AnyMessages, Time, TypeUrls, Validate } from "@spine-event-engine/core";
+import { ModelRef as ModelRefFactory, } from "@spine-event-engine/ai";
+import { backendDefinition, registryOptions, selectDeployment, } from "@spine-event-engine/ai/spi/runtime";
+import { AiAccountIdentitySchema, AiConnectionIdentitySchema, AiEndpointIdentitySchema, AiModelKind, AiProviderModelNameSchema as ModelNameSchema, AiProviderNameSchema, ModelRefSchema, } from "@spine-event-engine/proto/agent";
+import { CommandIdSchema, EventIdSchema, MessageIdSchema, ActorContextSchema, TenantIdSchema, } from "@spine-event-engine/proto";
+import { AgentSelectedModelSchema, } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { AgentExecutionFault } from "./agent-execution-fault.js";
+/**
+ * Copies every accepted-scope identity before passing it to an application callback.
+ *
+ * @param scope Original accepted actor, tenant, Agent and source facts.
+ * @returns Detached scope with independent nested Protobuf values.
+ */
+const copyScope = (scope) => ({
+    actor: clone(ActorContextSchema, scope.actor),
+    tenant: scope.tenant.kind === "tenant"
+        ? { kind: "tenant", id: clone(TenantIdSchema, scope.tenant.id) }
+        : { kind: "single-tenant" },
+    agent: clone(MessageIdSchema, scope.agent),
+    source: clone(MessageIdSchema, scope.source),
+});
+/**
+ * Chooses the earliest configured callback or invocation deadline.
+ *
+ * @param registry Effective callback policy.
+ * @param invocationDeadline Accepted invocation deadline, when configured.
+ * @returns Absolute callback deadline, or undefined when no ceiling applies.
+ */
+const selectionHookDeadline = (registry, invocationDeadline) => {
+    const hookTimeoutMs = registryOptions(registry).hookTimeoutMs;
+    const hookDeadline = hookTimeoutMs === undefined ? undefined : Time.currentTimeMillis() + hookTimeoutMs;
+    return invocationDeadline === undefined
+        ? hookDeadline
+        : hookDeadline === undefined
+            ? invocationDeadline
+            : Math.min(invocationDeadline, hookDeadline);
+};
+/**
+ * Selects and authenticates each available model kind at execution start.
+ */
+export const AgentModelSelection = Object.freeze({
+    /**
+     * Constructs the accepted actor, tenant, Agent and source authorization scope.
+     *
+     * @param accepted Original accepted signal and typed recipient.
+     * @param state Generated Agent state descriptor.
+     * @param tenantId Delivery tenant, if this Bounded Context is tenant-scoped.
+     * @returns Scope passed to identity and authorization callbacks.
+     */
+    scope(accepted, state, tenantId) {
+        const recipient = accepted.recipientId;
+        if (recipient === undefined)
+            throw new Error("Agent selection requires the typed recipient.");
+        const signal = accepted.signal;
+        if (signal.case !== "command" && signal.case !== "event")
+            throw new Error("Agent selection requires its original source signal.");
+        const sourceId = signal.case === "command"
+            ? signal.value.id === undefined
+                ? undefined
+                : AnyMessages.pack(CommandIdSchema, signal.value.id)
+            : signal.value.id === undefined
+                ? undefined
+                : AnyMessages.pack(EventIdSchema, signal.value.id);
+        if (sourceId === undefined)
+            throw new Error("Agent selection requires the source ID.");
+        const payloadType = signal.value.message?.typeUrl;
+        if (payloadType === undefined || payloadType.trim().length === 0)
+            throw new Error("Agent selection requires the source payload type.");
+        const actor = accepted.actor;
+        if (actor === undefined)
+            throw new Error("Agent selection requires the accepted actor.");
+        return {
+            actor,
+            tenant: tenantId === undefined ? { kind: "single-tenant" } : { kind: "tenant", id: tenantId },
+            agent: create(MessageIdSchema, { id: recipient, typeUrl: TypeUrls.derive(state) }),
+            source: create(MessageIdSchema, {
+                id: sourceId,
+                typeUrl: payloadType,
+            }),
+        };
+    },
+    /**
+     * Resolves, authorizes and records one selected deployment for each available kind.
+     *
+     * @param registry Effective deployment registry.
+     * @param repository Repository models and selection policy.
+     * @param scope Authenticated accepted-invocation scope.
+     * @param preferences Claim-time per-instance selections.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param sourceMessage Detached original accepted payload when selection is required.
+     * @returns Selected deployments for kinds used by the repository.
+     */
+    async select(registry, repository, scope, preferences, signal, deadlineEpochMs, sourceMessage) {
+        const selected = [];
+        for (const kind of ["generation", "decision"]) {
+            if (!repository.models.some((model) => model.definition.kind === kind))
+                continue;
+            selected.push(await this.selectKind(registry, repository, scope, preferences, signal, deadlineEpochMs, kind, sourceMessage));
+        }
+        return selected;
+    },
+    /**
+     * Resolves a deployment through normal precedence and checks authenticated identity.
+     *
+     * @param registry Effective deployment registry.
+     * @param repository Repository models and selection policy.
+     * @param scope Authenticated accepted-invocation scope.
+     * @param preferences Claim-time per-instance selections.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param kind Generation or decision kind to select.
+     * @param sourceMessage Detached original accepted payload when selection is required.
+     * @returns Chosen deployment and validated connection identity.
+     */
+    async selectKind(registry, repository, scope, preferences, signal, deadlineEpochMs, kind, sourceMessage) {
+        const registration = await this.deployment(registry, repository, scope, preferences, signal, deadlineEpochMs, kind, sourceMessage);
+        const connection = await this.connection(backendDefinition(registration), scope, signal, deadlineEpochMs);
+        return create(AgentSelectedModelSchema, {
+            kind: this.kind(kind),
+            model: registration.ref,
+            connection,
+        });
+    },
+    /**
+     * Finds a deployment and checks a concrete resolver choice before identity work.
+     *
+     * @param registry Effective registry and hook bound.
+     * @param repository Repository selection policy.
+     * @param scope Accepted source and actor.
+     * @param preferences Claim-time per-instance selections.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param kind Generation or decision kind.
+     * @param sourceMessage Original accepted payload.
+     * @returns A registered authorized deployment.
+     */
+    async deployment(registry, repository, scope, preferences, signal, deadlineEpochMs, kind, sourceMessage) {
+        const override = await this.resolveOverride(registry, repository, scope, signal, deadlineEpochMs, kind, sourceMessage);
+        const normal = this.selection(registry, repository, preferences, kind);
+        const registration = selectDeployment(registry, {
+            ...normal,
+            ...(override === undefined ? {} : { instancePreference: override }),
+        });
+        if (override !== undefined)
+            await this.authorizeSelection(registry, repository, scope, override, signal, deadlineEpochMs);
+        return registration;
+    },
+    /**
+     * Resolves and copies one explicit model from the accepted payload.
+     *
+     * @param registry Effective registry and hook bound.
+     * @param repository Repository selection policy.
+     * @param scope Accepted source and actor.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param kind Generation or decision kind.
+     * @param sourceMessage Detached source supplied by the runner.
+     * @returns A validated explicit model or absence.
+     */
+    async resolveOverride(registry, repository, scope, signal, deadlineEpochMs, kind, sourceMessage) {
+        if (repository.resolveModel === undefined)
+            return undefined;
+        if (sourceMessage === undefined)
+            throw new Error("Agent selection requires source payload.");
+        const result = await this.invokeHook(registry, signal, deadlineEpochMs, (control) => repository.resolveModel?.(kind, copyScope(scope), clone(AnySchema, sourceMessage), control));
+        if (result === undefined)
+            return undefined;
+        Validate.check(ModelRefSchema, result);
+        return ModelRefFactory.of(result.name?.value ?? "", result.revision?.value ?? "");
+    },
+    /**
+     * Checks a concrete or inherited selection with the repository policy.
+     *
+     * @param registry Effective registry and hook bound.
+     * @param repository Repository selection policy.
+     * @param scope Accepted source and actor.
+     * @param reference Selected deployment or inherited preference.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @returns When selection is authorized.
+     */
+    async authorizeSelection(registry, repository, scope, reference, signal, deadlineEpochMs) {
+        if (repository.authorizeSelection === undefined)
+            return;
+        const allowed = await this.invokeHook(registry, signal, deadlineEpochMs, (control) => repository.authorizeSelection?.(scope, reference, control));
+        if (allowed !== true)
+            throw new Error("Agent model selection is unauthorized.");
+    },
+    /**
+     * Calls a hook only while active and races its bounded cancellation.
+     *
+     * @typeParam Value Callback result.
+     * @param registry Effective registry and hook bound.
+     * @param signal Invocation cancellation.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @param callback Hook receiving a linked bounded control.
+     * @returns A result produced before cancellation or expiry.
+     */
+    async invokeHook(registry, signal, deadlineEpochMs, callback) {
+        const deadline = selectionHookDeadline(registry, deadlineEpochMs);
+        if (signal.aborted)
+            throw new Error("Agent model selection cancelled.");
+        if (deadline !== undefined && deadline <= Time.currentTimeMillis())
+            throw new Error("Agent model selection expired.");
+        const controller = new AbortController();
+        const linked = AbortSignal.any([signal, controller.signal]);
+        const timer = deadline === undefined
+            ? undefined
+            : setTimeout(() => {
+                controller.abort();
+            }, Math.max(0, deadline - Time.currentTimeMillis()));
+        try {
+            return await this.awaitHook(callback({
+                signal: linked,
+                ...(deadline === undefined ? {} : { deadlineEpochMs: deadline }),
+            }), linked, deadline);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            controller.abort();
+        }
+    },
+    /**
+     * Builds the accepted deployment precedence from repository and claim-time facts.
+     *
+     * @param registry Effective deployment registry.
+     * @param repository Repository models and selection policy.
+     * @param preferences Claim-time per-instance selections.
+     * @param kind Generation or decision kind to select.
+     * @returns Inputs for the registry's normal selection path.
+     */
+    selection(registry, repository, preferences, kind) {
+        const preference = preferences.find((item) => item.kind === this.kind(kind));
+        const instancePreference = preference?.selection.case === "model" ? preference.selection.value : undefined;
+        return {
+            kind,
+            models: repository.models,
+            ...(instancePreference === undefined ? {} : { instancePreference }),
+            ...(repository.defaultModels?.[kind] === undefined
+                ? {}
+                : { repositoryDefault: repository.defaultModels[kind] }),
+            ...(registryOptions(registry).defaultModels[kind] === undefined
+                ? {}
+                : { contextDefault: registryOptions(registry).defaultModels[kind] }),
+            ...(repository.allowedModels?.[kind] === undefined
+                ? {}
+                : { allowedModels: repository.allowedModels[kind] }),
+        };
+    },
+    /**
+     * Resolves a connection identity within the deadline. An explicit use denial
+     * becomes a safe terminal execution fault before the Agent handler runs.
+     *
+     * @param backend Factory-proven selected backend callbacks.
+     * @param scope Authenticated accepted-invocation scope.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @returns Validated nonsecret connection identity.
+     */
+    async connection(backend, scope, signal, deadlineEpochMs) {
+        if (signal.aborted)
+            throw new Error("Agent model selection cancelled.");
+        if (deadlineEpochMs !== undefined && deadlineEpochMs <= Time.currentTimeMillis())
+            throw new Error("Agent model selection expired.");
+        const control = { signal, ...(deadlineEpochMs === undefined ? {} : { deadlineEpochMs }) };
+        const identity = await this.awaitHook(backend.resolveIdentity(scope, control), signal, deadlineEpochMs);
+        signal.throwIfAborted();
+        if (deadlineEpochMs !== undefined && deadlineEpochMs <= Time.currentTimeMillis())
+            throw new Error("Agent model selection expired.");
+        const allowed = await this.awaitHook(backend.authorizeUse(scope, identity, control), signal, deadlineEpochMs);
+        if (!allowed)
+            throw new AgentExecutionFault("MODEL_USE_DENIED", "Selected Agent model use was denied.");
+        const connection = create(AiConnectionIdentitySchema, {
+            provider: create(AiProviderNameSchema, { value: identity.provider }),
+            account: create(AiAccountIdentitySchema, { value: identity.account }),
+            endpoint: create(AiEndpointIdentitySchema, { value: identity.endpoint }),
+            model: create(ModelNameSchema, { value: identity.model }),
+        });
+        Validate.check(AiConnectionIdentitySchema, connection);
+        return connection;
+    },
+    /**
+     * Converts a registered deployment role to the generated closed enum.
+     *
+     * @param kind Registered generation or decision role.
+     * @returns Matching generated model kind.
+     */
+    kind(kind) {
+        return kind === "generation" ? AiModelKind.GENERATION : AiModelKind.DECISION;
+    },
+    /**
+     * Bounds a connection or authorization hook even if its callback ignores cancellation.
+     *
+     * @typeParam Value Hook result type.
+     * @param work Hook result or pending callback promise.
+     * @param signal Cancellation signal for this execution.
+     * @param deadlineEpochMs Absolute invocation deadline.
+     * @returns Hook value if it settles before cancellation or expiry.
+     */
+    awaitHook(work, signal, deadlineEpochMs) {
+        const remaining = deadlineEpochMs === undefined ? undefined : deadlineEpochMs - Time.currentTimeMillis();
+        if (signal.aborted)
+            return Promise.reject(new Error("Agent model selection cancelled."));
+        if (remaining !== undefined && remaining <= 0)
+            return Promise.reject(new Error("Agent model selection expired."));
+        return new Promise((resolve, reject) => {
+            const abort = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                reject(new Error("Agent model selection cancelled."));
+            };
+            const timer = remaining === undefined ? undefined : setTimeout(abort, remaining);
+            signal.addEventListener("abort", abort, { once: true });
+            Promise.resolve(work)
+                .then(resolve, reject)
+                .finally(() => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                signal.removeEventListener("abort", abort);
+            })
+                .catch(() => undefined);
+        });
+    },
+});
+//# sourceMappingURL=agent-model-selection.js.map

package/dist/agent/agent-model-selection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-model-selection.js","sourceRoot":"","sources":["../../src/agent/agent-model-selection.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,70 @@
+import { type MessageShape } from "@bufbuild/protobuf";
+import { type MessageSchema } from "@spine-event-engine/core";
+import { type Query } from "@spine-event-engine/proto/client";
+import { type AgentExecutionRecord } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import { type AgentExecutionCapacity, type AgentHistoryPage, type AgentHistoryView } from "@spine-event-engine/storage/provider";
+import type { HistoryRead } from "@spine-event-engine/ai";
+import type { AgentHistoryScope } from "./agent-history.js";
+interface ReadSession {
+    /**
+     * Returns the current fenced execution record.
+     *
+     * @returns The execution record.
+     */
+    record(): AgentExecutionRecord;
+    /**
+     * Persists a change to the fenced execution record.
+     *
+     * @param change Applies the read evidence to the current record.
+     * @returns The updated execution record.
+     */
+    update(change: (record: AgentExecutionRecord) => AgentExecutionRecord): Promise<AgentExecutionRecord>;
+    /**
+     * Returns the configured journal capacity.
+     *
+     * @returns The execution capacity limits.
+     */
+    capacity(): AgentExecutionCapacity;
+}
+/**
+ * Reuses complete indexed pages under one handler's fenced journal.
+ */
+export declare class AgentReadRuntime {
+    #private;
+    private readonly session;
+    private readonly handlerOrdinal;
+    /**
+     * Creates a read sequencer for one handler invocation.
+     *
+     * @param session Fenced execution journal for this invocation.
+     * @param handlerOrdinal Ordinal of the handler within the accepted delivery.
+     */
+    constructor(session: ReadSession, handlerOrdinal: number);
+    /**
+     * Returns one saved page or persists a live page before the handler sees it.
+     *
+     * @param scope Accepted Agent instance for this read.
+     * @param view History view selected by the handler.
+     * @param request Requested page and cursor.
+     * @param live Performs the live read when no saved page exists.
+     * @param maxBytes Maximum size of a live history page.
+     * @returns The saved or newly persisted page.
+     */
+    history(scope: AgentHistoryScope, view: AgentHistoryView, request: HistoryRead, live: () => Promise<AgentHistoryPage>, maxBytes: number | undefined): Promise<AgentHistoryPage>;
+    /**
+     * Returns saved typed projection states or persists a live query result.
+     *
+     * @typeParam Schema Schema of each returned projection state.
+     * @param schema Projection state schema.
+     * @param query Typed query to replay or execute.
+     * @param live Performs the live query when no saved result exists.
+     * @returns The saved or newly persisted projection states.
+     */
+    query<Schema extends MessageSchema>(schema: Schema, query: Query, live: () => Promise<readonly MessageShape<Schema>[]>): Promise<readonly MessageShape<Schema>[]>;
+    /**
+     * Rejects omitted saved reads after all handler methods have returned.
+     */
+    finish(): void;
+}
+export {};
+//# sourceMappingURL=agent-read-runtime.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-read-runtime.d.ts","sourceRoot":"","sources":["../../src/agent/agent-read-runtime.ts"],"names":[],"mappings":"AAcA,OAAO,EAAyB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE9E,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACrF,OAAO,EAAe,KAAK,KAAK,EAAE,MAAM,kCAAkC,CAAC;AAC3E,OAAO,EAQL,KAAK,oBAAoB,EAE1B,MAAM,+EAA+E,CAAC;AACvF,OAAO,EAEL,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5D,UAAU,WAAW;IACnB;;;;OAIG;IACH,MAAM,IAAI,oBAAoB,CAAC;IAE/B;;;;;OAKG;IACH,MAAM,CACJ,MAAM,EAAE,CAAC,MAAM,EAAE,oBAAoB,KAAK,oBAAoB,GAC7D,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC;;;;OAIG;IACH,QAAQ,IAAI,sBAAsB,CAAC;CACpC;AAED;;GAEG;AACH,qBAAa,gBAAgB;;IAczB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,cAAc;IARjC;;;;;OAKG;gBAEgB,OAAO,EAAE,WAAW,EACpB,cAAc,EAAE,MAAM;IAGzC;;;;;;;;;OASG;IACH,OAAO,CACL,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,MAAM,OAAO,CAAC,gBAAgB,CAAC,EACrC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAC3B,OAAO,CAAC,gBAAgB,CAAC;IAY5B;;;;;;;;OAQG;IACH,KAAK,CAAC,MAAM,SAAS,aAAa,EAChC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,OAAO,CAAC,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,GACnD,OAAO,CAAC,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;IAiM3C;;OAEG;IACH,MAAM,IAAI,IAAI;CA6Jf"}