@substrate-ai/core 0.19.54

package/dist/persistence/dolt-adapter.js

@@ -0,0 +1,98 @@
+/**
+ * DoltDatabaseAdapter — wraps a DoltClientLike and exposes it through the
+ * unified async DatabaseAdapter interface.
+ *
+ * Uses a duck-typed DoltClientLike interface to avoid cross-package imports.
+ * All SQL operations are delegated to the client, which connects via mysql2
+ * unix socket (primary) or dolt CLI (fallback).
+ * Transactions delegate atomicity enforcement to DoltClientLike.transact().
+ */
+export class DoltDatabaseAdapter {
+    backendType = 'dolt';
+    _client;
+    /**
+     * Create a DoltDatabaseAdapter wrapping the supplied DoltClientLike.
+     * The caller should construct the client with the correct `repoPath`
+     * before passing it here; `connect()` is called lazily by DoltClient.
+     */
+    constructor(client) {
+        this._client = client;
+    }
+    /**
+     * Execute a SQL query and return all result rows as typed objects.
+     *
+     * Delegates to `DoltClientLike.query<T>()` which supports both mysql2
+     * pool mode and CLI fallback.
+     */
+    async query(sql, params) {
+        return this._client.query(sql, params);
+    }
+    /**
+     * Execute a SQL statement with no return value (DDL or DML).
+     *
+     * Delegates to `DoltClientLike.query()` and discards the result rows.
+     */
+    async exec(sql) {
+        await this._client.query(sql, undefined);
+    }
+    /**
+     * Execute a function within an explicit SQL transaction.
+     *
+     * Delegates atomicity enforcement to `DoltClientLike.transact()`:
+     * - Pool mode: acquires a dedicated connection, issues BEGIN/COMMIT on that
+     *   connection, preventing query scatter across the pool.
+     * - CLI mode: collects all SQL statements and executes them as a single
+     *   `dolt sql -q "BEGIN; ...; COMMIT"` invocation.
+     *
+     * The `fn` callback receives a transaction-scoped `DatabaseAdapter` whose
+     * `query()` and `exec()` are bound to the connection-bound query lambda.
+     * Nested `transaction()` calls on the scoped adapter are pass-through
+     * (no nested BEGIN).
+     */
+    async transaction(fn) {
+        return this._client.transact(async (txQuery) => {
+            // Build a transaction-scoped adapter that routes queries through the
+            // connection-bound txQuery lambda provided by transact().
+            // eslint-disable-next-line @typescript-eslint/no-this-alias
+            const self = this;
+            const txAdapter = {
+                backendType: this.backendType,
+                query: txQuery,
+                exec: async (sql) => {
+                    await txQuery(sql, undefined);
+                },
+                // Nested transaction() calls are pass-through — no nested BEGIN.
+                transaction: async (innerFn) => innerFn(txAdapter),
+                close: async () => { },
+                queryReadyStories: () => self.queryReadyStories(),
+            };
+            return fn(txAdapter);
+        });
+    }
+    /**
+     * Close the underlying DoltClient connection pool.
+     */
+    async close() {
+        await this._client.close();
+    }
+    /**
+     * Query story keys from the `ready_stories` SQL view.
+     *
+     * Returns story keys whose status is `planned` or `ready` and whose
+     * hard dependencies are all `complete` in the work graph.
+     *
+     * On any SQL error (e.g., view not yet created by story 31-1 schema,
+     * or empty stories table), returns `[]` so the caller falls through to
+     * the legacy discovery chain.
+     */
+    async queryReadyStories() {
+        try {
+            const rows = await this._client.query('SELECT `key` FROM ready_stories ORDER BY `key` ASC', undefined);
+            return rows.map((r) => r.key);
+        }
+        catch {
+            return [];
+        }
+    }
+}
+//# sourceMappingURL=dolt-adapter.js.map

