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

package/README.md

@@ -11,6 +11,10 @@ record schemas, and a reachable MySQL database.
 For database requirements, query limits, lifecycle, and error details, see
 [REFERENCE documentation for agents](REFERENCE.md).
 
+For an application using Agents, this provider keeps the Agent's accepted
+work and recorded interactions across restarts. Use InnoDB for Agent repositories;
+see the [coding-agent reference](REFERENCE.md) for database requirements.
+
 ## 💡 Why use it?
 
 - ✅ Stores Spine records durably in a MySQL database.
@@ -123,6 +127,10 @@ numbers, enums, bytes, messages, `Timestamp`, and `Version`. Spine JVM JDBC
 does not support `float` or `double` record columns, so this adapter rejects
 them too.
 
+Indexed `Timestamp` columns store epoch nanoseconds in signed 64-bit `BIGINT`.
+Values must fit that range (approximately 1677–2262 UTC); Protobuf's wider
+`Timestamp` range does not expand the SQL range.
+
 MyISAM and Aria limit the byte length of an indexed key. Their `VARCHAR(512)`
 ID column therefore needs a one-byte binary collation, such as `latin1_bin`,
 and every ID must be representable in that character set. The normal InnoDB

package/REFERENCE.md

@@ -1,6 +1,6 @@
 # @spine-event-engine/storage-mysql reference
 
-This reference is for agents configuring the supported MySQL storage adapter.
+This reference is for coding agents configuring the supported MySQL storage adapter.
 
 ## Public entry point
 
@@ -88,8 +88,10 @@ revision. Proto fields without `(column)` exist only inside the authoritative
 never altered. A mismatched type, nullability, primary key, unique constraint,
 or extra column is rejected. Ordinary message columns use the same configured
 reversible stringifier for writes and query operands. `Timestamp` uses epoch
-nanoseconds and `Version` uses its number. Floating-point record columns are
-not supported by Spine JVM JDBC and are rejected here.
+nanoseconds in signed 64-bit `BIGINT` columns. Indexed timestamp values must
+fit that range (approximately 1677–2262 UTC); Protobuf's wider `Timestamp`
+range does not expand the SQL range. `Version` uses its number. Floating-point
+record columns are not supported by Spine JVM JDBC and are rejected here.
 
 Queries execute ID filters, ANDed column filters, materialized-column sorts,
 keyset continuations, offsets, and limits in MySQL. Before executing, MySQL
@@ -131,6 +133,40 @@ nontransactional engines use a deterministic immutable-history prefix and may
 require an identical retry after a storage failure. Standalone history
 operations remain separate.
 
+## Agent history
+
+The provider-only Agent history handle stores original complete
+`AgentHistoryEntry` bytes and full repository scope in one `agent_history`
+record family per tenant database. SHA-256 digests provide bounded physical
+record IDs and indexed scope/conversation keys; reads also compare the full
+state type, Agent key, and selected conversation key with binary equality.
+Three validated InnoDB B-tree indexes cover scope plus full order, scope plus
+category plus full order, and scope plus conversation digest plus full order.
+The `VARBINARY(2944)` order column fits the 3,072-byte InnoDB composite-index
+budget with two 64-byte digests; category uses 12 bytes. Its value encodes the
+complete Timestamp, category, and unsigned UTF-8 record ID. Longer values
+reject before storage rather than using a prefix index. Existing prefix,
+misordered, or otherwise incompatible same-name indexes reject when the handle
+opens. Pages use bounded native SQL chunks and sum serialized entry bytes; a
+fetched chunk can be larger than the returned byte budget.
+
+## Agent execution
+
+Agent execution conformance is exercised with MySQL 5.7 and 8.4, and MariaDB 11.4.
+
+Agent repositories require InnoDB. The execution handle rejects a nontransactional
+engine before accepting Agent work; the existing engine choices for other Entity
+families are unchanged. Execution and per-instance pending records use complete
+binary ordering keys and validated composite indexes.
+
+One connection transaction checks the claim and initial Entity Version, then
+writes state, mandatory history, preferences and outgoing signals. Connection
+binding is scoped to that asynchronous operation. Encoded execution,
+per-instance, and Agent history records must each fit the 65,535-byte BLOB limit. The runtime must
+check its response reservation against the provider limits before inference.
+Reopening a factory can read the saved work. No transaction remains open during
+a model request.
+
 `MysqlStorageSchemaError` reports incompatible layouts,
 `MysqlStorageDataError` reports stored bytes that cannot be decoded, and
 `MysqlStorageOperationError` reports sanitized bounds, query, collision, and

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

