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

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

@@ -0,0 +1,104 @@
+import type { AgentHistoryEntry } from "@spine-event-engine/proto/agent";
+import type { AgentHistoryRecord } from "@spine-event-engine/proto/generated/spine/server/agent/history_record_pb.js";
+import { type AgentHistoryPage, type AgentHistoryRead, type AgentHistoryStorage, type AgentHistoryStorageInput } from "@spine-event-engine/storage/provider";
+import { MysqlRecordStorage } from "./record-storage.js";
+/**
+ * Hashes complete identities into bounded physical IDs and indexed scope keys.
+ */
+export declare const AgentHistoryHash: {
+    /**
+     * Calculates the fixed-width digest of a complete logical identity.
+     *
+     * @param value Complete logical identity.
+     * @returns Full SHA-256 hex digest.
+     */
+    value(value: string): string;
+};
+/**
+ * Stores Agent history in the shared MySQL immutable record family.
+ *
+ * @typeParam Id Typed Agent identifier.
+ */
+export declare class MysqlAgentHistory<Id> implements AgentHistoryStorage<Id> {
+    #private;
+    private readonly input;
+    private readonly records;
+    /**
+     * Binds one typed Agent repository to the provider record handle.
+     *
+     * @param input Repository and complete tenant scope.
+     * @param records Native record-family storage.
+     */
+    constructor(input: AgentHistoryStorageInput<Id>, records: MysqlRecordStorage<string, AgentHistoryRecord>);
+    /**
+     * Writes one original entry or confirms byte-identical content.
+     *
+     * @param entityId Typed Agent identifier.
+     * @param entry Complete history entry.
+     * @returns Completion after immutable storage confirms the entry.
+     */
+    append(entityId: Id, entry: AgentHistoryEntry): Promise<void>;
+    /**
+     * Reads a bounded indexed page in full Timestamp/category/UTF-8 order.
+     *
+     * @param request Typed Agent, view, continuation, and response limits.
+     * @returns Original entries and continuation status.
+     */
+    read(request: AgentHistoryRead<Id>): Promise<AgentHistoryPage>;
+    /**
+  
+     * Closes this handle without deleting stored records.
+  
+     */
+    close(): void;
+    /**
+     * Prepares fixed composite indexes after canonical table initialization.
+     *
+     * @returns Shared preparation promise for this handle.
+     */
+    private ready;
+    /**
+     * Creates each native index idempotently on the shared record family.
+     *
+     * @returns Completion after all three definitions are validated.
+     */
+    private initialize;
+    /**
+     * Reads a bounded native page with complete scope and view predicates.
+     *
+     * @param agentKey Canonical Agent key.
+     * @param request View and response bounds.
+     * @param after Exclusive encoded order key.
+     * @param limit Maximum native rows for this chunk.
+     * @returns Complete original stored records.
+     */
+    private fetch;
+    /**
+     * Adds the indexed view predicate and exact original selector.
+     *
+     * @param request Selected history view.
+     * @param clauses Mutable bound SQL predicates.
+     * @param values Mutable bound SQL values.
+     */
+    private viewPredicate;
+    /**
+     * Validates view identity and complete-key continuation category.
+     *
+     * @param request View and continuation key.
+     */
+    private validateView;
+    /**
+     * Converts a typed Agent ID to its canonical key.
+     *
+     * @param id Typed Agent identifier.
+     * @returns Canonical storage key.
+     */
+    private key;
+    /**
+  
+     * Rejects calls after this handle closes.
+  
+     */
+    private requireOpen;
+}
+//# sourceMappingURL=agent-history.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-history.d.ts","sourceRoot":"","sources":["../../src/mysql/agent-history.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6EAA6E,CAAC;AACtH,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC9B,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAGzD;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;iBACU,MAAM,GAAG,MAAM;CAG7B,CAAC;AAEF;;;;GAIG;AACH,qBAAa,iBAAiB,CAAC,EAAE,CAAE,YAAW,mBAAmB,CAAC,EAAE,CAAC;;IAoBjE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAR1B;;;;;OAKG;gBAEgB,KAAK,EAAE,wBAAwB,CAAC,EAAE,CAAC,EACnC,OAAO,EAAE,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAG1E;;;;;;OAMG;IACG,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnE;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAYpE;;;;OAIG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAIb;;;;OAIG;YACW,UAAU;IAexB;;;;;;;;OAQG;YACW,KAAK;IA4BnB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAkBrB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACH,OAAO,CAAC,GAAG;IAMX;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAGpB"}

