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

package/dist/entity/agent-execution.d.ts

@@ -0,0 +1,234 @@
+import type { Message } from "@bufbuild/protobuf";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import type { AgentHistoryEntry, ModelPreference } from "@spine-event-engine/proto/agent";
+import type { AgentAcceptedInvocation, AgentExecutionRecord, AgentExecutionScope, AgentInvocationKey, AgentSignalKey } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { EntityCommitInput } from "../internal/entity-commit.js";
+import type { EntityStorageInput } from "../internal/entity-history.js";
+/**
+ * Defines one Agent repository scope for a provider handle.
+ *
+ * @typeParam I Typed Agent identifier.
+ * @typeParam S Generated Agent state.
+ */
+export interface AgentExecutionStorageInput<I, S extends Message> {
+    /**
+     * Entity layout and complete tenant boundary used by conditional completion.
+     */
+    readonly entity: EntityStorageInput<I, S>;
+    /**
+     * Generated Agent state type named in every execution scope.
+     */
+    readonly stateType: string;
+}
+/**
+ * Selects a bounded page of provider-observed candidate heads in one Agent state type.
+ */
+export interface AgentPendingRead {
+    /**
+     * Provider-observed continuation and fixed time boundary from the preceding page.
+     */
+    readonly after?: AgentPendingCursor;
+    /**
+     * Maximum number of observed candidates returned.
+     */
+    readonly count: number;
+}
+/**
+ * Orders observed candidate heads without allocating a history position.
+ */
+export interface AgentPendingKey {
+    /**
+     * Complete Agent instance identity.
+     */
+    readonly scope: AgentExecutionScope;
+    /**
+     * Provider time at which this instance became eligible.
+     */
+    readonly eligibleAt: Timestamp;
+}
+/**
+ * Fixed sweep time and complete index key observed by a provider page.
+ */
+export interface AgentPendingCursor {
+    /**
+     * Time sampled once when the sweep began.
+     */
+    readonly asOf: Timestamp;
+    /**
+     * Last examined head index key, before any concurrent mutation.
+     */
+    readonly key: AgentPendingKey;
+}
+/**
+ * Returns detached records for observed candidates and their continuation.
+ * A concurrent mutation can make a record stale; claim decides whether work is current.
+ */
+export interface AgentPendingPage {
+    /**
+     * Candidate records observed through the pending-head index.
+     */
+    readonly records: readonly AgentExecutionRecord[];
+    /**
+     * Last examined provider index key; advance it even when no claim succeeds.
+     */
+    readonly after?: AgentPendingCursor;
+    /**
+     * Whether another indexed candidate was observed during this page read.
+     */
+    readonly hasMore: boolean;
+}
+/**
+ * Provides a claimed record and queryable current model preferences.
+ */
+export interface AgentExecutionClaim {
+    /**
+     * Complete claimed execution record.
+     */
+    readonly record: AgentExecutionRecord;
+    /**
+     * Current per-instance preferences at the claim boundary.
+     */
+    readonly preferences: readonly ModelPreference[];
+}
+/**
+ * Replaces one fenced execution record and appends its conversation or System history.
+ */
+export interface AgentExecutionUpdate {
+    /**
+     * Exact accepted invocation identity.
+     */
+    readonly key: AgentInvocationKey;
+    /**
+     * Exclusive token granted by the current per-instance claim.
+     */
+    readonly token: string;
+    /**
+     * Exact binary image read before constructing this update.
+     */
+    readonly expectedRecordBytes: Uint8Array;
+    /**
+     * Complete next record with immutable acceptance unchanged.
+     */
+    readonly next: AgentExecutionRecord;
+    /**
+     * Original conversation or System entries committed with the journal.
+     */
+    readonly historyEntries?: readonly AgentHistoryEntry[];
+}
+/**
+ * Commits an Agent transition and its fenced execution record together.
+ *
+ * @typeParam I Typed Agent identifier.
+ * @typeParam S Generated Agent state.
+ */
+export interface AgentExecutionComplete<I, S extends Message> extends AgentExecutionUpdate {
+    /**
+     * Current-state and framework history mutation; absent for a no-op.
+     */
+    readonly entityCommit?: EntityCommitInput<I, S>;
+}
+/**
+ * Native serialized payload bounds available before model or tool dispatch.
+ *
+ * Every limit applies to the complete internal Protobuf record, including its
+ * scope and metadata. An absent limit means this provider enforces no tighter
+ * fixed bound for that record.
+ */
+export interface AgentExecutionCapacity {
+    /**
+     * Maximum serialized AgentExecutionRecord bytes.
+     */
+    readonly executionRecordBytes?: number;
+    /**
+     * Maximum serialized AgentExecutionHead bytes.
+     */
+    readonly executionHeadBytes?: number;
+    /**
+     * Maximum serialized AgentHistoryRecord bytes.
+     */
+    readonly historyRecordBytes?: number;
+    /**
+     * Maximum aggregate staged native transaction payload bytes.
+     */
+    readonly transactionPayloadBytes?: number;
+}
+/**
+ * Provider-only durable execution capability for one Agent repository scope.
+ *
+ * @typeParam I Typed Agent identifier.
+ * @typeParam S Generated Agent state.
+ */
+export interface AgentExecutionStorage<I, S extends Message> {
+    /**
+     * Native bounds used to reject unjournalable work before external dispatch.
+     */
+    readonly capacity: AgentExecutionCapacity;
+    /**
+     * Persists accepted source work before its Inbox handoff is acknowledged.
+     *
+     * @param accepted Exact source envelope and selected handler bindings.
+     * @returns Stored record, accepting an identical repeat only.
+     */
+    admit(accepted: AgentAcceptedInvocation): Promise<AgentExecutionRecord>;
+    /**
+     * Reads bounded, time-eligible unresolved work through a provider index.
+     *
+     * @param request Page count and complete continuation.
+     * @returns Independent records and continuation state.
+     */
+    pending(request: AgentPendingRead): Promise<AgentPendingPage>;
+    /**
+     * Reads a complete execution record after reconstruction.
+     *
+     * @param key Exact source and Agent instance identity.
+     * @returns Stored record, if present.
+     */
+    read(key: AgentInvocationKey): Promise<AgentExecutionRecord | undefined>;
+    /**
+     * Acquires the earliest unresolved invocation with a fresh provider-side time check.
+     *
+     * @param key Exact source and Agent instance identity.
+     * @param token New unpredictable exclusive token.
+     * @param expiresAt Requested claim expiry.
+     * @returns Claimed record and current preferences, if eligible.
+     */
+    claim(key: AgentInvocationKey, token: string, expiresAt: Timestamp): Promise<AgentExecutionClaim | undefined>;
+    /**
+     * Updates the same unexpired token under the per-instance claim lock.
+     *
+     * @param key Exact source and Agent instance identity.
+     * @param token Current exclusive token.
+     * @param expiresAt Requested later expiry.
+     * @returns Whether the current token was renewed.
+     */
+    renew(key: AgentInvocationKey, token: string, expiresAt: Timestamp): Promise<boolean>;
+    /**
+     * Persists fenced budgets, evidence and conversation/System history atomically.
+     *
+     * @param input Expected exact record and next retained evidence.
+     * @returns Completion after fenced evidence is persisted.
+     */
+    update(input: AgentExecutionUpdate): Promise<void>;
+    /**
+     * Persists Entity, history, preferences, execution result and output obligations atomically.
+     *
+     * @param input Expected exact record and complete transition.
+     * @returns Completion after conditional Entity and evidence commit.
+     */
+    complete(input: AgentExecutionComplete<I, S>): Promise<void>;
+    /**
+     * Marks output IDs accepted by normal delivery without rerunning handlers.
+     *
+     * @param key Exact source and Agent instance identity.
+     * @param token Current exclusive token.
+     * @param expectedRecordBytes Exact binary image before acknowledgement.
+     * @param signals Original IDs accepted by delivery.
+     * @returns Completion after original output IDs are marked delivered.
+     */
+    markDelivered(key: AgentInvocationKey, token: string, expectedRecordBytes: Uint8Array, signals: readonly AgentSignalKey[]): Promise<void>;
+    /**
+     * Closes this handle without deleting any persisted work.
+     */
+    close(): void;
+}
+//# sourceMappingURL=agent-execution.d.ts.map

