@pcircle/footprint 1.5.0 → 1.7.0

package/dist/src/lib/storage/database.js

@@ -1,15 +1,66 @@
 /* global Buffer, crypto */
 import Database from "better-sqlite3";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getArtifactSearchableText, parseArtifactMetadata, } from "../session-artifacts.js";
+import { traceSyncOperation } from "../observability.js";
 import { createSchema } from "./schema.js";
 function escapeLikePattern(pattern) {
     return pattern.replace(/[%_\\]/g, "\\$&");
 }
+function normalizeWorkspaceKeyForMatching(value) {
+    const resolved = path.resolve(value);
+    try {
+        return fs.realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+function matchesWorkspaceKey(session, workspaceKey) {
+    const normalizedWorkspaceKey = normalizeWorkspaceKeyForMatching(workspaceKey);
+    return (normalizeWorkspaceKeyForMatching(session.projectRoot) ===
+        normalizedWorkspaceKey ||
+        normalizeWorkspaceKeyForMatching(session.cwd) === normalizedWorkspaceKey);
+}
+/**
+ * Append LIMIT/OFFSET clause to SQL query string.
+ * Mutates the params array by pushing limit/offset values.
+ * @returns The query string with pagination appended.
+ */
+function appendPaginationClause(query, params, limit, offset) {
+    const off = offset ?? 0;
+    if (limit !== undefined) {
+        query += " LIMIT ?";
+        params.push(limit);
+        if (off > 0) {
+            query += " OFFSET ?";
+            params.push(off);
+        }
+    }
+    else if (off > 0) {
+        query += " LIMIT -1 OFFSET ?";
+        params.push(off);
+    }
+    return query;
+}
+function formatDbError(action, error) {
+    return new Error(`Failed to ${action}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+}
+const TREND_FAILED_OUTCOME_PATTERN = /\b(?:fail|failed|error|timeout|timed-out|interrupted|non-zero)\b/i;
+const TREND_SUCCEEDED_OUTCOME_PATTERN = /\b(?:success|succeeded|passed|completed|captured|ok)\b/i;
+const SESSION_HISTORY_CACHE_VERSION_KEY = "session_history_cache_version";
+const SESSION_TREND_CACHE_VERSION_KEY = "session_trend_cache_version";
+const CURRENT_SESSION_HISTORY_CACHE_VERSION = 1;
+const CURRENT_SESSION_TREND_CACHE_VERSION = 1;
 /**
  * Evidence database with CRUD operations
  * Manages encrypted evidence storage with SQLite backend
  */
 export class EvidenceDatabase {
     db;
+    sessionHistoryCacheBackfilled = false;
+    sessionTrendAttemptsBackfilled = false;
     /**
      * Creates or opens an evidence database
      * @param dbPath - Path to SQLite database file
@@ -19,12 +70,101 @@ export class EvidenceDatabase {
         this.db = new Database(dbPath);
         try {
             createSchema(this.db);
+            this.initializeMaterializedCaches();
         }
         catch (error) {
             // Clean up database connection on any initialization failure
             this.db.close();
-            throw new Error(`Failed to initialize database: ${error instanceof Error ? error.message : String(error)}`);
+            throw formatDbError("initialize database", error);
+        }
+    }
+    getMetadataValue(key) {
+        const row = this.db
+            .prepare(`
+          SELECT value
+          FROM metadata
+          WHERE key = ?
+        `)
+            .get(key);
+        return row?.value ?? null;
+    }
+    getMetadataVersion(key) {
+        const value = this.getMetadataValue(key);
+        const parsed = Number.parseInt(value ?? "", 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+    }
+    setMetadataValue(key, value) {
+        this.db
+            .prepare(`
+          INSERT INTO metadata (key, value)
+          VALUES (?, ?)
+          ON CONFLICT(key) DO UPDATE SET value = excluded.value
+        `)
+            .run(key, value);
+    }
+    getAllSessionIds() {
+        return this.db
+            .prepare(`
+            SELECT id
+            FROM sessions
+            ORDER BY startedAt ASC, id ASC
+          `)
+            .all().map((row) => row.id);
+    }
+    initializeMaterializedCaches() {
+        if (this.getMetadataVersion(SESSION_HISTORY_CACHE_VERSION_KEY) <
+            CURRENT_SESSION_HISTORY_CACHE_VERSION) {
+            this.rebuildAllSessionHistoryCaches();
+            this.setMetadataValue(SESSION_HISTORY_CACHE_VERSION_KEY, String(CURRENT_SESSION_HISTORY_CACHE_VERSION));
+            this.sessionHistoryCacheBackfilled = true;
+        }
+        else {
+            this.sessionHistoryCacheBackfilled = false;
+            this.ensureSessionHistoryCacheBackfilled();
+        }
+        if (this.getMetadataVersion(SESSION_TREND_CACHE_VERSION_KEY) <
+            CURRENT_SESSION_TREND_CACHE_VERSION) {
+            this.rebuildAllSessionTrendAttempts();
+            this.setMetadataValue(SESSION_TREND_CACHE_VERSION_KEY, String(CURRENT_SESSION_TREND_CACHE_VERSION));
+            this.sessionTrendAttemptsBackfilled = true;
+        }
+        else {
+            this.sessionTrendAttemptsBackfilled = false;
+            this.ensureSessionTrendAttemptsBackfilled();
+        }
+    }
+    dbOp(action, fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            throw formatDbError(action, error);
+        }
+    }
+    resolveActiveContextIdOrThrow(contextId) {
+        let currentId = contextId.trim();
+        const visited = new Set();
+        while (currentId) {
+            if (visited.has(currentId)) {
+                throw new Error(`Context merge loop detected for ${contextId}`);
+            }
+            visited.add(currentId);
+            const row = this.db
+                .prepare(`
+            SELECT id, status, mergedIntoContextId
+            FROM contexts
+            WHERE id = ?
+          `)
+                .get(currentId);
+            if (!row) {
+                throw new Error(`Context not found: ${contextId}`);
+            }
+            if (row.status !== "merged" || !row.mergedIntoContextId) {
+                return row.id;
+            }
+            currentId = row.mergedIntoContextId;
         }
+        throw new Error(`Context not found: ${contextId}`);
     }
     /**
      * Creates a new evidence record
@@ -34,7 +174,7 @@ export class EvidenceDatabase {
     create(evidence) {
         const id = crypto.randomUUID();
         const now = new Date().toISOString();
-        try {
+        return this.dbOp("create evidence", () => {
             const stmt = this.db.prepare(`
         INSERT INTO evidences (
           id, timestamp, conversationId, llmProvider,
@@ -44,10 +184,7 @@ export class EvidenceDatabase {
       `);
             stmt.run(id, evidence.timestamp, evidence.conversationId, evidence.llmProvider, Buffer.from(evidence.encryptedContent), Buffer.from(evidence.nonce), evidence.contentHash, evidence.messageCount, evidence.gitCommitHash, evidence.gitTimestamp, evidence.tags, now, now);
             return id;
-        }
-        catch (error) {
-            throw new Error(`Failed to create evidence: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Finds evidence by ID
@@ -55,7 +192,7 @@ export class EvidenceDatabase {
      * @returns Evidence or null if not found
      */
     findById(id) {
-        try {
+        return this.dbOp("find evidence by ID", () => {
             const stmt = this.db.prepare(`
         SELECT * FROM evidences WHERE id = ?
       `);
@@ -64,11 +201,7 @@ export class EvidenceDatabase {
                 return null;
             }
             return this.rowToEvidence(row);
-        }
-        catch (error) {
-            // Don't swallow database errors - re-throw with context
-            throw new Error(`Failed to find evidence by ID: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Finds all evidences for a conversation
@@ -76,7 +209,7 @@ export class EvidenceDatabase {
      * @returns Array of evidences (empty if none found)
      */
     findByConversationId(conversationId) {
-        try {
+        return this.dbOp("find evidences by conversationId", () => {
             const stmt = this.db.prepare(`
         SELECT * FROM evidences
         WHERE conversationId = ?
@@ -84,10 +217,7 @@ export class EvidenceDatabase {
       `);
             const rows = stmt.all(conversationId);
             return rows.map((row) => this.rowToEvidence(row));
-        }
-        catch (error) {
-            throw new Error(`Failed to find evidences by conversationId: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Lists evidences with pagination
@@ -95,31 +225,1407 @@ export class EvidenceDatabase {
      * @returns Array of evidences
      */
     list(options) {
+        return this.dbOp("list evidences", () => {
+            const params = [];
+            const query = appendPaginationClause("SELECT * FROM evidences ORDER BY timestamp DESC", params, options?.limit, options?.offset);
+            const stmt = this.db.prepare(query);
+            const rows = stmt.all(...params);
+            return rows.map((row) => this.rowToEvidence(row));
+        });
+    }
+    static joinSearchParts(parts) {
+        return parts
+            .map((part) => part.trim())
+            .filter(Boolean)
+            .join("\n");
+    }
+    static appendSearchPart(existing, addition) {
+        const normalizedAddition = addition.trim();
+        if (!normalizedAddition) {
+            return existing;
+        }
+        return existing.trim()
+            ? `${existing}\n${normalizedAddition}`
+            : normalizedAddition;
+    }
+    static normalizeTrendOutcome(value) {
+        if (!value) {
+            return "other";
+        }
+        if (TREND_FAILED_OUTCOME_PATTERN.test(value)) {
+            return "failed";
+        }
+        if (TREND_SUCCEEDED_OUTCOME_PATTERN.test(value)) {
+            return "succeeded";
+        }
+        return "other";
+    }
+    buildArtifactHistoryCache(artifacts) {
+        const issueKeys = new Set();
+        const text = EvidenceDatabase.joinSearchParts(artifacts.flatMap((artifact) => {
+            const metadata = parseArtifactMetadata(artifact.metadata);
+            if (metadata.issueKey) {
+                issueKeys.add(metadata.issueKey);
+            }
+            return getArtifactSearchableText(artifact);
+        }));
+        return {
+            text,
+            issueKeys: Array.from(issueKeys).sort(),
+        };
+    }
+    buildNarrativeHistoryCache(narratives) {
+        return EvidenceDatabase.joinSearchParts(narratives.map((narrative) => narrative.content));
+    }
+    buildDecisionHistoryCache(decisions) {
+        return EvidenceDatabase.joinSearchParts(decisions.map((decision) => decision.summary));
+    }
+    ensureSessionHistoryCacheRow(sessionId) {
+        this.db
+            .prepare(`
+          INSERT INTO session_history_cache (
+            sessionId, titleText, metadataText, messagesText,
+            artifactsText, narrativesText, decisionsText, updatedAt
+          )
+          SELECT
+            id,
+            COALESCE(title, ''),
+            COALESCE(metadata, ''),
+            '',
+            '',
+            '',
+            '',
+            ?
+          FROM sessions
+          WHERE id = ?
+          ON CONFLICT(sessionId) DO NOTHING
+        `)
+            .run(new Date().toISOString(), sessionId);
+    }
+    updateSessionHistoryCache(sessionId, updates) {
+        this.ensureSessionHistoryCacheRow(sessionId);
+        const current = this.db
+            .prepare(`
+          SELECT * FROM session_history_cache
+          WHERE sessionId = ?
+        `)
+            .get(sessionId);
+        if (!current) {
+            return;
+        }
+        const next = {
+            ...current,
+            ...updates,
+            sessionId,
+            updatedAt: new Date().toISOString(),
+        };
+        this.db
+            .prepare(`
+          UPDATE session_history_cache
+          SET titleText = ?,
+              metadataText = ?,
+              messagesText = ?,
+              artifactsText = ?,
+              narrativesText = ?,
+              decisionsText = ?,
+              updatedAt = ?
+          WHERE sessionId = ?
+        `)
+            .run(next.titleText, next.metadataText, next.messagesText, next.artifactsText, next.narrativesText, next.decisionsText, next.updatedAt, sessionId);
+    }
+    replaceSessionIssueKeys(sessionId, issueKeys) {
+        this.db
+            .prepare(`DELETE FROM session_issue_keys WHERE sessionId = ?`)
+            .run(sessionId);
+        const insertIssueKey = this.db.prepare(`
+        INSERT INTO session_issue_keys (sessionId, issueKey)
+        VALUES (?, ?)
+      `);
+        for (const issueKey of issueKeys) {
+            insertIssueKey.run(sessionId, issueKey);
+        }
+    }
+    rebuildSessionHistoryCache(sessionId) {
+        const session = this.findSessionById(sessionId);
+        if (!session) {
+            return;
+        }
+        const messagesText = EvidenceDatabase.joinSearchParts(this.getSessionMessages(sessionId).map((message) => message.content));
+        const artifacts = this.getSessionArtifacts(sessionId);
+        const artifactCache = this.buildArtifactHistoryCache(artifacts);
+        const narrativesText = this.buildNarrativeHistoryCache(this.getSessionNarratives(sessionId));
+        const decisionsText = this.buildDecisionHistoryCache(this.getSessionDecisions(sessionId));
+        this.updateSessionHistoryCache(sessionId, {
+            titleText: session.title ?? "",
+            metadataText: session.metadata ?? "",
+            messagesText,
+            artifactsText: artifactCache.text,
+            narrativesText,
+            decisionsText,
+        });
+        this.replaceSessionIssueKeys(sessionId, artifactCache.issueKeys);
+    }
+    ensureSessionHistoryCacheBackfilled() {
+        if (this.sessionHistoryCacheBackfilled) {
+            return;
+        }
+        const missingRows = this.db
+            .prepare(`
+          SELECT s.id
+          FROM sessions s
+          LEFT JOIN session_history_cache cache ON cache.sessionId = s.id
+          WHERE cache.sessionId IS NULL
+          ORDER BY s.startedAt ASC, s.id ASC
+        `)
+            .all();
+        for (const row of missingRows) {
+            this.rebuildSessionHistoryCache(row.id);
+        }
+        this.sessionHistoryCacheBackfilled = true;
+    }
+    rebuildAllSessionHistoryCaches() {
+        for (const sessionId of this.getAllSessionIds()) {
+            this.rebuildSessionHistoryCache(sessionId);
+        }
+    }
+    fetchTrendSeenAtByEventIds(sessionId, eventIds) {
+        if (eventIds.length === 0) {
+            return new Map();
+        }
+        const placeholders = eventIds.map(() => "?").join(", ");
+        const rows = this.db
+            .prepare(`
+          SELECT id, COALESCE(endedAt, startedAt) as seenAt
+          FROM timeline_events
+          WHERE sessionId = ? AND id IN (${placeholders})
+        `)
+            .all(sessionId, ...eventIds);
+        return new Map(rows.map((row) => [row.id, row.seenAt]));
+    }
+    buildSessionTrendAttempts(sessionId, artifacts) {
+        const eventIds = [
+            ...new Set(artifacts
+                .map((artifact) => artifact.eventId)
+                .filter((eventId) => Boolean(eventId))),
+        ];
+        const seenAtByEventId = this.fetchTrendSeenAtByEventIds(sessionId, eventIds);
+        return artifacts.flatMap((artifact) => {
+            const metadata = parseArtifactMetadata(artifact.metadata);
+            const eventType = typeof metadata.details.eventType === "string"
+                ? metadata.details.eventType
+                : null;
+            const outcome = metadata.outcome ?? metadata.status ?? "captured";
+            const outcomeCategory = EvidenceDatabase.normalizeTrendOutcome(outcome);
+            if (!artifact.eventId || !metadata.issueKey) {
+                return [];
+            }
+            if (!eventType ||
+                (!eventType.startsWith("command.") && !eventType.startsWith("test."))) {
+                return [];
+            }
+            if (outcomeCategory === "other") {
+                return [];
+            }
+            return [
+                {
+                    artifactId: artifact.id,
+                    sessionId,
+                    issueKey: metadata.issueKey,
+                    issueLabel: metadata.issueLabel ?? metadata.issueKey,
+                    kind: metadata.intent ?? metadata.category,
+                    issueFamilyKey: metadata.issueFamilyKey,
+                    issueFamilyLabel: metadata.issueFamilyLabel ??
+                        metadata.issueFamilyKey ??
+                        metadata.issueLabel,
+                    outcome,
+                    outcomeCategory,
+                    seenAt: seenAtByEventId.get(artifact.eventId) ?? artifact.createdAt,
+                    createdAt: artifact.createdAt,
+                },
+            ];
+        });
+    }
+    markSessionTrendAttemptsFresh(sessionId) {
+        this.db
+            .prepare(`
+          INSERT INTO session_trend_cache_state (sessionId, updatedAt)
+          VALUES (?, ?)
+          ON CONFLICT(sessionId) DO UPDATE SET updatedAt = excluded.updatedAt
+        `)
+            .run(sessionId, new Date().toISOString());
+    }
+    replaceSessionTrendAttempts(sessionId, artifacts) {
+        this.db
+            .prepare(`DELETE FROM session_trend_attempts WHERE sessionId = ?`)
+            .run(sessionId);
+        const attempts = this.buildSessionTrendAttempts(sessionId, artifacts);
+        if (attempts.length === 0) {
+            this.markSessionTrendAttemptsFresh(sessionId);
+            return;
+        }
+        const insertAttempt = this.db.prepare(`
+        INSERT INTO session_trend_attempts (
+          artifactId, sessionId, issueKey, issueLabel, kind,
+          issueFamilyKey, issueFamilyLabel, outcome, outcomeCategory,
+          seenAt, createdAt
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+        for (const attempt of attempts) {
+            insertAttempt.run(attempt.artifactId, attempt.sessionId, attempt.issueKey, attempt.issueLabel, attempt.kind, attempt.issueFamilyKey, attempt.issueFamilyLabel, attempt.outcome, attempt.outcomeCategory, attempt.seenAt, attempt.createdAt);
+        }
+        this.markSessionTrendAttemptsFresh(sessionId);
+    }
+    insertSessionTrendAttempts(sessionId, artifacts) {
+        const attempts = this.buildSessionTrendAttempts(sessionId, artifacts);
+        if (attempts.length === 0) {
+            this.markSessionTrendAttemptsFresh(sessionId);
+            return;
+        }
+        const insertAttempt = this.db.prepare(`
+        INSERT INTO session_trend_attempts (
+          artifactId, sessionId, issueKey, issueLabel, kind,
+          issueFamilyKey, issueFamilyLabel, outcome, outcomeCategory,
+          seenAt, createdAt
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(artifactId) DO UPDATE SET
+          sessionId = excluded.sessionId,
+          issueKey = excluded.issueKey,
+          issueLabel = excluded.issueLabel,
+          kind = excluded.kind,
+          issueFamilyKey = excluded.issueFamilyKey,
+          issueFamilyLabel = excluded.issueFamilyLabel,
+          outcome = excluded.outcome,
+          outcomeCategory = excluded.outcomeCategory,
+          seenAt = excluded.seenAt,
+          createdAt = excluded.createdAt
+      `);
+        for (const attempt of attempts) {
+            insertAttempt.run(attempt.artifactId, attempt.sessionId, attempt.issueKey, attempt.issueLabel, attempt.kind, attempt.issueFamilyKey, attempt.issueFamilyLabel, attempt.outcome, attempt.outcomeCategory, attempt.seenAt, attempt.createdAt);
+        }
+        this.markSessionTrendAttemptsFresh(sessionId);
+    }
+    rebuildSessionTrendAttempts(sessionId) {
+        const session = this.findSessionById(sessionId);
+        if (!session) {
+            return;
+        }
+        this.replaceSessionTrendAttempts(sessionId, this.getSessionArtifacts(sessionId));
+    }
+    ensureSessionTrendAttemptsBackfilled() {
+        if (this.sessionTrendAttemptsBackfilled) {
+            return;
+        }
+        const missingRows = this.db
+            .prepare(`
+          SELECT s.id
+          FROM sessions s
+          LEFT JOIN session_trend_cache_state state ON state.sessionId = s.id
+          WHERE state.sessionId IS NULL
+          ORDER BY s.startedAt ASC, s.id ASC
+        `)
+            .all();
+        for (const row of missingRows) {
+            this.rebuildSessionTrendAttempts(row.id);
+        }
+        this.sessionTrendAttemptsBackfilled = true;
+    }
+    rebuildAllSessionTrendAttempts() {
+        for (const sessionId of this.getAllSessionIds()) {
+            this.rebuildSessionTrendAttempts(sessionId);
+        }
+    }
+    querySessionsByHistory(options) {
+        return traceSyncOperation("db.query-sessions-by-history", {
+            host: options.host,
+            status: options.status,
+            hasQuery: Boolean(options.query?.trim()),
+            issueKey: options.issueKey?.trim() || undefined,
+            sessionIds: options.sessionIds?.length ?? 0,
+            limit: options.limit,
+            offset: options.offset,
+        }, () => this.dbOp("query sessions by history", () => {
+            this.ensureSessionHistoryCacheBackfilled();
+            const conditions = [];
+            const params = [];
+            if (options.host) {
+                conditions.push(`s.host = ?`);
+                params.push(options.host);
+            }
+            if (options.status) {
+                conditions.push(`s.status = ?`);
+                params.push(options.status);
+            }
+            if (options.query && options.query.trim()) {
+                const pattern = `%${escapeLikePattern(options.query.trim())}%`;
+                conditions.push(`
+              (
+                cache.titleText LIKE ? ESCAPE '\\'
+                OR cache.metadataText LIKE ? ESCAPE '\\'
+                OR cache.messagesText LIKE ? ESCAPE '\\'
+                OR cache.artifactsText LIKE ? ESCAPE '\\'
+                OR cache.narrativesText LIKE ? ESCAPE '\\'
+                OR cache.decisionsText LIKE ? ESCAPE '\\'
+              )
+            `);
+                params.push(pattern, pattern, pattern, pattern, pattern, pattern);
+            }
+            if (options.issueKey && options.issueKey.trim()) {
+                conditions.push(`
+              EXISTS (
+                SELECT 1
+                FROM session_issue_keys issue_keys
+                WHERE issue_keys.sessionId = s.id
+                  AND issue_keys.issueKey = ?
+              )
+            `);
+                params.push(options.issueKey.trim());
+            }
+            if (options.sessionIds && options.sessionIds.length > 0) {
+                const normalizedIds = options.sessionIds
+                    .map((sessionId) => sessionId.trim())
+                    .filter(Boolean);
+                if (normalizedIds.length === 0) {
+                    return {
+                        sessions: [],
+                        total: 0,
+                    };
+                }
+                conditions.push(`s.id IN (${normalizedIds.map(() => "?").join(", ")})`);
+                params.push(...normalizedIds);
+            }
+            const whereSql = conditions.length
+                ? `WHERE ${conditions.join(" AND ")}`
+                : "";
+            const fromSql = `
+            FROM sessions s
+            LEFT JOIN session_history_cache cache ON cache.sessionId = s.id
+            ${whereSql}
+          `;
+            const total = this.db
+                .prepare(`SELECT COUNT(*) as total ${fromSql}`)
+                .get(...params)?.total ?? 0;
+            let query = `
+            SELECT s.*
+            ${fromSql}
+            ORDER BY s.startedAt DESC, s.id DESC
+          `;
+            const pageParams = [...params];
+            query = appendPaginationClause(query, pageParams, options.limit, options.offset);
+            const rows = this.db
+                .prepare(query)
+                .all(...pageParams);
+            return {
+                sessions: rows.map((row) => this.rowToSession(row)),
+                total,
+            };
+        }));
+    }
+    querySessionTrendAttempts(options) {
+        return traceSyncOperation("db.query-session-trend-attempts", {
+            host: options?.host,
+            status: options?.status,
+            sessionIds: options?.sessionIds?.length ?? 0,
+        }, () => this.dbOp("query session trend attempts", () => {
+            this.ensureSessionTrendAttemptsBackfilled();
+            const conditions = [];
+            const params = [];
+            if (options?.host) {
+                conditions.push(`s.host = ?`);
+                params.push(options.host);
+            }
+            if (options?.status) {
+                conditions.push(`s.status = ?`);
+                params.push(options.status);
+            }
+            if (options?.sessionIds && options.sessionIds.length > 0) {
+                const normalizedIds = options.sessionIds
+                    .map((sessionId) => sessionId.trim())
+                    .filter(Boolean);
+                if (normalizedIds.length === 0) {
+                    return [];
+                }
+                conditions.push(`ta.sessionId IN (${normalizedIds.map(() => "?").join(", ")})`);
+                params.push(...normalizedIds);
+            }
+            const whereSql = conditions.length
+                ? `WHERE ${conditions.join(" AND ")}`
+                : "";
+            return this.db
+                .prepare(`
+                SELECT
+                  ta.*,
+                  s.host,
+                  s.status,
+                  s.cwd,
+                  s.startedAt,
+                  s.endedAt,
+                  s.title
+                FROM session_trend_attempts ta
+                INNER JOIN sessions s ON s.id = ta.sessionId
+                ${whereSql}
+                ORDER BY ta.seenAt DESC, ta.artifactId DESC
+              `)
+                .all(...params);
+        }));
+    }
+    querySessionTrendContextAttempts(sessionId) {
+        return this.dbOp("query session trend context attempts", () => {
+            const normalizedSessionId = sessionId.trim();
+            if (!normalizedSessionId) {
+                return [];
+            }
+            this.ensureSessionTrendAttemptsBackfilled();
+            return this.db
+                .prepare(`
+            WITH target_issue_keys AS (
+              SELECT DISTINCT issueKey
+              FROM session_trend_attempts
+              WHERE sessionId = ?
+            )
+            SELECT
+              ta.*,
+              s.host,
+              s.status,
+              s.cwd,
+              s.startedAt,
+              s.endedAt,
+              s.title
+            FROM session_trend_attempts ta
+            INNER JOIN target_issue_keys tik ON tik.issueKey = ta.issueKey
+            INNER JOIN sessions s ON s.id = ta.sessionId
+            ORDER BY ta.issueKey ASC, ta.seenAt DESC, ta.artifactId DESC
+          `)
+                .all(normalizedSessionId);
+        });
+    }
+    getSessionFollowUpMessages(sessionIds, options) {
+        return traceSyncOperation("db.get-session-follow-up-messages", {
+            sessionIds: sessionIds.length,
+            limit: options?.limit,
+            offset: options?.offset,
+        }, () => this.dbOp("get session follow-up messages", () => {
+            const normalizedIds = sessionIds
+                .map((sessionId) => sessionId.trim())
+                .filter(Boolean);
+            if (normalizedIds.length === 0) {
+                return [];
+            }
+            const params = [...normalizedIds];
+            let query = `
+            SELECT id, sessionId, content, capturedAt, seq
+            FROM messages
+            WHERE sessionId IN (${normalizedIds.map(() => "?").join(", ")})
+              AND (
+                content LIKE '%?%'
+                OR lower(content) LIKE 'next:%'
+              )
+            ORDER BY capturedAt DESC, sessionId DESC, seq DESC, id DESC
+          `;
+            query = appendPaginationClause(query, params, options?.limit, options?.offset);
+            const rows = this.db
+                .prepare(query)
+                .all(...params);
+            return rows.map((row) => ({
+                sessionId: row.sessionId,
+                content: row.content,
+                capturedAt: row.capturedAt,
+            }));
+        }));
+    }
+    createSession(session) {
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString();
+        return this.dbOp("create session", () => {
+            const stmt = this.db.prepare(`
+        INSERT INTO sessions (
+          id, host, projectRoot, cwd, title, status,
+          startedAt, endedAt, metadata, createdAt, updatedAt
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            stmt.run(id, session.host, session.projectRoot, session.cwd, session.title, session.status, session.startedAt, session.endedAt, session.metadata, now, now);
+            this.db
+                .prepare(`
+            INSERT INTO session_history_cache (
+              sessionId, titleText, metadataText, messagesText,
+              artifactsText, narrativesText, decisionsText, updatedAt
+            ) VALUES (?, ?, ?, '', '', '', '', ?)
+          `)
+                .run(id, session.title ?? "", session.metadata ?? "", now);
+            this.markSessionTrendAttemptsFresh(id);
+            return id;
+        });
+    }
+    appendMessage(message) {
+        const id = crypto.randomUUID();
+        return this.dbOp("append message", () => {
+            const stmt = this.db.prepare(`
+        INSERT INTO messages (
+          id, sessionId, seq, role, source, content, capturedAt, metadata
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            stmt.run(id, message.sessionId, message.seq, message.role, message.source, message.content, message.capturedAt, message.metadata);
+            const currentCache = this.db
+                .prepare(`
+            SELECT messagesText FROM session_history_cache
+            WHERE sessionId = ?
+          `)
+                .get(message.sessionId);
+            this.updateSessionHistoryCache(message.sessionId, {
+                messagesText: EvidenceDatabase.appendSearchPart(currentCache?.messagesText ?? "", message.content),
+            });
+            return id;
+        });
+    }
+    appendTimelineEvent(event) {
+        const id = crypto.randomUUID();
+        return this.dbOp("append timeline event", () => {
+            const stmt = this.db.prepare(`
+        INSERT INTO timeline_events (
+          id, sessionId, seq, eventType, eventSubType, source,
+          summary, payload, startedAt, endedAt, status, relatedMessageId
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `);
+            stmt.run(id, event.sessionId, event.seq, event.eventType, event.eventSubType, event.source, event.summary, event.payload, event.startedAt, event.endedAt, event.status, event.relatedMessageId);
+            return id;
+        });
+    }
+    updateSessionTitle(id, title) {
+        this.dbOp("update session title", () => {
+            const stmt = this.db.prepare(`
+        UPDATE sessions
+        SET title = ?,
+            updatedAt = ?
+        WHERE id = ?
+      `);
+            const result = stmt.run(title, new Date().toISOString(), id);
+            if (result.changes === 0) {
+                throw new Error(`Session with id ${id} not found`);
+            }
+            this.updateSessionHistoryCache(id, {
+                titleText: title,
+            });
+        });
+    }
+    finalizeSession(id, updates) {
+        this.dbOp("finalize session", () => {
+            const stmt = this.db.prepare(`
+        UPDATE sessions
+        SET status = ?,
+            endedAt = ?,
+            title = COALESCE(?, title),
+            updatedAt = ?
+        WHERE id = ?
+      `);
+            const result = stmt.run(updates.status, updates.endedAt, updates.title, new Date().toISOString(), id);
+            if (result.changes === 0) {
+                throw new Error(`Session with id ${id} not found`);
+            }
+        });
+    }
+    findSessionById(id) {
+        return this.dbOp("find session by ID", () => {
+            const row = this.db
+                .prepare(`SELECT * FROM sessions WHERE id = ?`)
+                .get(id);
+            return row ? this.rowToSession(row) : null;
+        });
+    }
+    listSessions(options) {
+        return this.dbOp("list sessions", () => {
+            const params = [];
+            const query = appendPaginationClause("SELECT * FROM sessions ORDER BY startedAt DESC", params, options?.limit, options?.offset);
+            const rows = this.db.prepare(query).all(...params);
+            return rows.map((row) => this.rowToSession(row));
+        });
+    }
+    createContext(context) {
+        const id = crypto.randomUUID();
+        const now = new Date().toISOString();
+        return this.dbOp("create context", () => {
+            this.db
+                .prepare(`
+            INSERT INTO contexts (
+              id, label, workspaceKey, status, mergedIntoContextId,
+              metadata, createdAt, updatedAt
+            ) VALUES (?, ?, ?, 'active', NULL, ?, ?, ?)
+          `)
+                .run(id, context.label, context.workspaceKey, context.metadata ?? null, now, now);
+            return {
+                id,
+                label: context.label,
+                workspaceKey: context.workspaceKey,
+                status: "active",
+                mergedIntoContextId: null,
+                metadata: context.metadata ?? null,
+                createdAt: now,
+                updatedAt: now,
+            };
+        });
+    }
+    findContextById(id) {
+        return this.dbOp("find context by ID", () => {
+            const row = this.db
+                .prepare(`SELECT * FROM contexts WHERE id = ?`)
+                .get(id);
+            return row ? this.rowToContext(row) : null;
+        });
+    }
+    resolveContextById(id) {
         try {
-            const limit = options?.limit;
-            const offset = options?.offset ?? 0;
-            let query = "SELECT * FROM evidences ORDER BY timestamp DESC";
+            const activeId = this.resolveActiveContextIdOrThrow(id);
+            return this.findContextById(activeId);
+        }
+        catch {
+            return null;
+        }
+    }
+    listContexts(options) {
+        return this.dbOp("list contexts", () => {
+            const conditions = [];
+            const params = [];
+            if (options?.workspaceKey) {
+                conditions.push("workspaceKey = ?");
+                params.push(options.workspaceKey);
+            }
+            if (options?.status) {
+                conditions.push("status = ?");
+                params.push(options.status);
+            }
+            else if (!options?.includeMerged) {
+                conditions.push("status = 'active'");
+            }
+            const whereSql = conditions.length
+                ? `WHERE ${conditions.join(" AND ")}`
+                : "";
+            const query = appendPaginationClause(`
+        SELECT *
+        FROM contexts
+        ${whereSql}
+        ORDER BY updatedAt DESC, createdAt DESC, id DESC
+      `, params, options?.limit, options?.offset);
+            const rows = this.db.prepare(query).all(...params);
+            return rows.map((row) => this.rowToContext(row));
+        });
+    }
+    getContextCount(options) {
+        return this.dbOp("count contexts", () => {
+            const conditions = [];
+            const params = [];
+            if (options?.workspaceKey) {
+                conditions.push("workspaceKey = ?");
+                params.push(options.workspaceKey);
+            }
+            if (options?.status) {
+                conditions.push("status = ?");
+                params.push(options.status);
+            }
+            else if (!options?.includeMerged) {
+                conditions.push("status = 'active'");
+            }
+            const whereSql = conditions.length
+                ? `WHERE ${conditions.join(" AND ")}`
+                : "";
+            const row = this.db
+                .prepare(`SELECT COUNT(*) as count FROM contexts ${whereSql}`)
+                .get(...params);
+            return row?.count ?? 0;
+        });
+    }
+    listSessionsForContext(contextId) {
+        return this.dbOp("list sessions for context", () => {
+            const activeId = this.resolveActiveContextIdOrThrow(contextId);
+            const rows = this.db
+                .prepare(`
+            SELECT s.*
+            FROM context_session_links links
+            INNER JOIN sessions s ON s.id = links.sessionId
+            WHERE links.contextId = ?
+            ORDER BY s.startedAt ASC, s.id ASC
+          `)
+                .all(activeId);
+            return rows.map((row) => this.rowToSession(row));
+        });
+    }
+    listUnlinkedSessions(options) {
+        return this.dbOp("list unlinked sessions", () => {
+            const conditions = [
+                "NOT EXISTS (SELECT 1 FROM context_session_links links WHERE links.sessionId = s.id)",
+            ];
             const params = [];
-            if (limit !== undefined) {
-                query += " LIMIT ?";
-                params.push(limit);
-                if (offset > 0) {
-                    query += " OFFSET ?";
-                    params.push(offset);
+            let query = `
+        SELECT s.*
+        FROM sessions s
+        WHERE ${conditions.join(" AND ")}
+        ORDER BY s.startedAt ASC, s.id ASC
+      `;
+            if (!options?.workspaceKey) {
+                query = appendPaginationClause(query, params, options?.limit, options?.offset);
+            }
+            const rows = this.db.prepare(query).all(...params);
+            let sessions = rows.map((row) => this.rowToSession(row));
+            if (options?.workspaceKey) {
+                sessions = sessions.filter((session) => matchesWorkspaceKey(session, options.workspaceKey));
+                const off = options.offset ?? 0;
+                if (off > 0) {
+                    sessions = sessions.slice(off);
+                }
+                if (options.limit !== undefined) {
+                    sessions = sessions.slice(0, options.limit);
                 }
             }
-            else if (offset > 0) {
-                query += " LIMIT -1 OFFSET ?";
-                params.push(offset);
+            return sessions;
+        });
+    }
+    findContextLinkForSession(sessionId) {
+        return this.dbOp("find context link for session", () => {
+            const row = this.db
+                .prepare(`
+            SELECT *
+            FROM context_session_links
+            WHERE sessionId = ?
+          `)
+                .get(sessionId);
+            return row ? this.rowToContextSessionLink(row) : null;
+        });
+    }
+    listContextSessionLinks(contextId) {
+        return this.dbOp("list context session links", () => {
+            const activeId = this.resolveActiveContextIdOrThrow(contextId);
+            const rows = this.db
+                .prepare(`
+            SELECT *
+            FROM context_session_links
+            WHERE contextId = ?
+            ORDER BY updatedAt DESC, sessionId DESC
+          `)
+                .all(activeId);
+            return rows.map((row) => this.rowToContextSessionLink(row));
+        });
+    }
+    assignSessionToContext(input) {
+        const now = new Date().toISOString();
+        return this.dbOp("assign session to context", () => {
+            const session = this.findSessionById(input.sessionId);
+            if (!session) {
+                throw new Error(`Session not found: ${input.sessionId}`);
+            }
+            const activeContextId = this.resolveActiveContextIdOrThrow(input.contextId);
+            this.db
+                .prepare(`
+            INSERT INTO context_session_links (
+              sessionId, contextId, linkSource, createdAt, updatedAt
+            ) VALUES (?, ?, ?, ?, ?)
+            ON CONFLICT(sessionId) DO UPDATE SET
+              contextId = excluded.contextId,
+              linkSource = excluded.linkSource,
+              updatedAt = excluded.updatedAt
+          `)
+                .run(input.sessionId, activeContextId, input.linkSource, now, now);
+            this.db
+                .prepare(`
+            DELETE FROM context_link_rejections
+            WHERE sessionId = ? AND contextId = ?
+          `)
+                .run(input.sessionId, activeContextId);
+            this.db
+                .prepare(`
+            UPDATE contexts
+            SET updatedAt = ?
+            WHERE id = ?
+          `)
+                .run(now, activeContextId);
+            return {
+                sessionId: input.sessionId,
+                contextId: activeContextId,
+                linkSource: input.linkSource,
+                createdAt: now,
+                updatedAt: now,
+            };
+        });
+    }
+    rejectContextForSession(sessionId, contextId) {
+        const now = new Date().toISOString();
+        return this.dbOp("reject context for session", () => {
+            if (!this.findSessionById(sessionId)) {
+                throw new Error(`Session not found: ${sessionId}`);
+            }
+            const activeContextId = this.resolveActiveContextIdOrThrow(contextId);
+            this.db
+                .prepare(`
+            INSERT INTO context_link_rejections (sessionId, contextId, createdAt)
+            VALUES (?, ?, ?)
+            ON CONFLICT(sessionId, contextId) DO NOTHING
+          `)
+                .run(sessionId, activeContextId, now);
+            return {
+                sessionId,
+                contextId: activeContextId,
+                createdAt: now,
+            };
+        });
+    }
+    listContextRejectionsForSession(sessionId) {
+        return this.dbOp("list context rejections", () => {
+            const rows = this.db
+                .prepare(`
+            SELECT *
+            FROM context_link_rejections
+            WHERE sessionId = ?
+            ORDER BY createdAt DESC, contextId DESC
+          `)
+                .all(sessionId);
+            return rows.map((row) => this.rowToContextLinkRejection(row));
+        });
+    }
+    setWorkspacePreferredContext(workspaceKey, contextId) {
+        const now = new Date().toISOString();
+        return this.dbOp("set preferred context", () => {
+            const activeContextId = this.resolveActiveContextIdOrThrow(contextId);
+            this.db
+                .prepare(`
+            INSERT INTO context_workspace_preferences (
+              workspaceKey, contextId, createdAt, updatedAt
+            ) VALUES (?, ?, ?, ?)
+            ON CONFLICT(workspaceKey) DO UPDATE SET
+              contextId = excluded.contextId,
+              updatedAt = excluded.updatedAt
+          `)
+                .run(workspaceKey, activeContextId, now, now);
+            return {
+                workspaceKey,
+                contextId: activeContextId,
+                createdAt: now,
+                updatedAt: now,
+            };
+        });
+    }
+    getWorkspacePreferredContext(workspaceKey) {
+        return this.dbOp("get preferred context", () => {
+            const row = this.db
+                .prepare(`
+            SELECT *
+            FROM context_workspace_preferences
+            WHERE workspaceKey = ?
+          `)
+                .get(workspaceKey);
+            if (!row) {
+                return null;
+            }
+            try {
+                const activeContextId = this.resolveActiveContextIdOrThrow(row.contextId);
+                if (activeContextId !== row.contextId) {
+                    const now = new Date().toISOString();
+                    this.db
+                        .prepare(`
+                UPDATE context_workspace_preferences
+                SET contextId = ?, updatedAt = ?
+                WHERE workspaceKey = ?
+              `)
+                        .run(activeContextId, now, workspaceKey);
+                    return this.rowToContextWorkspacePreference({
+                        ...row,
+                        contextId: activeContextId,
+                        updatedAt: now,
+                    });
+                }
+            }
+            catch {
+                return this.rowToContextWorkspacePreference(row);
+            }
+            return this.rowToContextWorkspacePreference(row);
+        });
+    }
+    mergeContexts(sourceContextId, targetContextId) {
+        this.dbOp("merge contexts", () => {
+            const sourceId = this.resolveActiveContextIdOrThrow(sourceContextId);
+            const targetId = this.resolveActiveContextIdOrThrow(targetContextId);
+            if (sourceId === targetId) {
+                throw new Error("Cannot merge a context into itself");
+            }
+            const now = new Date().toISOString();
+            const transaction = this.db.transaction(() => {
+                this.db
+                    .prepare(`
+              UPDATE context_session_links
+              SET contextId = ?, linkSource = 'merge', updatedAt = ?
+              WHERE contextId = ?
+            `)
+                    .run(targetId, now, sourceId);
+                this.db
+                    .prepare(`
+              UPDATE context_workspace_preferences
+              SET contextId = ?, updatedAt = ?
+              WHERE contextId = ?
+            `)
+                    .run(targetId, now, sourceId);
+                this.db
+                    .prepare(`
+              UPDATE contexts
+              SET status = 'merged',
+                  mergedIntoContextId = ?,
+                  updatedAt = ?
+              WHERE id = ?
+            `)
+                    .run(targetId, now, sourceId);
+                this.db
+                    .prepare(`
+              UPDATE contexts
+              SET updatedAt = ?
+              WHERE id = ?
+            `)
+                    .run(now, targetId);
+            });
+            transaction();
+        });
+    }
+    countSessionMessages(sessionId) {
+        return this.dbOp("count session messages", () => {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) as total FROM messages WHERE sessionId = ?`)
+                .get(sessionId);
+            return row?.total ?? 0;
+        });
+    }
+    getSessionMessageStats(sessionId) {
+        return this.dbOp("summarize session messages", () => {
+            const summaryRow = this.db
+                .prepare(`
+            SELECT
+              COUNT(*) as total,
+              COALESCE(SUM(CASE WHEN role = 'user' THEN 1 ELSE 0 END), 0) as userCount,
+              COALESCE(SUM(CASE WHEN role = 'assistant' THEN 1 ELSE 0 END), 0) as assistantCount,
+              COALESCE(SUM(CASE WHEN role = 'system' THEN 1 ELSE 0 END), 0) as systemCount,
+              MIN(capturedAt) as firstCapturedAt,
+              MAX(capturedAt) as lastCapturedAt
+            FROM messages
+            WHERE sessionId = ?
+          `)
+                .get(sessionId);
+            const previewRow = this.db
+                .prepare(`
+            SELECT content FROM messages
+            WHERE sessionId = ?
+            ORDER BY seq ASC, capturedAt ASC
+            LIMIT 1
+          `)
+                .get(sessionId);
+            return {
+                total: summaryRow?.total ?? 0,
+                byRole: {
+                    user: summaryRow?.userCount ?? 0,
+                    assistant: summaryRow?.assistantCount ?? 0,
+                    system: summaryRow?.systemCount ?? 0,
+                },
+                firstCapturedAt: summaryRow?.firstCapturedAt ?? null,
+                lastCapturedAt: summaryRow?.lastCapturedAt ?? null,
+                previewContent: previewRow?.content ?? null,
+            };
+        });
+    }
+    getSessionMessages(sessionId, options) {
+        return this.dbOp("get session messages", () => {
+            const params = [sessionId];
+            const query = appendPaginationClause("SELECT * FROM messages WHERE sessionId = ? ORDER BY seq ASC, capturedAt ASC", params, options?.limit, options?.offset);
+            const rows = this.db.prepare(query).all(...params);
+            return rows.map((row) => this.rowToMessage(row));
+        });
+    }
+    countSessionTimeline(sessionId) {
+        return this.dbOp("count session timeline", () => {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) as total FROM timeline_events WHERE sessionId = ?`)
+                .get(sessionId);
+            return row?.total ?? 0;
+        });
+    }
+    getSessionTimelineStats(sessionId) {
+        return this.dbOp("summarize session timeline", () => {
+            const summaryRow = this.db
+                .prepare(`
+            SELECT
+              COUNT(*) as total,
+              MIN(startedAt) as firstStartedAt,
+              MAX(COALESCE(endedAt, startedAt)) as lastEndedAt
+            FROM timeline_events
+            WHERE sessionId = ?
+          `)
+                .get(sessionId);
+            const eventTypeRows = this.db
+                .prepare(`
+            SELECT eventType FROM timeline_events
+            WHERE sessionId = ?
+            GROUP BY eventType
+            ORDER BY MIN(seq) ASC, MIN(startedAt) ASC
+          `)
+                .all(sessionId);
+            const statusRows = this.db
+                .prepare(`
+            SELECT status FROM timeline_events
+            WHERE sessionId = ? AND status IS NOT NULL
+            GROUP BY status
+            ORDER BY MIN(seq) ASC, MIN(startedAt) ASC
+          `)
+                .all(sessionId);
+            return {
+                total: summaryRow?.total ?? 0,
+                eventTypes: eventTypeRows.map((row) => row.eventType),
+                statuses: statusRows.map((row) => row.status),
+                firstStartedAt: summaryRow?.firstStartedAt ?? null,
+                lastEndedAt: summaryRow?.lastEndedAt ?? null,
+            };
+        });
+    }
+    getSessionTimeline(sessionId, options) {
+        return this.dbOp("get session timeline", () => {
+            const params = [sessionId];
+            const query = appendPaginationClause(`
+        SELECT * FROM timeline_events
+        WHERE sessionId = ?
+        ORDER BY seq ASC, startedAt ASC
+      `, params, options?.limit, options?.offset);
+            const rows = this.db.prepare(query).all(...params);
+            return rows.map((row) => this.rowToTimelineEvent(row));
+        });
+    }
+    createArtifact(artifact) {
+        const id = crypto.randomUUID();
+        const createdAt = new Date().toISOString();
+        return this.dbOp("create artifact", () => {
+            this.db
+                .prepare(`
+            INSERT INTO artifacts (
+              id, sessionId, eventId, artifactType, path, metadata, createdAt
+            ) VALUES (?, ?, ?, ?, ?, ?, ?)
+          `)
+                .run(id, artifact.sessionId, artifact.eventId, artifact.artifactType, artifact.path, artifact.metadata, createdAt);
+            const artifactRecord = {
+                id,
+                sessionId: artifact.sessionId,
+                eventId: artifact.eventId,
+                artifactType: artifact.artifactType,
+                path: artifact.path,
+                metadata: artifact.metadata,
+                createdAt,
+            };
+            const artifactCache = this.buildArtifactHistoryCache([artifactRecord]);
+            const currentCache = this.db
+                .prepare(`
+            SELECT artifactsText FROM session_history_cache
+            WHERE sessionId = ?
+          `)
+                .get(artifact.sessionId);
+            this.updateSessionHistoryCache(artifact.sessionId, {
+                artifactsText: EvidenceDatabase.appendSearchPart(currentCache?.artifactsText ?? "", artifactCache.text),
+            });
+            for (const issueKey of artifactCache.issueKeys) {
+                this.db
+                    .prepare(`
+              INSERT INTO session_issue_keys (sessionId, issueKey)
+              VALUES (?, ?)
+              ON CONFLICT(sessionId, issueKey) DO NOTHING
+            `)
+                    .run(artifact.sessionId, issueKey);
+            }
+            this.insertSessionTrendAttempts(artifact.sessionId, [artifactRecord]);
+            return artifactRecord;
+        });
+    }
+    replaceArtifactsForSession(sessionId, artifacts) {
+        return this.dbOp("replace artifacts", () => {
+            const transaction = this.db.transaction(() => {
+                this.db
+                    .prepare(`DELETE FROM artifacts WHERE sessionId = ?`)
+                    .run(sessionId);
+                const insertArtifact = this.db.prepare(`
+            INSERT INTO artifacts (
+              id, sessionId, eventId, artifactType, path, metadata, createdAt
+            ) VALUES (?, ?, ?, ?, ?, ?, ?)
+          `);
+                const createdArtifacts = artifacts.map((artifact) => {
+                    const id = crypto.randomUUID();
+                    const createdAt = new Date().toISOString();
+                    insertArtifact.run(id, sessionId, artifact.eventId, artifact.artifactType, artifact.path, artifact.metadata, createdAt);
+                    return {
+                        id,
+                        sessionId,
+                        eventId: artifact.eventId,
+                        artifactType: artifact.artifactType,
+                        path: artifact.path,
+                        metadata: artifact.metadata,
+                        createdAt,
+                    };
+                });
+                const artifactCache = this.buildArtifactHistoryCache(createdArtifacts);
+                this.updateSessionHistoryCache(sessionId, {
+                    artifactsText: artifactCache.text,
+                });
+                this.replaceSessionIssueKeys(sessionId, artifactCache.issueKeys);
+                this.replaceSessionTrendAttempts(sessionId, createdArtifacts);
+                return createdArtifacts;
+            });
+            return transaction();
+        });
+    }
+    countSessionArtifacts(sessionId, options) {
+        return this.dbOp("count session artifacts", () => {
+            const row = (options?.artifactType
+                ? this.db
+                    .prepare(`SELECT COUNT(*) as count FROM artifacts WHERE sessionId = ? AND artifactType = ?`)
+                    .get(sessionId, options.artifactType)
+                : this.db
+                    .prepare(`SELECT COUNT(*) as count FROM artifacts WHERE sessionId = ?`)
+                    .get(sessionId));
+            return row?.count ?? 0;
+        });
+    }
+    getSessionArtifactSummary(sessionId) {
+        return this.dbOp("summarize session artifacts", () => {
+            const row = this.db
+                .prepare(`
+            SELECT
+              COUNT(*) as total,
+              COALESCE(SUM(CASE WHEN artifactType = 'file-change' THEN 1 ELSE 0 END), 0) as fileChange,
+              COALESCE(SUM(CASE WHEN artifactType = 'command-output' THEN 1 ELSE 0 END), 0) as commandOutput,
+              COALESCE(SUM(CASE WHEN artifactType = 'test-result' THEN 1 ELSE 0 END), 0) as testResult,
+              COALESCE(SUM(CASE WHEN artifactType = 'git-commit' THEN 1 ELSE 0 END), 0) as gitCommit
+            FROM artifacts
+            WHERE sessionId = ?
+          `)
+                .get(sessionId);
+            return {
+                total: row?.total ?? 0,
+                byType: {
+                    fileChange: row?.fileChange ?? 0,
+                    commandOutput: row?.commandOutput ?? 0,
+                    testResult: row?.testResult ?? 0,
+                    gitCommit: row?.gitCommit ?? 0,
+                },
+            };
+        });
+    }
+    getSessionArtifacts(sessionId, options) {
+        return this.dbOp("get session artifacts", () => {
+            const conditions = ["sessionId = ?"];
+            const parameters = [sessionId];
+            if (options?.artifactType) {
+                conditions.push("artifactType = ?");
+                parameters.push(options.artifactType);
+            }
+            const query = appendPaginationClause(`SELECT * FROM artifacts WHERE ${conditions.join(" AND ")} ORDER BY createdAt ASC, id ASC`, parameters, options?.limit, options?.offset);
+            const rows = this.db.prepare(query).all(...parameters);
+            return rows.map((row) => this.rowToArtifact(row));
+        });
+    }
+    replaceDecisionsForSession(sessionId, decisions) {
+        return this.dbOp("replace decisions", () => {
+            const transaction = this.db.transaction(() => {
+                this.db
+                    .prepare(`DELETE FROM decisions WHERE sessionId = ?`)
+                    .run(sessionId);
+                const createdDecisions = decisions.map((decision) => {
+                    const id = crypto.randomUUID();
+                    const createdAt = new Date().toISOString();
+                    this.db
+                        .prepare(`
+                INSERT INTO decisions (
+                  id, sessionId, title, summary, rationale, status, sourceRefs, createdAt
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+              `)
+                        .run(id, sessionId, decision.title, decision.summary, decision.rationale, decision.status, decision.sourceRefs, createdAt);
+                    return {
+                        id,
+                        sessionId,
+                        title: decision.title,
+                        summary: decision.summary,
+                        rationale: decision.rationale,
+                        status: decision.status,
+                        sourceRefs: decision.sourceRefs,
+                        createdAt,
+                    };
+                });
+                this.updateSessionHistoryCache(sessionId, {
+                    decisionsText: this.buildDecisionHistoryCache(createdDecisions),
+                });
+                return createdDecisions;
+            });
+            return transaction();
+        });
+    }
+    countSessionDecisions(sessionId) {
+        return this.dbOp("count session decisions", () => {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) as count FROM decisions WHERE sessionId = ?`)
+                .get(sessionId);
+            return row?.count ?? 0;
+        });
+    }
+    getSessionDecisions(sessionId, options) {
+        return this.dbOp("get session decisions", () => {
+            const params = [sessionId];
+            const query = appendPaginationClause(`
+        SELECT * FROM decisions
+        WHERE sessionId = ?
+        ORDER BY createdAt ASC, id ASC
+      `, params, options?.limit, options?.offset);
+            const rows = this.db.prepare(query).all(...params);
+            return rows.map((row) => this.rowToDecision(row));
+        });
+    }
+    replaceNarrativesForSession(sessionId, narratives) {
+        return this.dbOp("replace narratives", () => {
+            const transaction = this.db.transaction(() => {
+                this.db
+                    .prepare(`DELETE FROM narratives WHERE sessionId = ?`)
+                    .run(sessionId);
+                const createdNarratives = narratives.map((narrative) => {
+                    const id = crypto.randomUUID();
+                    const now = new Date().toISOString();
+                    this.db
+                        .prepare(`
+                INSERT INTO narratives (
+                  id, sessionId, kind, content, sourceRefs, createdAt, updatedAt
+                ) VALUES (?, ?, ?, ?, ?, ?, ?)
+              `)
+                        .run(id, sessionId, narrative.kind, narrative.content, narrative.sourceRefs, now, now);
+                    return {
+                        id,
+                        sessionId,
+                        kind: narrative.kind,
+                        content: narrative.content,
+                        sourceRefs: narrative.sourceRefs,
+                        createdAt: now,
+                        updatedAt: now,
+                    };
+                });
+                this.updateSessionHistoryCache(sessionId, {
+                    narrativesText: this.buildNarrativeHistoryCache(createdNarratives),
+                });
+                return createdNarratives;
+            });
+            return transaction();
+        });
+    }
+    countSessionNarratives(sessionId, options) {
+        return this.dbOp("count session narratives", () => {
+            const row = (options?.kind
+                ? this.db
+                    .prepare(`SELECT COUNT(*) as count FROM narratives WHERE sessionId = ? AND kind = ?`)
+                    .get(sessionId, options.kind)
+                : this.db
+                    .prepare(`SELECT COUNT(*) as count FROM narratives WHERE sessionId = ?`)
+                    .get(sessionId));
+            return row?.count ?? 0;
+        });
+    }
+    getSessionNarratives(sessionId, options) {
+        return this.dbOp("get session narratives", () => {
+            const conditions = ["sessionId = ?"];
+            const params = [sessionId];
+            if (options?.kind) {
+                conditions.push("kind = ?");
+                params.push(options.kind);
+            }
+            let query = `
+            SELECT * FROM narratives
+            WHERE ${conditions.join(" AND ")}
+            ORDER BY CASE kind
+              WHEN 'journal' THEN 1
+              WHEN 'project-summary' THEN 2
+              WHEN 'handoff' THEN 3
+              ELSE 99
+            END, createdAt ASC, id ASC
+          `;
+            query = appendPaginationClause(query, params, options?.limit, options?.offset);
+            const rows = this.db.prepare(query).all(...params);
+            return rows.map((row) => this.rowToNarrative(row));
+        });
+    }
+    hasNarrativesForSession(sessionId) {
+        return this.dbOp("check session narratives", () => {
+            const row = this.db
+                .prepare(`SELECT EXISTS(SELECT 1 FROM narratives WHERE sessionId = ?) as present`)
+                .get(sessionId);
+            return Boolean(row?.present);
+        });
+    }
+    createIngestionRun(run) {
+        const id = crypto.randomUUID();
+        const startedAt = new Date().toISOString();
+        return this.dbOp("create ingestion run", () => {
+            this.db
+                .prepare(`
+            INSERT INTO ingestion_runs (
+              id, sessionId, stage, status, error, startedAt, endedAt
+            ) VALUES (?, ?, ?, ?, ?, ?, ?)
+          `)
+                .run(id, run.sessionId, run.stage, run.status, run.error ?? null, startedAt, null);
+            return {
+                id,
+                sessionId: run.sessionId,
+                stage: run.stage,
+                status: run.status,
+                error: run.error ?? null,
+                startedAt,
+                endedAt: null,
+            };
+        });
+    }
+    completeIngestionRun(id, status, error = null) {
+        try {
+            const endedAt = new Date().toISOString();
+            const result = this.db
+                .prepare(`
+            UPDATE ingestion_runs
+            SET status = ?, error = ?, endedAt = ?
+            WHERE id = ?
+          `)
+                .run(status, error, endedAt, id);
+            if (result.changes === 0) {
+                throw new Error(`Ingestion run with id ${id} not found`);
             }
-            const stmt = this.db.prepare(query);
-            const rows = stmt.all(...params);
-            return rows.map((row) => this.rowToEvidence(row));
         }
-        catch (error) {
-            throw new Error(`Failed to list evidences: ${error instanceof Error ? error.message : String(error)}`);
+        catch (cause) {
+            throw new Error(`Failed to complete ingestion run: ${cause instanceof Error ? cause.message : String(cause)}`);
         }
     }
+    getSessionIngestionRuns(sessionId) {
+        return this.dbOp("get ingestion runs", () => {
+            const rows = this.db
+                .prepare(`
+            SELECT * FROM ingestion_runs
+            WHERE sessionId = ?
+            ORDER BY startedAt ASC
+          `)
+                .all(sessionId);
+            return rows.map((row) => this.rowToIngestionRun(row));
+        });
+    }
+    getSessionDetail(sessionId) {
+        // Wrap all reads in a single transaction for atomic snapshot
+        const readAll = this.db.transaction(() => {
+            const session = this.findSessionById(sessionId);
+            if (!session) {
+                return null;
+            }
+            const messages = this.getSessionMessages(sessionId);
+            const timeline = this.getSessionTimeline(sessionId);
+            const artifacts = this.getSessionArtifacts(sessionId);
+            const narratives = this.getSessionNarratives(sessionId);
+            const decisions = this.getSessionDecisions(sessionId);
+            const ingestionRuns = this.getSessionIngestionRuns(sessionId);
+            return {
+                session,
+                messages,
+                timeline,
+                artifacts,
+                narratives,
+                decisions,
+                ingestionRuns,
+                hasNarratives: narratives.length > 0,
+            };
+        });
+        return readAll();
+    }
     /**
      * Updates git commit information for an evidence
      * @param id - Evidence UUID
@@ -127,7 +1633,7 @@ export class EvidenceDatabase {
      * @param gitTimestamp - Git commit timestamp (ISO 8601)
      */
     updateGitInfo(id, gitCommitHash, gitTimestamp) {
-        try {
+        this.dbOp("update git info", () => {
             const stmt = this.db.prepare(`
         UPDATE evidences
         SET gitCommitHash = ?,
@@ -139,10 +1645,7 @@ export class EvidenceDatabase {
             if (result.changes === 0) {
                 throw new Error(`Evidence with id ${id} not found`);
             }
-        }
-        catch (error) {
-            throw new Error(`Failed to update git info: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Adds tags to an evidence (appends to existing tags)
@@ -151,7 +1654,7 @@ export class EvidenceDatabase {
      * @throws Error if tags array is empty or all tags are whitespace
      */
     addTags(id, tags) {
-        try {
+        this.dbOp("add tags", () => {
             if (tags.length === 0) {
                 throw new Error("Tags array cannot be empty");
             }
@@ -185,10 +1688,7 @@ export class EvidenceDatabase {
                 stmt.run(mergedTags.join(","), new Date().toISOString(), id);
             });
             transaction();
-        }
-        catch (error) {
-            throw new Error(`Failed to add tags: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Builds a WHERE clause from search/filter options
@@ -227,23 +1727,20 @@ export class EvidenceDatabase {
      * @returns Number of matching evidences
      */
     getFilteredCount(options) {
-        try {
+        return this.dbOp("get filtered count", () => {
             const { sql: whereClause, params } = this.buildWhereClause(options);
             const row = this.db
                 .prepare(`SELECT COUNT(*) as count FROM evidences${whereClause}`)
                 .get(...params);
             return row.count;
-        }
-        catch (error) {
-            throw new Error(`Failed to get filtered count: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Search evidences and return both paginated results and total matching count
      * in a single pass (builds WHERE clause once instead of twice)
      */
     searchWithCount(options) {
-        try {
+        return this.dbOp("search evidences", () => {
             const { limit, offset = 0 } = options;
             const { sql: whereClause, params: baseParams } = this.buildWhereClause(options);
             // Wrap both queries in a transaction for consistent snapshot
@@ -254,19 +1751,7 @@ export class EvidenceDatabase {
                     .get(...baseParams);
                 // Build paginated query (clone params since we append to it)
                 const searchParams = [...baseParams];
-                let sql = `SELECT * FROM evidences${whereClause} ORDER BY timestamp DESC`;
-                if (limit !== undefined) {
-                    sql += " LIMIT ?";
-                    searchParams.push(limit);
-                    if (offset > 0) {
-                        sql += " OFFSET ?";
-                        searchParams.push(offset);
-                    }
-                }
-                else if (offset > 0) {
-                    sql += " LIMIT -1 OFFSET ?";
-                    searchParams.push(offset);
-                }
+                const sql = appendPaginationClause(`SELECT * FROM evidences${whereClause} ORDER BY timestamp DESC`, searchParams, limit, offset);
                 const rows = this.db.prepare(sql).all(...searchParams);
                 return {
                     evidences: rows.map((row) => this.rowToEvidence(row)),
@@ -274,10 +1759,7 @@ export class EvidenceDatabase {
                 };
             });
             return query();
-        }
-        catch (error) {
-            throw new Error(`Failed to search evidences: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Search and filter evidences by various criteria
@@ -285,31 +1767,17 @@ export class EvidenceDatabase {
      * @returns Array of matching evidences
      */
     search(options) {
-        try {
+        return this.dbOp("search evidences", () => {
             const { limit, offset = 0 } = options;
             const { sql: whereClause, params } = this.buildWhereClause(options);
             // Build final query
             let sql = `SELECT * FROM evidences${whereClause} ORDER BY timestamp DESC`;
             // Add pagination
-            if (limit !== undefined) {
-                sql += " LIMIT ?";
-                params.push(limit);
-                if (offset > 0) {
-                    sql += " OFFSET ?";
-                    params.push(offset);
-                }
-            }
-            else if (offset > 0) {
-                sql += " LIMIT -1 OFFSET ?";
-                params.push(offset);
-            }
+            sql = appendPaginationClause(sql, params, limit, offset);
             const stmt = this.db.prepare(sql);
             const rows = stmt.all(...params);
             return rows.map((row) => this.rowToEvidence(row));
-        }
-        catch (error) {
-            throw new Error(`Failed to search evidences: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Deletes evidence by ID
@@ -317,14 +1785,11 @@ export class EvidenceDatabase {
      * @returns true if deleted, false if not found
      */
     delete(id) {
-        try {
+        return this.dbOp("delete evidence", () => {
             const stmt = this.db.prepare(`DELETE FROM evidences WHERE id = ?`);
             const result = stmt.run(id);
             return result.changes > 0;
-        }
-        catch (error) {
-            throw new Error(`Failed to delete evidence: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Deletes multiple evidences by IDs
@@ -334,7 +1799,7 @@ export class EvidenceDatabase {
     deleteMany(ids) {
         if (ids.length === 0)
             return 0;
-        try {
+        return this.dbOp("delete evidences", () => {
             // Batch deletions to stay under SQLite's 999 parameter limit
             const BATCH_SIZE = 999;
             let totalDeleted = 0;
@@ -346,10 +1811,7 @@ export class EvidenceDatabase {
                 totalDeleted += result.changes;
             }
             return totalDeleted;
-        }
-        catch (error) {
-            throw new Error(`Failed to delete evidences: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Updates tags for an evidence (replaces existing tags)
@@ -358,7 +1820,7 @@ export class EvidenceDatabase {
      * @returns true if updated, false if not found
      */
     updateTags(id, tags) {
-        try {
+        return this.dbOp("update tags", () => {
             const stmt = this.db.prepare(`
         UPDATE evidences
         SET tags = ?,
@@ -367,10 +1829,7 @@ export class EvidenceDatabase {
       `);
             const result = stmt.run(tags, new Date().toISOString(), id);
             return result.changes > 0;
-        }
-        catch (error) {
-            throw new Error(`Failed to update tags: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Renames a tag across all evidences atomically using transaction
@@ -380,7 +1839,7 @@ export class EvidenceDatabase {
      * @throws Error if transaction fails (no partial updates)
      */
     renameTag(oldTag, newTag) {
-        try {
+        return this.dbOp("rename tag", () => {
             // Wrap in transaction for atomic updates
             const transaction = this.db.transaction(() => {
                 // Get all evidences with this tag
@@ -398,10 +1857,7 @@ export class EvidenceDatabase {
                 return updatedCount;
             });
             return transaction();
-        }
-        catch (error) {
-            throw new Error(`Failed to rename tag: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Removes a tag from all evidences atomically using transaction
@@ -410,7 +1866,7 @@ export class EvidenceDatabase {
      * @throws Error if transaction fails (no partial updates)
      */
     removeTag(tag) {
-        try {
+        return this.dbOp("remove tag", () => {
             // Wrap in transaction for atomic updates
             const transaction = this.db.transaction(() => {
                 // Get all evidences with this tag
@@ -431,17 +1887,14 @@ export class EvidenceDatabase {
                 return updatedCount;
             });
             return transaction();
-        }
-        catch (error) {
-            throw new Error(`Failed to remove tag: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Gets all unique tags with their counts
      * @returns Map of tag to count
      */
     getTagCounts() {
-        try {
+        return this.dbOp("get tag counts", () => {
             const stmt = this.db.prepare(`SELECT tags FROM evidences WHERE tags IS NOT NULL AND tags != ''`);
             const rows = stmt.all();
             const tagCounts = new Map();
@@ -455,10 +1908,7 @@ export class EvidenceDatabase {
                 }
             }
             return tagCounts;
-        }
-        catch (error) {
-            throw new Error(`Failed to get tag counts: ${error instanceof Error ? error.message : String(error)}`);
-        }
+        });
     }
     /**
      * Gets total count of all evidence records
@@ -470,6 +1920,12 @@ export class EvidenceDatabase {
             .get();
         return row.count;
     }
+    getSessionCount() {
+        const row = this.db
+            .prepare("SELECT COUNT(*) as count FROM sessions")
+            .get();
+        return row.count;
+    }
     /**
      * Gets count of evidence records matching a search query
      * @param query - Search text to match against conversationId and tags
@@ -517,5 +1973,129 @@ export class EvidenceDatabase {
             updatedAt: row.updatedAt,
         };
     }
+    rowToSession(row) {
+        return {
+            id: row.id,
+            host: row.host,
+            projectRoot: row.projectRoot,
+            cwd: row.cwd,
+            title: row.title,
+            status: row.status,
+            startedAt: row.startedAt,
+            endedAt: row.endedAt,
+            metadata: row.metadata,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    rowToContext(row) {
+        return {
+            id: row.id,
+            label: row.label,
+            workspaceKey: row.workspaceKey,
+            status: row.status,
+            mergedIntoContextId: row.mergedIntoContextId,
+            metadata: row.metadata,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    rowToContextSessionLink(row) {
+        return {
+            sessionId: row.sessionId,
+            contextId: row.contextId,
+            linkSource: row.linkSource,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    rowToContextLinkRejection(row) {
+        return {
+            sessionId: row.sessionId,
+            contextId: row.contextId,
+            createdAt: row.createdAt,
+        };
+    }
+    rowToContextWorkspacePreference(row) {
+        return {
+            workspaceKey: row.workspaceKey,
+            contextId: row.contextId,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    rowToMessage(row) {
+        return {
+            id: row.id,
+            sessionId: row.sessionId,
+            seq: row.seq,
+            role: row.role,
+            source: row.source,
+            content: row.content,
+            capturedAt: row.capturedAt,
+            metadata: row.metadata,
+        };
+    }
+    rowToTimelineEvent(row) {
+        return {
+            id: row.id,
+            sessionId: row.sessionId,
+            seq: row.seq,
+            eventType: row.eventType,
+            eventSubType: row.eventSubType,
+            source: row.source,
+            summary: row.summary,
+            payload: row.payload,
+            startedAt: row.startedAt,
+            endedAt: row.endedAt,
+            status: row.status,
+            relatedMessageId: row.relatedMessageId,
+        };
+    }
+    rowToArtifact(row) {
+        return {
+            id: row.id,
+            sessionId: row.sessionId,
+            eventId: row.eventId,
+            artifactType: row.artifactType,
+            path: row.path,
+            metadata: row.metadata,
+            createdAt: row.createdAt,
+        };
+    }
+    rowToDecision(row) {
+        return {
+            id: row.id,
+            sessionId: row.sessionId,
+            title: row.title,
+            summary: row.summary,
+            rationale: row.rationale,
+            status: row.status,
+            sourceRefs: row.sourceRefs,
+            createdAt: row.createdAt,
+        };
+    }
+    rowToNarrative(row) {
+        return {
+            id: row.id,
+            sessionId: row.sessionId,
+            kind: row.kind,
+            content: row.content,
+            sourceRefs: row.sourceRefs,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+        };
+    }
+    rowToIngestionRun(row) {
+        return {
+            id: row.id,
+            sessionId: row.sessionId,
+            stage: row.stage,
+            status: row.status,
+            error: row.error,
+            startedAt: row.startedAt,
+            endedAt: row.endedAt,
+        };
+    }
 }
 //# sourceMappingURL=database.js.map