actor-ts 0.9.1 → 0.10.0

package/dist/persistence/journals/MariaDbJournal.js

@@ -0,0 +1,161 @@
+import { JournalConcurrencyError, JournalError, } from '../JournalTypes.js';
+import { assertSafeIdentifier, buildMariaDbPool, isDuplicateKeyError, rowsOf, } from './MariaDbClient.js';
+/**
+ * Journal backed by MariaDB / MySQL via the `mariadb` connector.  Sibling
+ * of `PostgresJournal` (separate implementation, MariaDB dialect): `?`
+ * placeholders, `INSERT IGNORE` for the tag dedup, `ER_DUP_ENTRY` (1062)
+ * as the optimistic-concurrency backstop, and `LONGTEXT`/`BIGINT` columns.
+ * Cross-process backend → no in-process event bus.
+ */
+export class MariaDbJournal {
+    settings;
+    table;
+    tagsTable;
+    autoCreate;
+    pool = null;
+    initPromise = null;
+    closed = false;
+    constructor(options = {}) {
+        const s = options;
+        this.settings = s;
+        this.table = assertSafeIdentifier(s.eventsTable ?? 'events', 'events table');
+        this.tagsTable = assertSafeIdentifier(s.tagsTable ?? `${this.table}_tags`, 'tags table');
+        this.autoCreate = s.autoCreateTables ?? true;
+    }
+    async append(pid, events, expectedSeq, tags) {
+        if (events.length === 0)
+            return [];
+        const pool = await this.ensureOpen();
+        const conn = await pool.getConnection();
+        const now = Date.now();
+        try {
+            await conn.beginTransaction();
+            const head = rowsOf(await conn.query(`SELECT COALESCE(MAX(sequence_nr), 0) AS hi FROM ${this.table} WHERE persistence_id = ?`, [pid]));
+            const actualSeq = Number(head[0].hi);
+            if (actualSeq !== expectedSeq) {
+                await conn.rollback();
+                throw new JournalConcurrencyError(pid, expectedSeq, actualSeq);
+            }
+            const out = [];
+            const tagString = tags && tags.length ? tags.join(',') : null;
+            let seq = actualSeq;
+            for (const ev of events) {
+                seq++;
+                await conn.query(`INSERT INTO ${this.table}(persistence_id, sequence_nr, payload, tags, timestamp) VALUES (?, ?, ?, ?, ?)`, [pid, seq, JSON.stringify(ev), tagString, now]);
+                if (tags) {
+                    for (const tag of tags) {
+                        if (tag.length === 0)
+                            continue;
+                        await conn.query(`INSERT IGNORE INTO ${this.tagsTable}(persistence_id, sequence_nr, tag, timestamp) VALUES (?, ?, ?, ?)`, [pid, seq, tag, now]);
+                    }
+                }
+                out.push({
+                    persistenceId: pid,
+                    sequenceNr: seq,
+                    event: ev,
+                    timestamp: now,
+                    tags: tags ? [...tags] : undefined,
+                });
+            }
+            await conn.commit();
+            return out;
+        }
+        catch (e) {
+            try {
+                await conn.rollback();
+            }
+            catch { /* already rolled back */ }
+            if (e instanceof JournalConcurrencyError)
+                throw e;
+            if (isDuplicateKeyError(e)) {
+                const actual = await this.highestSeq(pid).catch(() => expectedSeq);
+                throw new JournalConcurrencyError(pid, expectedSeq, actual);
+            }
+            throw new JournalError(`MariaDbJournal.append failed: ${e.message}`, e);
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async read(pid, fromSeq, toSeq) {
+        const pool = await this.ensureOpen();
+        try {
+            const rows = rowsOf(toSeq === undefined
+                ? await pool.query(`SELECT persistence_id, sequence_nr, payload, tags, timestamp FROM ${this.table} WHERE persistence_id = ? AND sequence_nr >= ? ORDER BY sequence_nr ASC`, [pid, fromSeq])
+                : await pool.query(`SELECT persistence_id, sequence_nr, payload, tags, timestamp FROM ${this.table} WHERE persistence_id = ? AND sequence_nr >= ? AND sequence_nr <= ? ORDER BY sequence_nr ASC`, [pid, fromSeq, toSeq]));
+            return rows.map((r) => ({
+                persistenceId: r.persistence_id,
+                sequenceNr: Number(r.sequence_nr),
+                event: JSON.parse(r.payload),
+                timestamp: Number(r.timestamp),
+                tags: r.tags ? String(r.tags).split(',') : undefined,
+            }));
+        }
+        catch (e) {
+            throw new JournalError(`MariaDbJournal.read failed: ${e.message}`, e);
+        }
+    }
+    async highestSeq(pid) {
+        const pool = await this.ensureOpen();
+        const rows = rowsOf(await pool.query(`SELECT COALESCE(MAX(sequence_nr), 0) AS hi FROM ${this.table} WHERE persistence_id = ?`, [pid]));
+        return Number(rows[0].hi);
+    }
+    async delete(pid, toSeq) {
+        const pool = await this.ensureOpen();
+        await pool.query(`DELETE FROM ${this.tagsTable} WHERE persistence_id = ? AND sequence_nr <= ?`, [pid, toSeq]);
+        await pool.query(`DELETE FROM ${this.table} WHERE persistence_id = ? AND sequence_nr <= ?`, [pid, toSeq]);
+    }
+    async persistenceIds() {
+        const pool = await this.ensureOpen();
+        const rows = rowsOf(await pool.query(`SELECT DISTINCT persistence_id FROM ${this.table}`));
+        return rows.map((r) => r.persistence_id);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            await this.pool?.end();
+        }
+        catch { /* ignore */ }
+        this.pool = null;
+    }
+    /* --------------------------- internals -------------------------------- */
+    async ensureOpen() {
+        if (this.closed)
+            throw new JournalError('MariaDbJournal is closed');
+        if (this.pool)
+            return this.pool;
+        if (!this.initPromise)
+            this.initPromise = this.init();
+        await this.initPromise;
+        return this.pool;
+    }
+    async init() {
+        const pool = await buildMariaDbPool(this.settings);
+        if (this.autoCreate) {
+            // Indexes declared inline — `CREATE INDEX IF NOT EXISTS` isn't
+            // portable across MariaDB/MySQL versions, but inline INDEX in
+            // CREATE TABLE is.
+            await pool.query(`CREATE TABLE IF NOT EXISTS ${this.table} (
+           persistence_id VARCHAR(255) NOT NULL,
+           sequence_nr    BIGINT NOT NULL,
+           payload        LONGTEXT NOT NULL,
+           tags           TEXT,
+           timestamp      BIGINT NOT NULL,
+           PRIMARY KEY (persistence_id, sequence_nr),
+           INDEX idx_${this.table}_pid (persistence_id)
+         )`);
+            await pool.query(`CREATE TABLE IF NOT EXISTS ${this.tagsTable} (
+           persistence_id VARCHAR(255) NOT NULL,
+           sequence_nr    BIGINT NOT NULL,
+           tag            VARCHAR(255) NOT NULL,
+           timestamp      BIGINT NOT NULL,
+           PRIMARY KEY (tag, timestamp, persistence_id, sequence_nr),
+           INDEX idx_${this.tagsTable}_pid_seq (persistence_id, sequence_nr)
+         )`);
+        }
+        this.pool = pool;
+    }
+}
+//# sourceMappingURL=MariaDbJournal.js.map

package/dist/persistence/journals/MariaDbJournal.js.map

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

package/dist/persistence/journals/MariaDbJournalOptions.d.ts

@@ -0,0 +1,43 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import type { MariaDbPoolLike, MariaDbConnection } from './MariaDbClient.js';
+export interface MariaDbJournalOptionsType extends MariaDbConnection {
+    /** Events table name.  Default: `events`. */
+    readonly eventsTable?: string;
+    /** Tags join table name.  Default: `${eventsTable}_tags`. */
+    readonly tagsTable?: string;
+    /** Run `CREATE TABLE IF NOT EXISTS` on first use.  Default: true. */
+    readonly autoCreateTables?: boolean;
+}
+/**
+ * Fluent builder for {@link MariaDbJournalOptionsType}:
+ *
+ *     new MariaDbJournal(MariaDbJournalOptions.create().withUrl('mariadb://…').withEventsTable('journal'))
+ *
+ * The connection fields (`withUrl` / `withPoolConfig` / `withPool`) come
+ * from the shared {@link MariaDbConnection} mixin; the rest are journal
+ * specific.
+ */
+export declare class MariaDbJournalOptionsBuilder extends OptionsBuilder<MariaDbJournalOptionsType> {
+    /** Start a fresh builder.  Equivalent to `new MariaDbJournalOptionsBuilder()`. */
+    static create(): MariaDbJournalOptionsBuilder;
+    /** Connection URI passed straight to `createPool`, e.g. `mariadb://user:pass@host:3306/db`. */
+    withUrl(url: string): this;
+    /** `createPool` config object (host/user/password/database/…); takes precedence over `url`. */
+    withPoolConfig(poolConfig: Record<string, unknown>): this;
+    /** Pre-built pool — shares one pool across the three stores, or injects a fake in tests. */
+    withPool(pool: MariaDbPoolLike): this;
+    /** Events table name.  Default: `events`. */
+    withEventsTable(eventsTable: string): this;
+    /** Tags join table name.  Default: `${eventsTable}_tags`. */
+    withTagsTable(tagsTable: string): this;
+    /** Run `CREATE TABLE IF NOT EXISTS` on first use.  Default: true. */
+    withAutoCreateTables(autoCreateTables: boolean): this;
+}
+/**
+ * Accepted input for any MariaDB-journal constructor: the fluent
+ * {@link MariaDbJournalOptionsBuilder} OR a plain {@link MariaDbJournalOptionsType} object.
+ */
+export type MariaDbJournalOptions = MariaDbJournalOptionsBuilder | Partial<MariaDbJournalOptionsType>;
+/** Value alias so `MariaDbJournalOptions.create()` / `new MariaDbJournalOptions()` resolve to the builder. */
+export declare const MariaDbJournalOptions: typeof MariaDbJournalOptionsBuilder;
+//# sourceMappingURL=MariaDbJournalOptions.d.ts.map

package/dist/persistence/journals/MariaDbJournalOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MariaDbJournalOptions.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/MariaDbJournalOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE7E,MAAM,WAAW,yBAA0B,SAAQ,iBAAiB;IAClE,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,qEAAqE;IACrE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,qBAAa,4BAA6B,SAAQ,cAAc,CAAC,yBAAyB,CAAC;IACzF,kFAAkF;IAClF,MAAM,CAAC,MAAM,IAAI,4BAA4B;IAI7C,+FAA+F;IAC/F,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAI1B,+FAA+F;IAC/F,cAAc,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIzD,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAIrC,6CAA6C;IAC7C,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI1C,6DAA6D;IAC7D,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAItC,qEAAqE;IACrE,oBAAoB,CAAC,gBAAgB,EAAE,OAAO,GAAG,IAAI;CAGtD;AAED;;;GAGG;AACH,MAAM,MAAM,qBAAqB,GAAG,4BAA4B,GAAG,OAAO,CAAC,yBAAyB,CAAC,CAAC;AACtG,8GAA8G;AAC9G,eAAO,MAAM,qBAAqB,qCAA+B,CAAC"}

package/dist/persistence/journals/MariaDbJournalOptions.js

@@ -0,0 +1,43 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/**
+ * Fluent builder for {@link MariaDbJournalOptionsType}:
+ *
+ *     new MariaDbJournal(MariaDbJournalOptions.create().withUrl('mariadb://…').withEventsTable('journal'))
+ *
+ * The connection fields (`withUrl` / `withPoolConfig` / `withPool`) come
+ * from the shared {@link MariaDbConnection} mixin; the rest are journal
+ * specific.
+ */
+export class MariaDbJournalOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new MariaDbJournalOptionsBuilder()`. */
+    static create() {
+        return new MariaDbJournalOptionsBuilder();
+    }
+    /** Connection URI passed straight to `createPool`, e.g. `mariadb://user:pass@host:3306/db`. */
+    withUrl(url) {
+        return this.set('url', url);
+    }
+    /** `createPool` config object (host/user/password/database/…); takes precedence over `url`. */
+    withPoolConfig(poolConfig) {
+        return this.set('poolConfig', poolConfig);
+    }
+    /** Pre-built pool — shares one pool across the three stores, or injects a fake in tests. */
+    withPool(pool) {
+        return this.set('pool', pool);
+    }
+    /** Events table name.  Default: `events`. */
+    withEventsTable(eventsTable) {
+        return this.set('eventsTable', eventsTable);
+    }
+    /** Tags join table name.  Default: `${eventsTable}_tags`. */
+    withTagsTable(tagsTable) {
+        return this.set('tagsTable', tagsTable);
+    }
+    /** Run `CREATE TABLE IF NOT EXISTS` on first use.  Default: true. */
+    withAutoCreateTables(autoCreateTables) {
+        return this.set('autoCreateTables', autoCreateTables);
+    }
+}
+/** Value alias so `MariaDbJournalOptions.create()` / `new MariaDbJournalOptions()` resolve to the builder. */
+export const MariaDbJournalOptions = MariaDbJournalOptionsBuilder;
+//# sourceMappingURL=MariaDbJournalOptions.js.map

