@psnext/lscg 0.1.3 → 0.1.5

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;

package/dist/src/storage/queries.js

@@ -1,11 +1,77 @@
 import { DatabaseSync } from 'node:sqlite';
 import { parsePoint } from './row-decoders.js';
+export function selectFreshnessReport(db, repositoryId) {
+    const scanState = db.prepare('SELECT state FROM repository_scan_state WHERE repository_id = ?').get(repositoryId);
+    if (!scanState?.state)
+        return { state: 'stale', reason: 'not_scanned' };
+    const failures = db.prepare('SELECT count(*) AS count FROM file_scan_failures WHERE repository_id = ?').get(repositoryId);
+    if (scanState.state === 'degraded' || failures.count > 0)
+        return { state: 'degraded', reason: 'retained_failure' };
+    if (scanState.state === 'stale')
+        return { state: 'stale', reason: 'known_invalidation' };
+    return { state: 'fresh' };
+}
+export function selectFileEnrichmentState(db, repositoryId, fileId) {
+    const row = db.prepare(`
+    SELECT repository_id AS repositoryId, file_id AS fileId, source_hash AS sourceHash,
+      state, diagnostic, queued_at AS queuedAt, updated_at AS updatedAt,
+      completed_at AS completedAt, failed_at AS failedAt
+    FROM file_enrichment_state
+    WHERE repository_id = ? AND file_id = ?
+  `).get(repositoryId, fileId);
+    return row ?? null;
+}
+export function selectFileEnrichmentStates(db, repositoryId, states = ['pending', 'failed']) {
+    if (states.length === 0)
+        return [];
+    const placeholders = states.map(() => '?').join(', ');
+    return db.prepare(`
+    SELECT repository_id AS repositoryId, file_id AS fileId, source_hash AS sourceHash,
+      state, diagnostic, queued_at AS queuedAt, updated_at AS updatedAt,
+      completed_at AS completedAt, failed_at AS failedAt
+    FROM file_enrichment_state
+    WHERE repository_id = ? AND state IN (${placeholders})
+    ORDER BY queued_at, file_id
+  `).all(repositoryId, ...states);
+}
+export function selectEnrichmentWork(db, repositoryId, states = ['pending', 'failed']) {
+    if (states.length === 0)
+        return [];
+    const placeholders = states.map(() => '?').join(', ');
+    return db.prepare(`
+    SELECT e.repository_id AS repositoryId, e.file_id AS fileId, e.source_hash AS sourceHash,
+      e.state, e.diagnostic, e.queued_at AS queuedAt, e.updated_at AS updatedAt,
+      e.completed_at AS completedAt, e.failed_at AS failedAt, f.path, f.language
+    FROM file_enrichment_state e
+    JOIN files f ON f.id = e.file_id
+    WHERE e.repository_id = ? AND e.state IN (${placeholders})
+    ORDER BY e.queued_at, e.file_id
+  `).all(repositoryId, ...states);
+}
+export function selectEnrichmentSummary(db, repositoryId) {
+    const states = selectFileEnrichmentStates(db, repositoryId, ['pending', 'complete', 'failed']);
+    const failedEntries = states.filter((entry) => entry.state === 'failed');
+    return {
+        state: failedEntries.length > 0 ? 'failed' : states.some((entry) => entry.state === 'pending') ? 'pending' : 'complete',
+        pending: states.filter((entry) => entry.state === 'pending').length,
+        complete: states.filter((entry) => entry.state === 'complete').length,
+        failed: failedEntries.length,
+        diagnostics: failedEntries.flatMap((entry) => entry.diagnostic ? [entry.diagnostic] : [])
+    };
+}
 export function getStatus(db, repositoryId) {
     const repository = db.prepare('SELECT * FROM repositories WHERE id = ?').get(repositoryId);
     const files = db.prepare('SELECT count(*) AS count FROM files WHERE repository_id = ?').get(repositoryId).count;
     const nodes = db.prepare('SELECT count(*) AS count FROM nodes WHERE repository_id = ?').get(repositoryId).count;
     const edges = db.prepare('SELECT count(*) AS count FROM edges WHERE repository_id = ?').get(repositoryId).count;
-    return { repository: repository ?? null, files, nodes, edges };
+    return {
+        repository: repository ?? null,
+        files,
+        nodes,
+        edges,
+        freshness: selectFreshnessReport(db, repositoryId),
+        enrichment: selectEnrichmentSummary(db, repositoryId)
+    };
 }
 export function selectNodes(db, repositoryId, { kind, limit = 50 } = {}) {
     const safeLimit = clampLimit(limit);

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

@@ -1,4 +1,4 @@
-export declare const SCHEMA_VERSION = 4;
-export declare const CREATE_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS schema_migrations (\n  version INTEGER PRIMARY KEY,\n  applied_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE IF NOT EXISTS repositories (\n  id TEXT PRIMARY KEY,\n  root TEXT NOT NULL,\n  name TEXT NOT NULL,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE IF NOT EXISTS files (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  path TEXT NOT NULL,\n  language TEXT NOT NULL,\n  hash TEXT NOT NULL,\n  size INTEGER NOT NULL,\n  mtime_ms INTEGER NOT NULL,\n  scanned_at TEXT NOT NULL DEFAULT (datetime('now')),\n  UNIQUE(repository_id, path)\n);\n\nCREATE TABLE IF NOT EXISTS nodes (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  file_id TEXT REFERENCES files(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL,\n  type TEXT NOT NULL,\n  name TEXT,\n  start_byte INTEGER NOT NULL,\n  end_byte INTEGER NOT NULL,\n  start_point TEXT NOT NULL,\n  end_point TEXT NOT NULL,\n  source_hash TEXT NOT NULL,\n  parser TEXT NOT NULL,\n  parser_version TEXT NOT NULL,\n  metadata_json TEXT NOT NULL DEFAULT '{}',\n  last_modified_user_id TEXT\n);\n\nCREATE TABLE IF NOT EXISTS edges (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  file_id TEXT REFERENCES files(id) ON DELETE CASCADE,\n  source_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,\n  target_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL,\n  confidence REAL NOT NULL DEFAULT 1.0,\n  metadata_json TEXT NOT NULL DEFAULT '{}'\n);\n\nCREATE TABLE IF NOT EXISTS overlays (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  subject_id TEXT NOT NULL,\n  subject_kind TEXT NOT NULL,\n  operation TEXT NOT NULL,\n  metadata_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE INDEX IF NOT EXISTS idx_files_repo_path ON files(repository_id, path);\nCREATE INDEX IF NOT EXISTS idx_nodes_repo_kind ON nodes(repository_id, kind);\nCREATE INDEX IF NOT EXISTS idx_nodes_repo_name ON nodes(repository_id, name);\nCREATE INDEX IF NOT EXISTS idx_edges_repo_kind ON edges(repository_id, kind);\nCREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);\nCREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);\n\nCREATE TABLE IF NOT EXISTS plugin_contributions (\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  plugin_name TEXT NOT NULL,\n  generation INTEGER NOT NULL,\n  nodes_json TEXT NOT NULL,\n  edges_json TEXT NOT NULL,\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY(repository_id, plugin_name)\n);\nCREATE INDEX IF NOT EXISTS idx_plugin_contributions_repo ON plugin_contributions(repository_id);\n";
+export declare const SCHEMA_VERSION = 7;
+export declare const CREATE_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS schema_migrations (\n  version INTEGER PRIMARY KEY,\n  applied_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE IF NOT EXISTS repositories (\n  id TEXT PRIMARY KEY,\n  root TEXT NOT NULL,\n  name TEXT NOT NULL,\n  created_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE IF NOT EXISTS files (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  path TEXT NOT NULL,\n  language TEXT NOT NULL,\n  hash TEXT NOT NULL,\n  size INTEGER NOT NULL,\n  mtime_ms INTEGER NOT NULL,\n  scanned_at TEXT NOT NULL DEFAULT (datetime('now')),\n  UNIQUE(repository_id, path)\n);\n\nCREATE TABLE IF NOT EXISTS nodes (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  file_id TEXT REFERENCES files(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL,\n  type TEXT NOT NULL,\n  name TEXT,\n  start_byte INTEGER NOT NULL,\n  end_byte INTEGER NOT NULL,\n  start_point TEXT NOT NULL,\n  end_point TEXT NOT NULL,\n  source_hash TEXT NOT NULL,\n  parser TEXT NOT NULL,\n  parser_version TEXT NOT NULL,\n  metadata_json TEXT NOT NULL DEFAULT '{}',\n  last_modified_user_id TEXT\n);\n\nCREATE TABLE IF NOT EXISTS edges (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  file_id TEXT REFERENCES files(id) ON DELETE CASCADE,\n  source_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,\n  target_id TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL,\n  confidence REAL NOT NULL DEFAULT 1.0,\n  metadata_json TEXT NOT NULL DEFAULT '{}'\n);\n\nCREATE TABLE IF NOT EXISTS overlays (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  subject_id TEXT NOT NULL,\n  subject_kind TEXT NOT NULL,\n  operation TEXT NOT NULL,\n  metadata_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE INDEX IF NOT EXISTS idx_files_repo_path ON files(repository_id, path);\nCREATE INDEX IF NOT EXISTS idx_nodes_repo_kind ON nodes(repository_id, kind);\nCREATE INDEX IF NOT EXISTS idx_nodes_repo_name ON nodes(repository_id, name);\nCREATE INDEX IF NOT EXISTS idx_edges_repo_kind ON edges(repository_id, kind);\nCREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id);\nCREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id);\n\nCREATE TABLE IF NOT EXISTS plugin_contributions (\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  plugin_name TEXT NOT NULL,\n  generation INTEGER NOT NULL,\n  nodes_json TEXT NOT NULL,\n  edges_json TEXT NOT NULL,\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY(repository_id, plugin_name)\n);\nCREATE INDEX IF NOT EXISTS idx_plugin_contributions_repo ON plugin_contributions(repository_id);\n\nCREATE TABLE IF NOT EXISTS file_scan_failures (\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  path TEXT NOT NULL,\n  diagnostic TEXT NOT NULL,\n  failed_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY(repository_id, path)\n);\n\nCREATE TABLE IF NOT EXISTS repository_scan_state (\n  repository_id TEXT PRIMARY KEY REFERENCES repositories(id) ON DELETE CASCADE,\n  state TEXT NOT NULL CHECK(state IN ('fresh', 'degraded', 'stale')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now'))\n);\n\nCREATE TABLE IF NOT EXISTS file_enrichment_state (\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  file_id TEXT PRIMARY KEY REFERENCES files(id) ON DELETE CASCADE,\n  source_hash TEXT NOT NULL,\n  state TEXT NOT NULL CHECK(state IN ('pending', 'complete', 'failed')),\n  diagnostic TEXT,\n  queued_at TEXT NOT NULL DEFAULT (datetime('now')),\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  completed_at TEXT,\n  failed_at TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_file_enrichment_state_repo_state ON file_enrichment_state(repository_id, state);\n\nCREATE TABLE IF NOT EXISTS repository_manifest_inventory (\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  path TEXT NOT NULL,\n  kind TEXT NOT NULL CHECK(kind IN ('maven-pom', 'gradle-groovy', 'gradle-kotlin')),\n  module_identity TEXT NOT NULL,\n  status TEXT NOT NULL CHECK(status IN ('observed', 'read_failed', 'traversal_incomplete', 'confirmed_deleted')),\n  size INTEGER NOT NULL,\n  mtime_ms INTEGER NOT NULL,\n  source_hash TEXT,\n  generation INTEGER NOT NULL,\n  updated_at TEXT NOT NULL DEFAULT (datetime('now')),\n  PRIMARY KEY(repository_id, path)\n);\nCREATE INDEX IF NOT EXISTS idx_repository_manifest_inventory_repo_status\n  ON repository_manifest_inventory(repository_id, status);\n";
 export declare const CREATE_NODES_TABLE_SQL = "\nCREATE TABLE nodes_new (\n  id TEXT PRIMARY KEY,\n  repository_id TEXT NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,\n  file_id TEXT REFERENCES files(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL,\n  type TEXT NOT NULL,\n  name TEXT,\n  start_byte INTEGER NOT NULL,\n  end_byte INTEGER NOT NULL,\n  start_point TEXT NOT NULL,\n  end_point TEXT NOT NULL,\n  source_hash TEXT NOT NULL,\n  parser TEXT NOT NULL,\n  parser_version TEXT NOT NULL,\n  metadata_json TEXT NOT NULL DEFAULT '{}',\n  last_modified_user_id TEXT\n);\n";
 //# sourceMappingURL=schema.d.ts.map

package/dist/src/storage/schema.js

@@ -1,4 +1,4 @@
-export const SCHEMA_VERSION = 4;
+export const SCHEMA_VERSION = 7;
 export const CREATE_SCHEMA_SQL = `
 CREATE TABLE IF NOT EXISTS schema_migrations (
   version INTEGER PRIMARY KEY,
@@ -81,6 +81,49 @@ CREATE TABLE IF NOT EXISTS plugin_contributions (
   PRIMARY KEY(repository_id, plugin_name)
 );
 CREATE INDEX IF NOT EXISTS idx_plugin_contributions_repo ON plugin_contributions(repository_id);
+
+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'))
+);
+
+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);
+
+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);
 `;
 export const CREATE_NODES_TABLE_SQL = `
 CREATE TABLE nodes_new (

package/dist/src/types.d.ts

@@ -73,6 +73,51 @@ export interface FileAttribution {
     contributorEmails: ContributorIdentity[];
     nodeAttributions: NodeAttribution[];
 }
+/** The result of attempting optional Git attribution for one file. */
+export type AttributionOutcome = {
+    status: 'complete';
+    attribution: FileAttribution;
+} | {
+    status: 'unavailable';
+    reason: 'not_applicable' | 'unavailable';
+} | {
+    status: 'failed';
+    diagnostic: string;
+};
+export type EnrichmentState = 'pending' | 'complete' | 'failed';
+/** Durable, hash-bound optional-enrichment work for a scanned file. */
+export interface FileEnrichmentState {
+    repositoryId: string;
+    fileId: string;
+    sourceHash: string;
+    state: EnrichmentState;
+    diagnostic: string | null;
+    queuedAt: string;
+    updatedAt: string;
+    completedAt: string | null;
+    failedAt: string | null;
+}
+export interface EnrichmentWork extends FileEnrichmentState {
+    path: string;
+    language: string;
+}
+export type AttributionApplyResult = 'applied' | 'stale';
+/** Input supplied to an optional attribution runner for hash-compatible work. */
+export interface EnrichmentRunnerInput {
+    repository: RepositoryRecord;
+    work: EnrichmentWork;
+    source: string;
+    nodes: GraphNode[];
+}
+/** Injectable optional-attribution implementation used when enrichment is drained. */
+export type EnrichmentRunner = (input: EnrichmentRunnerInput) => AttributionOutcome | Promise<AttributionOutcome>;
+export interface EnrichmentSummary {
+    state: EnrichmentState;
+    pending: number;
+    complete: number;
+    failed: number;
+    diagnostics: string[];
+}
 export interface ScanSummary {
     repository: RepositoryRecord;
     scopes: Array<{
@@ -84,10 +129,56 @@ export interface ScanSummary {
     nodesWritten: number;
     edgesWritten: number;
     skipped: string[];
+    enrichment: EnrichmentSummary;
     pluginDiagnostics?: string[];
     failedPlugins?: string[];
     stalePlugins?: string[];
 }
+/**
+ * Internal, transport-neutral facts emitted by an explicit scan. These are
+ * deliberately aggregate/lifecycle events rather than a public wire format.
+ * In particular, counters describe one scan operation (including scope=both),
+ * not one database handle.
+ */
+export type ScanProgressOperation = 'incremental' | 'full';
+export type ScanProgressPhase = 'discovery' | 'plugins' | 'files' | 'reconciliation' | 'enrichment' | 'terminal';
+export type ScanProgressStatus = 'started' | 'completed' | 'processed' | 'skipped' | 'deferred' | 'failed' | 'retrying' | 'degraded';
+export interface ScanProgressEvent {
+    kind: 'scan';
+    operation: ScanProgressOperation;
+    scope: GraphScope;
+    phase: ScanProgressPhase;
+    status: ScanProgressStatus;
+    repository: RepositoryRecord;
+    attempt?: number;
+    detail?: string;
+    path?: string;
+    counts?: {
+        discovered?: number;
+        selected?: number;
+        unchanged?: number;
+        deleted?: number;
+        processed?: number;
+        skipped?: number;
+        plugins?: number;
+        failedPlugins?: number;
+        stalePlugins?: number;
+        pending?: number;
+        complete?: number;
+        failed?: number;
+    };
+}
+export type WatchProgressEventName = 'watching' | 'initial-scan' | 'rescan' | 'coalesced-change' | 'follow-up' | 'waiting' | 'polling-fallback' | 'enrichment' | 'stopped' | 'failed';
+export interface WatchProgressEvent {
+    kind: 'watch';
+    event: WatchProgressEventName;
+    mode: 'watch' | 'scan --watch';
+    repository: RepositoryRecord;
+    scope: StorageScope;
+    detail?: string;
+}
+export type ProgressEvent = ScanProgressEvent | WatchProgressEvent;
+export type ProgressReporter = (event: ProgressEvent) => void;
 export interface RepositoryInfo {
     id: string;
     root: string;
@@ -142,15 +233,24 @@ export interface CallGraphMatch extends GraphNodeTextRow {
     upstream: CallGraphRelation[];
     downstream: CallGraphRelation[];
 }
+export type FreshnessState = 'fresh' | 'stale' | 'degraded';
+export type FreshnessReason = 'not_scanned' | 'known_invalidation' | 'retained_failure';
+/** Persisted graph freshness, evaluated only from stored scan state. */
+export interface FreshnessReport {
+    state: FreshnessState;
+    reason?: FreshnessReason | undefined;
+}
 export interface StatusResult {
     repository: RepositoryRecord | null;
     files: number;
     nodes: number;
     edges: number;
+    freshness: FreshnessReport;
+    enrichment: EnrichmentSummary;
 }
 /** Stable, transport-neutral contract returned by the context retrieval command. */
 export type ContextResultState = 'ok' | 'ambiguous' | 'not_found' | 'refresh_failed' | 'stale';
-export type ContextFreshnessState = 'unchanged' | 'refreshed' | 'stale' | 'refresh_failed';
+export type ContextFreshnessState = FreshnessState;
 export type ContextFreshnessVerification = 'metadata_only' | 'content_hash';
 export type ContextRelationCategory = 'definition' | 'impact' | 'dependency';
 export interface ContextBudget {
@@ -224,11 +324,7 @@ export interface ContextScopeResult {
         warnings: string[];
         truncation: ContextTruncation[];
     };
-    freshness: {
-        state: ContextFreshnessState;
-        verification: ContextFreshnessVerification;
-        refresh: ContextRefreshSummary;
-    };
+    freshness: FreshnessReport;
 }
 export interface ContextGraphResult {
     contract_version: 1;

package/dist/src/view/templates/icons/call.svg

@@ -1,11 +1,13 @@
-<svg viewBox="0 0 48 48" fill="none" xmlns="http://www.w3.org/2000/svg">
-    <g id="call_icon">
-        <circle cx="24" cy="24" r="21" fill="#ff6d2e" stroke="inherit" stroke-width="4"></circle>
-        <path d="M37 22.0001L34 25.0001L23 14.0001L26 11.0001C27.5 9.50002 33 7.00005 37 11.0001C41 15.0001 38.5 20.5 37 22.0001Z" fill="#b71111" stroke="#3a1304" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
-        <path d="M42 6L37 11" stroke="#3a1304" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
-        <path d="M11 25.9999L14 22.9999L25 33.9999L22 36.9999C20.5 38.5 15 41 11 36.9999C7 32.9999 9.5 27.5 11 25.9999Z" fill="#b71111" stroke="#3a1304" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
-        <path d="M23 32L27 28" stroke="#3a1304" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
-        <path d="M6 42L11 37" stroke="#3a1304" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
-        <path d="M16 25L20 21" stroke="#3a1304" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
+<svg viewBox="0 0 48 48" fill="none" stroke="#3a3a3a" xmlns="http://www.w3.org/2000/svg">
+    <g id="call_icon" >
+        <circle cx="24" cy="24" r="21" fill="#fb7185" stroke="inherit" stroke-width="2"></circle>
+        <path d="M37 22.0001L34 25.0001L23 14.0001L26 11.0001C27.5 9.50002 33 7.00005 37 11.0001C41 15.0001 38.5 20.5 37 22.0001Z" 
+            fill="#fb7185" stroke="inherit" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
+        <path d="M42 6L37 11" stroke="inherit" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
+        <path d="M11 25.9999L14 22.9999L25 33.9999L22 36.9999C20.5 38.5 15 41 11 36.9999C7 32.9999 9.5 27.5 11 25.9999Z" 
+            fill="#fb7185" stroke="inherit" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
+        <path d="M23 32L27 28" stroke="inherit" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
+        <path d="M6 42L11 37" stroke="inherit" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
+        <path d="M16 25L20 21" stroke="inherit" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path> 
     </g>
 </svg>

package/dist/src/view/templates/interactive.css

@@ -193,20 +193,23 @@ html, body {
   font-weight: 200;
   paint-order: stroke;
   stroke: #020617;
-  stroke-width: 3px;
+  stroke-width: 2px;
   stroke-linejoin: round;
   -webkit-user-select: none;
   user-select: none;
   pointer-events: none;
 }
-.node.is-highlighted .node-shape,
 .node.is-selected .node-shape {
-  stroke: white;
-  stroke-width: 2.5;
-}
-.node.is-hidden,
-.edge.is-hidden {
-  display: none;
+  stroke: rgb(255, 255, 255);
+  stroke-width: 1;
+  filter: 
+    drop-shadow(0px 0px 12px #00a2ff)
+    drop-shadow(0px 0px 24px #00a2ff)
+    drop-shadow(0px 0px 36px #00a2ff);
+}
+.node.is-highlighted .node.is-selected .node-shape {
+  stroke: rgb(193, 193, 193);
+  stroke-width: 2;
 }
 .node.is-dimmed {
   opacity: 0.18;