@psnext/lscg 0.1.4 → 0.1.5

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(`

package/dist/src/storage/manifest-inventory.d.ts

@@ -0,0 +1,23 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { ManifestKind, ManifestStatus, RepositoryManifest } from '../scanner/artifactInventory.js';
+export interface RepositoryManifestInventoryRow {
+    repositoryId: string;
+    path: string;
+    kind: ManifestKind;
+    moduleIdentity: string;
+    status: ManifestStatus;
+    size: number;
+    mtimeMs: number;
+    sourceHash: string | null;
+    generation: number;
+}
+export declare function selectManifestInventory(db: DatabaseSync, repositoryId: string): RepositoryManifestInventoryRow[];
+/** Persist one complete inventory snapshot. Uncertain records remain queryable for restart-safe retention. */
+export declare function persistManifestInventory(db: DatabaseSync, repositoryId: string, manifests: readonly RepositoryManifest[], generation: number): void;
+/** Persist inventory and freshness together at the end of a structural scan. */
+export declare function persistManifestInventoryAndScanState(db: DatabaseSync, repositoryId: string, manifests: readonly RepositoryManifest[], generation: number, state: 'fresh' | 'degraded' | 'stale'): void;
+/** Descriptive aliases for callers that prefer the table's full name. */
+export declare const selectRepositoryManifestInventory: typeof selectManifestInventory;
+export declare const persistRepositoryManifestInventory: typeof persistManifestInventory;
+export declare function manifestRowsAsRecords(rows: readonly RepositoryManifestInventoryRow[]): RepositoryManifest[];
+//# sourceMappingURL=manifest-inventory.d.ts.map

package/dist/src/storage/manifest-inventory.js

@@ -0,0 +1,82 @@
+export function selectManifestInventory(db, repositoryId) {
+    const rows = db.prepare(`
+    SELECT repository_id AS repositoryId, path, kind, module_identity AS moduleIdentity,
+      status, size, mtime_ms AS mtimeMs, source_hash AS sourceHash, generation
+    FROM repository_manifest_inventory
+    WHERE repository_id = ?
+    ORDER BY path
+  `).all(repositoryId);
+    return rows.map((row) => ({
+        repositoryId: String(row.repositoryId),
+        path: String(row.path),
+        kind: row.kind,
+        moduleIdentity: String(row.moduleIdentity),
+        status: row.status,
+        size: Number(row.size),
+        mtimeMs: Number(row.mtimeMs),
+        sourceHash: typeof row.sourceHash === 'string' ? row.sourceHash : null,
+        generation: Number(row.generation)
+    }));
+}
+/** Persist one complete inventory snapshot. Uncertain records remain queryable for restart-safe retention. */
+export function persistManifestInventory(db, repositoryId, manifests, generation) {
+    inTransaction(db, () => writeManifestInventory(db, repositoryId, manifests, generation));
+}
+/** Persist inventory and freshness together at the end of a structural scan. */
+export function persistManifestInventoryAndScanState(db, repositoryId, manifests, generation, state) {
+    inTransaction(db, () => {
+        writeManifestInventory(db, repositoryId, manifests, generation);
+        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 = excluded.updated_at
+    `).run(repositoryId, state);
+    });
+}
+function writeManifestInventory(db, repositoryId, manifests, generation) {
+    const statement = db.prepare(`
+    INSERT INTO repository_manifest_inventory(
+      repository_id, path, kind, module_identity, status, size, mtime_ms, source_hash, generation
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(repository_id, path) DO UPDATE SET
+      kind = excluded.kind,
+      module_identity = excluded.module_identity,
+      status = excluded.status,
+      size = excluded.size,
+      mtime_ms = excluded.mtime_ms,
+      source_hash = excluded.source_hash,
+      generation = excluded.generation,
+      updated_at = datetime('now')
+  `);
+    for (const manifest of manifests) {
+        statement.run(repositoryId, manifest.path, manifest.kind, manifest.moduleIdentity, manifest.status, manifest.size, manifest.mtimeMs, manifest.sourceHash, generation);
+    }
+}
+function inTransaction(db, work) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        work();
+        db.exec('COMMIT');
+    }
+    catch (error) {
+        db.exec('ROLLBACK');
+        throw error;
+    }
+}
+/** Descriptive aliases for callers that prefer the table's full name. */
+export const selectRepositoryManifestInventory = selectManifestInventory;
+export const persistRepositoryManifestInventory = persistManifestInventory;
+export function manifestRowsAsRecords(rows) {
+    return rows.map((row) => ({
+        path: row.path,
+        kind: row.kind,
+        moduleIdentity: row.moduleIdentity,
+        size: row.size,
+        mtimeMs: row.mtimeMs,
+        sourceHash: row.sourceHash,
+        content: null,
+        status: row.status,
+        generation: row.generation
+    }));
+}
+//# sourceMappingURL=manifest-inventory.js.map

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

@@ -1,5 +1,10 @@
 import { DatabaseSync } from 'node:sqlite';
-import type { GraphEdgeRow, GraphNodeRow, GraphNodeTextRow, StatusResult } from '../types.js';
+import type { EnrichmentState, EnrichmentSummary, EnrichmentWork, FileEnrichmentState, FreshnessReport, GraphEdgeRow, GraphNodeRow, GraphNodeTextRow, StatusResult } from '../types.js';
+export declare function selectFreshnessReport(db: DatabaseSync, repositoryId: string): FreshnessReport;
+export declare function selectFileEnrichmentState(db: DatabaseSync, repositoryId: string, fileId: string): FileEnrichmentState | null;
+export declare function selectFileEnrichmentStates(db: DatabaseSync, repositoryId: string, states?: readonly EnrichmentState[]): FileEnrichmentState[];
+export declare function selectEnrichmentWork(db: DatabaseSync, repositoryId: string, states?: readonly EnrichmentState[]): EnrichmentWork[];
+export declare function selectEnrichmentSummary(db: DatabaseSync, repositoryId: string): EnrichmentSummary;
 export declare function getStatus(db: DatabaseSync, repositoryId: string): StatusResult;
 export declare function selectNodes(db: DatabaseSync, repositoryId: string, { kind, limit }?: {
     kind?: string | undefined;