package/dist/persistence/journals/MariaDbJournalOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MariaDbJournalOptions.js","sourceRoot":"","sources":["../../../src/persistence/journals/MariaDbJournalOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAY9D;;;;;;;;GAQG;AACH,MAAM,OAAO,4BAA6B,SAAQ,cAAyC;IACzF,kFAAkF;IAClF,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,4BAA4B,EAAE,CAAC;IAC5C,CAAC;IAED,+FAA+F;IAC/F,OAAO,CAAC,GAAW;QACjB,OAAO,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,+FAA+F;IAC/F,cAAc,CAAC,UAAmC;QAChD,OAAO,IAAI,CAAC,GAAG,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC5C,CAAC;IAED,4FAA4F;IAC5F,QAAQ,CAAC,IAAqB;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,6CAA6C;IAC7C,eAAe,CAAC,WAAmB;QACjC,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;IAED,6DAA6D;IAC7D,aAAa,CAAC,SAAiB;QAC7B,OAAO,IAAI,CAAC,GAAG,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAC1C,CAAC;IAED,qEAAqE;IACrE,oBAAoB,CAAC,gBAAyB;QAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;IACxD,CAAC;CACF;AAOD,8GAA8G;AAC9G,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAC"}

package/dist/persistence/journals/MariaDbPlugin.d.ts