package/dist/persistence/dolt-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dolt-adapter.js","sourceRoot":"","sources":["../../src/persistence/dolt-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,MAAM,OAAO,mBAAmB;IACrB,WAAW,GAAG,MAAe,CAAA;IACrB,OAAO,CAAgB;IAExC;;;;OAIG;IACH,YAAY,MAAsB;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAc,GAAW,EAAE,MAAkB;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAI,GAAG,EAAE,MAAM,CAAC,CAAA;IAC3C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CAAC,GAAW;QACpB,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IAC1C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,WAAW,CAAI,EAA4C;QAC/D,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE;YAC7C,qEAAqE;YACrE,0DAA0D;YAC1D,4DAA4D;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAA;YACjB,MAAM,SAAS,GAAoB;gBACjC,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,KAAK,EAAE,OAAO;gBACd,IAAI,EAAE,KAAK,EAAE,GAAW,EAAiB,EAAE;oBACzC,MAAM,OAAO,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;gBAC/B,CAAC;gBACD,iEAAiE;gBACjE,WAAW,EAAE,KAAK,EAAK,OAAiD,EAAc,EAAE,CACtF,OAAO,CAAC,SAAS,CAAC;gBACpB,KAAK,EAAE,KAAK,IAAmB,EAAE,GAAE,CAAC;gBACpC,iBAAiB,EAAE,GAAsB,EAAE,CAAC,IAAI,CAAC,iBAAiB,EAAE;aACrE,CAAA;YACD,OAAO,EAAE,CAAC,SAAS,CAAC,CAAA;QACtB,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;IAC5B,CAAC;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,iBAAiB;QACrB,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CACnC,oDAAoD,EACpD,SAAS,CACV,CAAA;YACD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAA;QAC/B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAA;QACX,CAAC;IACH,CAAC;CACF"}

package/dist/persistence/dolt-client.d.ts

@@ -0,0 +1,69 @@
+import type { ILogger } from '../dispatch/types.js';
+export interface DoltClientOptions {
+    repoPath: string;
+    socketPath?: string;
+    logger?: ILogger;
+}
+export declare class DoltClient {
+    readonly repoPath: string;
+    readonly socketPath: string;
+    private _pool;
+    private _useCliMode;
+    private _connected;
+    private readonly _log;
+    /** Promise-chain mutex that serializes all CLI operations to prevent concurrent noms manifest access */
+    private _cliMutex;
+    constructor(options: DoltClientOptions);
+    connect(): Promise<void>;
+    query<T>(sql: string, params?: unknown[], branch?: string): Promise<T[]>;
+    /**
+     * Execute a function within an explicit SQL transaction, enforcing
+     * atomicity in both pool mode and CLI mode.
+     *
+     * Pool mode: acquires a dedicated connection from the pool, executes
+     * BEGIN/COMMIT on that connection, and passes a connection-bound query
+     * lambda to `fn`. Connection is released in a `finally` block.
+     *
+     * CLI mode: collects all SQL statements issued within `fn()` via a
+     * statement-collecting query lambda (returns [] immediately), then
+     * executes the combined batch as a single `dolt sql -q "BEGIN; ...; COMMIT"`
+     * invocation via `_withCliLock()`. This ensures atomicity for pure-write
+     * transactions. NOTE: read-then-write patterns within `fn()` are not
+     * supported in CLI mode — SELECT queries always return [] in the collector.
+     * See Dev Notes in story 53-14 for documented call-site exceptions.
+     */
+    transact<T>(fn: (query: <R>(sql: string, params?: unknown[]) => Promise<R[]>) => Promise<T>): Promise<T>;
+    private _queryPool;
+    /**
+     * Acquire an exclusive CLI lock. Dolt CLI takes an exclusive lock on the noms
+     * manifest, so concurrent `dolt sql -q` / `dolt <subcommand>` processes
+     * produce "cannot update manifest: database is read only" errors.
+     * Serialize all CLI operations through a single promise chain.
+     */
+    private _withCliLock;
+    /**
+     * Substitute `?` placeholders in a SQL string with properly escaped literal
+     * values from the `params` array.  Used by both `_queryCli` and the CLI
+     * `transact` path to produce a fully-resolved SQL string for shell execution.
+     */
+    private _resolveParams;
+    private _queryCli;
+    /**
+     * Execute a raw Dolt CLI command (e.g. `dolt diff main...story/26-1 --stat`)
+     * and return the stdout as a string.
+     *
+     * This is distinct from `query()` which runs SQL. Use `exec()` for Dolt
+     * sub-commands like `diff`, `log`, `branch`, etc.
+     */
+    exec(command: string): Promise<string>;
+    /**
+     * Execute a Dolt CLI command with pre-split arguments.
+     *
+     * Use this instead of `exec()` when arguments contain spaces (e.g. commit
+     * messages) to avoid whitespace-splitting issues.
+     */
+    execArgs(args: string[]): Promise<string>;
+    close(): Promise<void>;
+}
+export declare function createDoltClient(options: DoltClientOptions): DoltClient;
+//# sourceMappingURL=dolt-client.d.ts.map

