@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/dist/resources/extensions/gsd/db/engine.js

@@ -0,0 +1,800 @@
+// Project/App: gsd-pi
+// File Purpose: GSD engine — connection ownership, lifecycle, schema/migrations,
+// and transaction primitives for the single-writer layer. The shared handle
+// (currentDb) lives here; domain writers, allowlisted coordination/runtime
+// writers, schema/migration helpers, and the Query Module (db/queries.ts) read
+// it through getDb()/getDbOrNull().
+//
+// This file legitimately holds DDL and BEGIN/COMMIT control, so it is
+// allowlisted in tests/single-writer-invariant.test.ts alongside the explicit
+// writer layer.
+import { createRequire } from "node:module";
+import { existsSync, copyFileSync, mkdirSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { GSDError, GSD_STALE_STATE } from "../errors.js";
+import { logError, logWarning } from "../workflow-logger.js";
+import { createDbAdapter } from "../db-adapter.js";
+import { createBaseSchemaObjects } from "../db-base-schema.js";
+import { createCoordinationTablesV24 } from "../db-coordination-schema.js";
+import { createDbConnectionCache } from "../db-connection-cache.js";
+import { backupDatabaseBeforeMigration, isMigrationBackupError } from "../db-migration-backup.js";
+import { applyMigrationV2Artifacts, applyMigrationV3Memories, applyMigrationV4DecisionMadeBy, applyMigrationV5HierarchyTables, applyMigrationV6SliceSummaries, applyMigrationV7Dependencies, applyMigrationV8PlanningFields, applyMigrationV9Ordering, applyMigrationV10ReplanTrigger, applyMigrationV11TaskPlanning, applyMigrationV12QualityGates, applyMigrationV13HotPathIndexes, applyMigrationV14SliceDependencies, applyMigrationV15AuditTables, applyMigrationV16EscalationSource, applyMigrationV17TaskEscalation, applyMigrationV18MemorySources, applyMigrationV19MemoryFts, applyMigrationV20MemoryRelations, applyMigrationV21StructuredMemories, applyMigrationV22QualityGateRepair, applyMigrationV23MilestoneQueue, applyMigrationV26MilestoneCommitAttributions, applyMigrationV27ArtifactHash, applyMigrationV28MemoryLastHitAt, applyMigrationV29RepositoryTargets, } from "../db-migration-steps.js";
+import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "../db-memory-fts-schema.js";
+import { createDbOpenState } from "../db-open-state.js";
+import { createRuntimeKvTableV25 } from "../db-runtime-kv-schema.js";
+import { getCurrentSchemaVersion, recordSchemaVersion } from "../db-schema-metadata.js";
+import { createDbTransactionRunner } from "../db-transaction.js";
+import { ensureVerificationEvidenceDedupIndex } from "../db-verification-evidence-schema.js";
+import { BETTER_SQLITE3_PACKAGE, createSqliteProviderLoader, suppressSqliteWarning, } from "../db-provider.js";
+let _gsdRequire;
+function getGsdRequire() {
+    if (_gsdRequire !== undefined)
+        return _gsdRequire;
+    try {
+        _gsdRequire = createRequire(import.meta.url);
+    }
+    catch {
+        _gsdRequire = null;
+    }
+    return _gsdRequire;
+}
+const providerLoader = createSqliteProviderLoader({
+    tryRequireNodeSqlite: () => {
+        const req = getGsdRequire();
+        if (!req)
+            throw new Error("unavailable");
+        return req("node:sqlite");
+    },
+    tryRequireBetterSqlite3: () => {
+        const req = getGsdRequire();
+        if (!req)
+            throw new Error("unavailable");
+        return req(BETTER_SQLITE3_PACKAGE);
+    },
+    suppressSqliteWarning,
+    nodeVersion: process.versions.node,
+    writeStderr: (message) => process.stderr.write(message),
+});
+export const SCHEMA_VERSION = 29;
+function initSchema(db, fileBacked, dbPath) {
+    const conservativeFilePragmas = fileBacked && _isLikelyWslDrvFsPathForTest(dbPath);
+    if (fileBacked)
+        db.exec(conservativeFilePragmas ? "PRAGMA journal_mode=DELETE" : "PRAGMA journal_mode=WAL");
+    if (fileBacked)
+        db.exec("PRAGMA busy_timeout = 5000");
+    if (fileBacked)
+        db.exec(conservativeFilePragmas ? "PRAGMA synchronous = FULL" : "PRAGMA synchronous = NORMAL");
+    if (fileBacked)
+        db.exec("PRAGMA auto_vacuum = INCREMENTAL");
+    if (fileBacked)
+        db.exec("PRAGMA cache_size = -8000"); // 8 MB page cache
+    if (fileBacked && !conservativeFilePragmas && process.platform !== "darwin")
+        db.exec("PRAGMA mmap_size = 67108864"); // 64 MB mmap
+    db.exec("PRAGMA temp_store = MEMORY");
+    db.exec("PRAGMA foreign_keys = ON");
+    db.exec("BEGIN");
+    try {
+        createBaseSchemaObjects(db, {
+            tryCreateMemoriesFts,
+            ensureVerificationEvidenceDedupIndex,
+        });
+        const existing = db.prepare("SELECT count(*) as cnt FROM schema_version").get();
+        if (existing && existing["cnt"] === 0) {
+            createCoordinationTablesV24(db);
+            createRuntimeKvTableV25(db);
+            // Fresh install — all tables are created above with the full current schema,
+            // so it is safe to create all migration-specific indexes here.  For existing
+            // databases these indexes are created inside the individual migration guards
+            // in migrateSchema() after the corresponding columns have been added.
+            db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_escalation_pending ON tasks(milestone_id, slice_id, escalation_pending)");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memories_scope ON memories(scope)");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_kind ON memory_sources(kind)");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_sources_scope ON memory_sources(scope)");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_from ON memory_relations(from_id)");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memory_relations_to ON memory_relations(to_id)");
+            recordSchemaVersion(db, SCHEMA_VERSION);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    migrateSchema(db, dbPath);
+}
+export function _isLikelyWslDrvFsPathForTest(dbPath) {
+    if (!dbPath || process.platform !== "linux")
+        return false;
+    const drvFsPathPattern = /^\/mnt\/[a-z](?:\/|$)/i;
+    if (drvFsPathPattern.test(dbPath))
+        return true;
+    try {
+        return drvFsPathPattern.test(realpathSync(dbPath));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Create the FTS5 virtual table for memories plus the triggers that keep it
+ * in sync with the base table. FTS5 may be unavailable on stripped-down
+ * SQLite builds — callers should treat failure as non-fatal and fall back
+ * to LIKE-based scans in `memory-store.queryMemoriesRanked`.
+ */
+export function tryCreateMemoriesFts(db) {
+    return tryCreateMemoriesFtsSchema(db, {
+        onUnavailable: (message) => logWarning("db", message),
+    });
+}
+export function isMemoriesFtsAvailable(db) {
+    return isMemoriesFtsAvailableSchema(db);
+}
+function backfillMemoriesFts(db) {
+    db.exec(`INSERT INTO memories_fts(rowid, content) SELECT seq, content FROM memories`);
+}
+function copyQualityGateRowsToRepairedTable(db) {
+    db.exec(`
+    INSERT OR IGNORE INTO quality_gates_new
+      (milestone_id, slice_id, gate_id, scope, task_id, status, verdict, rationale, findings, evaluated_at)
+    SELECT milestone_id, slice_id, gate_id, scope, COALESCE(task_id, ''), status, verdict, rationale, findings, evaluated_at
+    FROM quality_gates
+  `);
+}
+function migrateSchema(db, dbPath) {
+    const currentVersion = getCurrentSchemaVersion(db);
+    if (currentVersion >= SCHEMA_VERSION)
+        return;
+    backupDatabaseBeforeMigration(db, dbPath, currentVersion, {
+        existsSync,
+        copyFileSync,
+        logWarning,
+    });
+    db.exec("BEGIN");
+    try {
+        if (currentVersion < 2) {
+            applyMigrationV2Artifacts(db);
+            recordSchemaVersion(db, 2);
+        }
+        if (currentVersion < 3) {
+            applyMigrationV3Memories(db);
+            recordSchemaVersion(db, 3);
+        }
+        if (currentVersion < 4) {
+            applyMigrationV4DecisionMadeBy(db);
+            recordSchemaVersion(db, 4);
+        }
+        if (currentVersion < 5) {
+            applyMigrationV5HierarchyTables(db);
+            recordSchemaVersion(db, 5);
+        }
+        if (currentVersion < 6) {
+            applyMigrationV6SliceSummaries(db);
+            recordSchemaVersion(db, 6);
+        }
+        if (currentVersion < 7) {
+            applyMigrationV7Dependencies(db);
+            recordSchemaVersion(db, 7);
+        }
+        if (currentVersion < 8) {
+            applyMigrationV8PlanningFields(db);
+            recordSchemaVersion(db, 8);
+        }
+        if (currentVersion < 9) {
+            applyMigrationV9Ordering(db);
+            recordSchemaVersion(db, 9);
+        }
+        if (currentVersion < 10) {
+            applyMigrationV10ReplanTrigger(db);
+            recordSchemaVersion(db, 10);
+        }
+        if (currentVersion < 11) {
+            applyMigrationV11TaskPlanning(db);
+            recordSchemaVersion(db, 11);
+        }
+        if (currentVersion < 12) {
+            // NOTE: The original DDL used COALESCE(task_id, '') in the PRIMARY KEY
+            // expression, which is invalid SQLite syntax and causes startup errors on
+            // DBs that migrate through v12. The corrected DDL uses
+            // task_id TEXT NOT NULL DEFAULT '' with a plain column list PK. DBs that
+            // were created with the broken DDL are repaired by the v22 migration below.
+            applyMigrationV12QualityGates(db);
+            recordSchemaVersion(db, 12);
+        }
+        if (currentVersion < 13) {
+            applyMigrationV13HotPathIndexes(db, ensureVerificationEvidenceDedupIndex);
+            recordSchemaVersion(db, 13);
+        }
+        if (currentVersion < 14) {
+            applyMigrationV14SliceDependencies(db);
+            recordSchemaVersion(db, 14);
+        }
+        if (currentVersion < 15) {
+            applyMigrationV15AuditTables(db);
+            recordSchemaVersion(db, 15);
+        }
+        if (currentVersion < 16) {
+            applyMigrationV16EscalationSource(db);
+            recordSchemaVersion(db, 16);
+        }
+        if (currentVersion < 17) {
+            applyMigrationV17TaskEscalation(db);
+            recordSchemaVersion(db, 17);
+        }
+        if (currentVersion < 18) {
+            applyMigrationV18MemorySources(db);
+            recordSchemaVersion(db, 18);
+        }
+        if (currentVersion < 19) {
+            applyMigrationV19MemoryFts(db, {
+                tryCreateMemoriesFts,
+                isMemoriesFtsAvailable,
+                backfillMemoriesFts,
+                logWarning,
+            });
+            recordSchemaVersion(db, 19);
+        }
+        if (currentVersion < 20) {
+            applyMigrationV20MemoryRelations(db);
+            recordSchemaVersion(db, 20);
+        }
+        if (currentVersion < 21) {
+            applyMigrationV21StructuredMemories(db);
+            recordSchemaVersion(db, 21);
+        }
+        if (currentVersion < 22) {
+            applyMigrationV22QualityGateRepair(db, { copyQualityGateRowsToRepairedTable });
+            recordSchemaVersion(db, 22);
+        }
+        if (currentVersion < 23) {
+            applyMigrationV23MilestoneQueue(db);
+            recordSchemaVersion(db, 23);
+        }
+        if (currentVersion < 24) {
+            // v24: auto-mode coordination tables. See createCoordinationTablesV24
+            // for full schema + invariants. No-op for fresh installs (the same
+            // helper runs in the fresh-install path); for upgraded DBs this is
+            // the only place these tables get created.
+            createCoordinationTablesV24(db);
+            recordSchemaVersion(db, 24);
+        }
+        if (currentVersion < 25) {
+            // v25: runtime_kv non-correctness-critical key-value storage. See
+            // createRuntimeKvTableV25 for the full schema + invariants.
+            createRuntimeKvTableV25(db);
+            recordSchemaVersion(db, 25);
+        }
+        if (currentVersion < 26) {
+            applyMigrationV26MilestoneCommitAttributions(db);
+            recordSchemaVersion(db, 26);
+        }
+        if (currentVersion < 27) {
+            applyMigrationV27ArtifactHash(db);
+            recordSchemaVersion(db, 27);
+        }
+        if (currentVersion < 28) {
+            applyMigrationV28MemoryLastHitAt(db);
+            recordSchemaVersion(db, 28);
+        }
+        if (currentVersion < 29) {
+            applyMigrationV29RepositoryTargets(db);
+            recordSchemaVersion(db, 29);
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+}
+let currentDb = null;
+let currentPath = null;
+let currentPid = 0;
+let _exitHandlerRegistered = false;
+const _dbOpenState = createDbOpenState();
+/**
+ * Identity key of the workspace whose connection is currently active
+ * (currentDb). Set by openDatabaseByWorkspace(); null when the active
+ * connection was opened via the legacy openDatabase(path) path.
+ */
+let _currentIdentityKey = null;
+/**
+ * Workspace-scoped connection cache.
+ * Key: GsdWorkspace.identityKey (realpath-normalized project root).
+ * Value: the DB path and open adapter for that workspace.
+ *
+ * Sibling worktrees of the same project share the same identityKey (set by
+ * createWorkspace) and therefore reuse the same cached connection, preserving
+ * shared-WAL semantics. Different projects get distinct cache entries.
+ *
+ * NOTE: Only one connection is "active" at a time (currentDb/currentPath).
+ * The cache allows fast re-activation of a previously opened connection when
+ * callers switch between known workspaces via openDatabaseByWorkspace().
+ */
+const _dbCache = createDbConnectionCache();
+/** Test helper: expose the internal cache for inspection. Not for production use. */
+export function _getDbCache() {
+    return _dbCache.asReadonlyMap();
+}
+function closeCachedConnection(entry, source) {
+    try {
+        entry.db.exec("PRAGMA wal_checkpoint(TRUNCATE)");
+    }
+    catch (e) {
+        if (source === "workspace")
+            logWarning("db", `WAL checkpoint (byWorkspace) failed: ${e.message}`);
+    }
+    try {
+        entry.db.exec("PRAGMA incremental_vacuum(64)");
+    }
+    catch (e) {
+        if (source === "workspace")
+            logWarning("db", `incremental vacuum (byWorkspace) failed: ${e.message}`);
+    }
+    try {
+        entry.db.close();
+    }
+    catch (e) {
+        if (source === "workspace")
+            logWarning("db", `database close (byWorkspace) failed: ${e.message}`);
+    }
+}
+/**
+ * Close and evict every entry in the workspace connection cache, then call
+ * closeDatabase() to close the active connection.
+ *
+ * Use this for test teardown or process-shutdown paths where every open
+ * connection must be flushed. Normal callers should use closeDatabase() or
+ * closeDatabaseByWorkspace() instead.
+ */
+export function closeAllDatabases() {
+    // Close all non-active cached connections first.
+    _dbCache.closeNonActive(currentDb, (entry) => closeCachedConnection(entry, "all"));
+    closeDatabase();
+}
+/**
+ * Open (or reuse) the database connection scoped to the given workspace.
+ *
+ * Uses workspace.identityKey as the cache key, so sibling worktrees of the
+ * same project resolve to the same connection. On a cache hit the existing
+ * adapter is reactivated as the current connection without re-opening the
+ * file. On a cache miss, delegates to openDatabase() for the full
+ * open + schema-init + migration flow, then caches the result.
+ *
+ * When switching to a different workspace, the previously active connection
+ * is preserved in the cache (not closed), so callers can switch back to it
+ * cheaply via a subsequent openDatabaseByWorkspace() call.
+ *
+ * @param workspace A GsdWorkspace created by createWorkspace().
+ * @returns true if the connection is open and ready, false otherwise.
+ */
+export function openDatabaseByWorkspace(workspace) {
+    const key = workspace.identityKey;
+    const dbPath = workspace.contract.projectDb;
+    const cached = _dbCache.get(key);
+    if (cached) {
+        // Reactivate the cached connection as the current singleton.
+        currentDb = cached.db;
+        currentPath = cached.dbPath;
+        currentPid = process.pid;
+        _dbOpenState.markAttempted();
+        _currentIdentityKey = key;
+        return true;
+    }
+    // Cache miss — need to open a new connection.
+    //
+    // If there is a currently active workspace connection, stash it in the
+    // cache under its identity key before calling openDatabase(), because
+    // openDatabase() will call closeDatabase() when the path changes (which
+    // would destroy the existing adapter). By nulling out currentDb first,
+    // we prevent openDatabase() from closing the live adapter.
+    let oldDb = null;
+    let oldPath = null;
+    let oldPid = 0;
+    let oldKey = null;
+    if (currentDb !== null && _currentIdentityKey !== null) {
+        // Snapshot the old globals so we can restore them on failure.
+        oldDb = currentDb;
+        oldPath = currentPath;
+        oldPid = currentPid;
+        oldKey = _currentIdentityKey;
+        // Save the current connection so it stays alive in the cache.
+        _dbCache.set(_currentIdentityKey, {
+            dbPath: currentPath,
+            db: currentDb,
+        });
+        // Detach from globals so openDatabase() opens fresh without closing it.
+        currentDb = null;
+        currentPath = null;
+        currentPid = 0;
+        _currentIdentityKey = null;
+    }
+    // Run the full open/schema/migration flow for the new workspace.
+    // openDatabase() can throw on corrupt DB or permission error — catch so we
+    // can restore the previous connection rather than leaving globals null.
+    let opened;
+    try {
+        opened = openDatabase(dbPath);
+    }
+    catch (err) {
+        // Failed to open the new DB. Restore the previous workspace connection so
+        // the caller's workspace remains active (it is still safe in _dbCache).
+        if (oldDb !== null) {
+            currentDb = oldDb;
+            currentPath = oldPath;
+            currentPid = oldPid;
+            _currentIdentityKey = oldKey;
+        }
+        throw err;
+    }
+    if (opened && currentDb) {
+        _dbCache.set(key, { dbPath, db: currentDb });
+        _currentIdentityKey = key;
+    }
+    else if (!opened && oldDb !== null) {
+        // Restore the previous connection so the caller's workspace remains active.
+        // The failed attempt left no live adapter, so the globals stayed null.
+        currentDb = oldDb;
+        currentPath = oldPath;
+        currentPid = oldPid;
+        _currentIdentityKey = oldKey;
+    }
+    return opened;
+}
+/**
+ * Open (or reuse) the database connection scoped to the workspace in a
+ * MilestoneScope. Thin delegation to openDatabaseByWorkspace().
+ */
+export function openDatabaseByScope(scope) {
+    return openDatabaseByWorkspace(scope.workspace);
+}
+/**
+ * Close the database connection for the given workspace and remove it from
+ * the cache. If the workspace's connection is currently active (currentDb),
+ * performs a full closeDatabase() including WAL checkpoint. Otherwise only
+ * removes the cache entry (the adapter was already replaced by a later open).
+ */
+export function closeDatabaseByWorkspace(workspace) {
+    const key = workspace.identityKey;
+    const cached = _dbCache.get(key);
+    if (!cached)
+        return;
+    _dbCache.delete(key);
+    if (currentDb === cached.db) {
+        // This workspace's connection is the active one — full close.
+        closeDatabase();
+    }
+    else {
+        // Connection was displaced by a later open; close the adapter directly.
+        closeCachedConnection(cached, "workspace");
+    }
+}
+export function getDbProvider() {
+    providerLoader.load();
+    return providerLoader.getProviderName();
+}
+export function isDbAvailable() {
+    return currentDb !== null;
+}
+/**
+ * Returns true if openDatabase() has been called at least once this session.
+ * Used to distinguish "DB not yet initialized" from "DB genuinely unavailable"
+ * so that early callers (e.g. before_agent_start context injection) don't
+ * trigger a false degraded-mode warning.
+ */
+export function wasDbOpenAttempted() {
+    return _dbOpenState.snapshot().attempted;
+}
+export function getDbStatus() {
+    providerLoader.load();
+    const openState = _dbOpenState.snapshot();
+    return {
+        available: currentDb !== null,
+        provider: providerLoader.getProviderName(),
+        attempted: openState.attempted,
+        lastError: openState.lastError,
+        lastPhase: openState.lastPhase,
+    };
+}
+export function openDatabase(path) {
+    _dbOpenState.markAttempted();
+    if (currentDb && currentPath !== path)
+        closeDatabase();
+    if (currentDb && currentPath === path)
+        return true;
+    // Reset error state only when a new open attempt is actually going to run.
+    _dbOpenState.clearError();
+    let rawDb;
+    let fallbackOpen = null;
+    try {
+        rawDb = providerLoader.openRaw(path);
+    }
+    catch (primaryErr) {
+        _dbOpenState.recordError("open", primaryErr);
+        // node:sqlite loaded but failed to open this file — try better-sqlite3 as fallback.
+        fallbackOpen = providerLoader.tryOpenBetterSqliteFallback(path);
+        if (fallbackOpen) {
+            rawDb = fallbackOpen.rawDb;
+            _dbOpenState.clearError();
+        }
+        if (!rawDb)
+            throw primaryErr;
+    }
+    if (!rawDb)
+        return false;
+    const adapter = createDbAdapter(rawDb);
+    const fileBacked = path !== ":memory:";
+    try {
+        initSchema(adapter, fileBacked, path);
+    }
+    catch (err) {
+        // Corrupt freelist: DDL fails with "malformed" but VACUUM can rebuild.
+        // Pre-migration backup failures are already pre-DDL and must propagate
+        // instead of being masked by VACUUM recovery (see #2519).
+        if (shouldAttemptVacuumRecovery(fileBacked, err)) {
+            try {
+                adapter.exec("VACUUM");
+                initSchema(adapter, fileBacked, path);
+                process.stderr.write("gsd-db: recovered corrupt database via VACUUM\n");
+            }
+            catch (retryErr) {
+                _dbOpenState.recordError("vacuum-recovery", retryErr);
+                try {
+                    adapter.close();
+                }
+                catch (e) {
+                    logWarning("db", `close after VACUUM failed: ${e.message}`);
+                }
+                throw retryErr;
+            }
+        }
+        else {
+            _dbOpenState.recordError("initSchema", err);
+            try {
+                adapter.close();
+            }
+            catch (e) {
+                logWarning("db", `close after initSchema failed: ${e.message}`);
+            }
+            throw err;
+        }
+    }
+    // Commit fallback provider switch only after open + schema both succeeded.
+    if (fallbackOpen)
+        providerLoader.commitFallback(fallbackOpen);
+    currentDb = adapter;
+    currentPath = path;
+    currentPid = process.pid;
+    if (!_exitHandlerRegistered) {
+        _exitHandlerRegistered = true;
+        process.on("exit", () => { try {
+            closeDatabase();
+        }
+        catch (e) {
+            logWarning("db", `exit handler close failed: ${e.message}`);
+        } });
+    }
+    return true;
+}
+function shouldAttemptVacuumRecovery(fileBacked, err) {
+    return fileBacked && err instanceof Error && err.message.includes("malformed") && !isMigrationBackupError(err);
+}
+export const _shouldAttemptVacuumRecoveryForTest = shouldAttemptVacuumRecovery;
+export function closeDatabase() {
+    if (currentDb) {
+        try {
+            currentDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+        }
+        catch (e) {
+            logWarning("db", `WAL checkpoint failed: ${e.message}`);
+        }
+        try {
+            // Incremental vacuum to reclaim space without blocking
+            currentDb.exec('PRAGMA incremental_vacuum(64)');
+        }
+        catch (e) {
+            logWarning("db", `incremental vacuum failed: ${e.message}`);
+        }
+        try {
+            currentDb.close();
+        }
+        catch (e) {
+            logWarning("db", `database close failed: ${e.message}`);
+        }
+        // If this connection was workspace-tracked, evict it from the cache so
+        // subsequent openDatabaseByWorkspace() calls re-open rather than reactivate
+        // a closed adapter.
+        if (_currentIdentityKey !== null) {
+            _dbCache.delete(_currentIdentityKey);
+            _currentIdentityKey = null;
+        }
+        currentDb = null;
+        currentPath = null;
+        currentPid = 0;
+    }
+    // Reset session-scoped state unconditionally so stale error info from a
+    // failed open doesn't persist into the next open attempt or status check.
+    _dbOpenState.reset();
+}
+/**
+ * Open an isolated database connection that does NOT touch the process-wide
+ * `currentDb` singleton. Intended for background observers (e.g. the parallel
+ * monitor overlay) that must read a database without displacing an active
+ * workflow session connection.
+ *
+ * The caller MUST call `adapter.close()` when done. Schema migrations are NOT
+ * run — the database must already exist and be fully migrated by the primary
+ * connection. Returns null if the connection cannot be opened.
+ */
+export function openIsolatedDatabase(path) {
+    try {
+        const rawDb = providerLoader.openRaw(path);
+        if (!rawDb)
+            return null;
+        const adapter = createDbAdapter(rawDb);
+        // Minimal pragmas for a short-lived read-only observer connection.
+        // WAL mode is already set file-wide by the primary connection; repeating
+        // it here is a no-op on an existing WAL file and safe to issue.
+        adapter.exec("PRAGMA journal_mode=WAL");
+        adapter.exec("PRAGMA busy_timeout = 5000");
+        return adapter;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Re-open the active database connection from disk.
+ *
+ * Auto-mode can observe artifacts written by a workflow server running in a
+ * different process before its long-lived singleton has re-synchronized. The
+ * recovery path uses this to force the next state derivation to read from the
+ * current on-disk database instead of continuing with a possibly stale handle.
+ */
+export function refreshOpenDatabaseFromDisk() {
+    if (!currentDb || !currentPath)
+        return false;
+    if (currentPath === ":memory:")
+        return false;
+    const dbPath = currentPath;
+    const identityKey = _currentIdentityKey;
+    try {
+        closeDatabase();
+        const opened = openDatabase(dbPath);
+        if (opened && identityKey && currentDb) {
+            _dbCache.set(identityKey, { dbPath, db: currentDb });
+            _currentIdentityKey = identityKey;
+        }
+        return opened;
+    }
+    catch (e) {
+        logWarning("db", `database refresh failed: ${e.message}`);
+        return false;
+    }
+}
+/** Run a full VACUUM — call sparingly (e.g. after milestone completion). */
+export function vacuumDatabase() {
+    if (!currentDb)
+        return;
+    try {
+        currentDb.exec('VACUUM');
+    }
+    catch (e) {
+        logWarning("db", `VACUUM failed: ${e.message}`);
+    }
+}
+/** Flush WAL into gsd.db so `git add .gsd/gsd.db` stages current state — safe while DB is open. */
+export function checkpointDatabase() {
+    if (!currentDb)
+        return;
+    try {
+        currentDb.exec('PRAGMA wal_checkpoint(TRUNCATE)');
+    }
+    catch (e) {
+        logWarning("db", `WAL checkpoint failed: ${e.message}`);
+    }
+}
+/**
+ * Copy the live database file to `.gsd/backups/<label>-<timestamp>.db` so a
+ * destructive operation (e.g. recover, which clears the hierarchy tables) is
+ * reversible. Checkpoints the WAL first so the snapshot is complete. Returns
+ * the backup path, or null if no DB is open or the copy failed.
+ */
+export function backupDatabaseSnapshot(label) {
+    if (!currentPath)
+        return null;
+    try {
+        checkpointDatabase();
+        const backupsDir = join(dirname(currentPath), "backups");
+        mkdirSync(backupsDir, { recursive: true });
+        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+        const dest = join(backupsDir, `${label}-${stamp}.db`);
+        copyFileSync(currentPath, dest);
+        return dest;
+    }
+    catch (e) {
+        logWarning("db", `database snapshot failed: ${e.message}`);
+        return null;
+    }
+}
+const _transactionRunner = createDbTransactionRunner();
+function createTransactionControls(db) {
+    return {
+        begin: () => db.exec("BEGIN"),
+        beginRead: () => db.exec("BEGIN DEFERRED"),
+        beginImmediate: () => db.exec("BEGIN IMMEDIATE"),
+        commit: () => db.exec("COMMIT"),
+        rollback: () => db.exec("ROLLBACK"),
+    };
+}
+/**
+ * Whether the current call is running inside an active SQLite transaction.
+ * Statement-time recovery paths (e.g. VACUUM retry on a malformed memory
+ * store) MUST gate on this — SQLite refuses VACUUM inside a transaction
+ * and would mask the original error with a secondary "cannot VACUUM" throw.
+ */
+export function isInTransaction() {
+    return _transactionRunner.isInTransaction();
+}
+export function transaction(fn) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    return _transactionRunner.transaction(createTransactionControls(currentDb), fn);
+}
+/**
+ * Run a BEGIN IMMEDIATE write transaction for operations that need SQLite's
+ * reserved writer lock before issuing updates. Re-entrant like transaction():
+ * nested calls run inside the outer transaction without a nested BEGIN.
+ */
+export function immediateTransaction(fn) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    return _transactionRunner.immediateTransaction(createTransactionControls(currentDb), fn);
+}
+/**
+ * Wrap a block of reads in a DEFERRED transaction so that all SELECTs observe
+ * a consistent snapshot of the DB even if a concurrent writer commits between
+ * them. Use this for multi-query read flows (e.g. tool executors that query
+ * milestone + slices + counts and want one snapshot). Re-entrant — if already
+ * inside a transaction, runs fn() without starting a nested one.
+ */
+export function readTransaction(fn) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    return _transactionRunner.readTransaction(createTransactionControls(currentDb), fn, (rollbackErr) => {
+        // A failed ROLLBACK after a failed read is a split-brain signal —
+        // the transaction is in an indeterminate state. Surface it via the
+        // logger instead of swallowing it.
+        logError("db", "snapshotState ROLLBACK failed", {
+            error: rollbackErr.message,
+        });
+    });
+}
+export function getDbOwnerPid() {
+    return currentPid;
+}
+export function getDbPath() {
+    return currentPath;
+}
+export function _getAdapter() {
+    return currentDb;
+}
+export function _resetProvider() {
+    providerLoader.reset();
+}
+/**
+ * The active engine handle, or throw if no database is open. Use in write
+ * wrappers — replaces the historical `if (!currentDb) throw ...; currentDb.X`
+ * guard with `getDb().X`.
+ */
+export function getDb() {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    return currentDb;
+}
+/**
+ * The active engine handle or null. Use in read wrappers that no-op (return
+ * [] / null) when no database is open.
+ */
+export function getDbOrNull() {
+    return currentDb;
+}