package/dist/entity/agent-execution.d.ts.map

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

package/dist/entity/agent-execution.js

@@ -0,0 +1,15 @@
+/*
+ * 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.
+ */
+export {};
+//# sourceMappingURL=agent-execution.js.map

package/dist/entity/agent-execution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution.js","sourceRoot":"","sources":["../../src/entity/agent-execution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/entity/agent-history-conformance.d.ts

@@ -0,0 +1,78 @@
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { type AgentHistoryEntry } from "@spine-event-engine/proto/agent";
+import { type AgentHistoryStorage, type AgentHistoryStorageInput } from "./agent-history.js";
+/**
+ * Supplies domain-correct Proto entries and real provider handles to shared checks.
+ */
+export interface AgentHistoryConformanceAdapter {
+    /**
+     * Repository and tenant scope used as the baseline.
+     */
+    readonly scope: AgentHistoryStorageInput<string>;
+    /**
+     * Opens a provider handle for a repository scope.
+     *
+     * @param input Bounded Context, state type, and typed ID scope.
+     * @returns Provider history handle.
+     */
+    readonly open: (input: AgentHistoryStorageInput<string>) => AgentHistoryStorage<string>;
+    /**
+     * Builds a typed model request history entry.
+     *
+     * @param id Immutable record ID.
+     * @param conversation Conversation ID value.
+     * @param time Original occurrence time.
+     * @returns Complete request history entry.
+     */
+    readonly conversation: (id: string, conversation: string, time: Timestamp) => AgentHistoryEntry;
+    /**
+     * Builds a typed model response history entry.
+     *
+     * @param id Immutable record ID.
+     * @param conversation Conversation ID value.
+     * @param time Original occurrence time.
+     * @returns Complete response history entry.
+     */
+    readonly response: (id: string, conversation: string, time: Timestamp) => AgentHistoryEntry;
+    /**
+     * Builds a canonical Agent System Event envelope.
+     *
+     * @param id Original Event ID.
+     * @param time Original occurrence time.
+     * @returns Complete System Event history entry.
+     */
+    readonly system: (id: string, time: Timestamp) => AgentHistoryEntry;
+    /**
+     * Builds a canonical Agent domain Event envelope.
+     *
+     * @param id Original Event ID.
+     * @param time Original occurrence time.
+     * @returns Complete domain Event history entry.
+     */
+    readonly domain: (id: string, time: Timestamp) => AgentHistoryEntry;
+    /**
+     * Builds a full-precision occurrence time.
+     *
+     * @param seconds Complete Timestamp seconds.
+     * @param nanos Nanoseconds within the second.
+     * @returns Original occurrence time.
+     */
+    readonly occurredAt: (seconds: bigint, nanos?: number) => Timestamp;
+}
+/**
+ * Shared assertions that each Agent history provider must satisfy.
+ */
+export interface AgentHistoryConformanceChecks {
+    /**
+     * Checks provider Agent history behavior.
+     *
+     * @param adapter Real provider handle and domain fixtures.
+     * @returns Completes after all checks pass.
+     */
+    check(adapter: AgentHistoryConformanceAdapter): Promise<void>;
+}
+/**
+ * Runs provider-neutral Agent history ordering, paging, and retention checks.
+ */
+export declare const AgentHistoryConformance: AgentHistoryConformanceChecks;
+//# sourceMappingURL=agent-history-conformance.d.ts.map

package/dist/entity/agent-history-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-history-conformance.d.ts","sourceRoot":"","sources":["../../src/entity/agent-history-conformance.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,EAGL,KAAK,iBAAiB,EACvB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAGL,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAE9B,MAAM,oBAAoB,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,wBAAwB,CAAC,MAAM,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,wBAAwB,CAAC,MAAM,CAAC,KAAK,mBAAmB,CAAC,MAAM,CAAC,CAAC;IAExF;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,iBAAiB,CAAC;IAEhG;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,iBAAiB,CAAC;IAE5F;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,iBAAiB,CAAC;IAEpE;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,KAAK,iBAAiB,CAAC;IAEpE;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,SAAS,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,8BAA8B,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/D;AAED;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,6BAmBpC,CAAC"}