package/dist/mysql/agent-history.js

@@ -0,0 +1,212 @@
+/*
+ * 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 { createHash } from "node:crypto";
+import { AgentHistoryKeys, AgentHistoryPages, } from "@spine-event-engine/storage/provider";
+import { AgentHistoryRecords } from "@spine-event-engine/storage/provider";
+import { MysqlRecordStorage } from "./record-storage.js";
+import { AgentHistoryIndexBytes } from "./table-spec.js";
+/**
+ * Hashes complete identities into bounded physical IDs and indexed scope keys.
+ */
+export const AgentHistoryHash = {
+    /**
+     * Calculates the fixed-width digest of a complete logical identity.
+     *
+     * @param value Complete logical identity.
+     * @returns Full SHA-256 hex digest.
+     */
+    value(value) {
+        return createHash("sha256").update(value, "utf8").digest("hex");
+    },
+};
+/**
+ * Stores Agent history in the shared MySQL immutable record family.
+ *
+ * @typeParam Id Typed Agent identifier.
+ */
+export class MysqlAgentHistory {
+    input;
+    records;
+    /**
+     * Records whether this handle accepts calls.
+     */
+    #open = true;
+    /**
+  
+     * Reuses one table and index preparation promise.
+  
+     */
+    #ready;
+    /**
+     * Binds one typed Agent repository to the provider record handle.
+     *
+     * @param input Repository and complete tenant scope.
+     * @param records Native record-family storage.
+     */
+    constructor(input, records) {
+        this.input = input;
+        this.records = records;
+    }
+    /**
+     * Writes one original entry or confirms byte-identical content.
+     *
+     * @param entityId Typed Agent identifier.
+     * @param entry Complete history entry.
+     * @returns Completion after immutable storage confirms the entry.
+     */
+    async append(entityId, entry) {
+        this.requireOpen();
+        if (AgentHistoryKeys.indexValue(AgentHistoryKeys.fromEntry(entry)).length > AgentHistoryIndexBytes)
+            throw new RangeError("Agent history ordering key exceeds the MySQL index capacity.");
+        await this.ready();
+        await this.records.writeImmutable(AgentHistoryRecords.record(this.input.stateType, this.key(entityId), entry));
+    }
+    /**
+     * Reads a bounded indexed page in full Timestamp/category/UTF-8 order.
+     *
+     * @param request Typed Agent, view, continuation, and response limits.
+     * @returns Original entries and continuation status.
+     */
+    async read(request) {
+        this.requireOpen();
+        await this.ready();
+        const agentKey = this.key(request.entityId);
+        const after = request.after === undefined ? undefined : AgentHistoryKeys.indexValue(request.after);
+        this.validateView(request);
+        return AgentHistoryPages.read(request, after, (cursor, limit) => this.fetch(agentKey, request, cursor, limit));
+    }
+    /**
+  
+     * Closes this handle without deleting stored records.
+  
+     */
+    close() {
+        if (!this.#open)
+            return;
+        this.#open = false;
+        this.records.close();
+    }
+    /**
+     * Prepares fixed composite indexes after canonical table initialization.
+     *
+     * @returns Shared preparation promise for this handle.
+     */
+    ready() {
+        return (this.#ready ??= this.initialize());
+    }
+    /**
+     * Creates each native index idempotently on the shared record family.
+     *
+     * @returns Completion after all three definitions are validated.
+     */
+    async initialize() {
+        await this.records.prepare();
+        await this.records.ensureHistoryIndex("agent_history_full", ["scope_digest", "order_key"]);
+        await this.records.ensureHistoryIndex("agent_history_category", [
+            "scope_digest",
+            "category",
+            "order_key",
+        ]);
+        await this.records.ensureHistoryIndex("agent_history_conversation", [
+            "scope_digest",
+            "conversation_digest",
+            "order_key",
+        ]);
+    }
+    /**
+     * Reads a bounded native page with complete scope and view predicates.
+     *
+     * @param agentKey Canonical Agent key.
+     * @param request View and response bounds.
+     * @param after Exclusive encoded order key.
+     * @param limit Maximum native rows for this chunk.
+     * @returns Complete original stored records.
+     */
+    async fetch(agentKey, request, after, limit) {
+        const values = [
+            AgentHistoryHash.value(AgentHistoryRecords.scope(this.input.stateType, agentKey)),
+            this.input.stateType,
+            agentKey,
+        ];
+        const clauses = [
+            "`scope_digest` = ?",
+            "BINARY `state_type` = BINARY ?",
+            "BINARY `agent_key` = BINARY ?",
+        ];
+        this.viewPredicate(request, clauses, values);
+        if (after !== undefined) {
+            values.push(after);
+            clauses.push("`order_key` > ?");
+        }
+        values.push(limit);
+        const sql = `SELECT \`bytes\` FROM \`${this.records.tableName}\` WHERE ${clauses.join(" AND ")} ` +
+            "ORDER BY `order_key` ASC LIMIT ?";
+        return this.records.historyPage(sql, values);
+    }
+    /**
+     * Adds the indexed view predicate and exact original selector.
+     *
+     * @param request Selected history view.
+     * @param clauses Mutable bound SQL predicates.
+     * @param values Mutable bound SQL values.
+     */
+    viewPredicate(request, clauses, values) {
+        if (request.view.kind === "full")
+            return;
+        if (request.view.kind === "conversation") {
+            const conversation = request.view.conversation.value;
+            values.push(AgentHistoryHash.value(conversation));
+            clauses.push("`conversation_digest` = ?");
+            values.push(conversation);
+            clauses.push("BINARY `conversation_key` = BINARY ?");
+            return;
+        }
+        values.push(request.view.kind);
+        clauses.push("`category` = ?");
+    }
+    /**
+     * Validates view identity and complete-key continuation category.
+     *
+     * @param request View and continuation key.
+     */
+    validateView(request) {
+        const kind = request.view.kind;
+        if (kind === "conversation" && request.view.conversation.value.length === 0)
+            throw new TypeError("Conversation history requires a ConversationId.");
+        if (request.after !== undefined && kind !== "full" && request.after.category !== kind)
+            throw new TypeError("Agent history boundary category does not match the view.");
+    }
+    /**
+     * Converts a typed Agent ID to its canonical key.
+     *
+     * @param id Typed Agent identifier.
+     * @returns Canonical storage key.
+     */
+    key(id) {
+        const key = this.input.id.key(id);
+        if (key.length === 0)
+            throw new TypeError("Agent history Entity ID is required.");
+        return key;
+    }
+    /**
+  
+     * Rejects calls after this handle closes.
+  
+     */
+    requireOpen() {
+        if (!this.#open)
+            throw new Error("Agent history storage handle is closed.");
+    }
+}
+//# sourceMappingURL=agent-history.js.map

package/dist/mysql/agent-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-history.js","sourceRoot":"","sources":["../../src/mysql/agent-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAGzC,OAAO,EACL,gBAAgB,EAChB,iBAAiB,GAKlB,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAE3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B;;;;;OAKG;IACH,KAAK,CAAC,KAAa;QACjB,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClE,CAAC;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,OAAO,iBAAiB;IAoBT;IACA;IApBnB;;OAEG;IACH,KAAK,GAAG,IAAI,CAAC;IAEb;;;;OAIG;IACH,MAAM,CAA4B;IAElC;;;;;OAKG;IACH,YACmB,KAAmC,EACnC,OAAuD;QADvD,UAAK,GAAL,KAAK,CAA8B;QACnC,YAAO,GAAP,OAAO,CAAgD;IACvE,CAAC;IAEJ;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CAAC,QAAY,EAAE,KAAwB;QACjD,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,IACE,gBAAgB,CAAC,UAAU,CAAC,gBAAgB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,GAAG,sBAAsB;YAE9F,MAAM,IAAI,UAAU,CAAC,8DAA8D,CAAC,CAAC;QACvF,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,IAAI,CAAC,OAAO,CAAC,cAAc,CAC/B,mBAAmB,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAC5E,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,CAAC,OAA6B;QACtC,IAAI,CAAC,WAAW,EAAE,CAAC;QACnB,MAAM,IAAI,CAAC,KAAK,EAAE,CAAC;QACnB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC5C,MAAM,KAAK,GACT,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACvF,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QAC3B,OAAO,iBAAiB,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAC9D,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,CAC7C,CAAC;IACJ,CAAC;IAED;;;;OAIG;IACH,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO;QACxB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACvB,CAAC;IAED;;;;OAIG;IACK,KAAK;QACX,OAAO,CAAC,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;IAC7C,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,UAAU;QACtB,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7B,MAAM,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,oBAAoB,EAAE,CAAC,cAAc,EAAE,WAAW,CAAC,CAAC,CAAC;QAC3F,MAAM,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,wBAAwB,EAAE;YAC9D,cAAc;YACd,UAAU;YACV,WAAW;SACZ,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,4BAA4B,EAAE;YAClE,cAAc;YACd,qBAAqB;YACrB,WAAW;SACZ,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;OAQG;IACK,KAAK,CAAC,KAAK,CACjB,QAAgB,EAChB,OAA6B,EAC7B,KAAyB,EACzB,KAAa;QAEb,MAAM,MAAM,GAAwB;YAClC,gBAAgB,CAAC,KAAK,CAAC,mBAAmB,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACjF,IAAI,CAAC,KAAK,CAAC,SAAS;YACpB,QAAQ;SACT,CAAC;QACF,MAAM,OAAO,GAAG;YACd,oBAAoB;YACpB,gCAAgC;YAChC,+BAA+B;SAChC,CAAC;QACF,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;QAC7C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,OAAO,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAClC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,MAAM,GAAG,GACP,2BAA2B,IAAI,CAAC,OAAO,CAAC,SAAS,YAAY,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG;YACrF,kCAAkC,CAAC;QACrC,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACK,aAAa,CACnB,OAA6B,EAC7B,OAAiB,EACjB,MAA2B;QAE3B,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO;QACzC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACzC,MAAM,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;YACrD,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;YAClD,OAAO,CAAC,IAAI,CAAC,2BAA2B,CAAC,CAAC;YAC1C,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACK,YAAY,CAAC,OAA6B;QAChD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAC/B,IAAI,IAAI,KAAK,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC;YACzE,MAAM,IAAI,SAAS,CAAC,iDAAiD,CAAC,CAAC;QACzE,IAAI,OAAO,CAAC,KAAK,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC,QAAQ,KAAK,IAAI;YACnF,MAAM,IAAI,SAAS,CAAC,0DAA0D,CAAC,CAAC;IACpF,CAAC;IAED;;;;;OAKG;IACK,GAAG,CAAC,EAAM;QAChB,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAClC,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,SAAS,CAAC,sCAAsC,CAAC,CAAC;QAClF,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;OAIG;IACK,WAAW;QACjB,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC9E,CAAC;CACF"}

package/dist/mysql/record-storage.d.ts

@@ -52,6 +52,37 @@ export declare class MysqlRecordStorage<I, R extends Message> extends RecordStor
      * @returns Resolves after table creation and inspection complete.
      */
     prepare(): Promise<void>;
+    /**
+     * Reads a bounded package-local native history page.
+     *
+     * @param sql Parameterized SQL assembled by the Agent history provider.
+     * @param values Bound scope, view, boundary, and limit values.
+     * @returns Decoded original record envelopes.
+     */
+    historyPage(sql: string, values: readonly unknown[]): Promise<readonly R[]>;
+    /**
+     * Creates one required complete Agent history index when absent.
+     *
+     * @param name Fixed provider index name.
+     * @param columns Fixed complete index columns.
+     * @returns Completion after the native index definition is checked.
+     */
+    ensureHistoryIndex(name: string, columns: readonly string[]): Promise<void>;
+    /**
+     * Reads complete physical index metadata for one fixed history index.
+     *
+     * @param connection Active MySQL connection.
+     * @param name Fixed required index name.
+     * @returns Ordered native index components.
+     */
+    private historyIndex;
+    /**
+     * Rejects prefixes, wrong order, or a different native index.
+     *
+     * @param rows Ordered native index components.
+     * @param columns Required complete index columns.
+     */
+    private assertHistoryIndex;
     /**
      * Creates a MySQL record-family storage handle.
      *
@@ -160,11 +191,13 @@ export declare class MysqlRecordStorage<I, R extends Message> extends RecordStor
     protected queryRecordEntries(query: RecordQuery<I>): Promise<readonly RecordEntry<I, R>[]>;
     /**
      * Returns the normalized query features genuinely executed by MySQL.
+     *
      * @returns The normalized features executed by this provider.
      */
     protected queryCapabilities(): StorageQueryCapabilities;
     /**
      * Executes the complete candidate selection in contained, bound MySQL SQL.
+     *
      * @param plan The validated normalized query plan.
      * @returns The selected record entries.
      */

package/dist/mysql/record-storage.d.ts.map

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

package/dist/mysql/record-storage.js

@@ -12,6 +12,7 @@
  * the License.
  */
 import { fromBinary, ScalarType, toBinary } from "@bufbuild/protobuf";
+import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import { StringifierRegistry } from "@spine-event-engine/core";
 import { ColumnMappings, defaultQueryCandidateLimit, RecordStorage, } from "@spine-event-engine/storage";
@@ -37,7 +38,10 @@ export class MysqlRecordStorage extends RecordStorage {
      */
     atomicCompareAndSet = true;
     #ready;
-    #bound;
+    /**
+     * Keeps transaction connections separate across concurrent asynchronous calls.
+     */
+    #bound = new AsyncLocalStorage();
     #idColumn;
     #columnMapping;
     /**
@@ -56,6 +60,82 @@ export class MysqlRecordStorage extends RecordStorage {
     async prepare() {
         await this.using(() => Promise.resolve());
     }
+    /**
+     * Reads a bounded package-local native history page.
+     *
+     * @param sql Parameterized SQL assembled by the Agent history provider.
+     * @param values Bound scope, view, boundary, and limit values.
+     * @returns Decoded original record envelopes.
+     */
+    async historyPage(sql, values) {
+        return this.using(async (connection) => {
+            const [rows] = await connection.query(sql, [...values]);
+            try {
+                return rows.map((row) => fromBinary(this.recordSpec.recordType, row.bytes));
+            }
+            catch (error) {
+                throw mysqlError(MysqlStorageDataError, "Stored MySQL history data is invalid.", error);
+            }
+        });
+    }
+    /**
+     * Creates one required complete Agent history index when absent.
+     *
+     * @param name Fixed provider index name.
+     * @param columns Fixed complete index columns.
+     * @returns Completion after the native index definition is checked.
+     */
+    async ensureHistoryIndex(name, columns) {
+        await this.using(async (connection) => {
+            const existing = await this.historyIndex(connection, name);
+            if (existing.length !== 0) {
+                this.assertHistoryIndex(existing, columns);
+                return;
+            }
+            if (!/^[a-z_]+$/u.test(name) || columns.some((column) => !/^[a-z_]+$/u.test(column)))
+                throw new MysqlStorageSchemaError("MySQL Agent history index name is invalid.");
+            const quoted = columns.map((column) => `\`${column}\``).join(", ");
+            try {
+                await connection.query(`CREATE INDEX \`${name}\` ON \`${this.tableName}\` (${quoted})`);
+            }
+            catch (error) {
+                if (error.code !== "ER_DUP_KEYNAME")
+                    throw error;
+            }
+            this.assertHistoryIndex(await this.historyIndex(connection, name), columns);
+        });
+    }
+    /**
+     * Reads complete physical index metadata for one fixed history index.
+     *
+     * @param connection Active MySQL connection.
+     * @param name Fixed required index name.
+     * @returns Ordered native index components.
+     */
+    async historyIndex(connection, name) {
+        const [rows] = await connection.query("SELECT index_name AS index_name, non_unique AS non_unique, " +
+            "column_name AS column_name, seq_in_index AS seq_in_index, " +
+            "sub_part AS sub_part, collation AS collation, index_type AS index_type " +
+            "FROM information_schema.statistics WHERE table_schema=DATABASE() AND table_name=? " +
+            "AND index_name=? ORDER BY seq_in_index", [this.tableName, name]);
+        return rows;
+    }
+    /**
+     * Rejects prefixes, wrong order, or a different native index.
+     *
+     * @param rows Ordered native index components.
+     * @param columns Required complete index columns.
+     */
+    assertHistoryIndex(rows, columns) {
+        if (rows.length !== columns.length ||
+            rows.some((row, index) => row.column_name !== columns[index] ||
+                Number(row.seq_in_index) !== index + 1 ||
+                row.sub_part !== null ||
+                Number(row.non_unique) !== 1 ||
+                row.collation !== "A" ||
+                row.index_type !== "BTREE"))
+            throw new MysqlStorageSchemaError("MySQL Agent history index is incompatible.");
+    }
     /**
      * Creates a MySQL record-family storage handle.
      *
@@ -189,17 +269,16 @@ export class MysqlRecordStorage extends RecordStorage {
      * @returns Returns the work result.
      */
     async withConnection(connection, work) {
-        if (this.#bound !== undefined) {
+        const bound = this.#bound.getStore();
+        if (bound !== undefined) {
+            if (bound !== connection)
+                throw new Error("MySQL record handle is bound to another transaction.");
             return work();
         }
-        this.#bound = connection;
-        try {
+        return this.#bound.run(connection, async () => {
             await this.ready(connection);
             return await work();
-        }
-        finally {
-            this.#bound = undefined;
-        }
+        });
     }
     /**
      * Reads one record with the coordinator transaction's row/gap lock.
@@ -257,6 +336,7 @@ export class MysqlRecordStorage extends RecordStorage {
     }
     /**
      * Returns the normalized query features genuinely executed by MySQL.
+     *
      * @returns The normalized features executed by this provider.
      */
     queryCapabilities() {
@@ -267,6 +347,7 @@ export class MysqlRecordStorage extends RecordStorage {
     }
     /**
      * Executes the complete candidate selection in contained, bound MySQL SQL.
+     *
      * @param plan The validated normalized query plan.
      * @returns The selected record entries.
      */
@@ -419,7 +500,7 @@ export class MysqlRecordStorage extends RecordStorage {
      * @returns Resolves to the operation result.
      */
     async using(work) {
-        const bound = this.#bound;
+        const bound = this.#bound.getStore();
         if (bound !== undefined) {
             return work(bound);
         }
@@ -1034,10 +1115,10 @@ function groupedIndexes(indexes) {
     for (const index of indexes) {
         const existing = grouped.get(index.index_name) ?? {
             name: index.index_name,
-            nonUnique: index.non_unique,
+            nonUnique: Number(index.non_unique),
             columns: [],
         };
-        existing.columns[index.seq_in_index - 1] = index.column_name;
+        existing.columns[Number(index.seq_in_index) - 1] = index.column_name;
         grouped.set(index.index_name, existing);
     }
     return [...grouped.values()];