@@ -0,0 +1,27 @@
+import type { PersistenceExtension } from '../PersistenceExtension.js';
+import { MariaDbDurableStateStore } from '../durable-state-stores/MariaDbDurableStateStore.js';
+import type { RegisterMariaDbPluginsOptions } from './MariaDbPluginOptions.js';
+/** Canonical plug-in IDs for the MariaDB journal, snapshot, and durable-state stores. */
+export declare const MARIADB_JOURNAL_PLUGIN_ID = "actor-ts.persistence.journal.mariadb";
+export declare const MARIADB_SNAPSHOT_PLUGIN_ID = "actor-ts.persistence.snapshot-store.mariadb";
+export declare const MARIADB_DURABLE_STATE_PLUGIN_ID = "actor-ts.persistence.durable-state.mariadb";
+export interface MariaDbPluginHandles {
+    /**
+     * The DurableState store instance.  `PersistenceExtension` carries no
+     * DurableState registry (same as the object-storage / Postgres plugins),
+     * so callers who want DurableState read this from the return value and
+     * pass it into their `DurableStateActor` settings.
+     */
+    readonly durableStateStore: MariaDbDurableStateStore;
+}
+/**
+ * One-shot registration of the MariaDB journal + snapshot store against the
+ * running `PersistenceExtension`, returning a ready-to-use DurableState
+ * store handle.  Mirrors `registerPostgresPlugins`.
+ *
+ * After this call, activate via:
+ *   `actor-ts.persistence.journal.plugin = "actor-ts.persistence.journal.mariadb"`
+ *   `actor-ts.persistence.snapshot-store.plugin = "actor-ts.persistence.snapshot-store.mariadb"`
+ */
+export declare function registerMariaDbPlugins(ext: PersistenceExtension, options: RegisterMariaDbPluginsOptions): MariaDbPluginHandles;
+//# sourceMappingURL=MariaDbPlugin.d.ts.map

