gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

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

@@ -0,0 +1,735 @@
+// GSD Database Abstraction Layer
+// Provides a SQLite database with provider fallback chain:
+//   node:sqlite (built-in) → better-sqlite3 (npm) → null (unavailable)
+//
+// Exposes a unified sync API for decisions and requirements storage.
+// Schema is initialized on first open with WAL mode for file-backed DBs.
+import { createRequire } from "node:module";
+import { existsSync, copyFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { GSDError, GSD_STALE_STATE } from "./errors.js";
+// Create a require function for loading native modules in ESM context
+const _require = createRequire(import.meta.url);
+let providerName = null;
+let providerModule = null;
+let loadAttempted = false;
+/**
+ * Suppress the ExperimentalWarning for SQLite from node:sqlite.
+ * Must be called before require('node:sqlite').
+ */
+function suppressSqliteWarning() {
+    const origEmit = process.emit;
+    // @ts-expect-error — overriding process.emit with filtered version
+    process.emit = function (event, ...args) {
+        if (event === "warning" &&
+            args[0] &&
+            typeof args[0] === "object" &&
+            "name" in args[0] &&
+            args[0].name === "ExperimentalWarning" &&
+            "message" in args[0] &&
+            typeof args[0].message === "string" &&
+            args[0].message.includes("SQLite")) {
+            return false;
+        }
+        return origEmit.apply(process, [event, ...args]);
+    };
+}
+function loadProvider() {
+    if (loadAttempted)
+        return;
+    loadAttempted = true;
+    // Try node:sqlite first
+    try {
+        suppressSqliteWarning();
+        const mod = _require("node:sqlite");
+        if (mod.DatabaseSync) {
+            providerModule = mod;
+            providerName = "node:sqlite";
+            return;
+        }
+    }
+    catch {
+        // node:sqlite not available
+    }
+    // Try better-sqlite3
+    try {
+        const mod = _require("better-sqlite3");
+        if (typeof mod === "function" || (mod && mod.default)) {
+            providerModule = mod.default || mod;
+            providerName = "better-sqlite3";
+            return;
+        }
+    }
+    catch {
+        // better-sqlite3 not available
+    }
+    process.stderr.write("gsd-db: No SQLite provider available (tried node:sqlite, better-sqlite3)\n");
+}
+// ─── Database Adapter ──────────────────────────────────────────────────────
+/**
+ * Normalize a row from node:sqlite (null-prototype) to a plain object.
+ */
+function normalizeRow(row) {
+    if (row == null)
+        return undefined;
+    if (Object.getPrototypeOf(row) === null) {
+        return { ...row };
+    }
+    return row;
+}
+function normalizeRows(rows) {
+    return rows.map((r) => normalizeRow(r));
+}
+function createAdapter(rawDb) {
+    const db = rawDb;
+    return {
+        exec(sql) {
+            db.exec(sql);
+        },
+        prepare(sql) {
+            const stmt = db.prepare(sql);
+            return {
+                run(...params) {
+                    return stmt.run(...params);
+                },
+                get(...params) {
+                    return normalizeRow(stmt.get(...params));
+                },
+                all(...params) {
+                    return normalizeRows(stmt.all(...params));
+                },
+            };
+        },
+        close() {
+            db.close();
+        },
+    };
+}
+function openRawDb(path) {
+    loadProvider();
+    if (!providerModule || !providerName)
+        return null;
+    if (providerName === "node:sqlite") {
+        const { DatabaseSync } = providerModule;
+        return new DatabaseSync(path);
+    }
+    // better-sqlite3
+    const Database = providerModule;
+    return new Database(path);
+}
+// ─── Schema ────────────────────────────────────────────────────────────────
+const SCHEMA_VERSION = 3;
+function initSchema(db, fileBacked) {
+    // WAL mode for file-backed databases (must be outside transaction)
+    if (fileBacked) {
+        db.exec("PRAGMA journal_mode=WAL");
+    }
+    db.exec("BEGIN");
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS schema_version (
+        version INTEGER NOT NULL,
+        applied_at TEXT NOT NULL
+      )
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS decisions (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        id TEXT NOT NULL UNIQUE,
+        when_context TEXT NOT NULL DEFAULT '',
+        scope TEXT NOT NULL DEFAULT '',
+        decision TEXT NOT NULL DEFAULT '',
+        choice TEXT NOT NULL DEFAULT '',
+        rationale TEXT NOT NULL DEFAULT '',
+        revisable TEXT NOT NULL DEFAULT '',
+        superseded_by TEXT DEFAULT NULL
+      )
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS requirements (
+        id TEXT PRIMARY KEY,
+        class TEXT NOT NULL DEFAULT '',
+        status TEXT NOT NULL DEFAULT '',
+        description TEXT NOT NULL DEFAULT '',
+        why TEXT NOT NULL DEFAULT '',
+        source TEXT NOT NULL DEFAULT '',
+        primary_owner TEXT NOT NULL DEFAULT '',
+        supporting_slices TEXT NOT NULL DEFAULT '',
+        validation TEXT NOT NULL DEFAULT '',
+        notes TEXT NOT NULL DEFAULT '',
+        full_content TEXT NOT NULL DEFAULT '',
+        superseded_by TEXT DEFAULT NULL
+      )
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS artifacts (
+        path TEXT PRIMARY KEY,
+        artifact_type TEXT NOT NULL DEFAULT '',
+        milestone_id TEXT DEFAULT NULL,
+        slice_id TEXT DEFAULT NULL,
+        task_id TEXT DEFAULT NULL,
+        full_content TEXT NOT NULL DEFAULT '',
+        imported_at TEXT NOT NULL DEFAULT ''
+      )
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS memories (
+        seq INTEGER PRIMARY KEY AUTOINCREMENT,
+        id TEXT NOT NULL UNIQUE,
+        category TEXT NOT NULL,
+        content TEXT NOT NULL,
+        confidence REAL NOT NULL DEFAULT 0.8,
+        source_unit_type TEXT,
+        source_unit_id TEXT,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL,
+        superseded_by TEXT DEFAULT NULL,
+        hit_count INTEGER NOT NULL DEFAULT 0
+      )
+    `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS memory_processed_units (
+        unit_key TEXT PRIMARY KEY,
+        activity_file TEXT,
+        processed_at TEXT NOT NULL
+      )
+    `);
+        db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
+        // Views — DROP + CREATE since CREATE VIEW IF NOT EXISTS doesn't update definitions
+        db.exec(`CREATE VIEW IF NOT EXISTS active_decisions AS SELECT * FROM decisions WHERE superseded_by IS NULL`);
+        db.exec(`CREATE VIEW IF NOT EXISTS active_requirements AS SELECT * FROM requirements WHERE superseded_by IS NULL`);
+        db.exec(`CREATE VIEW IF NOT EXISTS active_memories AS SELECT * FROM memories WHERE superseded_by IS NULL`);
+        // Insert schema version if not already present
+        const existing = db
+            .prepare("SELECT count(*) as cnt FROM schema_version")
+            .get();
+        if (existing && existing["cnt"] === 0) {
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({
+                ":version": SCHEMA_VERSION,
+                ":applied_at": new Date().toISOString(),
+            });
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+    // Run incremental migrations for existing databases
+    migrateSchema(db);
+}
+/**
+ * Incremental schema migration. Reads current version from schema_version table
+ * and applies DDL for each version step up to SCHEMA_VERSION.
+ */
+function migrateSchema(db) {
+    const row = db.prepare("SELECT MAX(version) as v FROM schema_version").get();
+    const currentVersion = row ? row["v"] : 0;
+    if (currentVersion >= SCHEMA_VERSION)
+        return;
+    db.exec("BEGIN");
+    try {
+        // v1 → v2: add artifacts table
+        if (currentVersion < 2) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS artifacts (
+          path TEXT PRIMARY KEY,
+          artifact_type TEXT NOT NULL DEFAULT '',
+          milestone_id TEXT DEFAULT NULL,
+          slice_id TEXT DEFAULT NULL,
+          task_id TEXT DEFAULT NULL,
+          full_content TEXT NOT NULL DEFAULT '',
+          imported_at TEXT NOT NULL DEFAULT ''
+        )
+      `);
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({ ":version": 2, ":applied_at": new Date().toISOString() });
+        }
+        // v2 → v3: add memories + memory_processed_units tables
+        if (currentVersion < 3) {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS memories (
+          seq INTEGER PRIMARY KEY AUTOINCREMENT,
+          id TEXT NOT NULL UNIQUE,
+          category TEXT NOT NULL,
+          content TEXT NOT NULL,
+          confidence REAL NOT NULL DEFAULT 0.8,
+          source_unit_type TEXT,
+          source_unit_id TEXT,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL,
+          superseded_by TEXT DEFAULT NULL,
+          hit_count INTEGER NOT NULL DEFAULT 0
+        )
+      `);
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS memory_processed_units (
+          unit_key TEXT PRIMARY KEY,
+          activity_file TEXT,
+          processed_at TEXT NOT NULL
+        )
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_memories_active ON memories(superseded_by)");
+            db.exec("DROP VIEW IF EXISTS active_memories");
+            db.exec("CREATE VIEW active_memories AS SELECT * FROM memories WHERE superseded_by IS NULL");
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (:version, :applied_at)").run({ ":version": 3, ":applied_at": new Date().toISOString() });
+        }
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        db.exec("ROLLBACK");
+        throw err;
+    }
+}
+// ─── Module State ──────────────────────────────────────────────────────────
+let currentDb = null;
+let currentPath = null;
+/** PID that opened the current connection — used for diagnostic logging. */
+let currentPid = 0;
+// ─── Public API ────────────────────────────────────────────────────────────
+/**
+ * Returns which SQLite provider is available, or null if none.
+ */
+export function getDbProvider() {
+    loadProvider();
+    return providerName;
+}
+/**
+ * Returns true if a database is currently open and usable.
+ */
+export function isDbAvailable() {
+    return currentDb !== null;
+}
+/**
+ * Opens (or creates) a SQLite database at the given path.
+ * Initializes schema if needed. Sets WAL mode for file-backed DBs.
+ * Returns true on success, false if no provider is available.
+ */
+export function openDatabase(path) {
+    // Close existing if different path
+    if (currentDb && currentPath !== path) {
+        closeDatabase();
+    }
+    if (currentDb && currentPath === path) {
+        return true; // already open
+    }
+    const rawDb = openRawDb(path);
+    if (!rawDb)
+        return false;
+    const adapter = createAdapter(rawDb);
+    const fileBacked = path !== ":memory:";
+    try {
+        initSchema(adapter, fileBacked);
+    }
+    catch (err) {
+        try {
+            adapter.close();
+        }
+        catch {
+            /* swallow */
+        }
+        throw err;
+    }
+    currentDb = adapter;
+    currentPath = path;
+    currentPid = process.pid;
+    return true;
+}
+/**
+ * Closes the current database connection.
+ */
+export function closeDatabase() {
+    if (currentDb) {
+        try {
+            currentDb.close();
+        }
+        catch {
+            // swallow close errors
+        }
+        currentDb = null;
+        currentPath = null;
+        currentPid = 0;
+    }
+}
+/**
+ * Runs a function inside a transaction. Rolls back on error.
+ */
+export function transaction(fn) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb.exec("BEGIN");
+    try {
+        const result = fn();
+        currentDb.exec("COMMIT");
+        return result;
+    }
+    catch (err) {
+        currentDb.exec("ROLLBACK");
+        throw err;
+    }
+}
+// ─── Decision Wrappers ────────────────────────────────────────────────────
+/**
+ * Insert a decision. The `seq` field is auto-generated.
+ */
+export function insertDecision(d) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb
+        .prepare(`INSERT INTO decisions (id, when_context, scope, decision, choice, rationale, revisable, superseded_by)
+     VALUES (:id, :when_context, :scope, :decision, :choice, :rationale, :revisable, :superseded_by)`)
+        .run({
+        ":id": d.id,
+        ":when_context": d.when_context,
+        ":scope": d.scope,
+        ":decision": d.decision,
+        ":choice": d.choice,
+        ":rationale": d.rationale,
+        ":revisable": d.revisable,
+        ":superseded_by": d.superseded_by,
+    });
+}
+/**
+ * Get a decision by its ID (e.g. "D001"). Returns null if not found.
+ */
+export function getDecisionById(id) {
+    if (!currentDb)
+        return null;
+    const row = currentDb.prepare("SELECT * FROM decisions WHERE id = ?").get(id);
+    if (!row)
+        return null;
+    return {
+        seq: row["seq"],
+        id: row["id"],
+        when_context: row["when_context"],
+        scope: row["scope"],
+        decision: row["decision"],
+        choice: row["choice"],
+        rationale: row["rationale"],
+        revisable: row["revisable"],
+        superseded_by: row["superseded_by"] ?? null,
+    };
+}
+/**
+ * Get all active (non-superseded) decisions.
+ */
+export function getActiveDecisions() {
+    if (!currentDb)
+        return [];
+    const rows = currentDb.prepare("SELECT * FROM active_decisions").all();
+    return rows.map((row) => ({
+        seq: row["seq"],
+        id: row["id"],
+        when_context: row["when_context"],
+        scope: row["scope"],
+        decision: row["decision"],
+        choice: row["choice"],
+        rationale: row["rationale"],
+        revisable: row["revisable"],
+        superseded_by: null,
+    }));
+}
+// ─── Requirement Wrappers ─────────────────────────────────────────────────
+/**
+ * Insert a requirement.
+ */
+export function insertRequirement(r) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb
+        .prepare(`INSERT INTO requirements (id, class, status, description, why, source, primary_owner, supporting_slices, validation, notes, full_content, superseded_by)
+     VALUES (:id, :class, :status, :description, :why, :source, :primary_owner, :supporting_slices, :validation, :notes, :full_content, :superseded_by)`)
+        .run({
+        ":id": r.id,
+        ":class": r.class,
+        ":status": r.status,
+        ":description": r.description,
+        ":why": r.why,
+        ":source": r.source,
+        ":primary_owner": r.primary_owner,
+        ":supporting_slices": r.supporting_slices,
+        ":validation": r.validation,
+        ":notes": r.notes,
+        ":full_content": r.full_content,
+        ":superseded_by": r.superseded_by,
+    });
+}
+/**
+ * Get a requirement by its ID (e.g. "R001"). Returns null if not found.
+ */
+export function getRequirementById(id) {
+    if (!currentDb)
+        return null;
+    const row = currentDb
+        .prepare("SELECT * FROM requirements WHERE id = ?")
+        .get(id);
+    if (!row)
+        return null;
+    return {
+        id: row["id"],
+        class: row["class"],
+        status: row["status"],
+        description: row["description"],
+        why: row["why"],
+        source: row["source"],
+        primary_owner: row["primary_owner"],
+        supporting_slices: row["supporting_slices"],
+        validation: row["validation"],
+        notes: row["notes"],
+        full_content: row["full_content"],
+        superseded_by: row["superseded_by"] ?? null,
+    };
+}
+/**
+ * Get all active (non-superseded) requirements.
+ */
+export function getActiveRequirements() {
+    if (!currentDb)
+        return [];
+    const rows = currentDb.prepare("SELECT * FROM active_requirements").all();
+    return rows.map((row) => ({
+        id: row["id"],
+        class: row["class"],
+        status: row["status"],
+        description: row["description"],
+        why: row["why"],
+        source: row["source"],
+        primary_owner: row["primary_owner"],
+        supporting_slices: row["supporting_slices"],
+        validation: row["validation"],
+        notes: row["notes"],
+        full_content: row["full_content"],
+        superseded_by: null,
+    }));
+}
+/**
+ * Returns the PID of the process that opened the current DB connection.
+ * Returns 0 if no connection is open.
+ */
+export function getDbOwnerPid() {
+    return currentPid;
+}
+/**
+ * Returns the path of the currently open database, or null if none.
+ */
+export function getDbPath() {
+    return currentPath;
+}
+// ─── Internal Access (for testing) ─────────────────────────────────────────
+/**
+ * Get the raw adapter for direct queries (testing only).
+ */
+export function _getAdapter() {
+    return currentDb;
+}
+/**
+ * Reset provider state (testing only — allows re-detection).
+ */
+export function _resetProvider() {
+    loadAttempted = false;
+    providerModule = null;
+    providerName = null;
+}
+// ─── Upsert Wrappers (for idempotent import) ─────────────────────────────
+/**
+ * Insert or replace a decision. Uses the `id` UNIQUE constraint for idempotency.
+ */
+export function upsertDecision(d) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb
+        .prepare(`INSERT OR REPLACE INTO decisions (id, when_context, scope, decision, choice, rationale, revisable, superseded_by)
+     VALUES (:id, :when_context, :scope, :decision, :choice, :rationale, :revisable, :superseded_by)`)
+        .run({
+        ":id": d.id,
+        ":when_context": d.when_context,
+        ":scope": d.scope,
+        ":decision": d.decision,
+        ":choice": d.choice,
+        ":rationale": d.rationale,
+        ":revisable": d.revisable,
+        ":superseded_by": d.superseded_by ?? null,
+    });
+}
+/**
+ * Insert or replace a requirement. Uses the `id` PK for idempotency.
+ */
+export function upsertRequirement(r) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb
+        .prepare(`INSERT OR REPLACE INTO requirements (id, class, status, description, why, source, primary_owner, supporting_slices, validation, notes, full_content, superseded_by)
+     VALUES (:id, :class, :status, :description, :why, :source, :primary_owner, :supporting_slices, :validation, :notes, :full_content, :superseded_by)`)
+        .run({
+        ":id": r.id,
+        ":class": r.class,
+        ":status": r.status,
+        ":description": r.description,
+        ":why": r.why,
+        ":source": r.source,
+        ":primary_owner": r.primary_owner,
+        ":supporting_slices": r.supporting_slices,
+        ":validation": r.validation,
+        ":notes": r.notes,
+        ":full_content": r.full_content,
+        ":superseded_by": r.superseded_by ?? null,
+    });
+}
+/**
+ * Insert or replace an artifact. Uses the `path` PK for idempotency.
+ */
+/**
+ * Delete all rows from the artifacts table.
+ * The artifacts table is a read cache — clearing it forces the next
+ * deriveState() to fall through to disk reads (native Rust batch parse).
+ * Safe to call when no database is open (no-op).
+ */
+export function clearArtifacts() {
+    if (!currentDb)
+        return;
+    try {
+        currentDb.exec("DELETE FROM artifacts");
+    }
+    catch {
+        // Clearing a cache should never be fatal
+    }
+}
+export function insertArtifact(a) {
+    if (!currentDb)
+        throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
+    currentDb
+        .prepare(`INSERT OR REPLACE INTO artifacts (path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at)
+     VALUES (:path, :artifact_type, :milestone_id, :slice_id, :task_id, :full_content, :imported_at)`)
+        .run({
+        ":path": a.path,
+        ":artifact_type": a.artifact_type,
+        ":milestone_id": a.milestone_id,
+        ":slice_id": a.slice_id,
+        ":task_id": a.task_id,
+        ":full_content": a.full_content,
+        ":imported_at": new Date().toISOString(),
+    });
+}
+// ─── Worktree DB Helpers ──────────────────────────────────────────────────
+export function copyWorktreeDb(srcDbPath, destDbPath) {
+    try {
+        if (!existsSync(srcDbPath))
+            return false;
+        const destDir = dirname(destDbPath);
+        mkdirSync(destDir, { recursive: true });
+        copyFileSync(srcDbPath, destDbPath);
+        return true;
+    }
+    catch (err) {
+        process.stderr.write(`gsd-db: failed to copy DB to worktree: ${err.message}\n`);
+        return false;
+    }
+}
+export function reconcileWorktreeDb(mainDbPath, worktreeDbPath) {
+    const zero = {
+        decisions: 0,
+        requirements: 0,
+        artifacts: 0,
+        conflicts: [],
+    };
+    if (!existsSync(worktreeDbPath))
+        return zero;
+    if (worktreeDbPath.includes("'")) {
+        process.stderr.write(`gsd-db: worktree DB reconciliation failed: path contains unsafe characters\n`);
+        return zero;
+    }
+    if (!currentDb) {
+        const opened = openDatabase(mainDbPath);
+        if (!opened) {
+            process.stderr.write(`gsd-db: worktree DB reconciliation failed: cannot open main DB\n`);
+            return zero;
+        }
+    }
+    const adapter = currentDb;
+    const conflicts = [];
+    try {
+        adapter.exec(`ATTACH DATABASE '${worktreeDbPath}' AS wt`);
+        try {
+            const decConf = adapter
+                .prepare(`SELECT m.id FROM decisions m INNER JOIN wt.decisions w ON m.id = w.id WHERE m.decision != w.decision OR m.choice != w.choice OR m.rationale != w.rationale OR m.superseded_by IS NOT w.superseded_by`)
+                .all();
+            for (const row of decConf)
+                conflicts.push(`decision ${row["id"]}: modified in both`);
+            const reqConf = adapter
+                .prepare(`SELECT m.id FROM requirements m INNER JOIN wt.requirements w ON m.id = w.id WHERE m.description != w.description OR m.status != w.status OR m.notes != w.notes OR m.superseded_by IS NOT w.superseded_by`)
+                .all();
+            for (const row of reqConf)
+                conflicts.push(`requirement ${row["id"]}: modified in both`);
+            const merged = { decisions: 0, requirements: 0, artifacts: 0 };
+            adapter.exec("BEGIN");
+            try {
+                const dR = adapter
+                    .prepare(`
+          INSERT OR REPLACE INTO decisions (
+            id, when_context, scope, decision, choice, rationale, revisable, superseded_by
+          )
+          SELECT
+            id, when_context, scope, decision, choice, rationale, revisable, superseded_by
+          FROM wt.decisions
+        `)
+                    .run();
+                merged.decisions =
+                    typeof dR === "object" && dR !== null
+                        ? (dR.changes ?? 0)
+                        : 0;
+                const rR = adapter
+                    .prepare(`
+          INSERT OR REPLACE INTO requirements (
+            id, class, status, description, why, source, primary_owner,
+            supporting_slices, validation, notes, full_content, superseded_by
+          )
+          SELECT
+            id, class, status, description, why, source, primary_owner,
+            supporting_slices, validation, notes, full_content, superseded_by
+          FROM wt.requirements
+        `)
+                    .run();
+                merged.requirements =
+                    typeof rR === "object" && rR !== null
+                        ? (rR.changes ?? 0)
+                        : 0;
+                const aR = adapter
+                    .prepare(`
+          INSERT OR REPLACE INTO artifacts (
+            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
+          )
+          SELECT
+            path, artifact_type, milestone_id, slice_id, task_id, full_content, imported_at
+          FROM wt.artifacts
+        `)
+                    .run();
+                merged.artifacts =
+                    typeof aR === "object" && aR !== null
+                        ? (aR.changes ?? 0)
+                        : 0;
+                adapter.exec("COMMIT");
+            }
+            catch (txErr) {
+                try {
+                    adapter.exec("ROLLBACK");
+                }
+                catch {
+                    /* best-effort */
+                }
+                throw txErr;
+            }
+            return { ...merged, conflicts };
+        }
+        finally {
+            try {
+                adapter.exec("DETACH DATABASE wt");
+            }
+            catch {
+                /* best-effort */
+            }
+        }
+    }
+    catch (err) {
+        process.stderr.write(`gsd-db: worktree DB reconciliation failed: ${err.message}\n`);
+        return { ...zero, conflicts };
+    }
+}