@mycodemap/mycodemap 1.9.0 → 2.7.0

package/dist/infrastructure/storage/adapters/SQLiteStorage.js

@@ -5,8 +5,9 @@
 // ============================================
 import { mkdir } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { Dependency as DomainDependency } from '../../../domain/entities/Dependency.js';
 import { StorageBase, StorageError } from '../interfaces/StorageBase.js';
-import { calculateImpactInGraph, cloneCodeGraph, createEmptyCodeGraph, deserializeCodeGraphSnapshot, detectCyclesInGraph, getProjectStatisticsFromGraph, serializeCodeGraphSnapshot, upsertModuleInGraph, } from '../graph-helpers.js';
+import { calculateImpactInGraph, calculateSymbolImpactInGraph, cloneCodeGraph, createEmptyCodeGraph, deserializeCodeGraphSnapshot, detectCyclesInGraph, getProjectStatisticsFromGraph, serializeCodeGraphSnapshot, upsertModuleInGraph, } from '../graph-helpers.js';
 import { CURRENT_SQLITE_SCHEMA_VERSION, SQLITE_GOVERNANCE_SCHEMA_SQL, SQLITE_SCHEMA_VERSION_UPSERT_SQL, } from '../sqlite/schema.js';
 import { GovernanceGraphCache, readGovernanceGraphFromSQLite, } from '../sqlite/GovernanceGraphCache.js';
 import { DEFAULT_GOVERNANCE_GRAPH_PERF_THRESHOLDS, } from '../sqlite/perf-thresholds.js';
@@ -14,9 +15,16 @@ const GRAPH_STATUS_METADATA_KEY = 'graph_status';
 const FAILED_FILE_COUNT_METADATA_KEY = 'failed_file_count';
 const PARSE_FAILURE_FILES_METADATA_KEY = 'parse_failure_files_json';
 const LAST_GRAPH_SYNC_AT_METADATA_KEY = 'last_graph_sync_at';
+const LAST_REFRESH_METADATA_KEY = 'last_refresh_summary_json';
+const VALID_DEPENDENCY_CONFIDENCE = new Set([
+    'EXTRACTED',
+    'INFERRED',
+    'AMBIGUOUS',
+]);
+const SQLITE_REBUILD_REQUIRED_MESSAGE = 'Graph schema is outdated. Run `mycodemap generate` to rebuild the SQLite graph.';
+import { getLastSQLiteLoadDiagnostics, loadSQLite, } from './sqlite-loader.js';
 async function loadSQLiteModule() {
-    const sqliteModule = await import('better-sqlite3');
-    return sqliteModule.default;
+    return loadSQLite();
 }
 function toStringValue(value, fallback = '') {
     return typeof value === 'string' ? value : fallback;
@@ -55,6 +63,54 @@ function normalizeParseFailureFiles(value) {
     }
     return parsedValue.filter((item) => typeof item === 'string');
 }