package/dist/persistence/journals/MariaDbPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MariaDbPlugin.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/MariaDbPlugin.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAKvE,OAAO,EAAE,wBAAwB,EAAE,MAAM,qDAAqD,CAAC;AAE/F,OAAO,KAAK,EAAE,6BAA6B,EAAqC,MAAM,2BAA2B,CAAC;AAElH,yFAAyF;AACzF,eAAO,MAAM,yBAAyB,yCAAyC,CAAC;AAChF,eAAO,MAAM,0BAA0B,gDAAgD,CAAC;AACxF,eAAO,MAAM,+BAA+B,+CAA+C,CAAC;AAE5F,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,iBAAiB,EAAE,wBAAwB,CAAC;CACtD;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,oBAAoB,EACzB,OAAO,EAAE,6BAA6B,GACrC,oBAAoB,CAkBtB"}

package/dist/persistence/journals/MariaDbPlugin.js

@@ -0,0 +1,30 @@
+import { MariaDbJournal } from './MariaDbJournal.js';
+import { MariaDbSnapshotStore } from '../snapshot-stores/MariaDbSnapshotStore.js';
+import { MariaDbDurableStateStore } from '../durable-state-stores/MariaDbDurableStateStore.js';
+/** Canonical plug-in IDs for the MariaDB journal, snapshot, and durable-state stores. */
+export const MARIADB_JOURNAL_PLUGIN_ID = 'actor-ts.persistence.journal.mariadb';
+export const MARIADB_SNAPSHOT_PLUGIN_ID = 'actor-ts.persistence.snapshot-store.mariadb';
+export const MARIADB_DURABLE_STATE_PLUGIN_ID = 'actor-ts.persistence.durable-state.mariadb';
+/**
+ * One-shot registration of the MariaDB journal + snapshot store against the
+ * running `PersistenceExtension`, returning a ready-to-use DurableState
+ * store handle.  Mirrors `registerPostgresPlugins`.
+ *
+ * After this call, activate via:
+ *   `actor-ts.persistence.journal.plugin = "actor-ts.persistence.journal.mariadb"`
+ *   `actor-ts.persistence.snapshot-store.plugin = "actor-ts.persistence.snapshot-store.mariadb"`
+ */
+export function registerMariaDbPlugins(ext, options) {
+    const s = options;
+    // Resolve each leaf to a plain object and merge the shared pool (when set)
+    // onto it.  A missing leaf falls back to an empty object so the shared
+    // pool still reaches every store.
+    const journal = { ...(s.journal ?? {}), ...(s.pool ? { pool: s.pool } : {}) };
+    const snapshotStore = { ...(s.snapshotStore ?? {}), ...(s.pool ? { pool: s.pool } : {}) };
+    const durableState = { ...(s.durableStateStore ?? {}), ...(s.pool ? { pool: s.pool } : {}) };
+    ext.registerJournal(MARIADB_JOURNAL_PLUGIN_ID, (_system) => new MariaDbJournal(journal));
+    ext.registerSnapshotStore(MARIADB_SNAPSHOT_PLUGIN_ID, (_system) => new MariaDbSnapshotStore(snapshotStore));
+    const durableStateStore = new MariaDbDurableStateStore(durableState);
+    return { durableStateStore };
+}
+//# sourceMappingURL=MariaDbPlugin.js.map