package/dist/persistence/dolt-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dolt-client.d.ts","sourceRoot":"","sources":["../../src/persistence/dolt-client.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AA2BnD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAED,qBAAa,UAAU;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,OAAO,CAAC,KAAK,CAAoB;IACjC,OAAO,CAAC,WAAW,CAAQ;IAC3B,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,wGAAwG;IACxG,OAAO,CAAC,SAAS,CAAmC;gBAExC,OAAO,EAAE,iBAAiB;IAMhC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBxB,KAAK,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC;IAU9E;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,CAAC,EACd,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC9E,OAAO,CAAC,CAAC,CAAC;YA0DC,UAAU;IAwBxB;;;;;OAKG;IACH,OAAO,CAAC,YAAY;IAOpB;;;;OAIG;IACH,OAAO,CAAC,cAAc;YAWR,SAAS;IAyBvB;;;;;;OAMG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAO5C;;;;;OAKG;IACG,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAYzC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAO7B;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAEvE"}

package/dist/persistence/dolt-client.js

@@ -0,0 +1,278 @@
+/**
+ * DoltClient — low-level SQL client for Dolt repositories.
+ * Connects via mysql2 unix socket (primary) or falls back to dolt CLI.
+ * Extracted to @substrate-ai/core so downstream packages can import it.
+ */
+import { execFile as execFileCb } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { DoltQueryError } from './dolt-errors.js';
+/**
+ * Promise-wrapper around execFile that always resolves to { stdout, stderr }.
+ * Using an explicit wrapper rather than promisify() avoids the util.promisify.custom
+ * symbol complexity when mocking in tests.
+ */
+function runExecFile(cmd, args, opts) {
+    return new Promise((resolve, reject) => {
+        execFileCb(cmd, args, { ...opts, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve({ stdout, stderr });
+            }
+        });
+    });
+}
+const noopLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+};
+export class DoltClient {
+    repoPath;
+    socketPath;
+    _pool = null;
+    _useCliMode = false;
+    _connected = false;
+    _log;
+    /** Promise-chain mutex that serializes all CLI operations to prevent concurrent noms manifest access */
+    _cliMutex = Promise.resolve();
+    constructor(options) {
+        this.repoPath = options.repoPath;
+        this.socketPath = options.socketPath ?? `${options.repoPath}/.dolt/dolt.sock`;
+        this._log = options.logger ?? noopLogger;
+    }
+    async connect() {
+        // Probe unix socket
+        try {
+            await access(this.socketPath);
+            // Socket exists — try mysql2
+            const mysql = await import('mysql2/promise');
+            this._pool = mysql.createPool({
+                socketPath: this.socketPath,
+                user: 'root',
+                database: 'doltdb',
+                waitForConnections: true,
+                connectionLimit: 5,
+            });
+            this._useCliMode = false;
+            this._log.debug('Connected via unix socket: %s', this.socketPath);
+        }
+        catch {
+            // Socket absent or inaccessible — use CLI fallback
+            this._useCliMode = true;
+            this._log.debug('Unix socket not available, using CLI fallback for %s', this.repoPath);
+        }
+        this._connected = true;
+    }
+    async query(sql, params, branch) {
+        if (!this._connected) {
+            await this.connect();
+        }
+        if (this._useCliMode) {
+            return this._queryCli(sql, params, branch);
+        }
+        return this._queryPool(sql, params, branch);
+    }
+    /**
+     * Execute a function within an explicit SQL transaction, enforcing
+     * atomicity in both pool mode and CLI mode.
+     *
+     * Pool mode: acquires a dedicated connection from the pool, executes
+     * BEGIN/COMMIT on that connection, and passes a connection-bound query
+     * lambda to `fn`. Connection is released in a `finally` block.
+     *
+     * CLI mode: collects all SQL statements issued within `fn()` via a
+     * statement-collecting query lambda (returns [] immediately), then
+     * executes the combined batch as a single `dolt sql -q "BEGIN; ...; COMMIT"`
+     * invocation via `_withCliLock()`. This ensures atomicity for pure-write
+     * transactions. NOTE: read-then-write patterns within `fn()` are not
+     * supported in CLI mode — SELECT queries always return [] in the collector.
+     * See Dev Notes in story 53-14 for documented call-site exceptions.
+     */
+    async transact(fn) {
+        if (!this._connected) {
+            await this.connect();
+        }
+        if (!this._useCliMode) {
+            // Pool mode: acquire a dedicated connection so all queries in the
+            // transaction use the same session/connection (no scatter across pool).
+            const conn = await this._pool.getConnection();
+            try {
+                await conn.execute('BEGIN');
+                const txQuery = async (sql, params) => {
+                    try {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        const [rows] = await conn.execute(sql, params);
+                        return rows;
+                    }
+                    catch (err) {
+                        throw new DoltQueryError(sql, err instanceof Error ? err.message : String(err));
+                    }
+                };
+                const result = await fn(txQuery);
+                await conn.execute('COMMIT');
+                return result;
+            }
+            catch (err) {
+                try {
+                    await conn.execute('ROLLBACK');
+                }
+                catch {
+                    // ignore rollback error
+                }
+                throw err;
+            }
+            finally {
+                conn.release();
+            }
+        }
+        else {
+            // CLI mode: collect all SQL statements issued within fn(), then
+            // execute them as a single batched dolt sql invocation.
+            const statements = [];
+            const txQuery = async (sql, params) => {
+                statements.push(this._resolveParams(sql, params));
+                return [];
+            };
+            const result = await fn(txQuery);
+            if (statements.length > 0) {
+                const batchSql = `BEGIN; ${statements.join('; ')}; COMMIT`;
+                await this._withCliLock(async () => {
+                    try {
+                        await runExecFile('dolt', ['sql', '-q', batchSql, '--result-format', 'json'], {
+                            cwd: this.repoPath,
+                        });
+                    }
+                    catch (err) {
+                        throw new DoltQueryError(batchSql, err instanceof Error ? err.message : String(err));
+                    }
+                });
+            }
+            return result;
+        }
+    }
+    async _queryPool(sql, params, branch) {
+        try {
+            if (branch !== undefined && branch !== 'main') {
+                // For branch-targeting, acquire a dedicated connection and switch the database context.
+                // Dolt server mode supports `database/branch` as a database selector via USE statement.
+                const conn = await this._pool.getConnection();
+                try {
+                    await conn.execute(`USE \`substrate/${branch}\``);
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const [rows] = await conn.execute(sql, params);
+                    return rows;
+                }
+                finally {
+                    conn.release();
+                }
+            }
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const [rows] = await this._pool.execute(sql, params);
+            return rows;
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new DoltQueryError(sql, detail);
+        }
+    }
+    /**
+     * Acquire an exclusive CLI lock. Dolt CLI takes an exclusive lock on the noms
+     * manifest, so concurrent `dolt sql -q` / `dolt <subcommand>` processes
+     * produce "cannot update manifest: database is read only" errors.
+     * Serialize all CLI operations through a single promise chain.
+     */
+    _withCliLock(fn) {
+        const prev = this._cliMutex;
+        let release;
+        this._cliMutex = new Promise((resolve) => { release = resolve; });
+        return prev.then(fn).finally(() => release());
+    }
+    /**
+     * Substitute `?` placeholders in a SQL string with properly escaped literal
+     * values from the `params` array.  Used by both `_queryCli` and the CLI
+     * `transact` path to produce a fully-resolved SQL string for shell execution.
+     */
+    _resolveParams(sql, params) {
+        if (!params || params.length === 0)
+            return sql;
+        let i = 0;
+        return sql.replace(/\?/g, () => {
+            const val = params[i++];
+            if (val === null || val === undefined)
+                return 'NULL';
+            if (typeof val === 'number')
+                return String(val);
+            return `'${String(val).replace(/'/g, "''")}'`;
+        });
+    }
+    async _queryCli(sql, params, branch) {
+        // Substitute params with escaped literals using the shared helper
+        const finalSql = this._resolveParams(sql, params);
+        return this._withCliLock(async () => {
+            try {
+                // Dolt CLI has no branch flag for `dolt sql`. Prepend DOLT_CHECKOUT
+                // to switch branches when needed. Multi-statement output produces one
+                // JSON object per line — parse the last line for the actual result.
+                const branchPrefix = branch
+                    ? `CALL DOLT_CHECKOUT('${branch.replace(/'/g, "''")}'); `
+                    : '';
+                const args = ['sql', '-q', branchPrefix + finalSql, '--result-format', 'json'];
+                const { stdout } = await runExecFile('dolt', args, { cwd: this.repoPath });
+                // When branch prefix is used, stdout has multiple JSON lines; take the last one
+                const lines = (stdout || '').trim().split('\n').filter(Boolean);
+                const lastLine = lines.length > 0 ? lines[lines.length - 1] : '{"rows":[]}';
+                const parsed = JSON.parse(lastLine);
+                return (parsed.rows ?? []);
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new DoltQueryError(finalSql, detail);
+            }
+        });
+    }
+    /**
+     * Execute a raw Dolt CLI command (e.g. `dolt diff main...story/26-1 --stat`)
+     * and return the stdout as a string.
+     *
+     * This is distinct from `query()` which runs SQL. Use `exec()` for Dolt
+     * sub-commands like `diff`, `log`, `branch`, etc.
+     */
+    async exec(command) {
+        const parts = command.trim().split(/\s+/);
+        // If the command starts with 'dolt', strip it; otherwise pass all parts as args
+        const cmdArgs = parts[0] === 'dolt' ? parts.slice(1) : parts;
+        return this.execArgs(cmdArgs);
+    }
+    /**
+     * Execute a Dolt CLI command with pre-split arguments.
+     *
+     * Use this instead of `exec()` when arguments contain spaces (e.g. commit
+     * messages) to avoid whitespace-splitting issues.
+     */
+    async execArgs(args) {
+        return this._withCliLock(async () => {
+            try {
+                const { stdout } = await runExecFile('dolt', args, { cwd: this.repoPath });
+                return stdout;
+            }
+            catch (err) {
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new DoltQueryError(args.join(' '), detail);
+            }
+        });
+    }
+    async close() {
+        if (this._pool) {
+            await this._pool.end();
+            this._pool = null;
+        }
+        this._connected = false;
+    }
+}
+export function createDoltClient(options) {
+    return new DoltClient(options);
+}
+//# sourceMappingURL=dolt-client.js.map

