@psnext/lscg 0.1.3 → 0.1.5

package/dist/src/scanner/plugins.js

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto';
 import { readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { discoverSourceFiles } from './discover.js';
+import { inventoryRepositoryManifests } from './artifactInventory.js';
 export const SCANNER_PLUGIN_API_VERSION = 1;
 export const DEFAULT_PLUGIN_RESOURCE_LIMITS = {
     maxNodes: 100_000,
@@ -16,8 +17,9 @@ const GRAPH_NODE_KINDS = new Set(['file', 'symbol', 'import', 'export', 'call',
 const GRAPH_EDGE_KINDS = new Set(['contains', 'defines', 'imports', 'exports', 'calls', 'attributed_to', 'provides']);
 /** Namespace used by plugins to target nodes produced by the built-in scanner. */
 export const BUILTIN_GRAPH_PLUGIN = '__lscg_builtin__';
-export function createRepositoryScanContext(repoPath) {
+export function createRepositoryScanContext(repoPath, suppliedManifests) {
     const discoveredPaths = discoverSourceFiles(repoPath);
+    const manifests = suppliedManifests ? [...suppliedManifests] : inventoryRepositoryManifests(repoPath);
     const files = discoveredPaths.flatMap((relativePath) => {
         try {
             const absolutePath = path.join(repoPath, relativePath);
@@ -38,23 +40,31 @@ export function createRepositoryScanContext(repoPath) {
             return [];
         }
     });
-    return { repoPath, files, discoveredPaths, readFile: (relativePath) => readFileSync(path.join(repoPath, relativePath), 'utf8') };
+    return { repoPath, files, discoveredPaths, manifests, readFile: (relativePath) => readFileSync(path.join(repoPath, relativePath), 'utf8') };
 }
-export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
+export async function runScannerPlugins(context, plugins, resourceLimits = {}, delta, previousContributions = new Map()) {
     const limits = normalizePluginResourceLimits(resourceLimits);
     const nodes = [];
     const edges = [];
     const diagnostics = [];
     const failedPlugins = [];
+    const failedPaths = new Set();
     const successfulPlugins = [];
+    const incrementalRetractions = new Map();
     const owners = new Map();
     for (const plugin of plugins) {
         try {
             validatePlugin(plugin);
             await plugin.initialize?.(context);
-            const result = await plugin.scan(context);
+            const result = plugin.scanIncremental && delta
+                ? await plugin.scanIncremental(context, delta, previousContributions.get(plugin.name))
+                : await plugin.scan(context);
             const finalized = await plugin.finalize?.(context);
+            if (plugin.scanIncremental && delta && 'retractions' in result && result.retractions)
+                incrementalRetractions.set(plugin.name, result.retractions);
             validatePluginResult(plugin.name, result, 'scan');
+            for (const failedPath of result.failedPaths ?? [])
+                failedPaths.add(failedPath);
             if (finalized !== undefined)
                 validatePluginResult(plugin.name, finalized, 'finalize');
             enforceResourceLimits(plugin, result, finalized, limits);
@@ -86,6 +96,15 @@ export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
         return [canonicalNodeIdentity(node.pluginName ?? '', node.factKey), materialized];
     }));
     const materializedNodes = [...nodeByIdentity.values()];
+    for (const [plugin, retractions] of incrementalRetractions) {
+        const previous = previousContributions.get(plugin);
+        const retractedNodeKeys = new Set(retractions.nodes ?? []);
+        for (const node of previous?.nodes ?? []) {
+            const factKey = String(node.metadata.factKey ?? '');
+            if (factKey && !retractedNodeKeys.has(factKey))
+                nodeByIdentity.set(canonicalNodeIdentity(plugin, factKey), node);
+        }
+    }
     const materializedEdges = [];
     for (const edge of edges) {
         const sourceIdentity = canonicalNodeIdentity(edge.sourcePlugin ?? edge.pluginName ?? '', edge.sourceFactKey);
@@ -126,6 +145,33 @@ export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
         if (plugin)
             contributionFor(plugin).edges.push(edge);
     }
+    for (const [plugin, retractions] of incrementalRetractions) {
+        const previous = previousContributions.get(plugin);
+        if (!previous)
+            continue;
+        const current = contributionFor(plugin);
+        const nodeKeys = new Set(retractions.nodes ?? []);
+        const edgeKeys = new Set(retractions.edges ?? []);
+        const currentNodeKeys = new Set(current.nodes.map((node) => String(node.metadata.factKey ?? '')));
+        const currentEdgeKeys = new Set(current.edges.map((edge) => String(edge.metadata.factKey ?? '')));
+        current.nodes = [
+            ...previous.nodes.filter((node) => !nodeKeys.has(String(node.metadata.factKey ?? '')) && !currentNodeKeys.has(String(node.metadata.factKey ?? ''))),
+            ...current.nodes
+        ];
+        current.edges = [
+            ...previous.edges.filter((edge) => !edgeKeys.has(String(edge.metadata.factKey ?? '')) && !currentEdgeKeys.has(String(edge.metadata.factKey ?? ''))),
+            ...current.edges
+        ];
+    }
+    const partiallyReconciledPlugins = new Set(incrementalRetractions.keys());
+    const mergedNodes = [
+        ...materializedNodes.filter((node) => !partiallyReconciledPlugins.has(String(node.metadata.plugin ?? ''))),
+        ...[...partiallyReconciledPlugins].flatMap((plugin) => pluginContributions.get(plugin)?.nodes ?? [])
+    ];
+    const mergedEdges = [
+        ...materializedEdges.filter((edge) => !partiallyReconciledPlugins.has(String(edge.metadata.plugin ?? ''))),
+        ...[...partiallyReconciledPlugins].flatMap((plugin) => pluginContributions.get(plugin)?.edges ?? [])
+    ];
     function contributionFor(plugin) {
         const existing = pluginContributions.get(plugin);
         if (existing)
@@ -134,7 +180,7 @@ export async function runScannerPlugins(context, plugins, resourceLimits = {}) {
         pluginContributions.set(plugin, created);
         return created;
     }
-    return { nodes: materializedNodes, edges: materializedEdges, diagnostics, failedPlugins, successfulPlugins, pluginContributions };
+    return { nodes: mergedNodes, edges: mergedEdges, diagnostics, failedPaths: [...failedPaths].sort(), failedPlugins, successfulPlugins, pluginContributions };
     function collect(plugin, result, nodeOutput, edgeOutput, ownerMap, messages, contributionLimits) {
         for (const node of result.nodes ?? []) {
             const identity = canonicalNodeIdentity(plugin.name, node.factKey);

package/dist/src/scanner/pythonPlugin.d.ts

@@ -0,0 +1,5 @@
+import type { PluginScanResult, RepositoryScanFile, ScannerPlugin } from './plugins.js';
+export declare const PYTHON_SCANNER_PLUGIN_NAME = "python-scanner-plugin";
+export declare function scanPythonFiles(files: readonly RepositoryScanFile[]): PluginScanResult;
+export declare const PythonScannerPlugin: ScannerPlugin;
+//# sourceMappingURL=pythonPlugin.d.ts.map

package/dist/src/scanner/pythonPlugin.js

@@ -0,0 +1,198 @@
+import Parser from 'tree-sitter';
+import { parseSource } from '../parser/treeSitter.js';
+import { runBatchedWorkers } from './parallelScan.js';
+export const PYTHON_SCANNER_PLUGIN_NAME = 'python-scanner-plugin';
+const PYTHON_EXTENSIONS = new Set(['.py']);
+const SYMBOL_TYPES = new Set(['class_definition', 'function_definition', 'assignment']);
+const IMPORT_TYPES = new Set(['import_statement', 'import_from_statement']);
+const CALL_TYPES = new Set(['call']);
+export function scanPythonFiles(files) {
+    const nodes = [];
+    const edges = [];
+    for (const file of files) {
+        if (!isPython(file.path))
+            continue;
+        const parsed = parseSource(file.absolutePath, file.source);
+        if (!parsed || parsed.language !== 'python')
+            continue;
+        const sourceBuffer = Buffer.from(file.source, 'utf8');
+        const fileKey = factKey(file.path, 'file', 0, sourceBuffer.length);
+        nodes.push(node(file, fileKey, parsed, 'file', 'file', file.path, parsed.tree.rootNode, sourceBuffer, { language: 'python' }));
+        walk(parsed.tree.rootNode, [], [], fileKey, file, parsed, sourceBuffer, nodes, edges);
+    }
+    return { nodes, edges };
+}
+async function scanPythonFilesInBatches(files) {
+    const pythonFiles = files.filter((file) => isPython(file.path));
+    const results = await runBatchedWorkers(pythonFiles, new URL('./pythonScanWorker.js', import.meta.url), (batch) => batch);
+    return {
+        nodes: results.flatMap((result) => result.nodes),
+        edges: results.flatMap((result) => result.edges),
+        failedPaths: results.flatMap((result) => result.failedPaths ?? []),
+        diagnostics: results.flatMap((result) => result.diagnostics ?? [])
+    };
+}
+export const PythonScannerPlugin = {
+    name: PYTHON_SCANNER_PLUGIN_NAME,
+    apiVersion: 1,
+    capabilities: ['file-scanner'],
+    scan: (context) => scanPythonFilesInBatches(context.files),
+    scanIncremental: (context, delta, previous) => scanPythonIncremental(context, delta, previous)
+};
+async function scanPythonIncremental(context, delta, previous) {
+    if (delta.full || !previous)
+        return { ...(await scanPythonFilesInBatches(context.files)), retractions: { nodes: [], edges: [] } };
+    const changed = new Set([...delta.changedPaths, ...delta.deletedPaths].filter(isPython));
+    if (changed.size === 0)
+        return { nodes: [], edges: [], retractions: { nodes: [], edges: [] } };
+    const retractions = { nodes: [], edges: [] };
+    for (const fact of previous.nodes) {
+        if (fact.metadata.filePath && changed.has(String(fact.metadata.filePath))) {
+            const key = String(fact.metadata.factKey ?? '');
+            if (key)
+                retractions.nodes.push(key);
+        }
+    }
+    for (const fact of previous.edges) {
+        if (fact.metadata.filePath && changed.has(String(fact.metadata.filePath))) {
+            const key = String(fact.metadata.factKey ?? '');
+            if (key)
+                retractions.edges.push(key);
+        }
+    }
+    return {
+        ...(await scanPythonFilesInBatches(context.files.filter((file) => changed.has(file.path)))),
+        retractions
+    };
+}
+function walk(treeNode, symbolAncestry, graphAncestry, fileKey, file, parsed, sourceBuffer, nodes, edges) {
+    let currentKey;
+    let nextSymbols = symbolAncestry;
+    let nextGraph = graphAncestry;
+    const kind = kindFor(treeNode);
+    if (kind) {
+        const name = nameFor(treeNode, sourceBuffer);
+        currentKey = factKey(file.path, kind, treeNode.startIndex, treeNode.endIndex);
+        const metadata = metadataFor(treeNode, sourceBuffer, name);
+        nodes.push(node(file, currentKey, parsed, kind, treeNode.type, name, treeNode, sourceBuffer, metadata));
+        const parentKey = graphAncestry.at(-1) ?? fileKey;
+        edges.push({
+            factKey: `contains:${file.path}:${treeNode.startIndex}:${treeNode.endIndex}`,
+            sourceFactKey: parentKey,
+            targetFactKey: currentKey,
+            filePath: file.path,
+            kind: kind === 'symbol' && symbolAncestry.length === 0 ? 'defines' : 'contains',
+            metadata: { discoveredFrom: treeNode.type }
+        });
+        if (kind === 'import') {
+            edges.push({
+                factKey: `imports:${file.path}:${treeNode.startIndex}:${treeNode.endIndex}`,
+                sourceFactKey: fileKey,
+                targetFactKey: currentKey,
+                filePath: file.path,
+                kind: 'imports',
+                confidence: 0.65,
+                metadata: { module: metadata.module ?? name }
+            });
+        }
+        else if (kind === 'call') {
+            edges.push({
+                factKey: `calls:${file.path}:${treeNode.startIndex}:${treeNode.endIndex}`,
+                sourceFactKey: symbolAncestry.at(-1) ?? fileKey,
+                targetFactKey: currentKey,
+                filePath: file.path,
+                kind: 'calls',
+                confidence: 0.65,
+                metadata: { callee: name }
+            });
+        }
+        if (kind === 'symbol') {
+            if (symbolAncestry.length === 0 && name && !name.startsWith('_')) {
+                const exportKey = factKey(file.path, 'export', treeNode.startIndex, treeNode.endIndex);
+                nodes.push(node(file, exportKey, parsed, 'export', 'implicit_export', name, treeNode, sourceBuffer, {
+                    exportKind: 'implicit-python-export',
+                    symbol: name
+                }));
+                edges.push({
+                    factKey: `exports:${file.path}:${treeNode.startIndex}:${treeNode.endIndex}`,
+                    sourceFactKey: fileKey,
+                    targetFactKey: exportKey,
+                    filePath: file.path,
+                    kind: 'exports',
+                    metadata: { symbol: name, implicit: true }
+                });
+            }
+            nextSymbols = [...symbolAncestry, currentKey];
+        }
+        nextGraph = [...graphAncestry, currentKey];
+    }
+    for (const child of treeNode.namedChildren) {
+        walk(child, nextSymbols, nextGraph, fileKey, file, parsed, sourceBuffer, nodes, edges);
+    }
+}
+function kindFor(node) {
+    if (SYMBOL_TYPES.has(node.type))
+        return 'symbol';
+    if (IMPORT_TYPES.has(node.type))
+        return 'import';
+    if (CALL_TYPES.has(node.type))
+        return 'call';
+    return undefined;
+}
+function nameFor(node, sourceBuffer) {
+    const name = node.childForFieldName('name');
+    if (name)
+        return textFor(name, sourceBuffer).trim();
+    if (node.type === 'assignment' || node.type === 'augmented_assignment') {
+        const left = node.childForFieldName('left') ?? node.namedChildren[0];
+        return left ? textFor(left, sourceBuffer).trim() : null;
+    }
+    if (node.type === 'call') {
+        const fn = node.childForFieldName('function') ?? node.namedChildren[0];
+        return fn ? textFor(fn, sourceBuffer).trim().slice(0, 120) : null;
+    }
+    if (IMPORT_TYPES.has(node.type))
+        return moduleForImport(node, sourceBuffer);
+    return null;
+}
+function metadataFor(node, sourceBuffer, name) {
+    const snippet = textFor(node, sourceBuffer).trim().slice(0, 240);
+    if (IMPORT_TYPES.has(node.type))
+        return { module: moduleForImport(node, sourceBuffer), snippet };
+    if (node.type === 'call')
+        return { callee: name, snippet };
+    return { snippet };
+}
+function moduleForImport(node, sourceBuffer) {
+    const source = textFor(node, sourceBuffer).trim();
+    if (node.type === 'import_statement')
+        return source.replace(/^import\s+/, '').split(',')[0]?.trim() ?? source;
+    return /^from\s+([^\s]+)\s+import\s+/u.exec(source)?.[1] ?? source;
+}
+function node(file, factKeyValue, parsed, kind, type, name, treeNode, sourceBuffer, metadata) {
+    return {
+        factKey: factKeyValue,
+        filePath: file.path,
+        kind,
+        type,
+        name,
+        startByte: treeNode.startIndex,
+        endByte: treeNode.endIndex,
+        startPoint: treeNode.startPosition,
+        endPoint: treeNode.endPosition,
+        sourceHash: file.hash,
+        parser: parsed.parser,
+        parserVersion: parsed.parserVersion,
+        metadata: { ...metadata, filePath: file.path, factKey: factKeyValue, sourceBytes: sourceBuffer.length }
+    };
+}
+function factKey(filePath, kind, startByte, endByte) {
+    return `${kind}:${filePath}:${startByte}:${endByte}`;
+}
+function textFor(node, sourceBuffer) {
+    return sourceBuffer.subarray(node.startIndex, node.endIndex).toString('utf8');
+}
+function isPython(filePath) {
+    return PYTHON_EXTENSIONS.has(filePath.slice(filePath.lastIndexOf('.')).toLowerCase());
+}
+//# sourceMappingURL=pythonPlugin.js.map

package/dist/src/scanner/pythonScanWorker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pythonScanWorker.d.ts.map

package/dist/src/scanner/pythonScanWorker.js

@@ -0,0 +1,8 @@
+import { parentPort } from 'node:worker_threads';
+import { scanPythonFiles } from './pythonPlugin.js';
+if (!parentPort)
+    throw new Error('python scan worker requires a parent port');
+parentPort.on('message', (files) => {
+    parentPort.postMessage(scanPythonFiles(files));
+});
+//# sourceMappingURL=pythonScanWorker.js.map

package/dist/src/storage/connection.js

@@ -44,6 +44,18 @@ function ensureSchemaVersion(db) {
     }
     if (currentVersion <= 3) {
         migrateSchemaV3ToV4(db);
+        db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(4);
+    }
+    if (currentVersion <= 4) {
+        migrateSchemaV4ToV5(db);
+        db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(5);
+    }
+    if (currentVersion <= 5) {
+        migrateSchemaV5ToV6(db);
+        db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(6);
+    }
+    if (currentVersion <= 6) {
+        migrateSchemaV6ToV7(db);
         db.prepare('INSERT OR IGNORE INTO schema_migrations(version) VALUES (?)').run(SCHEMA_VERSION);
         return;
     }
@@ -63,6 +75,57 @@ function migrateSchemaV3ToV4(db) {
     CREATE INDEX IF NOT EXISTS idx_plugin_contributions_repo ON plugin_contributions(repository_id);
   `);
 }
+function migrateSchemaV4ToV5(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS file_scan_failures (
+      repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+      path TEXT NOT NULL,
+      diagnostic TEXT NOT NULL,
+      failed_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY(repository_id, path)
+    );
+    CREATE TABLE IF NOT EXISTS repository_scan_state (
+      repository_id TEXT PRIMARY KEY REFERENCES repositories(id) ON DELETE CASCADE,
+      state TEXT NOT NULL CHECK(state IN ('fresh', 'degraded', 'stale')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}
+function migrateSchemaV5ToV6(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS file_enrichment_state (
+      repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+      file_id TEXT PRIMARY KEY REFERENCES files(id) ON DELETE CASCADE,
+      source_hash TEXT NOT NULL,
+      state TEXT NOT NULL CHECK(state IN ('pending', 'complete', 'failed')),
+      diagnostic TEXT,
+      queued_at TEXT NOT NULL DEFAULT (datetime('now')),
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      completed_at TEXT,
+      failed_at TEXT
+    );
+    CREATE INDEX IF NOT EXISTS idx_file_enrichment_state_repo_state ON file_enrichment_state(repository_id, state);
+  `);
+}
+function migrateSchemaV6ToV7(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS repository_manifest_inventory (
+      repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
+      path TEXT NOT NULL,
+      kind TEXT NOT NULL CHECK(kind IN ('maven-pom', 'gradle-groovy', 'gradle-kotlin')),
+      module_identity TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('observed', 'read_failed', 'traversal_incomplete', 'confirmed_deleted')),
+      size INTEGER NOT NULL,
+      mtime_ms INTEGER NOT NULL,
+      source_hash TEXT,
+      generation INTEGER NOT NULL,
+      updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+      PRIMARY KEY(repository_id, path)
+    );
+    CREATE INDEX IF NOT EXISTS idx_repository_manifest_inventory_repo_status
+      ON repository_manifest_inventory(repository_id, status);
+  `);
+}
 function getCurrentSchemaVersion(db) {
     const row = db.prepare('SELECT COALESCE(MAX(version), 0) AS version FROM schema_migrations').get();
     return Number(row?.version ?? 0);

package/dist/src/storage/database.d.ts

@@ -5,6 +5,7 @@
  */
 export * from './connection.js';
 export * from './plugin-contributions.js';
+export * from './manifest-inventory.js';
 export * from './graph-writes.js';
 export * from './plugin-graph.js';
 export * from './queries.js';

package/dist/src/storage/database.js

@@ -5,6 +5,7 @@
  */
 export * from './connection.js';
 export * from './plugin-contributions.js';
+export * from './manifest-inventory.js';
 export * from './graph-writes.js';
 export * from './plugin-graph.js';
 export * from './queries.js';

package/dist/src/storage/graph-writes.d.ts

@@ -1,16 +1,29 @@
 import { DatabaseSync } from 'node:sqlite';
-import type { FileAttribution, FileRecord, GraphEdge, GraphNode, RepositoryRecord } from '../types.js';
+import type { AttributionApplyResult, AttributionOutcome, FileRecord, GraphEdge, GraphNode, RepositoryRecord } from '../types.js';
 export declare function upsertRepository(db: DatabaseSync, repository: RepositoryRecord): void;
-export declare function replaceFileGraph(db: DatabaseSync, { repository, file, nodes, edges, attribution }: {
+export declare function replaceFileGraph(db: DatabaseSync, { repository, file, nodes, edges }: {
     repository: RepositoryRecord;
     file: FileRecord;
     nodes: GraphNode[];
     edges: GraphEdge[];
-    attribution?: FileAttribution | null;
 }): void;
+/**
+ * Applies optional attribution only when it still matches the structural file
+ * hash. Failed outcomes never mutate existing attribution.
+ */
+export declare function applyFileAttribution(db: DatabaseSync, { repository, fileId, sourceHash, outcome }: {
+    repository: RepositoryRecord;
+    fileId: string;
+    sourceHash: string;
+    outcome: AttributionOutcome;
+}): AttributionApplyResult;
 export declare function reconcileDeletedFiles(db: DatabaseSync, repositoryId: string, discoveredPaths: string[]): void;
+export declare function recordFileScanFailure(db: DatabaseSync, repositoryId: string, filePath: string, diagnostic: string): void;
+export declare function clearFileScanFailure(db: DatabaseSync, repositoryId: string, filePath: string): void;
+export declare function setRepositoryScanState(db: DatabaseSync, repositoryId: string, state: 'fresh' | 'degraded' | 'stale'): void;
 export declare function selectFileInventory(db: DatabaseSync, repositoryId: string): Array<{
     path: string;
+    hash: string;
     size: number;
     mtimeMs: number;
 }>;

package/dist/src/storage/graph-writes.js

@@ -10,13 +10,14 @@ export function upsertRepository(db, repository) {
       updated_at = datetime('now')
   `).run(repository.id, repository.root, repository.name);
 }
-export function replaceFileGraph(db, { repository, file, nodes, edges, attribution }) {
+export function replaceFileGraph(db, { repository, file, nodes, edges }) {
     upsertRepository(db, repository);
     db.exec('BEGIN IMMEDIATE');
     try {
-        if (attribution) {
-            upsertContributorNodes(db, repository, attribution.contributorEmails);
-        }
+        // The structural replacement must not depend on Git attribution. Preserve
+        // attribution for structurally stable nodes so a later failed enrichment
+        // does not make previously successful data disappear.
+        const priorAttribution = captureFileAttribution(db, file.id);
         db.prepare('DELETE FROM edges WHERE file_id = ?').run(file.id);
         db.prepare('DELETE FROM nodes WHERE file_id = ?').run(file.id);
         db.prepare(`
@@ -36,10 +37,8 @@ export function replaceFileGraph(db, { repository, file, nodes, edges, attributi
         start_point, end_point, source_hash, parser, parser_version, metadata_json, last_modified_user_id
       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `);
-        const attributionByNodeId = new Map(attribution?.nodeAttributions.map((entry) => [entry.nodeId, entry]) ?? []);
         for (const node of nodes) {
-            const nodeAttribution = attributionByNodeId.get(node.id);
-            insertNode.run(node.id, repository.id, file.id, node.kind, node.type, node.name ?? null, node.startByte, node.endByte, JSON.stringify(node.startPoint), JSON.stringify(node.endPoint), node.sourceHash, node.parser, node.parserVersion, JSON.stringify(node.metadata ?? {}), node.lastModifiedUserId ?? resolveUserId(repository, nodeAttribution?.lastModifiedEmail ?? null));
+            insertNode.run(node.id, repository.id, file.id, node.kind, node.type, node.name ?? null, node.startByte, node.endByte, JSON.stringify(node.startPoint), JSON.stringify(node.endPoint), node.sourceHash, node.parser, node.parserVersion, JSON.stringify(node.metadata ?? {}), null);
         }
         const insertEdge = db.prepare(`
       INSERT INTO edges(
@@ -49,17 +48,43 @@ export function replaceFileGraph(db, { repository, file, nodes, edges, attributi
         for (const edge of edges) {
             insertEdge.run(edge.id, repository.id, file.id, edge.sourceId, edge.targetId, edge.kind, edge.confidence ?? 1, JSON.stringify(edge.metadata ?? {}));
         }
-        if (attribution) {
-            for (const entry of attribution.nodeAttributions) {
-                for (const email of entry.contributorEmails) {
-                    const contributorId = resolveUserId(repository, email);
-                    if (!contributorId)
-                        continue;
-                    insertEdge.run(hashParts([repository.id, file.id, entry.nodeId, contributorId, 'attributed_to']), repository.id, file.id, entry.nodeId, contributorId, 'attributed_to', 1, JSON.stringify({ email }));
-                }
-            }
+        restorePriorAttribution(db, file.id, new Set(nodes.map((node) => node.id)), priorAttribution);
+        queueFileEnrichment(db, repository.id, file.id, file.hash);
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}
+/**
+ * Applies optional attribution only when it still matches the structural file
+ * hash. Failed outcomes never mutate existing attribution.
+ */
+export function applyFileAttribution(db, { repository, fileId, sourceHash, outcome }) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        const current = db.prepare(`
+      SELECT f.hash AS sourceHash, e.source_hash AS enrichmentHash
+      FROM files f LEFT JOIN file_enrichment_state e ON e.file_id = f.id
+      WHERE f.id = ? AND f.repository_id = ?
+    `).get(fileId, repository.id);
+        if (current?.sourceHash !== sourceHash || current.enrichmentHash !== sourceHash) {
+            db.exec('ROLLBACK');
+            return 'stale';
+        }
+        if (outcome.status === 'complete') {
+            replaceAttribution(db, repository, fileId, outcome.attribution);
+            setFileEnrichmentState(db, repository.id, fileId, 'complete', null);
+        }
+        else if (outcome.status === 'unavailable') {
+            setFileEnrichmentState(db, repository.id, fileId, 'complete', null);
+        }
+        else {
+            setFileEnrichmentState(db, repository.id, fileId, 'failed', outcome.diagnostic);
         }
         db.exec('COMMIT');
+        return 'applied';
     }
     catch (error) {
         db.exec('ROLLBACK');
@@ -75,6 +100,8 @@ export function reconcileDeletedFiles(db, repositoryId, discoveredPaths) {
             if (!keep.has(row.path))
                 db.prepare('DELETE FROM files WHERE repository_id = ? AND path = ?').run(repositoryId, row.path);
         }
+        db.prepare(`DELETE FROM file_scan_failures WHERE repository_id = ? AND path NOT IN (SELECT value FROM json_each(?))`)
+            .run(repositoryId, JSON.stringify(discoveredPaths));
         db.exec('COMMIT');
     }
     catch (error) {
@@ -82,8 +109,106 @@ export function reconcileDeletedFiles(db, repositoryId, discoveredPaths) {
         throw error;
     }
 }
+export function recordFileScanFailure(db, repositoryId, filePath, diagnostic) {
+    db.prepare(`
+    INSERT INTO file_scan_failures(repository_id, path, diagnostic, failed_at)
+    VALUES (?, ?, ?, datetime('now'))
+    ON CONFLICT(repository_id, path) DO UPDATE SET
+      diagnostic = excluded.diagnostic,
+      failed_at = datetime('now')
+  `).run(repositoryId, filePath, diagnostic);
+}
+export function clearFileScanFailure(db, repositoryId, filePath) {
+    db.prepare('DELETE FROM file_scan_failures WHERE repository_id = ? AND path = ?').run(repositoryId, filePath);
+}
+export function setRepositoryScanState(db, repositoryId, state) {
+    db.prepare(`
+    INSERT INTO repository_scan_state(repository_id, state, updated_at)
+    VALUES (?, ?, datetime('now'))
+    ON CONFLICT(repository_id) DO UPDATE SET
+      state = excluded.state,
+      updated_at = datetime('now')
+  `).run(repositoryId, state);
+}
 export function selectFileInventory(db, repositoryId) {
-    return db.prepare('SELECT path, size, mtime_ms AS mtimeMs FROM files WHERE repository_id = ? ORDER BY path').all(repositoryId);
+    return db.prepare('SELECT path, hash, size, mtime_ms AS mtimeMs FROM files WHERE repository_id = ? ORDER BY path').all(repositoryId);
+}
+function captureFileAttribution(db, fileId) {
+    return {
+        lastModified: db.prepare(`
+      SELECT id AS nodeId, last_modified_user_id AS userId
+      FROM nodes
+      WHERE file_id = ? AND last_modified_user_id IS NOT NULL
+    `).all(fileId),
+        edges: db.prepare(`
+      SELECT id, source_id AS sourceId, target_id AS targetId, confidence, metadata_json AS metadataJson
+      FROM edges
+      WHERE file_id = ? AND kind = 'attributed_to'
+    `).all(fileId)
+    };
+}
+function restorePriorAttribution(db, fileId, currentNodeIds, prior) {
+    const updateLastModified = db.prepare('UPDATE nodes SET last_modified_user_id = ? WHERE id = ? AND file_id = ?');
+    for (const entry of prior.lastModified) {
+        if (currentNodeIds.has(entry.nodeId))
+            updateLastModified.run(entry.userId, entry.nodeId, fileId);
+    }
+    const insertEdge = db.prepare(`
+    INSERT OR IGNORE INTO edges(id, repository_id, file_id, source_id, target_id, kind, confidence, metadata_json)
+    SELECT ?, repository_id, ?, ?, ?, 'attributed_to', ?, ?
+    FROM files WHERE id = ?
+  `);
+    for (const edge of prior.edges) {
+        if (currentNodeIds.has(edge.sourceId)) {
+            insertEdge.run(edge.id, fileId, edge.sourceId, edge.targetId, edge.confidence, edge.metadataJson, fileId);
+        }
+    }
+}
+function queueFileEnrichment(db, repositoryId, fileId, sourceHash) {
+    db.prepare(`
+    INSERT INTO file_enrichment_state(
+      repository_id, file_id, source_hash, state, diagnostic, queued_at, updated_at, completed_at, failed_at
+    ) VALUES (?, ?, ?, 'pending', NULL, datetime('now'), datetime('now'), NULL, NULL)
+    ON CONFLICT(file_id) DO UPDATE SET
+      repository_id = excluded.repository_id,
+      source_hash = excluded.source_hash,
+      state = 'pending',
+      diagnostic = NULL,
+      queued_at = datetime('now'),
+      updated_at = datetime('now'),
+      completed_at = NULL,
+      failed_at = NULL
+  `).run(repositoryId, fileId, sourceHash);
+}
+function replaceAttribution(db, repository, fileId, attribution) {
+    upsertContributorNodes(db, repository, attribution.contributorEmails);
+    db.prepare("DELETE FROM edges WHERE file_id = ? AND kind = 'attributed_to'").run(fileId);
+    db.prepare('UPDATE nodes SET last_modified_user_id = NULL WHERE file_id = ?').run(fileId);
+    const updateLastModified = db.prepare('UPDATE nodes SET last_modified_user_id = ? WHERE id = ? AND file_id = ?');
+    const insertEdge = db.prepare(`
+    INSERT INTO edges(id, repository_id, file_id, source_id, target_id, kind, confidence, metadata_json)
+    VALUES (?, ?, ?, ?, ?, 'attributed_to', 1, ?)
+  `);
+    for (const entry of attribution.nodeAttributions) {
+        const lastModifiedUserId = resolveUserId(repository, entry.lastModifiedEmail);
+        if (lastModifiedUserId)
+            updateLastModified.run(lastModifiedUserId, entry.nodeId, fileId);
+        for (const email of entry.contributorEmails) {
+            const contributorId = resolveUserId(repository, email);
+            if (!contributorId)
+                continue;
+            insertEdge.run(hashParts([repository.id, fileId, entry.nodeId, contributorId, 'attributed_to']), repository.id, fileId, entry.nodeId, contributorId, JSON.stringify({ email: normalizeEmail(email) }));
+        }
+    }
+}
+function setFileEnrichmentState(db, repositoryId, fileId, state, diagnostic) {
+    db.prepare(`
+    UPDATE file_enrichment_state
+    SET state = ?, diagnostic = ?, updated_at = datetime('now'),
+      completed_at = CASE WHEN ? = 'complete' THEN datetime('now') ELSE NULL END,
+      failed_at = CASE WHEN ? = 'failed' THEN datetime('now') ELSE NULL END
+    WHERE repository_id = ? AND file_id = ?
+  `).run(state, diagnostic, state, state, repositoryId, fileId);
 }
 function upsertContributorNodes(db, repository, contributorEmails) {
     const insertNode = db.prepare(`