@psnext/lscg 0.1.4 → 0.1.6

package/dist/src/graph/repository.js

@@ -1,15 +1,20 @@
 import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { databasePathForScope, homeDatabasePath, normalizeScope, repoDatabasePath, resolveProjectRoot } from '../config/paths.js';
-import { parseSource } from '../parser/treeSitter.js';
 import { discoverSourceFiles } from '../scanner/discover.js';
-import { collectRepositoryFingerprint } from '../scanner/fingerprint.js';
-import { attachDatabase, closeDatabase, getStatus, openGraphDatabase, replaceFileGraph, runSelect, selectCallGraph, selectEdges, selectNeighbors, selectNodes, selectNodeTextRows, upsertRepository, reconcileDeletedFiles, reconcilePluginEdges, reconcileRepositoryPluginNodes, insertRepositoryPluginNodes, loadPluginContributions, persistPluginContributions, nextPluginGeneration, selectFileInventory, selectContextCandidates, selectContextRelationships } from '../storage/database.js';
-import { extractGraph, hashParts } from './extract.js';
+import { attachDatabase, closeDatabase, getStatus, openGraphDatabase, openReadOnlyGraphDatabase, replaceFileGraph, applyFileAttribution, selectEnrichmentWork, selectFileEnrichmentStates, clearFileScanFailure, recordFileScanFailure, persistManifestInventoryAndScanState, runSelect, selectCallGraph, selectEdges, selectNeighbors, selectNodes, selectNodeTextRows, upsertRepository, reconcileDeletedFiles, reconcilePluginEdges, reconcileRepositoryPluginNodes, insertRepositoryPluginNodes, loadPluginContributions, persistPluginContributions, nextPluginGeneration, selectFileInventory, selectManifestInventory, manifestRowsAsRecords, selectFreshnessReport, selectContextCandidates, selectContextRelationships } from '../storage/database.js';
+import { hashParts } from './extract.js';
 import { buildFileAttribution } from './attribution.js';
 import { createRepositoryScanContext, runScannerPlugins, DEFAULT_PLUGIN_RESOURCE_LIMITS } from '../scanner/plugins.js';
 import { PackagePlugin } from '../scanner/packagePlugin.js';
+import { PythonScannerPlugin } from '../scanner/pythonPlugin.js';
+import { JavaScannerPlugin } from '../scanner/javaPlugin.js';
+import { JavaDependencyPlugin } from '../scanner/javaDependencyPlugin.js';
+import { AttributionPlugin, ATTRIBUTION_PLUGIN_NAME } from '../scanner/attributionPlugin.js';
+import { inspectRepositoryManifests, mergeManifestInventories } from '../scanner/artifactInventory.js';
+import { runBatchedWorkers } from '../scanner/parallelScan.js';
 function normalizePluginFilePath(value) {
     if (typeof value !== 'string' || value.trim().length === 0)
         return undefined;
@@ -73,24 +78,150 @@ export function initGraph({ root = process.cwd(), scope = 'repo' } = {}) {
     }
     return { repository, initialized };
 }