package/dist/persistence/dolt-client.js.map

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

package/dist/persistence/dolt-errors.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Typed Dolt error classes for low-level persistence operations.
+ * Extracted here so downstream packages can import from @substrate-ai/core.
+ */
+export declare class DoltQueryError extends Error {
+    sql: string;
+    detail: string;
+    constructor(sql: string, detail: string);
+}
+//# sourceMappingURL=dolt-errors.d.ts.map

package/dist/persistence/dolt-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dolt-errors.d.ts","sourceRoot":"","sources":["../../src/persistence/dolt-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qBAAa,cAAe,SAAQ,KAAK;IACvC,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;gBAEF,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAMxC"}

package/dist/persistence/dolt-errors.js

@@ -0,0 +1,15 @@
+/**
+ * Typed Dolt error classes for low-level persistence operations.
+ * Extracted here so downstream packages can import from @substrate-ai/core.
+ */
+export class DoltQueryError extends Error {
+    sql;
+    detail;
+    constructor(sql, detail) {
+        super(`Dolt query failed: ${detail}`);
+        this.name = 'DoltQueryError';
+        this.sql = sql;
+        this.detail = detail;
+    }
+}
+//# sourceMappingURL=dolt-errors.js.map

package/dist/persistence/dolt-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dolt-errors.js","sourceRoot":"","sources":["../../src/persistence/dolt-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,OAAO,cAAe,SAAQ,KAAK;IACvC,GAAG,CAAQ;IACX,MAAM,CAAQ;IAEd,YAAY,GAAW,EAAE,MAAc;QACrC,KAAK,CAAC,sBAAsB,MAAM,EAAE,CAAC,CAAA;QACrC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAA;QAC5B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;QACd,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;CACF"}