package/dist/persistence/journals/MariaDbPlugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MariaDbPlugin.js","sourceRoot":"","sources":["../../../src/persistence/journals/MariaDbPlugin.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,EAAE,oBAAoB,EAAE,MAAM,4CAA4C,CAAC;AAElF,OAAO,EAAE,wBAAwB,EAAE,MAAM,qDAAqD,CAAC;AAI/F,yFAAyF;AACzF,MAAM,CAAC,MAAM,yBAAyB,GAAG,sCAAsC,CAAC;AAChF,MAAM,CAAC,MAAM,0BAA0B,GAAG,6CAA6C,CAAC;AACxF,MAAM,CAAC,MAAM,+BAA+B,GAAG,4CAA4C,CAAC;AAY5F;;;;;;;;GAQG;AACH,MAAM,UAAU,sBAAsB,CACpC,GAAyB,EACzB,OAAsC;IAEtC,MAAM,CAAC,GAAI,OAA6C,CAAC;IACzD,2EAA2E;IAC3E,uEAAuE;IACvE,kCAAkC;IAClC,MAAM,OAAO,GAAG,EAAE,GAAI,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAwC,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACtH,MAAM,aAAa,GAAG,EAAE,GAAI,CAAC,CAAC,CAAC,aAAa,IAAI,EAAE,CAA8C,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACxI,MAAM,YAAY,GAAG,EAAE,GAAI,CAAC,CAAC,CAAC,iBAAiB,IAAI,EAAE,CAAkD,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC/I,GAAG,CAAC,eAAe,CACjB,yBAAyB,EACzB,CAAC,OAAoB,EAAE,EAAE,CAAC,IAAI,cAAc,CAAC,OAAO,CAAC,CACtD,CAAC;IACF,GAAG,CAAC,qBAAqB,CACvB,0BAA0B,EAC1B,CAAC,OAAoB,EAAE,EAAE,CAAC,IAAI,oBAAoB,CAAC,aAAa,CAAC,CAClE,CAAC;IACF,MAAM,iBAAiB,GAAG,IAAI,wBAAwB,CAAC,YAAY,CAAC,CAAC;IACrE,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAC/B,CAAC"}

package/dist/persistence/journals/MariaDbPluginOptions.d.ts

@@ -0,0 +1,52 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+import type { MariaDbPoolLike } from './MariaDbClient.js';
+import type { MariaDbJournalOptions } from './MariaDbJournalOptions.js';
+import type { MariaDbSnapshotStoreOptions } from '../snapshot-stores/MariaDbSnapshotStoreOptions.js';
+import type { MariaDbDurableStateStoreOptions } from '../durable-state-stores/MariaDbDurableStateStoreOptions.js';
+export interface RegisterMariaDbPluginsOptionsType {
+    /**
+     * Shared connection pool injected into all three stores.  When provided,
+     * the journal + snapshot + durable-state stores reuse ONE pool.  When
+     * omitted, each store lazily builds its own from its `url` / `poolConfig`.
+     */
+    readonly pool?: MariaDbPoolLike;
+    /** Journal builder — its `pool` is overridden by the shared `pool` when set. */
+    readonly journal?: MariaDbJournalOptions;
+    /** Snapshot-store builder — its `pool` is overridden by the shared `pool` when set. */
+    readonly snapshotStore?: MariaDbSnapshotStoreOptions;
+    /** Durable-state-store builder — its `pool` is overridden by the shared `pool` when set. */
+    readonly durableStateStore?: MariaDbDurableStateStoreOptions;
+}
+/**
+ * Fluent builder for {@link RegisterMariaDbPluginsOptionsType}:
+ *
+ *     registerMariaDbPlugins(ext, RegisterMariaDbPluginsOptions.create()
+ *       .withPool(sharedPool)
+ *       .withJournal(MariaDbJournalOptions.create().withEventsTable('journal')))
+ *
+ * Each per-store field is the store's own leaf builder (or a plain object
+ * of its settings); the shared `pool` (when set via `withPool`) is merged
+ * onto every store's resolved settings at registration time, so a leaf
+ * need not repeat the connection.
+ */
+export declare class RegisterMariaDbPluginsOptionsBuilder extends OptionsBuilder<RegisterMariaDbPluginsOptionsType> {
+    /** Start a fresh builder.  Equivalent to `new RegisterMariaDbPluginsOptionsBuilder()`. */
+    static create(): RegisterMariaDbPluginsOptionsBuilder;
+    /** Shared connection pool reused by all three stores (overrides each leaf's own pool). */
+    withPool(pool: MariaDbPoolLike): this;
+    /** Journal builder — table names / autoCreate (connection filled from the shared pool). */
+    withJournal(journal: MariaDbJournalOptions): this;
+    /** Snapshot-store builder — table name / keepN (connection filled from the shared pool). */
+    withSnapshotStore(snapshotStore: MariaDbSnapshotStoreOptions): this;
+    /** Durable-state-store builder — table name (connection filled from the shared pool). */
+    withDurableStateStore(durableStateStore: MariaDbDurableStateStoreOptions): this;
+}
+/**
+ * Accepted input for {@link registerMariaDbPlugins}: the fluent
+ * {@link RegisterMariaDbPluginsOptionsBuilder} OR a plain
+ * {@link RegisterMariaDbPluginsOptionsType} object.
+ */
+export type RegisterMariaDbPluginsOptions = RegisterMariaDbPluginsOptionsBuilder | Partial<RegisterMariaDbPluginsOptionsType>;
+/** Value alias so `RegisterMariaDbPluginsOptions.create()` / `new RegisterMariaDbPluginsOptions()` resolve to the builder. */
+export declare const RegisterMariaDbPluginsOptions: typeof RegisterMariaDbPluginsOptionsBuilder;
+//# sourceMappingURL=MariaDbPluginOptions.d.ts.map

