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

package/README.md

@@ -1,5 +1,8 @@
 # MySQL storage for Spine TS
 
+See [storage layout and database preparation](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/STORAGE_LAYOUT.md) for
+physical structures, tenant placement, prerequisites, and customization.
+
 `@spine-event-engine/storage-mysql` stores Spine TS records in MySQL. It is a
 durable implementation of `@spine-event-engine/storage` and manages the mysql2
 connection pool and its private tables. PostgreSQL is not supported by this
@@ -11,14 +14,15 @@ 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;
+For an application using Agents, this provider retains typed admission receipts,
+Entity state, and recorded interactions across restarts, without resuming an
+interrupted handler. 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.
-- ✅ Manages a bounded `mysql2` connection pool; InnoDB writes are transactional.
+- ✅ Manages a bounded `mysql2` connection pool and atomic single-record conditions.
 - ✅ Supports declared-column filters, sorting, offsets, limits, and
   continuations.
 - ✅ Keeps adapter tables private behind the common `RecordStorage` API.
@@ -38,9 +42,12 @@ The snapshot tag can change before a stable release.
 
 ## 🔌 Create and close a MySQL factory
 
-Provide a MySQL URL that includes a database name. Building the factory opens
-its pool only; each record family creates and verifies its private table lazily
-on first use.
+Provide a MySQL URL that includes a database name. Building the factory
+validates settings locally and opens no pool. `checkConnection()` optionally
+probes the shared database with a read-only query. It reuses an existing
+runtime pool or opens and releases a temporary pool. The first storage
+operation binds its database and creates or verifies
+its private table lazily.
 
 <!-- docs-snippet-path: packages/storage-mysql/src/index.ts -->
 
@@ -74,7 +81,7 @@ try {
   if (stored?.value !== "task-42") throw new Error("The record was not stored.");
 } finally {
   await records.close();
-  factory.close();
+  await factory.close();
 }
 ```
 
@@ -83,8 +90,9 @@ require TLS and provide the issuing CA explicitly; do not enable certificate
 verification without the CA material needed by your managed MySQL endpoint.
 
 For a multitenant application, assign each complete generated `TenantId` to a
-different database. The factory creates one pool per configured tenant and
-selects that pool before it opens a table or starts a transaction:
+different database. The factory resolves each tenant's database and opens
+its pool on first use; concurrent first uses share the binding. It selects
+that pool before opening a table or starting a transaction:
 
 ```ts
 import { create } from "@bufbuild/protobuf";
@@ -95,6 +103,7 @@ const acme = create(TenantIdSchema, { kind: { case: "value", value: "acme" } });
 const globex = create(TenantIdSchema, { kind: { case: "value", value: "globex" } });
 
 const factory = await MysqlStorageFactory.newBuilder()