package/dist/persistence/dolt-init.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Dolt initialization logic for the Substrate state layer.
+ *
+ * Provides `initializeDolt()` which creates and seeds a Dolt repository
+ * using only the Dolt CLI — no mysql2 dependency is required at this stage.
+ * Extracted to @substrate-ai/core so downstream packages can import it.
+ */
+/**
+ * Configuration for `initializeDolt()`.
+ */
+export interface DoltInitConfig {
+    /** Absolute path to the project root. */
+    projectRoot: string;
+    /**
+     * Path where the Dolt repository will be created.
+     * Defaults to `<projectRoot>/.substrate/state/`.
+     */
+    statePath?: string;
+    /**
+     * Path to the `schema.sql` DDL file. REQUIRED — caller must provide an
+     * absolute path (e.g. via fileURLToPath(new URL('./schema.sql', import.meta.url))).
+     */
+    schemaPath: string;
+}
+/**
+ * Thrown when the `dolt` binary cannot be found in PATH.
+ */
+export declare class DoltNotInstalled extends Error {
+    constructor();
+}
+/**
+ * Thrown when a Dolt CLI command exits with a non-zero status code.
+ */
+export declare class DoltInitError extends Error {
+    constructor(args: string[], exitCode: number, stderr: string);
+}
+/**
+ * Verify that the `dolt` binary is installed and accessible.
+ *
+ * @throws {DoltNotInstalled} If the binary is not found in PATH.
+ */
+export declare function checkDoltInstalled(): Promise<void>;
+/**
+ * Run a Dolt CLI command in the given working directory.
+ *
+ * @param args - Arguments to pass to `dolt` (e.g. `['init']`).
+ * @param cwd  - Working directory for the command.
+ * @throws {DoltInitError} If the command exits with a non-zero code.
+ */
+export declare function runDoltCommand(args: string[], cwd: string): Promise<void>;
+/**
+ * Initialize a Dolt repository for Substrate state storage.
+ *
+ * This function is idempotent: running it a second time on an already-
+ * initialized repository is safe — `dolt init` is skipped, existing tables
+ * are not re-created (IF NOT EXISTS guards), and the schema version row is
+ * not duplicated (INSERT IGNORE).
+ *
+ * @param config - Initialization configuration. `schemaPath` is required.
+ * @throws {DoltNotInstalled} If the `dolt` binary is not in PATH.
+ * @throws {DoltInitError} If any Dolt CLI command fails.
+ */
+export declare function initializeDolt(config: DoltInitConfig): Promise<void>;
+//# sourceMappingURL=dolt-init.d.ts.map

package/dist/persistence/dolt-init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dolt-init.d.ts","sourceRoot":"","sources":["../../src/persistence/dolt-init.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;CACnB;AAMD;;GAEG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;;CAO1C;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,IAAI,EAAE,MAAM,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;CAM7D;AAMD;;;;GAIG;AACH,wBAAsB,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAgCxD;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB/E;AAwDD;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAoD1E"}