@@ -0,0 +1,278 @@
+import { type Message } from "@bufbuild/protobuf";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import type { Event, EventId } from "@spine-event-engine/proto";
+import { type AgentAcceptedInvocation, type AgentExecutionHead, type AgentExecutionRecord, type AgentInvocationKey, type AgentSignalKey } from "@spine-event-engine/proto/generated/spine/server/agent/execution_record_pb.js";
+import type { AgentHistoryRecord } from "@spine-event-engine/proto/generated/spine/server/agent/history_record_pb.js";
+import { type AgentExecutionStorage, type AgentExecutionCapacity, type AgentExecutionStorageInput, type AgentExecutionClaim, type AgentExecutionUpdate, type AgentExecutionComplete, type AgentPendingRead, type AgentPendingPage } from "@spine-event-engine/storage/provider";
+import { MysqlEntityCommitCoordinator } from "./entity-commit.js";
+import { MysqlEntityStorage } from "./entity-history.js";
+import { MysqlRecordStorage } from "./record-storage.js";
+/**
+ * Native records that participate in every Agent execution transaction.
+ *
+ * @typeParam I Typed entity identifier.
+ * @typeParam S Generated Entity state.
+ */
+interface ExecutionRows<I, S extends Message> {
+    readonly invocation: MysqlRecordStorage<string, AgentExecutionRecord>;
+    readonly head: MysqlRecordStorage<string, AgentExecutionHead>;
+    readonly history: MysqlRecordStorage<string, AgentHistoryRecord>;
+    readonly entity: MysqlEntityStorage<I, S>;
+    readonly events: MysqlRecordStorage<EventId, Event>;
+}
+/**
+ * Persists Agent claims and evidence through one required InnoDB transaction.
+ *
+ * @typeParam I Typed Agent identifier.
+ * @typeParam S Generated Agent state.
+ */
+export declare class MysqlAgentExecution<I, S extends Message> implements AgentExecutionStorage<I, S> {
+    #private;
+    private readonly input;
+    private readonly rows;
+    private readonly coordinator;
+    private readonly databaseName;
+    /**
+     * Native BLOB row limits for complete internal Protobuf wrappers.
+     */
+    readonly capacity: Required<Pick<AgentExecutionCapacity, "executionRecordBytes" | "executionHeadBytes" | "historyRecordBytes">>;
+    /**
+     * Binds tenant-scoped record families and the native transaction coordinator.
+     *
+     * @param coordinator Native transaction coordinator.
+     * @param databaseName Tenant database name.
+     * @param input Requested fenced execution change.
+     * @param rows Provider record handles bound to the tenant.
+     */
+    constructor(input: AgentExecutionStorageInput<I, S>, rows: ExecutionRows<I, S>, coordinator: MysqlEntityCommitCoordinator, databaseName: string);
+    /**
+     * Persists original accepted work once under the per-instance row lock.
+     *
+     * @param accepted Original accepted signal and selected bindings.
+     * @returns Persisted invocation with the original accepted facts.
+     */
+    admit(accepted: AgentAcceptedInvocation): Promise<AgentExecutionRecord>;
+    /**
+     * Reads one bounded page from complete native pending indexes.
+     *
+     * @param request Bounded pending-page request.
+     * @returns Bounded eligible work and continuation cursor.
+     */
+    pending(request: AgentPendingRead): Promise<AgentPendingPage>;
+    /**
+     * Builds the indexed native query for one fixed eligibility cutoff.
+     *
+     * @param request Bounded pending-page request.
+     * @param asOf Fixed provider-time eligibility cutoff.
+     * @returns Native SQL and exact bound values.
+     */
+    private pendingQuery;
+    /**
+     * Reads one complete invocation after provider reconstruction.
+     *
+     * @param key Original Agent invocation identity.
+     * @returns Complete stored invocation when present.
+     */
+    read(key: AgentInvocationKey): Promise<AgentExecutionRecord | undefined>;
+    /**
+     * Acquires earliest unresolved work and records the current exclusive token.
+     *
+     * @param expiresAt Requested future lease expiry.
+     * @param key Original Agent invocation identity.
+     * @param token Exclusive claim token.
+     * @returns Claimed work and preferences when eligible.
+     */
+    claim(key: AgentInvocationKey, token: string, expiresAt: Timestamp): Promise<AgentExecutionClaim | undefined>;
+    /**
+     * Checks the locked instance and writes one current lease.
+     *
+     * @param key Original Agent invocation identity.
+     * @param token New exclusive claim token.
+     * @param expiresAt Requested future lease expiry.
+     * @returns Claimed record and preferences when eligible.
+     */
+    private claimLocked;
+    /**
+     * Checks the current head and earliest same-instance source.
+     *
+     * @param head Per-instance pending and lease record.
+     * @param key Original Agent invocation identity.
+     * @param now Fresh time read in the locked transaction.
+     * @returns Whether this invocation may receive the next lease.
+     */
+    private eligibleClaim;
+    /**
+     * Updates a still-live token under a fresh transaction clock.
+     *
+     * @param expiresAt Requested future lease expiry.
+     * @param key Original Agent invocation identity.
+     * @param token Exclusive claim token.
+     * @returns Whether the current lease was extended.
+     */
+    renew(key: AgentInvocationKey, token: string, expiresAt: Timestamp): Promise<boolean>;
+    /**
+     * Persists a journal update and its immutable history under one transaction.
+     *
+     * @param input Requested fenced execution change.
+     * @returns Completion after fenced evidence is persisted.
+     */
+    update(input: AgentExecutionUpdate): Promise<void>;
+    /**
+     * Commits state, history, preferences and outgoing obligations together.
+     *
+     * @param input Requested fenced execution change.
+     * @returns Completion after conditional Entity and evidence commit.
+     */
+    complete(input: AgentExecutionComplete<I, S>): Promise<void>;
+    /**
+     * Marks original outgoing IDs delivered under the still-current token.
+     *
+     * @param expectedRecordBytes Exact prior execution record bytes.
+     * @param key Original Agent invocation identity.
+     * @param signals Original outgoing signal identities.
+     * @param token Exclusive claim token.
+     * @returns Completion after original output IDs are marked delivered.
+     */
+    markDelivered(key: AgentInvocationKey, token: string, expectedRecordBytes: Uint8Array, signals: readonly AgentSignalKey[]): Promise<void>;
+    /**
+     * Marks exact saved output IDs within the current per-instance transaction.
+     *
+     * @param key Original Agent invocation identity.
+     * @param token Current exclusive claim token.
+     * @param expectedRecordBytes Exact prior execution record bytes.
+     * @param signals Original accepted output IDs.
+     * @returns Completion after persisted output status is updated.
+     */
+    private deliverLocked;
+    /**
+     * Closes record handles without deleting accepted work.
+     */
+    close(): void;
+    /**
+     * Prepares existing record families and verifies complete binary indexes.
+     *
+     * @returns Completion after provider capabilities are checked.
+     */
+    private ready;
+    /**
+     * Prepares every table before transactions and checks the native indexes.
+     *
+     * @returns Completion after native tables and indexes are prepared.
+     */
+    private initialize;
+    /**
+     * Executes all record-family work on one required InnoDB connection.
+     *
+     * @param key Original Agent invocation identity.
+     * @param work Operation executed inside the transaction.
+     * @returns Callback result after the native transaction commits.
+     * @typeParam T Result returned by the transaction callback.
+     */
+    private transaction;
+    /**
+     * Reads a head under the transaction lock and verifies the full scope.
+     *
+     * @param key Original Agent invocation identity.
+     * @returns Per-instance head when present.
+     */
+    private currentHead;
+    /**
+     * Reads the invocation under the transaction lock and verifies its identity.
+     *
+     * @param key Original Agent invocation identity.
+     * @returns Stored invocation when present.
+     */
+    private existing;
+    /**
+     * Rejects a physical digest collision on an invocation row.
+     *
+     * @param found Stored record read in this transaction.
+     * @param key Original Agent invocation identity.
+     */
+    private checkIdentity;
+    /**
+     * Checks this is the earliest unresolved invocation in the full scope.
+     *
+     * @param key Original Agent invocation identity.
+     * @returns Whether this invocation is earliest unresolved work.
+     */
+    private earliest;
+    /**
+     * Reads at most two native rows for each unresolved status.
+     *
+     * @param exclude Invocation omitted while selecting the successor.
+     * @param key Original Agent invocation identity.
+     * @returns Earliest unresolved invocation when present.
+     */
+    private successor;
+    /**
+     * Adds an earlier source while retaining the prior eligibility value.
+     *
+     * @param head Per-instance pending and lease record.
+     * @param record Persisted Agent execution record.
+     */
+    private offerCandidate;
+    /**
+     * Updates terminal work to the next same-instance source in one transaction.
+     *
+     * @param head Per-instance pending and lease record.
+     * @param key Original Agent invocation identity.
+     * @param order Original Inbox order.
+     * @returns Completion after updating the next pending head.
+     */
+    private advanceCandidate;
+    /**
+     * Reads the current claim with fresh Time inside the native transaction.
+     *
+     * @param key Original Agent invocation identity.
+     * @param token Exclusive claim token.
+     * @returns Current record and head if the token remains valid.
+     */
+    private claimed;
+    /**
+     * Checks exact prior bytes and preserves immutable source facts.
+     *
+     * @param checkNext Whether to validate the proposed next record.
+     * @param input Requested fenced execution change.
+     * @returns Current fenced record and head.
+     */
+    private expected;
+    /**
+     * Prepares immutable history records under the same fenced transaction.
+     *
+     * @param entries Immutable history entries to append.
+     * @param key Original Agent invocation identity.
+     * @returns Completion after immutable history is appended.
+     */
+    private appendHistory;
+    /**
+     * Rejects a changed initial Version and applies Entity rows in this transaction.
+     *
+     * @param expectedVersion Expected current Entity Version.
+     * @param input Requested fenced execution change.
+     * @returns Completion after conditional Entity state and Version write.
+     */
+    private completeEntity;
+    /**
+     * Checks exactly one Version advance or a no-op completion.
+     *
+     * @param input Requested fenced execution change.
+     * @param prior Previously persisted execution record.
+     * @returns Expected initial Entity Version.
+     */
+    private validateCompletion;
+    /**
+     * Rejects values outside the full InnoDB index or record payload budget.
+     *
+     * @param record Persisted Agent execution record.
+     */
+    private validateRecord;
+    /**
+     * Checks complete indexed discovery and native record payload budgets.
+     *
+     * @param head Per-instance pending and lease record.
+     */
+    private validateHead;
+}
+export {};
+//# sourceMappingURL=agent-execution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-execution.d.ts","sourceRoot":"","sources":["../../src/mysql/agent-execution.ts"],"names":[],"mappings":"AAcA,OAAO,EAAoB,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAExD,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAC;AAEhE,OAAO,EAIL,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,oBAAoB,EACzB,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACpB,MAAM,+EAA+E,CAAC;AACvF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6EAA6E,CAAC;AACtH,OAAO,EAML,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAsB,4BAA4B,EAAE,MAAM,oBAAoB,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;;;;GAKG;AACH,UAAU,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO;IAC1C,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IACtE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC9D,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IACjE,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAC1C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;CACrD;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAE,YAAW,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC;;IA4BzF,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY;IA9B/B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CACzB,IAAI,CACF,sBAAsB,EACtB,sBAAsB,GAAG,oBAAoB,GAAG,oBAAoB,CACrE,CACF,CAIE;IAMH;;;;;;;OAOG;gBAEgB,KAAK,EAAE,0BAA0B,CAAC,CAAC,EAAE,CAAC,CAAC,EACvC,IAAI,EAAE,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,EACzB,WAAW,EAAE,4BAA4B,EACzC,YAAY,EAAE,MAAM;IAGvC;;;;;OAKG;IACG,KAAK,CAAC,QAAQ,EAAE,uBAAuB,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAwB7E;;;;;OAKG;IACG,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAyBnE;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAmBpB;;;;;OAKG;IACG,IAAI,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,GAAG,SAAS,CAAC;IAS9E;;;;;;;OAOG;IACG,KAAK,CACT,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IAK3C;;;;;;;OAOG;YACW,WAAW;IA6BzB;;;;;;;OAOG;YACW,aAAa;IAkB3B;;;;;;;OAOG;IACG,KAAK,CAAC,GAAG,EAAE,kBAAkB,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB3F;;;;;OAKG;IACG,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBxD;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE;;;;;;;;OAQG;IACG,aAAa,CACjB,GAAG,EAAE,kBAAkB,EACvB,KAAK,EAAE,MAAM,EACb,mBAAmB,EAAE,UAAU,EAC/B,OAAO,EAAE,SAAS,cAAc,EAAE,GACjC,OAAO,CAAC,IAAI,CAAC;IAKhB;;;;;;;;OAQG;YACW,aAAa;IA4B3B;;OAEG;IACH,KAAK,IAAI,IAAI;IAUb;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAKb;;;;OAIG;YACW,UAAU;IAmBxB;;;;;;;OAOG;YACW,WAAW;IAgCzB;;;;;OAKG;YACW,WAAW;IAczB;;;;;OAKG;YACW,QAAQ;IAMtB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAarB;;;;;OAKG;YACW,QAAQ;IAStB;;;;;;OAMG;YACW,SAAS;IAmCvB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAKtB;;;;;;;OAOG;YACW,gBAAgB;IAU9B;;;;;;OAMG;YACW,OAAO;IAcrB;;;;;;OAMG;YACW,QAAQ;IAetB;;;;;;OAMG;YACW,aAAa;IAe3B;;;;;;OAMG;YACW,cAAc;IA6B5B;;;;;;OAMG;IACH,OAAO,CAAC,kBAAkB;IA+B1B;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAUtB;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAarB"}