package/dist/persistence/journals/MariaDbPluginOptions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MariaDbPluginOptions.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/MariaDbPluginOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACxE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mDAAmD,CAAC;AACrG,OAAO,KAAK,EAAE,+BAA+B,EAAE,MAAM,4DAA4D,CAAC;AAElH,MAAM,WAAW,iCAAiC;IAChD;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,eAAe,CAAC;IAChC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;IACzC,uFAAuF;IACvF,QAAQ,CAAC,aAAa,CAAC,EAAE,2BAA2B,CAAC;IACrD,4FAA4F;IAC5F,QAAQ,CAAC,iBAAiB,CAAC,EAAE,+BAA+B,CAAC;CAC9D;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,oCAAqC,SAAQ,cAAc,CAAC,iCAAiC,CAAC;IACzG,0FAA0F;IAC1F,MAAM,CAAC,MAAM,IAAI,oCAAoC;IAIrD,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAIrC,2FAA2F;IAC3F,WAAW,CAAC,OAAO,EAAE,qBAAqB,GAAG,IAAI;IAIjD,4FAA4F;IAC5F,iBAAiB,CAAC,aAAa,EAAE,2BAA2B,GAAG,IAAI;IAInE,yFAAyF;IACzF,qBAAqB,CAAC,iBAAiB,EAAE,+BAA+B,GAAG,IAAI;CAGhF;AAED;;;;GAIG;AACH,MAAM,MAAM,6BAA6B,GACrC,oCAAoC,GACpC,OAAO,CAAC,iCAAiC,CAAC,CAAC;AAC/C,8HAA8H;AAC9H,eAAO,MAAM,6BAA6B,6CAAuC,CAAC"}

package/dist/persistence/journals/MariaDbPluginOptions.js

@@ -0,0 +1,38 @@
+import { OptionsBuilder } from '../../util/OptionsBuilder.js';
+/**
+ * Fluent builder for {@link RegisterMariaDbPluginsOptionsType}:
+ *
+ *     registerMariaDbPlugins(ext, RegisterMariaDbPluginsOptions.create()
+ *       .withPool(sharedPool)
+ *       .withJournal(MariaDbJournalOptions.create().withEventsTable('journal')))
+ *
+ * Each per-store field is the store's own leaf builder (or a plain object
+ * of its settings); the shared `pool` (when set via `withPool`) is merged
+ * onto every store's resolved settings at registration time, so a leaf
+ * need not repeat the connection.
+ */
+export class RegisterMariaDbPluginsOptionsBuilder extends OptionsBuilder {
+    /** Start a fresh builder.  Equivalent to `new RegisterMariaDbPluginsOptionsBuilder()`. */
+    static create() {
+        return new RegisterMariaDbPluginsOptionsBuilder();
+    }
+    /** Shared connection pool reused by all three stores (overrides each leaf's own pool). */
+    withPool(pool) {
+        return this.set('pool', pool);
+    }
+    /** Journal builder — table names / autoCreate (connection filled from the shared pool). */
+    withJournal(journal) {
+        return this.set('journal', journal);
+    }
+    /** Snapshot-store builder — table name / keepN (connection filled from the shared pool). */
+    withSnapshotStore(snapshotStore) {
+        return this.set('snapshotStore', snapshotStore);
+    }
+    /** Durable-state-store builder — table name (connection filled from the shared pool). */
+    withDurableStateStore(durableStateStore) {
+        return this.set('durableStateStore', durableStateStore);
+    }
+}
+/** Value alias so `RegisterMariaDbPluginsOptions.create()` / `new RegisterMariaDbPluginsOptions()` resolve to the builder. */
+export const RegisterMariaDbPluginsOptions = RegisterMariaDbPluginsOptionsBuilder;
+//# sourceMappingURL=MariaDbPluginOptions.js.map