-export async function scanRepository({ root = process.cwd(), scope = 'repo', plugins = [], pluginLimits } = {}) {
+const MAX_FULL_ENRICHMENT_ATTEMPTS = 3;
+/**
+ * A full scan must not report success with hash-incompatible enrichment work.
+ * Rebuild and drain again when a source changes while attribution is running.
+ */
+export async function scanRepository(options = {}) {
+    const progress = options.progress;
+    const operation = options.full ? 'full' : 'incremental';
+    const scope = options.scope ?? 'repo';
+    if (!options.full) {
+        try {
+            const summary = await scanRepositoryOnce({ ...options, attempt: 1 });
+            reportProgress(progress, {
+                kind: 'scan', operation, scope, phase: 'terminal', status: summary.enrichment.state === 'complete' || summary.enrichment.state === 'disabled' ? 'completed' : 'degraded',
+                repository: summary.repository, attempt: 1, detail: summary.enrichment.state === 'complete' || summary.enrichment.state === 'disabled' ? 'scan complete' : `scan complete with enrichment ${summary.enrichment.state}`,
+                counts: { processed: summary.filesScanned, skipped: summary.skipped.length, pending: summary.enrichment.pending, complete: summary.enrichment.complete, failed: summary.enrichment.failed }
+            });
+            return summary;
+        }
+        catch (error) {
+            reportProgress(progress, { kind: 'scan', operation, scope, phase: 'terminal', status: 'failed', repository: repositoryForRoot(options.root), detail: diagnosticFor(error) });
+            throw error;
+        }
+    }
+    for (let attempt = 1; attempt <= MAX_FULL_ENRICHMENT_ATTEMPTS; attempt += 1) {
+        try {
+            const summary = await scanRepositoryOnce({ ...options, attempt });
+            if (summary.enrichment.pending === 0) {
+                reportProgress(progress, {
+                    kind: 'scan', operation, scope, phase: 'terminal', status: summary.enrichment.state === 'complete' || summary.enrichment.state === 'disabled' ? 'completed' : 'degraded',
+                    repository: summary.repository, attempt, detail: summary.enrichment.state === 'complete' || summary.enrichment.state === 'disabled' ? 'full scan complete; enrichment stabilized' : `full scan complete with enrichment ${summary.enrichment.state}`,
+                    counts: { processed: summary.filesScanned, skipped: summary.skipped.length, pending: summary.enrichment.pending, complete: summary.enrichment.complete, failed: summary.enrichment.failed }
+                });
+                return summary;
+            }
+            if (attempt < MAX_FULL_ENRICHMENT_ATTEMPTS) {
+                reportProgress(progress, { kind: 'scan', operation, scope, phase: 'enrichment', status: 'retrying', repository: summary.repository, attempt, detail: `enrichment pending after attempt ${attempt}; retrying`, counts: { pending: summary.enrichment.pending } });
+            }
+        }
+        catch (error) {
+            reportProgress(progress, { kind: 'scan', operation, scope, phase: 'terminal', status: 'failed', repository: repositoryForRoot(options.root), attempt, detail: diagnosticFor(error) });
+            throw error;
+        }
+    }
+    const error = new Error(`full scan enrichment did not stabilize after ${MAX_FULL_ENRICHMENT_ATTEMPTS} attempts`);
+    reportProgress(progress, { kind: 'scan', operation, scope, phase: 'terminal', status: 'failed', repository: repositoryForRoot(options.root), attempt: MAX_FULL_ENRICHMENT_ATTEMPTS, detail: error.message });
+    throw error;
+}
+async function scanRepositoryOnce({ root = process.cwd(), scope = 'repo', plugins = [], attribution = false, pluginLimits, full = false, enrichmentRunner, progress, attempt = 1 } = {}) {
     const repository = repositoryForRoot(root);
+    const attributionEnabled = attribution || plugins.some((plugin) => plugin.name === ATTRIBUTION_PLUGIN_NAME);
     const scopes = normalizeScope(scope);
     const files = discoverSourceFiles(repository.root);
-    const configuredPlugins = [
-        ...(existsSync(path.join(repository.root, 'package.json')) ? [PackagePlugin] : []),
-        ...plugins.filter((plugin) => plugin.name !== PackagePlugin.name)
-    ];
-    const pluginRun = await runScannerPlugins(createRepositoryScanContext(repository.root), configuredPlugins, pluginLimits);
+    const operation = full ? 'full' : 'incremental';
+    reportProgress(progress, { kind: 'scan', operation, scope, phase: 'discovery', status: 'started', repository, attempt, detail: 'discovering source files' });
     const opened = scopes.map((graphScope) => {
         const databasePath = databasePathForScope(graphScope, repository.root);
         return { scope: graphScope, databasePath, db: openGraphDatabase(databasePath) };
     });
+    const inventoriesByScope = opened.map((handle) => new Map(selectFileInventory(handle.db, repository.id).map((entry) => [entry.path, entry])));
+    const currentManifestScan = inspectRepositoryManifests(repository.root);
+    const manifestRowsByScope = opened.map((handle) => selectManifestInventory(handle.db, repository.id));
+    const previousManifestRecords = manifestRowsByScope[0] ? manifestRowsAsRecords(manifestRowsByScope[0]) : [];
+    const manifests = mergeManifestInventories(currentManifestScan.manifests, previousManifestRecords, currentManifestScan.complete);
+    const previousManifestByPath = new Map(previousManifestRecords.map((manifest) => [manifest.path, manifest]));
+    const currentManifestPaths = new Set(currentManifestScan.manifests.map((manifest) => manifest.path));
+    const changedManifests = manifests.filter((manifest) => {
+        if (manifest.status === 'confirmed_deleted')
+            return false;
+        const previous = previousManifestByPath.get(manifest.path);
+        return !previous || previous.status !== manifest.status || previous.size !== manifest.size || previous.mtimeMs !== manifest.mtimeMs || previous.sourceHash !== manifest.sourceHash;
+    }).map((manifest) => manifest.path);
+    const deletedManifests = manifests.filter((manifest) => manifest.status === 'confirmed_deleted' && !currentManifestPaths.has(manifest.path)).map((manifest) => manifest.path);
+    const hasPythonFiles = files.some((file) => file.toLowerCase().endsWith('.py')) || inventoriesByScope.some((inventory) => [...inventory.keys()].some((file) => file.toLowerCase().endsWith('.py')));
+    const hasJavaFiles = files.some((file) => file.toLowerCase().endsWith('.java')) || inventoriesByScope.some((inventory) => [...inventory.keys()].some((file) => file.toLowerCase().endsWith('.java')));
+    const hasJavaManifests = manifests.some((manifest) => manifest.status !== 'confirmed_deleted');
+    const hasPriorJavaDependencyContribution = opened[0]
+        ? loadPluginContributions(opened[0].db, repository, [JavaDependencyPlugin.name]).has(JavaDependencyPlugin.name)
+        : false;
+    const configuredPlugins = [
+        ...(hasPythonFiles || plugins.some((plugin) => plugin.name === PythonScannerPlugin.name) ? [PythonScannerPlugin] : []),
+        ...(hasJavaFiles || plugins.some((plugin) => plugin.name === JavaScannerPlugin.name) ? [JavaScannerPlugin] : []),
+        ...(existsSync(path.join(repository.root, 'package.json')) ? [PackagePlugin] : []),
+        // Keep the analyzer active for current manifests and for one final
+        // reconciliation after a restart/deletion of the last manifest.
+        ...(hasJavaManifests || hasPriorJavaDependencyContribution ? [JavaDependencyPlugin] : []),
+        ...(attribution || plugins.some((plugin) => plugin.name === ATTRIBUTION_PLUGIN_NAME) ? [AttributionPlugin] : []),
+        ...plugins.filter((plugin) => ![PackagePlugin.name, PythonScannerPlugin.name, JavaScannerPlugin.name, JavaDependencyPlugin.name, ATTRIBUTION_PLUGIN_NAME].includes(plugin.name))
+    ];
+    const historyFingerprint = attributionEnabled ? gitHeadFingerprint(repository.root) : null;
+    const priorHistoryFingerprint = attributionEnabled && opened[0]
+        ? opened[0].db.prepare(`SELECT history_fingerprint AS historyFingerprint FROM file_enrichment_state WHERE repository_id = ? ORDER BY updated_at DESC LIMIT 1`).get(repository.id)?.historyFingerprint ?? null
+        : null;
+    const historyChanged = attributionEnabled && historyFingerprint !== priorHistoryFingerprint;
+    const missingAttributionState = attributionEnabled && opened[0]
+        ? Number(opened[0].db.prepare(`
+      SELECT count(*) AS count FROM files f
+      WHERE f.repository_id = ? AND NOT EXISTS (
+        SELECT 1 FROM file_enrichment_state e
+        WHERE e.file_id = f.id AND e.plugin_name = ?
+      )
+    `).get(repository.id, ATTRIBUTION_PLUGIN_NAME).count) > 0
+        : false;
+    const filesToScan = full || historyChanged || missingAttributionState || inventoriesByScope.some((inventory) => inventory.size === 0)
+        ? files
+        : files.filter((relativePath) => {
+            try {
+                const stat = statSync(path.join(repository.root, relativePath));
+                return inventoriesByScope.some((inventory) => {
+                    const previous = inventory.get(relativePath);
+                    if (!previous || previous.size !== stat.size || previous.mtimeMs !== Math.round(stat.mtimeMs))
+                        return true;
+                    // Filesystem metadata can remain unchanged when an editor rewrites a
+                    // file in place. Compare the persisted source hash before deciding
+                    // that an incremental scan may safely skip the file.
+                    try {
+                        return previous.hash !== sha256(readFileSync(path.join(repository.root, relativePath), 'utf8'));
+                    }
+                    catch {
+                        return true;
+                    }
+                });
+            }
+            catch {
+                return true;
+            }
+        });
+    const deletedPaths = [...new Set(inventoriesByScope.flatMap((inventory) => [...inventory.keys()].filter((relativePath) => !files.includes(relativePath))))];
+    reportProgress(progress, {
+        kind: 'scan', operation, scope, phase: 'discovery', status: 'completed', repository, attempt,
+        detail: `planned ${filesToScan.length} selected file(s)`,
+        counts: { discovered: files.length, selected: filesToScan.length, unchanged: Math.max(0, files.length - filesToScan.length), deleted: deletedPaths.length }
+    });
+    const previousContributions = opened[0]
+        ? loadPluginContributions(opened[0].db, repository, configuredPlugins.map((plugin) => plugin.name))
+        : new Map();
+    reportProgress(progress, { kind: 'scan', operation, scope, phase: 'plugins', status: 'started', repository, attempt, counts: { plugins: configuredPlugins.length } });
+    const pluginRun = await runScannerPlugins(createRepositoryScanContext(repository.root, manifests), configuredPlugins, pluginLimits, { changedPaths: filesToScan, deletedPaths, changedManifests, deletedManifests, manifestsComplete: currentManifestScan.complete, full: full || inventoriesByScope.some((inventory) => inventory.size === 0) }, previousContributions);
     let filesScanned = 0;
     let nodesWritten = 0;
     let edgesWritten = 0;
     const skipped = [];
     const stalePlugins = [];
+    let inventoryGeneration = 1;
     try {
         const primary = opened[0];
         const contributions = new Map(pluginRun.pluginContributions ?? new Map());
@@ -100,8 +231,8 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo', plu
         }
         if (primary) {
             upsertRepository(primary.db, repository);
-            const generation = nextPluginGeneration(primary.db, repository);
-            persistPluginContributions(primary.db, repository, contributions, generation);
+            inventoryGeneration = nextPluginGeneration(primary.db, repository);
+            persistPluginContributions(primary.db, repository, contributions, inventoryGeneration);
             const previous = loadPluginContributions(primary.db, repository, pluginRun.failedPlugins ?? []);
             for (const pluginName of pluginRun.failedPlugins ?? []) {
                 const contribution = previous.get(pluginName);
@@ -121,60 +252,104 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo', plu
             persistPluginContributions(handle.db, repository, contributions, nextPluginGeneration(handle.db, repository));
         }
         const activePlugins = [...(pluginRun.successfulPlugins ?? []), ...stalePlugins];
+        reportProgress(progress, {
+            kind: 'scan', operation, scope, phase: 'plugins', status: pluginRun.failedPlugins.length > 0 || stalePlugins.length > 0 ? 'degraded' : 'completed', repository, attempt,
+            detail: pluginRun.failedPlugins.length > 0
+                ? `failed plugins: ${pluginRun.failedPlugins.join(', ')}${stalePlugins.length > 0 ? `; reused stale: ${stalePlugins.join(', ')}` : ''}`
+                : 'plugin work complete',
+            counts: { plugins: configuredPlugins.length, failedPlugins: pluginRun.failedPlugins.length, stalePlugins: stalePlugins.length }
+        });
         for (const handle of opened) {
             upsertRepository(handle.db, repository);
             reconcileRepositoryPluginNodes(handle.db, repository, activePlugins);
             insertRepositoryPluginNodes(handle.db, repository, pluginRun.nodes);
         }
-        for (const relativePath of files) {
-            const absolutePath = path.join(repository.root, relativePath);
-            const source = readFileSync(absolutePath, 'utf8');
-            const parseResult = parseSource(absolutePath, source);
-            if (!parseResult) {
+        reportProgress(progress, { kind: 'scan', operation, scope, phase: 'files', status: 'started', repository, attempt, counts: { selected: filesToScan.length } });
+        const scanTasks = [];
+        const preScanFailures = new Map();
+        for (const relativePath of filesToScan) {
+            if ((pluginRun.failedPaths ?? []).includes(relativePath))
+                continue;
+            try {
+                const absolutePath = path.join(repository.root, relativePath);
+                const source = readFileSync(absolutePath, 'utf8');
+                const stat = statSync(absolutePath);
+                scanTasks.push({
+                    repositoryId: repository.id,
+                    relativePath,
+                    absolutePath,
+                    source,
+                    sourceHash: sha256(source),
+                    mtimeMs: Math.round(stat.mtimeMs)
+                });
+            }
+            catch (error) {
+                preScanFailures.set(relativePath, error instanceof Error ? error.message : String(error));
+            }
+        }
+        const scanResults = await runBatchedWorkers(scanTasks, new URL('./repositoryScanWorker.js', import.meta.url), (batch) => batch);
+        const scanResultsByPath = new Map(scanResults.flatMap((batch) => batch.map((result) => [result.relativePath, result])));
+        for (const relativePath of filesToScan) {
+            // A file-level plugin parse failure retains its prior graph contribution
+            // and is surfaced as degraded freshness; never replace it with partial
+            // Tree-sitter facts from an ERROR tree.
+            if ((pluginRun.failedPaths ?? []).includes(relativePath)) {
                 skipped.push(relativePath);
+                const diagnostic = pluginRun.diagnostics.find((message) => message.includes(relativePath)) ?? `${relativePath}: plugin parse failed`;
+                for (const handle of opened)
+                    recordFileScanFailure(handle.db, repository.id, relativePath, diagnostic);
+                continue;
+            }
+            const result = scanResultsByPath.get(relativePath);
+            const diagnostic = preScanFailures.get(relativePath) ?? result?.error;
+            if (!result || diagnostic) {
+                skipped.push(relativePath);
+                const message = diagnostic ?? 'scanner worker returned no result';
+                for (const handle of opened)
+                    recordFileScanFailure(handle.db, repository.id, relativePath, message);
+                reportProgress(progress, { kind: 'scan', operation, scope, phase: 'files', status: 'skipped', repository, attempt, path: relativePath, detail: message, counts: { processed: filesScanned, skipped: skipped.length } });
                 continue;
             }
-            const stat = statSync(absolutePath);
-            const sourceHash = sha256(source);
-            const fileId = hashParts([repository.id, relativePath]);
             const file = {
-                id: fileId,
+                id: hashParts([repository.id, relativePath]),
                 path: relativePath,
-                language: parseResult.language,
-                hash: sourceHash,
-                size: stat.size,
-                mtimeMs: Math.round(stat.mtimeMs)
+                language: result.language,
+                hash: result.sourceHash,
+                size: result.size,
+                mtimeMs: result.mtimeMs
             };
-            const builtInGraph = extractGraph({
-                repositoryId: repository.id,
-                fileId,
-                relativePath,
-                source,
-                sourceHash,
-                parseResult
-            });
+            const builtInGraph = result.graph ?? { nodes: [], edges: [] };
             const normalizedRelativePath = normalizePluginFilePath(relativePath);
             const pluginNodes = pluginRun.nodes.filter((node) => normalizePluginFilePath(node.metadata.filePath) === normalizedRelativePath);
             const graph = {
                 nodes: [...builtInGraph.nodes, ...pluginNodes],
                 edges: builtInGraph.edges
             };
-            const attribution = buildFileAttribution({
-                root: repository.root,
-                relativePath,
-                source,
-                nodes: graph.nodes
-            });
             for (const handle of opened) {
-                replaceFileGraph(handle.db, { repository, file, nodes: graph.nodes, edges: graph.edges, attribution });
+                replaceFileGraph(handle.db, {
+                    repository,
+                    file,
+                    nodes: graph.nodes,
+                    edges: graph.edges,
+                    ...(attributionEnabled ? { enrichment: { pluginName: ATTRIBUTION_PLUGIN_NAME, historyFingerprint } } : {})
+                });
+                clearFileScanFailure(handle.db, repository.id, relativePath);
             }
             filesScanned += 1;
-            nodesWritten += graph.nodes.length + (attribution?.contributorEmails.length ?? 0);
-            edgesWritten += graph.edges.length + (attribution?.nodeAttributions.reduce((sum, entry) => sum + entry.contributorEmails.length, 0) ?? 0);
+            nodesWritten += graph.nodes.length;
+            edgesWritten += graph.edges.length;
+            reportProgress(progress, { kind: 'scan', operation, scope, phase: 'files', status: 'processed', repository, attempt, path: relativePath, counts: { processed: filesScanned, skipped: skipped.length } });
+        }
+        reportProgress(progress, { kind: 'scan', operation, scope, phase: 'reconciliation', status: 'started', repository, attempt, counts: { deleted: deletedPaths.length } });
+        const manifestTraversalDegraded = !currentManifestScan.complete || manifests.some((manifest) => manifest.status === 'read_failed' || manifest.status === 'traversal_incomplete');
+        for (const handle of opened) {
+            reconcileDeletedFiles(handle.db, repository.id, files);
+            persistManifestInventoryAndScanState(handle.db, repository.id, manifests, inventoryGeneration, skipped.length > 0 || manifestTraversalDegraded || pluginRun.failedPlugins.length > 0 || stalePlugins.length > 0 ? 'degraded' : 'fresh');
         }
-        const persistedFileIds = new Map(files
-            .filter((relativePath) => !skipped.includes(relativePath))
-            .map((relativePath) => [normalizePluginFilePath(relativePath) ?? relativePath, hashParts([repository.id, relativePath])]));
+        const persistedFileIds = new Map(
+        // Failed paths retain their previous persisted file graph, so they are
+        // still valid owners for retained plugin facts during reconciliation.
+        files.map((relativePath) => [normalizePluginFilePath(relativePath) ?? relativePath, hashParts([repository.id, relativePath])]));
         const unresolvedOwnership = diagnoseUnresolvedPluginOwnership(pluginRun.nodes, pluginRun.edges, persistedFileIds);
         const diagnosticLimit = pluginLimits?.maxDiagnostics ?? DEFAULT_PLUGIN_RESOURCE_LIMITS.maxDiagnostics;
         const messageLimit = pluginLimits?.maxDiagnosticMessageBytes ?? DEFAULT_PLUGIN_RESOURCE_LIMITS.maxDiagnosticMessageBytes;
@@ -185,11 +360,25 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo', plu
             edgesWritten += reconcilePluginEdges(opened[0].db, repository, pluginRun.edges, persistedFileIds, activePlugins);
         for (const handle of opened.slice(1))
             reconcilePluginEdges(handle.db, repository, pluginRun.edges, persistedFileIds, activePlugins);
+        reportProgress(progress, { kind: 'scan', operation, scope, phase: 'reconciliation', status: 'completed', repository, attempt, counts: { deleted: deletedPaths.length, processed: filesScanned, skipped: skipped.length } });
     }
     finally {
         for (const handle of opened)
             closeDatabase(handle.db);
     }
+    reportProgress(progress, { kind: 'scan', operation, scope, phase: 'enrichment', status: 'started', repository, attempt });
+    const selectedEnrichmentPlugin = pluginRun.enrichmentPlugins?.get(ATTRIBUTION_PLUGIN_NAME);
+    const selectedRunner = enrichmentRunner ?? (selectedEnrichmentPlugin?.enrich?.bind(selectedEnrichmentPlugin));
+    const enrichment = attributionEnabled && full
+        ? await drainRepositoryEnrichment({ root: repository.root, scope, enrichmentRunner: selectedRunner, pluginName: ATTRIBUTION_PLUGIN_NAME, historyFingerprint })
+        : attributionEnabled
+            ? summarizeRepositoryEnrichment(repository, scopes)
+            : disabledEnrichmentSummary();
+    reportProgress(progress, {
+        kind: 'scan', operation, scope, phase: 'enrichment', status: enrichment.state === 'complete' || enrichment.state === 'disabled' ? 'completed' : enrichment.state === 'pending' ? 'deferred' : 'degraded', repository, attempt,
+        detail: enrichment.state === 'pending' ? 'structural scan complete; enrichment deferred' : enrichment.state === 'failed' ? 'enrichment failed; scan is degraded' : enrichment.state === 'disabled' ? 'optional enrichment disabled' : 'enrichment complete',
+        counts: { pending: enrichment.pending, complete: enrichment.complete, failed: enrichment.failed }
+    });
     return {
         repository,
         scopes: opened.map(({ scope: graphScope, databasePath }) => ({ scope: graphScope, databasePath })),
@@ -198,47 +387,207 @@ export async function scanRepository({ root = process.cwd(), scope = 'repo', plu
         nodesWritten,
         edgesWritten,
         skipped,
+        enrichment,
         pluginDiagnostics: pluginRun.diagnostics,
         failedPlugins: pluginRun.failedPlugins,
         stalePlugins
     };
 }
-export function graphStatus({ root = process.cwd(), scope = 'repo' } = {}) {
+export const defaultEnrichmentRunner = ({ repository, work, source, nodes }) => buildFileAttribution({
+    root: repository.root,
+    relativePath: work.path,
+    source,
+    nodes
+});
+/**
+ * Drains persisted, hash-compatible attribution work. This is deliberately
+ * explicit: one-shot structural scans persist work but never start it.
+ */
+export async function drainRepositoryEnrichment({ root = process.cwd(), scope = 'repo', enrichmentRunner = defaultEnrichmentRunner, pluginName = ATTRIBUTION_PLUGIN_NAME, historyFingerprint = null } = {}) {
     const repository = repositoryForRoot(root);
-    return withScopes(repository, scope, (db, graphScope, databasePath) => ({
-        scope: graphScope,
-        databasePath,
-        ...getStatus(db, repository.id)
+    const scopes = normalizeScope(scope);
+    for (const graphScope of scopes) {
+        const db = openGraphDatabase(databasePathForScope(graphScope, repository.root));
+        try {
+            const workItems = selectEnrichmentWork(db, repository.id).filter((work) => work.pluginName === pluginName && (historyFingerprint === null || work.historyFingerprint === historyFingerprint));
+            for (const work of workItems) {
+                let outcome;
+                try {
+                    const source = readFileSync(path.join(repository.root, work.path), 'utf8');
+                    // Work is tied to the structural source hash. Leave incompatible work
+                    // pending for the next structural scan instead of applying it late.
+                    if (sha256(source) !== work.sourceHash)
+                        continue;
+                    outcome = await enrichmentRunner({
+                        repository,
+                        work,
+                        source,
+                        nodes: selectStructuralNodesForEnrichment(db, work)
+                    });
+                    // The runner can be asynchronous, so verify the source again before
+                    // committing its result. A changed file remains pending and a full
+                    // scan will rebuild its structural graph before retrying enrichment.
+                    if (sha256(readFileSync(path.join(repository.root, work.path), 'utf8')) !== work.sourceHash)
+                        continue;
+                }
+                catch (error) {
+                    outcome = { status: 'failed', diagnostic: `enrichment failed: ${diagnosticFor(error)}` };
+                }
+                applyFileAttribution(db, { repository, fileId: work.fileId, sourceHash: work.sourceHash, outcome, pluginName, historyFingerprint });
+            }
+        }
+        finally {
+            closeDatabase(db);
+        }
+    }
+    return summarizeRepositoryEnrichment(repository, scopes);
+}
+function disabledEnrichmentSummary() {
+    return { state: 'disabled', pending: 0, complete: 0, failed: 0, unavailable: 0, notApplicable: 0, diagnostics: [] };
+}
+function gitHeadFingerprint(root) {
+    try {
+        const result = spawnSync('git', ['-C', root, 'rev-parse', '--verify', 'HEAD'], { encoding: 'utf8' });
+        if (result.status !== 0)
+            return null;
+        const head = String(result.stdout ?? '').trim();
+        return head || null;
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeRepositoryEnrichment(repository, scopes) {
+    const states = [];
+    for (const graphScope of scopes) {
+        const db = openGraphDatabase(databasePathForScope(graphScope, repository.root));
+        try {
+            states.push(...selectFileEnrichmentStates(db, repository.id, ['pending', 'complete', 'failed']));
+        }
+        finally {
+            closeDatabase(db);
+        }
+    }
+    const pending = states.filter((entry) => entry.state === 'pending').length;
+    const complete = states.filter((entry) => entry.state === 'complete').length;
+    const failedEntries = states.filter((entry) => entry.state === 'failed');
+    const unavailableEntries = states.filter((entry) => entry.outcome === 'unavailable');
+    return {
+        state: failedEntries.length > 0 ? 'failed' : pending > 0 ? 'pending' : 'complete',
+        pending,
+        complete: complete - unavailableEntries.length,
+        failed: failedEntries.length,
+        unavailable: unavailableEntries.length,
+        notApplicable: unavailableEntries.filter((entry) => entry.diagnostic === 'unavailable:not_applicable').length,
+        diagnostics: failedEntries.flatMap((entry) => entry.diagnostic ? [entry.diagnostic] : [])
+    };
+}
+function selectStructuralNodesForEnrichment(db, work) {
+    const rows = db.prepare(`
+    SELECT id, kind, type, name, start_byte AS startByte, end_byte AS endByte,
+      start_point AS startPoint, end_point AS endPoint, source_hash AS sourceHash,
+      parser, parser_version AS parserVersion, metadata_json AS metadataJson,
+      last_modified_user_id AS lastModifiedUserId
+    FROM nodes
+    WHERE repository_id = ? AND file_id = ? AND source_hash = ?
+    ORDER BY id
+  `).all(work.repositoryId, work.fileId, work.sourceHash);
+    return rows.map((row) => ({
+        ...row,
+        startPoint: JSON.parse(row.startPoint),
+        endPoint: JSON.parse(row.endPoint),
+        metadata: parseMetadata(row.metadataJson)
     }));
 }
+function parseMetadata(value) {
+    try {
+        const parsed = JSON.parse(value);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function diagnosticFor(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function reportProgress(reporter, event) {
+    // Progress is observational: a faulty consumer must never change scan
+    // semantics or turn a successful scan into a failed one.
+    try {
+        reporter?.(event);
+    }
+    catch { /* diagnostics must not affect scanning */ }
+}
+export function graphStatus({ root = process.cwd(), scope = 'repo' } = {}) {
+    const repository = repositoryForRoot(root);
+    return withReadOnlyScopes(repository, scope, (db, graphScope, databasePath) => db
+        ? { scope: graphScope, databasePath, ...getStatus(db, repository.id) }
+        : {
+            scope: graphScope,
+            databasePath,
+            repository: null,
+            files: 0,
+            nodes: 0,
+            edges: 0,
+            freshness: { state: 'stale', reason: 'not_scanned' },
+            enrichment: disabledEnrichmentSummary()
+        });
+}
 export function listNodes({ root = process.cwd(), scope = 'repo', kind, limit = 50 } = {}) {
     const repository = repositoryForRoot(root);
-    return withScopes(repository, scope, (db, graphScope) => selectNodes(db, repository.id, { kind, limit }).map((row) => ({ scope: graphScope, ...row }))).flat();
+    return withReadOnlyScopes(repository, scope, (db, graphScope) => {
+        if (!db)
+            return [];
+        const freshness = selectFreshnessReport(db, repository.id);
+        return selectNodes(db, repository.id, { kind, limit }).map((row) => ({ scope: graphScope, freshness, ...row }));
+    }).flat();
 }
 export function listNodeText({ root = process.cwd(), scope = 'repo', kind, term, limit = 50 } = {}) {
     const repository = repositoryForRoot(root);
-    return withScopes(repository, scope, (db, graphScope) => selectNodeTextRows(db, repository.id, { kind, term, limit }).map((row) => ({
-        scope: graphScope,
-        root: repository.root,
-        ...row,
-        path: row.path ? path.resolve(repository.root, row.path) : null
-    }))).flat();
+    return withReadOnlyScopes(repository, scope, (db, graphScope) => {
+        if (!db)
+            return [];
+        const freshness = selectFreshnessReport(db, repository.id);
+        return selectNodeTextRows(db, repository.id, { kind, term, limit }).map((row) => ({
+            scope: graphScope,
+            root: repository.root,
+            freshness,
+            ...row,
+            path: row.path ? path.resolve(repository.root, row.path) : null
+        }));
+    }).flat();
 }
-export function listEdges({ root = process.cwd(), scope = 'repo', kind, limit = 50 } = {}) {
+export function listEdges({ root = process.cwd(), scope = 'repo', kind, type, limit = 50 } = {}) {
     const repository = repositoryForRoot(root);
-    return withScopes(repository, scope, (db, graphScope) => selectEdges(db, repository.id, { kind, limit }).map((row) => ({ scope: graphScope, ...row }))).flat();
+    return withReadOnlyScopes(repository, scope, (db, graphScope) => {
+        if (!db)
+            return [];
+        const freshness = selectFreshnessReport(db, repository.id);
+        return selectEdges(db, repository.id, { kind, type, limit }).map((row) => ({ scope: graphScope, freshness, ...row }));
+    }).flat();
 }
 export function neighbors({ root = process.cwd(), scope = 'repo', nodeId, depth = 1, limit = 100 } = {}) {
     if (!nodeId)
         throw new Error('neighbors requires a nodeId');
     const repository = repositoryForRoot(root);
-    return withScopes(repository, scope, (db, graphScope) => selectNeighbors(db, repository.id, nodeId, { depth, limit }).map((row) => ({ scope: graphScope, ...row }))).flat();
+    return withReadOnlyScopes(repository, scope, (db, graphScope) => {
+        if (!db)
+            return [];
+        const freshness = selectFreshnessReport(db, repository.id);
+        return selectNeighbors(db, repository.id, nodeId, { depth, limit }).map((row) => ({ scope: graphScope, freshness, ...row }));
+    }).flat();
 }
 export function callGraph({ root = process.cwd(), scope = 'repo', term, kind, depth = 5, limit = 100 } = {}) {
     if (!term?.trim())
         throw new Error('callgraph requires a term');
     const repository = repositoryForRoot(root);
-    return withScopes(repository, scope, (db, graphScope) => selectCallGraph(db, repository.id, term.trim(), { kind, depth, limit }).map((row) => ({ scope: graphScope, ...row }))).flat();
+    return withReadOnlyScopes(repository, scope, (db, graphScope) => {
+        if (!db)
+            return [];
+        const freshness = selectFreshnessReport(db, repository.id);
+        return selectCallGraph(db, repository.id, term.trim(), { kind, depth, limit }).map((row) => ({ scope: graphScope, freshness, ...row }));
+    }).flat();
 }
 const CONTEXT_DEFAULTS = {
     depth: 2,
@@ -277,63 +626,15 @@ export async function contextGraph(options) {
 }
 async function contextForScope(repository, graphScope, request, excerpts) {
     const databasePath = databasePathForScope(graphScope, repository.root);
-    const discovered = discoverSourceFiles(repository.root);
-    const beforeFingerprint = collectRepositoryFingerprint(repository.root);
-    let db = openGraphDatabase(databasePath);
-    let refresh = {
-        outcome: 'reused', filesDiscovered: discovered.length, filesScanned: 0, skipped: []
-    };
-    let freshness = 'unchanged';
-    let priorGraph = false;
+    let db;
     try {
-        upsertRepository(db, repository);
-        const inventory = selectFileInventory(db, repository.id);
-        priorGraph = inventory.length > 0;
-        const inventoryChanged = inventory.length !== discovered.length || discovered.some((file, index) => {
-            const row = inventory[index];
-            if (!row || row.path !== file)
-                return true;
-            try {
-                const stat = statSync(path.join(repository.root, file));
-                return row.size !== stat.size || row.mtimeMs !== Math.round(stat.mtimeMs);
-            }
-            catch {
-                return true;
-            }
-        });
-        if (inventoryChanged) {
-            closeDatabase(db);
-            db = undefined;
-            try {
-                const summary = await scanRepository({ root: repository.root, scope: graphScope });
-                refresh = {
-                    outcome: summary.skipped.length > 0 ? 'refresh_failed' : 'refreshed',
-                    filesDiscovered: summary.filesDiscovered,
-                    filesScanned: summary.filesScanned,
-                    skipped: summary.skipped
-                };
-                if (summary.skipped.length > 0)
-                    return failedContextScope(graphScope, databasePath, refresh, priorGraph);
-                const refreshedDb = openGraphDatabase(databasePath);
-                try {
-                    reconcileDeletedFiles(refreshedDb, repository.id, discovered);
-                }
-                finally {
-                    closeDatabase(refreshedDb);
-                }
-                freshness = 'refreshed';
-                db = openGraphDatabase(databasePath);
-                upsertRepository(db, repository);
-            }
-            catch (error) {
-                refresh = { ...refresh, outcome: 'refresh_failed', skipped: [error instanceof Error ? error.message : String(error)] };
-                return failedContextScope(graphScope, databasePath, refresh, priorGraph);
-            }
-        }
-        const afterFingerprint = collectRepositoryFingerprint(repository.root);
-        if (afterFingerprint !== beforeFingerprint) {
-            return failedContextScope(graphScope, databasePath, refresh, priorGraph, 'stale');
-        }
+        db = openReadOnlyGraphDatabase(databasePath);
+    }
+    catch {
+        return emptyContextScope(graphScope, databasePath, { state: 'stale', reason: 'not_scanned' });
+    }
+    try {
+        const freshness = selectFreshnessReport(db, repository.id);
         const candidateRows = selectContextCandidates(db, repository.id, request.symbol, {
             kind: request.kind,
             file: request.file,
@@ -344,11 +645,12 @@ async function contextForScope(repository, graphScope, request, excerpts) {
         const truncation = candidateTruncated
             ? [{ section: 'candidates', reason: 'candidate_limit', omitted: 1 }]
             : [];
+        const excerptWarning = excerpts ? ['excerpt_unavailable:stored_graph_only'] : [];
         if (candidates.length === 0) {
-            return { scope: graphScope, databasePath, result: { state: 'not_found', impact: [], dependencies: [], warnings: [], truncation }, freshness: { state: freshness, verification: 'metadata_only', refresh } };
+            return { scope: graphScope, databasePath, result: { state: 'not_found', impact: [], dependencies: [], warnings: excerptWarning, truncation }, freshness };
         }
         if (candidateTruncated || candidates.length !== 1) {
-            return { scope: graphScope, databasePath, result: { state: 'ambiguous', candidates: candidates.map(stripCandidate), impact: [], dependencies: [], warnings: [], truncation }, freshness: { state: freshness, verification: 'metadata_only', refresh } };
+            return { scope: graphScope, databasePath, result: { state: 'ambiguous', candidates: candidates.map(stripCandidate), impact: [], dependencies: [], warnings: excerptWarning, truncation }, freshness };
         }
         const anchor = stripInternalReference(candidates[0]);
         const rawRelations = request.budget.depth === 0
@@ -366,35 +668,27 @@ async function contextForScope(repository, graphScope, request, excerpts) {
                 dependencies.push({ category: 'dependency', edgeKind: relation.edgeKind, direction: relation.edgeKind === 'imports' ? 'import' : 'export', source, target, confidence: relation.confidence, provenance: relation.metadata, depth: relation.depth });
             }
         }
-        const warnings = candidates[0]?.match === 'substring' ? ['substring_search=bounded_like'] : [];
-        let verification = 'metadata_only';
-        if (excerpts) {
-            const excerptStatus = await addExcerpt(repository.root, anchor, request.budget);
-            if (excerptStatus === 'checked')
-                verification = 'content_hash';
-            if (excerptStatus === 'unavailable')
-                warnings.push('excerpt_unavailable');
-            if (excerptStatus === 'mismatch')
-                warnings.push('excerpt_unavailable:source_hash_mismatch');
-        }
+        const warnings = [
+            ...(candidates[0]?.match === 'substring' ? ['substring_search=bounded_like'] : []),
+            ...excerptWarning
+        ];
         return {
             scope: graphScope,
             databasePath,
             result: { state: 'ok', anchor, definition: anchor, impact, dependencies, warnings, truncation },
-            freshness: { state: freshness, verification, refresh }
+            freshness
         };
     }
     finally {
-        if (db)
-            closeDatabase(db);
+        closeDatabase(db);
     }
 }
-function failedContextScope(scope, databasePath, refresh, priorGeneration, state = 'refresh_failed') {
+function emptyContextScope(scope, databasePath, freshness) {
     return {
         scope,
         databasePath,
-        result: { state, impact: [], dependencies: [], warnings: refresh.skipped, truncation: [] },
-        freshness: { state: state === 'stale' || priorGeneration ? 'stale' : 'refresh_failed', verification: 'metadata_only', refresh: { ...refresh, outcome: state === 'stale' ? refresh.outcome : 'refresh_failed' } }
+        result: { state: 'not_found', impact: [], dependencies: [], warnings: [], truncation: [] },
+        freshness
     };
 }
 function stripCandidate(candidate) {
@@ -405,24 +699,6 @@ function stripInternalReference(reference) {
     const { fileId: _fileId, rank: _rank, match: _match, ...publicReference } = reference;
     return publicReference;
 }
-async function addExcerpt(root, anchor, budget) {
-    if (!anchor.path || !anchor.sourceHash)
-        return 'unavailable';
-    try {
-        const source = readFileSync(path.join(root, anchor.path), 'utf8');
-        if (sha256(source) !== anchor.sourceHash)
-            return 'mismatch';
-        const lines = source.split(/\r?\n/);
-        const start = Math.max(0, anchor.span.start.row);
-        const end = Math.min(lines.length, start + budget.excerptLines);
-        const bounded = Buffer.from(lines.slice(start, end).join('\\n'), 'utf8').subarray(0, budget.excerptBytes).toString('utf8');
-        anchor.excerpt = bounded;
-        return 'checked';
-    }
-    catch {
-        return 'unavailable';
-    }
-}
 function clampContext(value, min, max, fallback) {
     if (value === undefined || !Number.isFinite(value))
         return fallback;
@@ -432,21 +708,29 @@ export function runReadOnlySql({ root = process.cwd(), scope = 'repo', sql, atta
     if (!sql)
         throw new Error('query requires SQL text');
     const repository = repositoryForRoot(root);
-    return withScopes(repository, scope, (db, graphScope) => {
+    return withReadOnlyScopes(repository, scope, (db, graphScope) => {
+        if (!db)
+            return { scope: graphScope, rows: [], freshness: { state: 'stale', reason: 'not_scanned' } };
         if (attachHome && graphScope === 'repo')
             attachDatabase(db, 'home_graph', homeDatabasePath());
         const rows = runSelect(db, sql, { limit });
-        return { scope: graphScope, rows };
+        return { scope: graphScope, rows, freshness: selectFreshnessReport(db, repository.id) };
     });
 }
-function withScopes(repository, scope, fn) {
+function withReadOnlyScopes(repository, scope, fn) {
     const scopes = normalizeScope(scope);
     const results = [];
     for (const graphScope of scopes) {
         const databasePath = graphScope === 'repo' ? repoDatabasePath(repository.root) : homeDatabasePath();
-        const db = openGraphDatabase(databasePath);
+        let db;
+        try {
+            db = openReadOnlyGraphDatabase(databasePath);
+        }
+        catch {
+            results.push(fn(undefined, graphScope, databasePath));
+            continue;
+        }
         try {
-            upsertRepository(db, repository);
             results.push(fn(db, graphScope, databasePath));
         }
         finally {