+function deduplicateDependenciesForStorage(dependencies, symbolIds) {
+    const seen = new Set();
+    const deduped = [];
+    for (const dependency of dependencies) {
+        const sourceEntityType = resolveEntityType(dependency.sourceEntityType, dependency.sourceId, symbolIds);
+        const targetEntityType = resolveEntityType(dependency.targetEntityType, dependency.targetId, symbolIds);
+        const key = DomainDependency.createKey(dependency.sourceId, dependency.targetId, dependency.type, sourceEntityType, targetEntityType, dependency.filePath);
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        deduped.push({
+            ...dependency,
+            sourceEntityType,
+            targetEntityType,
+        });
+    }
+    return deduped;
+}
+function buildModuleReferenceById(modules) {
+    return new Map(modules.map(module => [
+        module.id,
+        DomainDependency.createModuleReference(module.path),
+    ]));
+}
+function buildSymbolReferenceById(symbols, moduleReferenceById) {
+    return new Map(symbols.map(symbol => {
+        const symbolFilePath = moduleReferenceById.get(symbol.moduleId) ?? symbol.location.file;
+        return [
+            symbol.id,
+            DomainDependency.createSymbolReference(symbolFilePath, symbol.name, symbol.location.line, symbol.location.column),
+        ];
+    }));
+}
+function resolveDependencyReference(entityId, entityType, moduleReferenceById, symbolReferenceById) {
+    const stableReference = entityType === 'symbol'
+        ? symbolReferenceById.get(entityId)
+        : moduleReferenceById.get(entityId);
+    return stableReference ?? entityId;
+}
+function normalizeDependencyIdsForStorage(dependencies, modules, symbols) {
+    const moduleReferenceById = buildModuleReferenceById(modules);
+    const symbolReferenceById = buildSymbolReferenceById(symbols, moduleReferenceById);
+    return dependencies.map((dependency) => ({
+        ...dependency,
+        id: DomainDependency.createCanonicalId(resolveDependencyReference(dependency.sourceId, dependency.sourceEntityType ?? 'module', moduleReferenceById, symbolReferenceById), resolveDependencyReference(dependency.targetId, dependency.targetEntityType ?? 'module', moduleReferenceById, symbolReferenceById), dependency.type, dependency.sourceEntityType ?? 'module', dependency.targetEntityType ?? 'module', dependency.filePath),
+    }));
+}
 function readGraphIntegrityMetadata(database) {
     const metadataRows = database.prepare(`
     SELECT key, value
@@ -81,9 +137,9 @@ function readGraphMetadata(database) {
         .prepare(`
       SELECT key, value
       FROM metadata
-      WHERE key IN (?, ?, ?, ?)
+      WHERE key IN (?, ?, ?, ?, ?)
     `)
-        .all(GRAPH_STATUS_METADATA_KEY, FAILED_FILE_COUNT_METADATA_KEY, PARSE_FAILURE_FILES_METADATA_KEY, LAST_GRAPH_SYNC_AT_METADATA_KEY);
+        .all(GRAPH_STATUS_METADATA_KEY, FAILED_FILE_COUNT_METADATA_KEY, PARSE_FAILURE_FILES_METADATA_KEY, LAST_GRAPH_SYNC_AT_METADATA_KEY, LAST_REFRESH_METADATA_KEY);
     const metadataMap = new Map(metadataRows.map(row => [toStringValue(row.key), row.value]));
     const parseFailureFiles = normalizeParseFailureFiles(metadataMap.get(PARSE_FAILURE_FILES_METADATA_KEY));
     const moduleCount = toNumberValue(countsRow?.module_count);
@@ -98,13 +154,31 @@ function readGraphMetadata(database) {
         parseFailureFiles,
         moduleCount,
         symbolCount,
+        lastRefresh: parseRefreshSummary(metadataMap.get(LAST_REFRESH_METADATA_KEY)),
     };
 }
+function parseRefreshSummary(value) {
+    const raw = toStringValue(value);
+    if (!raw) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
 function createHistorySnapshotId(recordedAt) {
     const compactTimestamp = recordedAt.replace(/[^0-9]/g, '');
     const entropy = Math.random().toString(16).slice(2, 10);
     return `history-${compactTimestamp}-${entropy}`;
 }
+function createAgentMetricsRunId(recordedAt) {
+    const compactTimestamp = recordedAt.replace(/[^0-9]/g, '');
+    const entropy = Math.random().toString(16).slice(2, 10);
+    return `agent-metrics-run-${compactTimestamp}-${entropy}`;
+}
 function inferEntityType(entityId, symbolIds) {
     return symbolIds.has(entityId) ? 'symbol' : 'module';
 }
@@ -115,6 +189,17 @@ function hasColumn(database, tableName, columnName) {
     const rows = database.prepare(`PRAGMA table_info(${tableName})`).all();
     return rows.some((row) => toStringValue(row.name) === columnName);
 }
+function hasTable(database, tableName) {
+    const row = database
+        .prepare(`
+      SELECT name
+      FROM sqlite_master
+      WHERE type = 'table' AND name = ?
+      LIMIT 1
+    `)
+        .get(tableName);
+    return Boolean(row?.name);
+}
 function addColumnIfMissing(database, tableName, columnName, definition) {
     if (!hasColumn(database, tableName, columnName)) {
         database.exec(`ALTER TABLE ${tableName} ADD COLUMN ${definition}`);
@@ -134,6 +219,19 @@ function createUnavailableHistoryDiagnostics(reason) {
         requiresPrecompute: false,
     };
 }
+function createGraphRebuildRequiredError(reason) {
+    return new StorageError(`${reason} ${SQLITE_REBUILD_REQUIRED_MESSAGE}`, 'GRAPH_SCHEMA_REBUILD_REQUIRED');
+}
+function normalizeDependencyConfidence(value) {
+    if (value === null || value === undefined || toStringValue(value) === '') {
+        return undefined;
+    }
+    const confidence = toStringValue(value);
+    if (VALID_DEPENDENCY_CONFIDENCE.has(confidence)) {
+        return confidence;
+    }
+    throw new StorageError(`Invalid dependency confidence "${confidence}". Run \`mycodemap generate\` to rebuild the SQLite graph.`, 'GRAPH_INVALID_DEPENDENCY_CONFIDENCE');
+}
 function createUnavailableSymbolHistoryResult(query, reason) {
     return {
         query,
@@ -176,6 +274,9 @@ export class SQLiteStorage extends StorageBase {
         this.storageConfig = config;
         this.runtimeOptions = runtimeOptions;
     }
+    static getLastLoadDiagnostics() {
+        return getLastSQLiteLoadDiagnostics();
+    }
     async doInitialize() {
         if (!this.projectPath) {
             throw new StorageError('Project path not set', 'PROJECT_PATH_NOT_SET');
@@ -189,12 +290,15 @@ export class SQLiteStorage extends StorageBase {
             this.database = new Database(databasePath);
             this.database.pragma?.('journal_mode = WAL');
             this.database.pragma?.('foreign_keys = ON');
+            this.assertSchemaCompatibility(this.database);
             this.database.exec(SQLITE_GOVERNANCE_SCHEMA_SQL);
             this.ensureSchemaColumns(this.database);
+            this.assertProjectionParity(this.database);
             this.database
                 .prepare(SQLITE_SCHEMA_VERSION_UPSERT_SQL)
                 .run('schema_version', CURRENT_SQLITE_SCHEMA_VERSION);
             this.backfillLegacySnapshotIfNeeded(this.database);
+            this.backfillCanonicalDependencyIdsIfNeeded(this.database);
             this.refreshGovernanceGraphCache(this.database);
         }
         catch (error) {
@@ -221,6 +325,8 @@ export class SQLiteStorage extends StorageBase {
     async deleteProject() {
         const database = this.getDatabase();
         this.runInTransaction(database, () => {
+            database.prepare('DELETE FROM agent_metrics').run();
+            database.prepare('DELETE FROM agent_metrics_runs').run();
             database.prepare('DELETE FROM history_relations').run();
             database.prepare('DELETE FROM history_snapshots').run();
             database.prepare('DELETE FROM dependencies').run();
@@ -354,69 +460,7 @@ export class SQLiteStorage extends StorageBase {
         return calculateImpactInGraph(this.readGovernanceGraphForAnalysis(this.getDatabase()), moduleId, depth);
     }
     async calculateSymbolImpact(symbolId, depth, limit) {
-        const database = this.getDatabase();
-        const rootSymbol = await this.findSymbolById(symbolId);
-        if (!rootSymbol) {
-            throw new StorageError(`Symbol ${symbolId} not found`, 'SYMBOL_NOT_FOUND');
-        }
-        const selectCallers = database.prepare(`
-      SELECT s.id, s.module_id, s.name, s.kind, s.signature, s.file_path, s.line, s.column_number, s.end_line, s.end_column, s.visibility
-      FROM dependencies d
-      INNER JOIN symbols s ON s.id = d.source_id
-      WHERE d.target_id = ?
-        AND d.dependency_type = 'call'
-      ORDER BY d.id, s.id
-    `);
-        const affectedSymbols = [];
-        const visited = new Set([symbolId]);
-        const queue = [{
-                id: symbolId,
-                level: 0,
-                path: [symbolId],
-            }];
-        let truncated = false;
-        while (queue.length > 0) {
-            const current = queue.shift();
-            if (!current) {
-                continue;
-            }
-            if (current.level >= depth) {
-                continue;
-            }
-            const callerRows = selectCallers.all(current.id);
-            for (const row of callerRows) {
-                if (affectedSymbols.length >= limit) {
-                    truncated = true;
-                    queue.length = 0;
-                    break;
-                }
-                const callerId = toStringValue(row.id);
-                if (visited.has(callerId)) {
-                    continue;
-                }
-                visited.add(callerId);
-                const callerSymbol = this.mapSymbolRow(row);
-                const nextLevel = current.level + 1;
-                const nextPath = [...current.path, callerId];
-                affectedSymbols.push({
-                    symbol: callerSymbol,
-                    depth: nextLevel,
-                    path: nextPath,
-                });
-                queue.push({
-                    id: callerId,
-                    level: nextLevel,
-                    path: nextPath,
-                });
-            }
-        }
-        return {
-            rootSymbol,
-            affectedSymbols,
-            depth,
-            limit,
-            truncated,
-        };
+        return calculateSymbolImpactInGraph(await this.loadCodeGraph(), symbolId, depth, limit);
     }
     async getStatistics() {
         const database = this.getDatabase();
@@ -595,6 +639,96 @@ export class SQLiteStorage extends StorageBase {
             diagnostics: metadata.diagnostics,
         };
     }
+    async saveAgentMetricsRun(payload) {
+        const database = this.getDatabase();
+        const recordedAt = payload.recordedAt ?? new Date().toISOString();
+        const runId = payload.id ?? createAgentMetricsRunId(recordedAt);
+        const projectId = toStringValue(database.prepare('SELECT id FROM projects LIMIT 1').get()?.id, 'agent-metrics-project');
+        const insertRun = database.prepare(`
+      INSERT INTO agent_metrics_runs (
+        id, project_id, recorded_at, sample_set_version, estimator_version, detail_count, metadata_json
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `);
+        const insertDetail = database.prepare(`
+      INSERT INTO agent_metrics (
+        id, run_id, query_type, command_slug, response_size_bytes, raw_char_count,
+        estimated_input_tokens, estimated_output_tokens, estimated_total_tokens,
+        execution_time_ms, metadata_json
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        this.runInTransaction(database, () => {
+            insertRun.run(runId, projectId, recordedAt, payload.sampleSetVersion, payload.estimatorVersion, payload.items.length, payload.metadata ? JSON.stringify(payload.metadata) : null);
+            payload.items.forEach((item, index) => {
+                insertDetail.run(item.id ?? `${runId}:${index + 1}`, runId, item.queryType, item.commandSlug, item.responseSizeBytes, item.rawCharCount, item.estimatedInputTokens, item.estimatedOutputTokens, item.estimatedTotalTokens, item.executionTimeMs ?? null, item.metadata ? JSON.stringify(item.metadata) : null);
+            });
+        });
+        return {
+            id: runId,
+            projectId,
+            recordedAt,
+            sampleSetVersion: payload.sampleSetVersion,
+            estimatorVersion: payload.estimatorVersion,
+            detailCount: payload.items.length,
+            metadata: payload.metadata ?? null,
+        };
+    }
+    async loadLatestAgentMetricsRun() {
+        const row = this.getDatabase()
+            .prepare(`
+        SELECT id, project_id, recorded_at, sample_set_version, estimator_version, detail_count, metadata_json
+        FROM agent_metrics_runs
+        ORDER BY recorded_at DESC, id DESC
+        LIMIT 1
+      `)
+            .get();
+        return row ? this.mapAgentMetricsRunRow(row) : null;
+    }
+    async listRecentAgentMetricsRuns(limit) {
+        const normalizedLimit = Math.max(0, Math.floor(limit));
+        if (normalizedLimit === 0) {
+            return [];
+        }
+        const rows = this.getDatabase()
+            .prepare(`
+        SELECT id, project_id, recorded_at, sample_set_version, estimator_version, detail_count, metadata_json
+        FROM agent_metrics_runs
+        ORDER BY recorded_at DESC, id DESC
+        LIMIT ?
+      `)
+            .all(normalizedLimit);
+        return rows.map((row) => this.mapAgentMetricsRunRow(row));
+    }
+    async listAgentMetricsByRun(runId) {
+        const rows = this.getDatabase()
+            .prepare(`
+        SELECT id, run_id, query_type, command_slug, response_size_bytes, raw_char_count,
+               estimated_input_tokens, estimated_output_tokens, estimated_total_tokens,
+               execution_time_ms, metadata_json
+        FROM agent_metrics
+        WHERE run_id = ?
+        ORDER BY id
+      `)
+            .all(runId);
+        return rows.map((row) => this.mapAgentMetricsDetailRow(row));
+    }
+    async listAgentMetricsHistoryByQueryType(queryType) {
+        const rows = this.getDatabase()
+            .prepare(`
+        SELECT agent_metrics.id, agent_metrics.run_id, agent_metrics.query_type, agent_metrics.command_slug,
+               agent_metrics.response_size_bytes, agent_metrics.raw_char_count,
+               agent_metrics.estimated_input_tokens, agent_metrics.estimated_output_tokens,
+               agent_metrics.estimated_total_tokens, agent_metrics.execution_time_ms,
+               agent_metrics.metadata_json
+        FROM agent_metrics
+        INNER JOIN agent_metrics_runs ON agent_metrics_runs.id = agent_metrics.run_id
+        WHERE agent_metrics.query_type = ?
+        ORDER BY agent_metrics_runs.recorded_at DESC, agent_metrics_runs.id DESC, agent_metrics.id ASC
+      `)
+            .all(queryType);
+        return rows.map((row) => this.mapAgentMetricsDetailRow(row));
+    }
     getGovernanceGraphRuntimeStats() {
         return this.governanceGraphCache?.getStats() ?? {
             cacheMode: 'sqlite-direct',
@@ -612,6 +746,47 @@ export class SQLiteStorage extends StorageBase {
         addColumnIfMissing(database, 'dependencies', 'line', 'line INTEGER');
         addColumnIfMissing(database, 'dependencies', 'confidence', 'confidence TEXT');
     }
+    assertSchemaCompatibility(database) {
+        if (!hasTable(database, 'metadata')) {
+            return;
+        }
+        const schemaVersion = toStringValue(database.prepare('SELECT value FROM metadata WHERE key = ? LIMIT 1').get('schema_version')?.value);
+        const projectCount = hasTable(database, 'projects')
+            ? toNumberValue(database.prepare('SELECT COUNT(*) AS count FROM projects').get()?.count)
+            : 0;
+        const dependencyCount = hasTable(database, 'dependencies')
+            ? toNumberValue(database.prepare('SELECT COUNT(*) AS count FROM dependencies').get()?.count)
+            : 0;
+        const snapshotCount = hasTable(database, 'snapshots')
+            ? toNumberValue(database.prepare('SELECT COUNT(*) AS count FROM snapshots').get()?.count)
+            : 0;
+        const hasMaterializedGraph = projectCount > 0 || dependencyCount > 0;
+        if (!hasMaterializedGraph && (schemaVersion === '' || schemaVersion === 'bootstrap-v1') && snapshotCount > 0) {
+            return;
+        }
+        if (schemaVersion === '' && !hasMaterializedGraph) {
+            return;
+        }
+        if (schemaVersion !== CURRENT_SQLITE_SCHEMA_VERSION) {
+            throw createGraphRebuildRequiredError(`Found SQLite schema version "${schemaVersion || 'unknown'}" but expected "${CURRENT_SQLITE_SCHEMA_VERSION}".`);
+        }
+        if (dependencyCount > 0 && !hasTable(database, 'graph_edges')) {
+            throw createGraphRebuildRequiredError('Traversal projection table "graph_edges" is missing.');
+        }
+    }
+    assertProjectionParity(database) {
+        if (!hasTable(database, 'dependencies') || !hasTable(database, 'graph_edges')) {
+            return;
+        }
+        const dependencyCount = toNumberValue(database.prepare('SELECT COUNT(*) AS count FROM dependencies').get()?.count);
+        const projectionCount = toNumberValue(database.prepare('SELECT COUNT(*) AS count FROM graph_edges').get()?.count);
+        if (dependencyCount === 0 && projectionCount === 0) {
+            return;
+        }
+        if (dependencyCount !== projectionCount) {
+            throw createGraphRebuildRequiredError(`Traversal projection drift detected (${projectionCount}/${dependencyCount} rows).`);
+        }
+    }
     backfillLegacySnapshotIfNeeded(database) {
         const hasCurrentProject = toNumberValue(database.prepare('SELECT COUNT(*) AS count FROM projects').get()?.count) > 0;
         if (hasCurrentProject) {
@@ -636,6 +811,23 @@ export class SQLiteStorage extends StorageBase {
             .prepare(SQLITE_SCHEMA_VERSION_UPSERT_SQL)
             .run('legacy_snapshot_backfilled_at', recordedAt);
     }
+    backfillCanonicalDependencyIdsIfNeeded(database) {
+        const dependencyCount = toNumberValue(database.prepare('SELECT COUNT(*) AS count FROM dependencies').get()?.count);
+        if (dependencyCount === 0) {
+            return;
+        }
+        const currentGraph = this.readCodeGraph(database);
+        const normalizedGraph = this.normalizeGraph(currentGraph);
+        const requiresRewrite = currentGraph.dependencies.some((dependency, index) => (dependency.id !== normalizedGraph.dependencies[index]?.id));
+        if (!requiresRewrite) {
+            return;
+        }
+        const recordedAt = new Date().toISOString();
+        this.replaceCurrentGraph(database, currentGraph, 'edge-id-normalization-backfill', recordedAt);
+        database
+            .prepare(SQLITE_SCHEMA_VERSION_UPSERT_SQL)
+            .run('edge_id_normalized_at', recordedAt);
+    }
     replaceCurrentGraph(database, graph, historySource, recordedAt = new Date().toISOString()) {
         const normalizedGraph = this.normalizeGraph(graph);
         const symbolIds = new Set(normalizedGraph.symbols.map(symbol => symbol.id));
@@ -661,6 +853,12 @@ export class SQLiteStorage extends StorageBase {
         id, source_id, source_entity_type, target_id, target_entity_type, dependency_type, file_path, line, confidence
       )
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+        const insertGraphEdge = database.prepare(`
+      INSERT INTO graph_edges (
+        dependency_id, source_id, source_entity_type, target_id, target_entity_type, dependency_type, confidence, file_path, line
+      )
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
         const insertSnapshotMirror = database.prepare(`
       INSERT INTO snapshots (id, project_id, graph_json, updated_at)
@@ -681,6 +879,7 @@ export class SQLiteStorage extends StorageBase {
         const snapshotId = createHistorySnapshotId(recordedAt);
         this.runInTransaction(database, () => {
             database.prepare('DELETE FROM dependencies').run();
+            database.prepare('DELETE FROM graph_edges').run();
             database.prepare('DELETE FROM symbols').run();
             database.prepare('DELETE FROM modules').run();
             database.prepare('DELETE FROM projects').run();
@@ -695,7 +894,9 @@ export class SQLiteStorage extends StorageBase {
             for (const dependency of normalizedGraph.dependencies) {
                 const sourceEntityType = resolveEntityType(dependency.sourceEntityType, dependency.sourceId, symbolIds);
                 const targetEntityType = resolveEntityType(dependency.targetEntityType, dependency.targetId, symbolIds);
-                insertDependency.run(dependency.id, dependency.sourceId, sourceEntityType, dependency.targetId, targetEntityType, dependency.type, dependency.filePath ?? null, dependency.line ?? null, dependency.confidence ?? null);
+                const confidence = normalizeDependencyConfidence(dependency.confidence);
+                insertDependency.run(dependency.id, dependency.sourceId, sourceEntityType, dependency.targetId, targetEntityType, dependency.type, dependency.filePath ?? null, dependency.line ?? null, confidence ?? null);
+                insertGraphEdge.run(dependency.id, dependency.sourceId, sourceEntityType, dependency.targetId, targetEntityType, dependency.type, confidence ?? 'EXTRACTED', dependency.filePath ?? null, dependency.line ?? null);
             }
             insertSnapshotMirror.run('codemap-snapshot', normalizedGraph.project.id, serializeCodeGraphSnapshot(normalizedGraph), recordedAt);
             insertHistorySnapshot.run(snapshotId, normalizedGraph.project.id, recordedAt, historySource, normalizedGraph.modules.length, normalizedGraph.symbols.length, normalizedGraph.dependencies.length);
@@ -715,10 +916,11 @@ export class SQLiteStorage extends StorageBase {
             for (const dependency of normalizedGraph.dependencies) {
                 const sourceEntityType = resolveEntityType(dependency.sourceEntityType, dependency.sourceId, symbolIds);
                 const targetEntityType = resolveEntityType(dependency.targetEntityType, dependency.targetId, symbolIds);
+                const confidence = normalizeDependencyConfidence(dependency.confidence);
                 insertHistoryRelation.run(`${snapshotId}:dependency:${dependency.id}`, snapshotId, 'dependency_snapshot', dependency.sourceId, sourceEntityType, dependency.targetId, targetEntityType, recordedAt, JSON.stringify({
                     dependencyId: dependency.id,
                     dependencyType: dependency.type,
-                    confidence: dependency.confidence ?? null,
+                    confidence: confidence ?? null,
                     filePath: dependency.filePath ?? null,
                     line: dependency.line ?? null,
                 }));
@@ -727,11 +929,24 @@ export class SQLiteStorage extends StorageBase {
             upsertMetadata.run(FAILED_FILE_COUNT_METADATA_KEY, String(normalizedGraph.failedFileCount ?? 0));
             upsertMetadata.run(PARSE_FAILURE_FILES_METADATA_KEY, JSON.stringify(normalizedGraph.parseFailureFiles ?? []));
             upsertMetadata.run(LAST_GRAPH_SYNC_AT_METADATA_KEY, recordedAt);
+            upsertMetadata.run('schema_version', CURRENT_SQLITE_SCHEMA_VERSION);
+            upsertMetadata.run(LAST_REFRESH_METADATA_KEY, normalizedGraph.lastRefresh ? JSON.stringify(normalizedGraph.lastRefresh) : '');
         });
+        this.assertProjectionParity(database);
         this.refreshGovernanceGraphCache(database);
     }
     normalizeGraph(graph) {
         const projectRootPath = graph.project.rootPath || this.projectPath || '';
+        const symbols = graph.symbols.map(symbol => ({
+            ...symbol,
+            location: { ...symbol.location },
+        }));
+        const symbolIds = new Set(symbols.map(symbol => symbol.id));
+        const dependencies = deduplicateDependenciesForStorage(graph.dependencies.map(dependency => ({
+            ...dependency,
+            confidence: normalizeDependencyConfidence(dependency.confidence),
+        })), symbolIds);
+        const canonicalDependencies = normalizeDependencyIdsForStorage(dependencies, graph.modules, symbols);
         return {
             project: {
                 ...graph.project,
@@ -743,17 +958,17 @@ export class SQLiteStorage extends StorageBase {
                 ...module,
                 stats: { ...module.stats },
             })),
-            symbols: graph.symbols.map(symbol => ({
-                ...symbol,
-                location: { ...symbol.location },
-            })),
-            dependencies: graph.dependencies.map(dependency => ({ ...dependency })),
+            symbols,
+            dependencies: canonicalDependencies,
             graphStatus: graph.graphStatus ?? 'complete',
             failedFileCount: graph.failedFileCount ?? 0,
             parseFailureFiles: [...(graph.parseFailureFiles ?? [])],
+            lastRefresh: graph.lastRefresh,
         };
     }
     readCodeGraph(database) {
+        this.assertSchemaCompatibility(database);
+        this.assertProjectionParity(database);
         const projectRow = database
             .prepare(`
         SELECT id, name, root_path, created_at, updated_at
@@ -803,6 +1018,7 @@ export class SQLiteStorage extends StorageBase {
             graphStatus: graphIntegrity.graphStatus,
             failedFileCount: graphIntegrity.failedFileCount,
             parseFailureFiles: graphIntegrity.parseFailureFiles,
+            lastRefresh: readGraphMetadata(database).lastRefresh,
         };
     }
     mapModuleRow(row) {
@@ -846,7 +1062,33 @@ export class SQLiteStorage extends StorageBase {
             type: toStringValue(row.dependency_type),
             filePath: toStringValue(row.file_path) || undefined,
             line: toOptionalNumberValue(row.line),
-            confidence: toStringValue(row.confidence) === '' ? undefined : toStringValue(row.confidence),
+            confidence: normalizeDependencyConfidence(row.confidence),
+        };
+    }
+    mapAgentMetricsRunRow(row) {
+        return {
+            id: toStringValue(row.id),
+            projectId: toStringValue(row.project_id),
+            recordedAt: toStringValue(row.recorded_at),
+            sampleSetVersion: toStringValue(row.sample_set_version),
+            estimatorVersion: toStringValue(row.estimator_version),
+            detailCount: toNumberValue(row.detail_count),
+            metadata: parseJsonValue(row.metadata_json),
+        };
+    }
+    mapAgentMetricsDetailRow(row) {
+        return {
+            id: toStringValue(row.id),
+            runId: toStringValue(row.run_id),
+            queryType: toStringValue(row.query_type),
+            commandSlug: toStringValue(row.command_slug),
+            responseSizeBytes: toNumberValue(row.response_size_bytes),
+            rawCharCount: toNumberValue(row.raw_char_count),
+            estimatedInputTokens: toNumberValue(row.estimated_input_tokens),
+            estimatedOutputTokens: toNumberValue(row.estimated_output_tokens),
+            estimatedTotalTokens: toNumberValue(row.estimated_total_tokens),
+            executionTimeMs: toOptionalNumberValue(row.execution_time_ms),
+            metadata: parseJsonValue(row.metadata_json),
         };
     }
     runInTransaction(database, callback) {
@@ -868,9 +1110,13 @@ export class SQLiteStorage extends StorageBase {
         return this.database;
     }
     readGovernanceGraphForAnalysis(database) {
+        this.assertSchemaCompatibility(database);
+        this.assertProjectionParity(database);
         return readGovernanceGraphFromSQLite(database, this.projectPath ?? '');
     }
     refreshGovernanceGraphCache(database) {
+        this.assertSchemaCompatibility(database);
+        this.assertProjectionParity(database);
         const cache = new GovernanceGraphCache(database, this.projectPath ?? '', this.runtimeOptions.governanceGraphThresholds ?? DEFAULT_GOVERNANCE_GRAPH_PERF_THRESHOLDS);
         cache.hydrate();
         this.governanceGraphCache = cache;