+  .setOptions({ url: "mysql://user:password@db/shared" })
   .setTenantOptions([
     { tenantId: acme, options: { url: "mysql://user:password@db/acme" } },
     { tenantId: globex, options: { url: "mysql://user:password@db/globex" } },
@@ -102,6 +111,12 @@ const factory = await MysqlStorageFactory.newBuilder()
   .build();
 ```
 
+Alternatively, `setTenantResolver(async (tenantId) => options)` resolves each
+tenant's destination on first use. Fixed tenant entries and a resolver cannot
+be combined. Either mode requires shared `setOptions`; tenants must use
+distinct databases. Shared and tenant settings may point to the same database
+only when their physical table families do not collide.
+
 Use a dedicated database account. The account must be able to create and
 inspect the adapter tables and perform normal reads and writes. Do not commit
 connection URLs or credentials.
@@ -118,13 +133,16 @@ pnpm typecheck:build
 ## ✨ Supported records and queries
 
 The adapter performs record CRUD, payload-based compare-and-set, named-column
-queries, sort order, offsets, limits, and keyset continuations. InnoDB makes
-`writeAll` and Entity commits transactional. MyISAM and Aria instead use
-deterministic ordered writes with immutable-prefix retry semantics; a failed
-write may require an identical retry. It supports primitive and structured
+queries, sort order, offsets, limits, and keyset continuations. Batches and
+Entity commits use independent ordered records on InnoDB, MyISAM, and Aria.
+A failed operation can leave its completed prefix; an identical Entity retry
+reuses prepared versions and Event IDs. It supports primitive and structured
 storage IDs. Declared columns support strings, booleans, integral Protobuf
-numbers, enums, bytes, messages, `Timestamp`, and `Version`. Spine JVM JDBC
-does not support `float` or `double` record columns, so this adapter rejects
+numbers, enums, bytes, messages, `Timestamp`, and `Version`. The provider-only
+live Agent commit is a separate InnoDB transaction: it conditionally checks
+the initial Entity version and complete model preferences before committing
+any changed state, final audit, and preferences together. 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`.
@@ -228,21 +246,11 @@ TLS, and plan backups, monitoring, and migrations. Indexed `bigint` values must
 fit the exact signed 64-bit MySQL range. PostgreSQL is provided separately by
 [`@spine-event-engine/storage-postgres`](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/storage-postgres/README.md).
 
-Before starting this corrected layout against an existing database, run the
-legacy-layout inventory for every configured tenant database:
-
-```sh
-pnpm --dir packages/storage-mysql inventory:legacy -- \
-  --url 'mysql://user:password@127.0.0.1:3306/tenant_a' \
-  --url 'mysql://user:password@127.0.0.1:3306/tenant_b'
-```
-
-The command exits nonzero if a database is unreachable or contains the old
-`_scope`, `_revision`, or compound scope key. Do not start the corrected
-runtime until it passes. The factory repeats this check for every configured
-database before it becomes usable. The runtime does not read both layouts or choose
-between rows that old Bounded Context partitions would collapse onto the same
-new `ID`; migrate those rows offline and stop on every conflict.
+Factory construction validates configuration without connecting. Explicit preparation
+or first use checks the selected record families; it does not scan unrelated
+tables. Existing tables must satisfy the expected layout. See the
+[storage layout reference](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/STORAGE_LAYOUT.md#6-startup-sequence) for
+creation and compatibility-check timing.
 
 ## 🔗 Learn more
 

package/REFERENCE.md

@@ -5,6 +5,7 @@ This reference is for coding agents configuring the supported MySQL storage adap
 ## Public entry point
 
 Import `MysqlStorageFactory`, `MysqlStorageOptions`, `MysqlTenantStorageOptions`,
+`MysqlTenantResolver`,
 `MysqlEntityStorageHandle`, `MysqlStorageFactoryBuilder`,
 `MysqlCreateOperation`, `CreateOperationFactory`, `MysqlTableSpec`,
 `MysqlColumnSpec`, `MysqlStorageConfigurationError`,
@@ -15,12 +16,27 @@ Import `MysqlStorageFactory`, `MysqlStorageOptions`, `MysqlTenantStorageOptions`
 ## Connection and schema
 
 `MysqlStorageFactory.newBuilder().setOptions(options).build()` configures one
-single-tenant database. `setTenantOptions(entries)` configures one distinct
-database and pool per complete generated `TenantId`. The factory selects
-the matching pool before table, query, transaction, or lock work.
-`setStringifierRegistry(registry)` configures reversible mappings for
-message-valued IDs and ordinary message columns; the builder snapshots the
-registry so later caller changes do not alter stored or queried values.
+shared database without connecting. `setTenantOptions(entries)` configures
+distinct databases for complete generated `TenantId` values;
+`setTenantResolver(resolver)` selects them asynchronously on first use. Fixed
+entries and a resolver are mutually exclusive. Shared options are required in
+both modes. The first storage operation binds each database and its pool;
+concurrent first uses share that binding, while a failed binding can retry.
+`checkConnection()` probes only the shared database with `SELECT 1`, performs
+no schema checks or DDL, and releases a temporary pool unless runtime work
+already bound one. Successful checks are remembered; failed checks can retry.
+The provider-only `StoragePreparations` port accepts declared Record, current
+Entity and enabled history, or surviving Agent audit requirements. Its `check`
+mode reads physical metadata without creating tables or indexes. Its `create`
+mode creates missing structures and verifies their complete layout. Both modes
+reuse a bound runtime pool or release temporary pools, and compatible results
+are shared with later ordinary use. A failed attempt remains retryable.
+The default shared registry converts message-valued IDs and ordinary message
+columns using generated descriptors registered on module import.
+`setStringifierRegistry(registry)` accepts a custom registry; the builder
+snapshots it so later caller changes do not alter stored or queried values.
+`setEventStoreTable(contextName, table, role?)` selects one physical Event Store
+table for the exact bounded-context name and domain or system role.
 `Identifiers` choose the storage ID representation; the configured
 `StringifierRegistry` supplies the matching reversible representation for
 message-valued IDs and declared message columns. `RecordQuery<I>` statically
@@ -28,7 +44,8 @@ types IDs only. Filter names and values are runtime inputs: MySQL checks the
 name against the declared columns and maps each value through the corresponding
 descriptor/column mapping, rather than accepting an application-constructed
 provider string.
-Per-family tables are created and verified lazily on first use. Options support
+Without explicit preparation, per-family tables are created and verified lazily
+on first use. Options support
 `connectionLimit`, `connectTimeoutMs`, and TLS material. Failure to validate
 configuration throws `MysqlStorageConfigurationError`; inaccessible connections
 are reported as `MysqlStorageConnectionError`; an
@@ -45,34 +62,36 @@ one-byte binary collation, such as `latin1_bin`, and can store only IDs
 representable in that character set. An `utf8mb4` ID of that declared width
 cannot be converted to MyISAM.
 
-Before deployment, run `pnpm --dir packages/storage-mysql inventory:legacy --
---url <database-url>` once for every configured tenant database. The command
-fails closed on connection errors, `_scope`, `_revision`, or an old primary key
-containing `_scope`. Passing this inventory is a startup prerequisite for an
-upgraded application. Factory build repeats the inspection for every configured
-database; the runtime has no dual-layout reader or automatic
-conflict winner.
+The optional `inventory:legacy` command remains available for operators
+examining older layouts. Factory build and `checkConnection()` do not scan
+unrelated tables or perform an upgrade-layout inventory. Requested record
+families are checked when normal storage operations first use them.
 
 ## Lifecycle and tenancy
 
-`close(): void` marks the factory and its live handles closed and starts pool
-draining. Callers do not await it. A record handle closes independently. A
-single-tenant factory has one database. A multitenant factory requires a
-complete generated `TenantId` on each operation and routes it to its configured
-database. Bounded Context names are diagnostic only and never partition rows,
-tables, locks, or queries.
-
-Each Entity source and history family has an independent table. Errors do not
-include connection URLs, credentials, or provider details.
+`close(): Promise<void>` immediately fences new public operations, waits for
+complete admitted record, Entity, Agent, and commit work, then closes live
+handles and drains pools. Await it to
+observe cleanup failures; repeated calls return the same completion. A record
+handle closes independently. Shared operations use the configured shared
+destination. Creating a multitenant storage handle requires a complete
+generated `TenantId` in its `StorageContext`; that captured tenant selects the
+database for operations through the handle. Bounded Context names are
+diagnostic only and never partition rows, tables, locks, or queries.
+
+Each Entity source and history family has an independent table. Top-level
+provider error messages and public responses omit connection URLs,
+credentials, and driver details. The original driver failure remains available
+as the internal `cause`; do not expose it in public responses or unfiltered
+logs.
 
 ## Records and queries
 
-CRUD operations use normal statements. Payload-based compare-and-set uses an
-InnoDB transaction or a keyed `GET_LOCK` on MyISAM and Aria. On InnoDB,
-`writeAll` encodes the input first, applies entries in input order, and commits
-all rows or none. On MyISAM and Aria, `writeAll` has deterministic input-order
-semantics but is not transactional; a failed Entity prefix requires an
-identical retry. Repeated storage slots in a batch leave the last entry as the
+CRUD operations use normal statements. Payload-based compare-and-set uses
+atomic conditional statements for one storage slot on InnoDB, MyISAM, and Aria.
+`writeAll` encodes input first and writes entries in input order; a later failure
+leaves completed rows in place on every engine. Repeated storage slots in a
+batch leave the last completed entry as the
 stored value. IDs are declared as generated message IDs or the supported
 primitive `string`, `int32`, and `int64` kinds. Primitive IDs use native MySQL
 values; message IDs use their reversible stringifier, compact Proto JSON by
@@ -121,17 +140,18 @@ acquired.
 ## Entity history seam
 
 The provider/framework Entity handle returns current records plus immutable
-state and event history. It is not a remote application history API. State append and retention for one entity use a MySQL server lock;
-this coordination applies to one MySQL server only. Trim and truncate use
+state and event history. It is not a remote application history API. State and
+diagnostic append use immutable per-record insertion. Trim and truncate use
 fixed-size chunks. A failed chunk can leave earlier chunks durable, so callers
 retry maintenance. Current-record and history actions are separate calls, not
 one cross-storage transaction.
 
-The internal atomic Entity commit port writes current state, configured history,
-and framework delivery events. InnoDB uses one connection transaction;
-nontransactional engines use a deterministic immutable-history prefix and may
-require an identical retry after a storage failure. Standalone history
-operations remain separate.
+The internal Entity commit port writes state history, diagnostic Events,
+framework delivery Events, then current state as independent records. A failure
+can leave a completed prefix on every engine. One classified deadlock retry
+replays captured input with unchanged versions and Event IDs. Standalone
+history operations remain separate; a delivery Event alone does not prove the
+current-state write completed.
 
 ## Agent history
 
@@ -150,26 +170,15 @@ 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
-driver-operation failures. Custom creation uses `useOperationFactory()`; its
-resolved `MysqlTableSpec` has the same native column types and naming precedence
-as default DDL (explicit grouped name, explicit record name, then default).
+## Agent live persistence
+
+The live Agent path is exercised on MySQL and MariaDB. Agent repositories
+require transactional InnoDB tables for atomic Agent commits. The handle
+rejects a nontransactional engine before accepting Agent work; other Entity
+families retain their configured engine behavior. `appendAll()` commits an
+immutable Agent history group in one transaction. `commitAgent()` compares
+the exact Entity image and model preferences, then writes accepted state,
+preference, and history changes atomically. A no-op or preference-only turn
+can leave the Entity Version unchanged. The separate typed receipt records
+admission, not executable work for replay. Connection binding is scoped to an
+asynchronous operation; no transaction stays open during a model request.

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { MysqlStorageConfigurationError, MysqlStorageConnectionError, MysqlStorageDataError, MysqlStorageFactory, MysqlStorageOperationError, MysqlStorageSchemaError, type CreateOperationFactory, type MysqlColumnSpec, type MysqlCreateOperation, type MysqlStorageFactoryBuilder, type MysqlStorageOptions, type MysqlTenantStorageOptions, type MysqlTableSpec, } from "./mysql/storage-factory.js";
+export { MysqlStorageConfigurationError, MysqlStorageConnectionError, MysqlStorageDataError, MysqlStorageFactory, MysqlStorageOperationError, MysqlStorageSchemaError, type CreateOperationFactory, type MysqlColumnSpec, type MysqlCreateOperation, type MysqlStorageFactoryBuilder, type MysqlStorageOptions, type MysqlTenantStorageOptions, type MysqlTenantResolver, type MysqlTableSpec, } from "./mysql/storage-factory.js";
 export type { MysqlEntityStorageHandle } from "./mysql/entity-history.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,cAAc,GACpB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,EACvB,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,cAAc,GACpB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,GAQxB,MAAM,4BAA4B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,qBAAqB,EACrB,mBAAmB,EACnB,0BAA0B,EAC1B,uBAAuB,GASxB,MAAM,4BAA4B,CAAC"}

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

@@ -1,7 +1,8 @@
 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";
+import { type AgentHistoryRecord } from "@spine-event-engine/proto/generated/spine/server/agent/history_record_pb.js";
+import { type AgentHistoryCapacity, type AgentHistoryPage, type AgentHistoryRead, type AgentHistoryStorage, type AgentHistoryStorageInput } from "@spine-event-engine/storage/provider";
+import { MysqlRecordStorage, type OnPublicOperation } from "./record-storage.js";
+import { MysqlAgentTransaction } from "./agent-transaction.js";
 /**
  * Hashes complete identities into bounded physical IDs and indexed scope keys.
  */
@@ -14,6 +15,10 @@ export declare const AgentHistoryHash: {
      */
     value(value: string): string;
 };
+/**
+ * Declares the complete native indexes required by MySQL Agent history.
+ */
+export declare const AgentHistoryIndexes: readonly [readonly ["agent_history_full", readonly ["scope_digest", "order_key"]], readonly ["agent_history_category", readonly ["scope_digest", "category", "order_key"]], readonly ["agent_history_conversation", readonly ["scope_digest", "conversation_digest", "order_key"]]];
 /**
  * Stores Agent history in the shared MySQL immutable record family.
  *
@@ -23,13 +28,36 @@ export declare class MysqlAgentHistory<Id> implements AgentHistoryStorage<Id> {
     #private;
     private readonly input;
     private readonly records;
+    private readonly onAdmit;
+    private readonly transaction?;
+    /**
+     * Maximum immutable Agent history record bytes supported by MySQL.
+     */
+    readonly capacity: AgentHistoryCapacity;
     /**
      * Binds one typed Agent repository to the provider record handle.
      *
      * @param input Repository and complete tenant scope.
      * @param records Native record-family storage.
+     * @param onAdmit Admits complete public history operations.
+     * @param transaction Coordinates native immutable audit groups.
+     */
+    constructor(input: AgentHistoryStorageInput<Id>, records: MysqlRecordStorage<string, AgentHistoryRecord>, onAdmit?: OnPublicOperation, transaction?: MysqlAgentTransaction | undefined);
+    /**
+     * Writes atomically writes captured immutable rows in the selected tenant database.
+     * @param entityId Typed Agent identifier.
+     * @param entries Complete Agent audit group.
+     * @returns Completion after the native transaction commits.
+     */
+    appendAll(entityId: Id, entries: readonly AgentHistoryEntry[]): Promise<void>;
+    /**
+     * Performs one admitted Agent audit group on a native connection.
+     *
+     * @param entityId Typed Entity identifier.
+     * @param entries Complete immutable history group.
+     * @returns Completion after the complete immutable audit group commits atomically.
      */
-    constructor(input: AgentHistoryStorageInput<Id>, records: MysqlRecordStorage<string, AgentHistoryRecord>);
+    private appendAllAdmitted;
     /**
      * Writes one original entry or confirms byte-identical content.
      *
@@ -38,6 +66,14 @@ export declare class MysqlAgentHistory<Id> implements AgentHistoryStorage<Id> {
      * @returns Completion after immutable storage confirms the entry.
      */
     append(entityId: Id, entry: AgentHistoryEntry): Promise<void>;
+    /**
+     * Executes an admitted provider operation.
+     *
+     * @param entityId Typed Agent identifier.
+     * @param entry Original entry.
+     * @returns Completion after immutable storage.
+     */
+    private appendAdmitted;
     /**
      * Reads a bounded indexed page in full Timestamp/category/UTF-8 order.
      *
@@ -46,9 +82,14 @@ export declare class MysqlAgentHistory<Id> implements AgentHistoryStorage<Id> {
      */
     read(request: AgentHistoryRead<Id>): Promise<AgentHistoryPage>;
     /**
-  
+     * Executes an admitted provider operation.
+     *
+     * @param request Typed history page request.
+     * @returns Original entries and continuation status.
+     */
+    private readAdmitted;
+    /**
      * Closes this handle without deleting stored records.
-  
      */
     close(): void;
     /**
@@ -95,9 +136,7 @@ export declare class MysqlAgentHistory<Id> implements AgentHistoryStorage<Id> {
      */
     private key;
     /**
-  
      * Rejects calls after this handle closes.
-  
      */
     private requireOpen;
 }

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

@@ -1 +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"}
+{"version":3,"file":"agent-history.d.ts","sourceRoot":"","sources":["../../src/mysql/agent-history.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACzE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,6EAA6E,CAAC;AACrF,OAAO,EAGL,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,wBAAwB,EAC9B,MAAM,sCAAsC,CAAC;AAG9C,OAAO,EAAE,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACjF,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAG/D;;GAEG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;iBACU,MAAM,GAAG,MAAM;CAG7B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,qRAItB,CAAC;AAEX;;;;GAIG;AACH,qBAAa,iBAAiB,CAAC,EAAE,CAAE,YAAW,mBAAmB,CAAC,EAAE,CAAC;;IAyBjE,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IA3B/B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAiD;IAYxF;;;;;;;OAOG;gBAEgB,KAAK,EAAE,wBAAwB,CAAC,EAAE,CAAC,EACnC,OAAO,EAAE,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,CAAC,EACvD,OAAO,GAAE,iBAAoC,EAC7C,WAAW,CAAC,EAAE,qBAAqB,GAAG,SAAS;IAGlE;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,iBAAiB,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7E;;;;;;OAMG;YACW,iBAAiB;IA+B/B;;;;;;OAMG;IACG,MAAM,CAAC,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE;;;;;;OAMG;YACW,cAAc;IAY5B;;;;;OAKG;IACG,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIpE;;;;;OAKG;YACW,YAAY;IAY1B;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;;;OAIG;IACH,OAAO,CAAC,KAAK;IAOb;;;;OAIG;YACW,UAAU;IAMxB;;;;;;;;OAQG;YACW,KAAK;IA4BnB;;;;;;OAMG;IACH,OAAO,CAAC,aAAa;IAkBrB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACH,OAAO,CAAC,GAAG;IAMX;;OAEG;IACH,OAAO,CAAC,WAAW;CAGpB"}

package/dist/mysql/agent-history.js

@@ -12,9 +12,12 @@
  * the License.
  */
 import { createHash } from "node:crypto";
+import { clone, toBinary } from "@bufbuild/protobuf";
+import { AgentHistoryRecordSchema, } from "@spine-event-engine/proto/generated/spine/server/agent/history_record_pb.js";
 import { AgentHistoryKeys, AgentHistoryPages, } from "@spine-event-engine/storage/provider";
 import { AgentHistoryRecords } from "@spine-event-engine/storage/provider";
 import { MysqlRecordStorage } from "./record-storage.js";
+import { MysqlAgentTransaction } from "./agent-transaction.js";
 import { AgentHistoryIndexBytes } from "./table-spec.js";
 /**
  * Hashes complete identities into bounded physical IDs and indexed scope keys.
@@ -30,6 +33,14 @@ export const AgentHistoryHash = {
         return createHash("sha256").update(value, "utf8").digest("hex");
     },
 };
+/**
+ * Declares the complete native indexes required by MySQL Agent history.
+ */
+export const AgentHistoryIndexes = [
+    ["agent_history_full", ["scope_digest", "order_key"]],
+    ["agent_history_category", ["scope_digest", "category", "order_key"]],
+    ["agent_history_conversation", ["scope_digest", "conversation_digest", "order_key"]],
+];
 /**
  * Stores Agent history in the shared MySQL immutable record family.
  *
@@ -38,14 +49,18 @@ export const AgentHistoryHash = {
 export class MysqlAgentHistory {
     input;
     records;
+    onAdmit;
+    transaction;
+    /**
+     * Maximum immutable Agent history record bytes supported by MySQL.
+     */
+    capacity = Object.freeze({ historyRecordBytes: 65_535 });
     /**
      * Records whether this handle accepts calls.
      */
     #open = true;
     /**
-  
      * Reuses one table and index preparation promise.
-  
      */
     #ready;
     /**
@@ -53,10 +68,52 @@ export class MysqlAgentHistory {
      *
      * @param input Repository and complete tenant scope.
      * @param records Native record-family storage.
+     * @param onAdmit Admits complete public history operations.
+     * @param transaction Coordinates native immutable audit groups.
      */
-    constructor(input, records) {
+    constructor(input, records, onAdmit = (work) => work(), transaction) {
         this.input = input;
         this.records = records;
+        this.onAdmit = onAdmit;
+        this.transaction = transaction;
+    }
+    /**
+     * Writes atomically writes captured immutable rows in the selected tenant database.
+     * @param entityId Typed Agent identifier.
+     * @param entries Complete Agent audit group.
+     * @returns Completion after the native transaction commits.
+     */
+    appendAll(entityId, entries) {
+        return this.onAdmit(() => this.appendAllAdmitted(entityId, entries));
+    }
+    /**
+     * Performs one admitted Agent audit group on a native connection.
+     *
+     * @param entityId Typed Entity identifier.
+     * @param entries Complete immutable history group.
+     * @returns Completion after the complete immutable audit group commits atomically.
+     */
+    async appendAllAdmitted(entityId, entries) {
+        this.requireOpen();
+        const key = this.key(entityId);
+        const rows = entries.map((entry) => {
+            if (AgentHistoryKeys.indexValue(AgentHistoryKeys.fromEntry(entry)).length >
+                AgentHistoryIndexBytes)
+                throw new RangeError("Agent history ordering key exceeds the MySQL index capacity.");
+            const row = clone(AgentHistoryRecordSchema, AgentHistoryRecords.record(this.input.stateType, key, entry));
+            if (toBinary(AgentHistoryRecordSchema, row).length > 65_535)
+                throw new RangeError("Agent history record exceeds the MySQL row capacity.");
+            return row;
+        });
+        if (rows.length === 0)
+            return;
+        if (this.transaction === undefined)
+            throw new Error("MySQL Agent history transaction is unavailable.");
+        await this.ready();
+        await this.transaction.commit([this.records.tableName], (connection) => this.records.withConnection(connection, async () => {
+            for (const row of rows)
+                await this.records.writeImmutable(row);
+        }));
     }
     /**
      * Writes one original entry or confirms byte-identical content.
@@ -66,6 +123,16 @@ export class MysqlAgentHistory {
      * @returns Completion after immutable storage confirms the entry.
      */
     async append(entityId, entry) {
+        return this.onAdmit(() => this.appendAdmitted(entityId, entry));
+    }
+    /**
+     * Executes an admitted provider operation.
+     *
+     * @param entityId Typed Agent identifier.
+     * @param entry Original entry.
+     * @returns Completion after immutable storage.
+     */
+    async appendAdmitted(entityId, entry) {
         this.requireOpen();
         if (AgentHistoryKeys.indexValue(AgentHistoryKeys.fromEntry(entry)).length > AgentHistoryIndexBytes)
             throw new RangeError("Agent history ordering key exceeds the MySQL index capacity.");
@@ -79,6 +146,15 @@ export class MysqlAgentHistory {
      * @returns Original entries and continuation status.
      */
     async read(request) {
+        return this.onAdmit(() => this.readAdmitted(request));
+    }
+    /**
+     * Executes an admitted provider operation.
+     *
+     * @param request Typed history page request.
+     * @returns Original entries and continuation status.
+     */
+    async readAdmitted(request) {
         this.requireOpen();
         await this.ready();
         const agentKey = this.key(request.entityId);
@@ -87,9 +163,7 @@ export class MysqlAgentHistory {
         return AgentHistoryPages.read(request, after, (cursor, limit) => this.fetch(agentKey, request, cursor, limit));
     }
     /**
-  
      * Closes this handle without deleting stored records.
-  
      */
     close() {
         if (!this.#open)
@@ -103,7 +177,10 @@ export class MysqlAgentHistory {
      * @returns Shared preparation promise for this handle.
      */
     ready() {
-        return (this.#ready ??= this.initialize());
+        return (this.#ready ??= this.initialize().catch((error) => {
+            this.#ready = undefined;
+            throw error;
+        }));
     }
     /**
      * Creates each native index idempotently on the shared record family.
@@ -112,17 +189,8 @@ export class MysqlAgentHistory {
      */
     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",
-        ]);
+        for (const [name, columns] of AgentHistoryIndexes)
+            await this.records.ensureHistoryIndex(name, columns);
     }
     /**
      * Reads a bounded native page with complete scope and view predicates.
@@ -200,9 +268,7 @@ export class MysqlAgentHistory {
         return key;
     }
     /**
-  
      * Rejects calls after this handle closes.
-  
      */
     requireOpen() {
         if (!this.#open)