package/dist/persistence/journals/MariaDbPluginOptions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MariaDbPluginOptions.js","sourceRoot":"","sources":["../../../src/persistence/journals/MariaDbPluginOptions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAqB9D;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,oCAAqC,SAAQ,cAAiD;IACzG,0FAA0F;IAC1F,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,oCAAoC,EAAE,CAAC;IACpD,CAAC;IAED,0FAA0F;IAC1F,QAAQ,CAAC,IAAqB;QAC5B,OAAO,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAChC,CAAC;IAED,2FAA2F;IAC3F,WAAW,CAAC,OAA8B;QACxC,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED,4FAA4F;IAC5F,iBAAiB,CAAC,aAA0C;QAC1D,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,EAAE,aAAa,CAAC,CAAC;IAClD,CAAC;IAED,yFAAyF;IACzF,qBAAqB,CAAC,iBAAkD;QACtE,OAAO,IAAI,CAAC,GAAG,CAAC,mBAAmB,EAAE,iBAAiB,CAAC,CAAC;IAC1D,CAAC;CACF;AAUD,8HAA8H;AAC9H,MAAM,CAAC,MAAM,6BAA6B,GAAG,oCAAoC,CAAC"}

package/dist/persistence/journals/PostgresClient.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Minimal shapes of the `pg` (node-postgres) API the Postgres backends
+ * use.  We deliberately define our own interfaces rather than depend on
+ * `@types/pg` — the framework stays dependency-free, `pg` is an OPTIONAL
+ * peer-dep loaded lazily, and tests can inject a fake pool that satisfies
+ * just these methods.
+ *
+ * Note: node-postgres returns `BIGINT` columns as **strings** (to avoid
+ * precision loss), so every numeric column the backends read is coerced
+ * with `Number(...)` at the mapping boundary.
+ */
+export interface PgQueryResult {
+    readonly rows: ReadonlyArray<Record<string, unknown>>;
+    /** Rows affected by INSERT/UPDATE/DELETE — `null` for some statements. */
+    readonly rowCount: number | null;
+}
+/** A single pooled connection — `query` + `release` back to the pool. */
+export interface PgClientLike {
+    query(text: string, values?: ReadonlyArray<unknown>): Promise<PgQueryResult>;
+    release(): void;
+}
+export interface PgPoolLike {
+    query(text: string, values?: ReadonlyArray<unknown>): Promise<PgQueryResult>;
+    /** Check out a dedicated connection — required for multi-statement transactions. */
+    connect(): Promise<PgClientLike>;
+    end(): Promise<void>;
+}
+/** Connection options shared by all three Postgres stores. */
+export interface PostgresConnection {
+    /** Connection string, e.g. `postgres://user:pass@host:5432/db`. */
+    readonly url?: string;
+    /**
+     * Extra node-postgres `Pool` config, merged over `{ connectionString:
+     * url }` — e.g. `{ max: 10, ssl: { rejectUnauthorized: false } }`.
+     */
+    readonly poolConfig?: Record<string, unknown>;
+    /**
+     * Pre-built pool — bypasses the lazy `pg` import entirely.  Use to
+     * share ONE pool across the journal + snapshot + durable-state stores
+     * (see `registerPostgresPlugins`), or to inject a fake in tests.
+     */
+    readonly pool?: PgPoolLike;
+}
+/** Build (or pass through) the connection pool for a store. */
+export declare function buildPgPool(conn: PostgresConnection): Promise<PgPoolLike>;
+/**
+ * Guard configurable table names against SQL injection (#136).  Table
+ * names come from trusted config, not user input — but a parameter bind
+ * (`$1`) cannot stand in for an *identifier*, so the name is interpolated
+ * into the DDL/DML string directly.  Constrain it to a safe charset so a
+ * hostile/typo'd config can't smuggle SQL through the table name.
+ */
+export declare function assertSafeIdentifier(name: string, what: string): string;
+/** Test hook — reset the cached lazy `pg` import. */
+export declare function resetPgModuleCache(): void;
+//# sourceMappingURL=PostgresClient.d.ts.map

package/dist/persistence/journals/PostgresClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresClient.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/PostgresClient.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACtD,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAED,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7E,oFAAoF;IACpF,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IACjC,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACtB;AAaD,8DAA8D;AAC9D,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,+DAA+D;AAC/D,wBAAsB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,CAAC,CAM/E;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQvE;AAED,qDAAqD;AACrD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/persistence/journals/PostgresClient.js

