@spine-event-engine/storage-mysql 2.0.0-snapshot.24 → 2.0.0-snapshot.26

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,8 +14,9 @@ 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?
@@ -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.
@@ -123,8 +138,11 @@ 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`.
@@ -224,25 +242,15 @@ operations plan.
 ## ⚠️ Before production
 
 Use a dedicated database and account, protect the connection URL, configure
-TLS, and plan backups, monitoring, and migrations. Indexed `bigint` values must
+TLS, and plan backups and monitoring. 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,22 +62,20 @@ 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.
+Factory build and `checkConnection()` do not scan unrelated tables. 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.
+`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,
@@ -153,30 +168,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 Command obligations. Emitted
-domain Events enter immutable Agent history and are handed to the normal EventBus
-after completion without a saved delivery phase. 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 family-specific
-naming as default DDL. A grouped family uses its explicit grouped override or
-grouped default; an ungrouped family uses its explicit record override or
-ungrouped default. An ungrouped override never aliases a grouped family.
+## 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)

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

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

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

@@ -22,6 +22,12 @@ export declare class MysqlAgentTransaction {
      * @returns Returns the work result.
      */
     commit<T>(tables: readonly string[], work: (connection: PoolConnection) => Promise<T>): Promise<T>;
+    /**
+     * Checks every declared live Agent table for native transaction support.
+     * @param tables Participating physical table names.
+     * @returns Completion after a read-only InnoDB inspection.
+     */
+    check(tables: readonly string[]): Promise<void>;
     /**
      * Determines whether every participating table supports transactions.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"agent-transaction.d.ts","sourceRoot":"","sources":["../../src/mysql/agent-transaction.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AAEpE;;GAEG;AACH,qBAAa,qBAAqB;IAS9B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAN9B;;;;OAIG;gBAEgB,WAAW,EAAE;QAC5B,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;QACnC,OAAO,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC;KAC3C;IAGH;;;;;;;OAOG;IACG,MAAM,CAAC,CAAC,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAC/C,OAAO,CAAC,CAAC,CAAC;IAYb;;;;;;OAMG;YACW,gBAAgB;IAa9B;;;;;;;OAOG;YACW,iBAAiB;IAmB/B;;;;;OAKG;IACH,OAAO,CAAC,UAAU;CAOnB"}
+{"version":3,"file":"agent-transaction.d.ts","sourceRoot":"","sources":["../../src/mysql/agent-transaction.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,gBAAgB,CAAC;AAEpE;;GAEG;AACH,qBAAa,qBAAqB;IAS9B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAN9B;;;;OAIG;gBAEgB,WAAW,EAAE;QAC5B,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;QACnC,OAAO,CAAC,UAAU,EAAE,cAAc,GAAG,IAAI,CAAC;KAC3C;IAGH;;;;;;;OAOG;IACG,MAAM,CAAC,CAAC,EACZ,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,IAAI,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,OAAO,CAAC,CAAC,CAAC,GAC/C,OAAO,CAAC,CAAC,CAAC;IAYb;;;;OAIG;IACG,KAAK,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrD;;;;;;OAMG;YACW,gBAAgB;IAa9B;;;;;;;OAOG;YACW,iBAAiB;IAmB/B;;;;;OAKG;IACH,OAAO,CAAC,UAAU;CAOnB"}

package/dist/mysql/agent-transaction.js

@@ -45,6 +45,21 @@ export class MysqlAgentTransaction {
             this.connections.release(connection);
         }
     }
+    /**
+     * Checks every declared live Agent table for native transaction support.
+     * @param tables Participating physical table names.
+     * @returns Completion after a read-only InnoDB inspection.
+     */
+    async check(tables) {
+        const connection = await this.connections.acquire();
+        try {
+            if (!(await this.allTransactional(connection, tables)))
+                throw new Error("MySQL Agent execution requires transactional record tables.");
+        }
+        finally {
+            this.connections.release(connection);
+        }
+    }
     /**
      * Determines whether every participating table supports transactions.
      *