@@ -0,0 +1,35 @@
+import { Lazy } from '../../util/Lazy.js';
+import { lazyImportModule } from '../../util/LazyImport.js';
+const pgLazy = Lazy.of(() => lazyImportModule('pg', {
+    context: 'The Postgres persistence backends require',
+    installHint: 'npm install pg',
+}));
+/** Build (or pass through) the connection pool for a store. */
+export async function buildPgPool(conn) {
+    if (conn.pool)
+        return conn.pool;
+    const pg = await pgLazy.get();
+    const config = { ...conn.poolConfig };
+    if (conn.url !== undefined)
+        config.connectionString = conn.url;
+    return new pg.Pool(config);
+}
+/**
+ * Guard configurable table names against SQL injection (#136).  Table
+ * names come from trusted config, not user input — but a parameter bind
+ * (`$1`) cannot stand in for an *identifier*, so the name is interpolated
+ * into the DDL/DML string directly.  Constrain it to a safe charset so a
+ * hostile/typo'd config can't smuggle SQL through the table name.
+ */
+export function assertSafeIdentifier(name, what) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+        throw new Error(`Postgres: unsafe ${what} identifier ${JSON.stringify(name)} — `
+            + 'must match /^[A-Za-z_][A-Za-z0-9_]*$/.');
+    }
+    return name;
+}
+/** Test hook — reset the cached lazy `pg` import. */
+export function resetPgModuleCache() {
+    pgLazy.reset();
+}
+//# sourceMappingURL=PostgresClient.js.map

package/dist/persistence/journals/PostgresClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresClient.js","sourceRoot":"","sources":["../../../src/persistence/journals/PostgresClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAoC5D,MAAM,MAAM,GAA4B,IAAI,CAAC,EAAE,CAC7C,GAAG,EAAE,CAAC,gBAAgB,CAAW,IAAI,EAAE;IACrC,OAAO,EAAE,2CAA2C;IACpD,WAAW,EAAE,gBAAgB;CAC9B,CAAC,CACH,CAAC;AAmBF,+DAA+D;AAC/D,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAwB;IACxD,IAAI,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAChC,MAAM,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC;IAC9B,MAAM,MAAM,GAA4B,EAAE,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;IAC/D,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;QAAE,MAAM,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,CAAC;IAC/D,OAAO,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAY,EAAE,IAAY;IAC7D,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CACb,oBAAoB,IAAI,eAAe,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,KAAK;cAC9D,wCAAwC,CAC3C,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,kBAAkB;IAChC,MAAM,CAAC,KAAK,EAAE,CAAC;AACjB,CAAC"}

package/dist/persistence/journals/PostgresJournal.d.ts

@@ -0,0 +1,41 @@
+import type { Journal } from '../Journal.js';
+import { type PersistentEvent } from '../JournalTypes.js';
+import type { PostgresJournalOptions } from './PostgresJournalOptions.js';
+/**
+ * Journal backed by PostgreSQL via the `pg` (node-postgres) driver.
+ *
+ * Mirrors `SqliteJournal`'s shape — an events table keyed on
+ * `(persistence_id, sequence_nr)` plus a tags join table for indexed
+ * tag queries — using Postgres types and `$1` bind parameters.
+ *
+ * Optimistic concurrency: `append` runs `SELECT MAX(sequence_nr)` and the
+ * INSERTs inside one transaction; a racing writer that slips between the
+ * read and the insert trips the primary-key unique constraint (SQLSTATE
+ * `23505`), which is translated to `JournalConcurrencyError` as a
+ * backstop.  Construction is lazy — the pool opens and tables are created
+ * on the first call.
+ *
+ * No in-process event bus: Postgres is a cross-process backend (like
+ * Cassandra), so the `events` field is left undefined and the query layer
+ * falls back to polling.  (A `LISTEN/NOTIFY` bus is a possible future
+ * enhancement.)
+ */
+export declare class PostgresJournal implements Journal {
+    private readonly settings;
+    private readonly table;
+    private readonly tagsTable;
+    private readonly autoCreate;
+    private pool;
+    private initPromise;
+    private closed;
+    constructor(options?: PostgresJournalOptions);
+    append<E>(pid: string, events: ReadonlyArray<E>, expectedSeq: number, tags?: ReadonlyArray<string>): Promise<PersistentEvent<E>[]>;
+    read<E>(pid: string, fromSeq: number, toSeq?: number): Promise<PersistentEvent<E>[]>;
+    highestSeq(pid: string): Promise<number>;
+    delete(pid: string, toSeq: number): Promise<void>;
+    persistenceIds(): Promise<string[]>;
+    close(): Promise<void>;
+    private ensureOpen;
+    private init;
+}
+//# sourceMappingURL=PostgresJournal.d.ts.map

package/dist/persistence/journals/PostgresJournal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PostgresJournal.d.ts","sourceRoot":"","sources":["../../../src/persistence/journals/PostgresJournal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EAAE,sBAAsB,EAA8B,MAAM,6BAA6B,CAAC;AAUtG;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,eAAgB,YAAW,OAAO;IAC7C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAU;IAErC,OAAO,CAAC,IAAI,CAA2B;IACvC,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,MAAM,CAAS;gBAEX,OAAO,GAAE,sBAA2B;IAU1C,MAAM,CAAC,CAAC,EACZ,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC,EACxB,WAAW,EAAE,MAAM,EACnB,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,CAAC,GAC3B,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IA4D1B,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,CAAC;IAwBpF,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IASxC,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAejD,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMnC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YASd,UAAU;YAQV,IAAI;CA+BnB"}