@psnext/lscg 0.1.4 → 0.1.5

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/watch.d.ts

@@ -1,9 +1,10 @@
-import { scanRepository } from './graph/repository.js';
-import type { RepositoryRecord, StorageScope } from './types.js';
+import { drainRepositoryEnrichment, scanRepository } from './graph/repository.js';
+import type { EnrichmentSummary, ProgressReporter, RepositoryRecord, StorageScope } from './types.js';
 export interface WatchCommandOptions {
     root?: string | undefined;
     scope?: StorageScope | 'both' | undefined;
     intervalMs?: number | undefined;
+    debounceMs?: number | undefined;
 }
 export interface WatchSummary {
     filesDiscovered: number;
@@ -11,6 +12,7 @@ export interface WatchSummary {
     nodesWritten: number;
     edgesWritten: number;
     skippedCount: number;
+    enrichment: EnrichmentSummary;
 }
 export interface WatchEvent {
     event: 'watching' | 'scan' | 'waiting' | 'rescan-triggered' | 'stopped';
@@ -22,13 +24,26 @@ export interface WatchEvent {
     summary?: WatchSummary | undefined;
     scans?: number | undefined;
 }
+export type FileSystemWatchEvent = 'change' | 'rename';
+export type FileSystemWatchListener = (event: FileSystemWatchEvent, filename: string | Buffer | null) => void;
+/** Minimal fs.watch surface so watch behavior can be tested without the filesystem. */
+export interface FileSystemWatcher {
+    close(): void;
+    on(event: 'error', listener: (error: Error) => void): this;
+}
+export type FileSystemWatcherFactory = (directory: string, options: {
+    recursive: boolean;
+}, listener: FileSystemWatchListener) => FileSystemWatcher;
 export interface WatchDependencies {
     scanRepository?: typeof scanRepository | undefined;
+    drainEnrichment?: typeof drainRepositoryEnrichment | undefined;
     fingerprint?: ((root: string) => Promise<string> | string) | undefined;
+    watcherFactory?: FileSystemWatcherFactory | undefined;
     emit?: ((event: WatchEvent) => void) | undefined;
     wait?: ((ms: number, signal?: AbortSignal) => Promise<void>) | undefined;
     signal?: AbortSignal | undefined;
     mode?: 'watch' | 'scan --watch' | undefined;
+    progress?: ProgressReporter | undefined;
 }
 export interface WatchRunResult {
     repository: RepositoryRecord;

package/dist/src/watch.js

@@ -1,30 +1,115 @@
+import { readdirSync, watch as watchFileSystem } from 'node:fs';
+import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
-import { repositoryForRoot, scanRepository } from './graph/repository.js';
+import { drainRepositoryEnrichment, repositoryForRoot, scanRepository } from './graph/repository.js';
 import { collectRepositoryFingerprint } from './scanner/fingerprint.js';
+import { discoverSourceFiles } from './scanner/discover.js';
+import { isSupportedSourceFile } from './parser/treeSitter.js';
 const DEFAULT_POLL_INTERVAL_MS = 1000;
+const DEFAULT_DEBOUNCE_MS = 100;
+const IGNORED_WATCH_DIRECTORIES = new Set(['.git', 'node_modules', 'dist', 'coverage', '.next', '.turbo', '.cache', '.sling']);
 export async function watchRepository(options = {}, dependencies = {}) {
     const scope = resolveWatchScope(options.scope);
     const repository = repositoryForRoot(options.root);
     const scanFn = dependencies.scanRepository ?? scanRepository;
+    const drainEnrichment = dependencies.drainEnrichment ?? drainRepositoryEnrichment;
     const fingerprintFn = dependencies.fingerprint ?? ((root) => collectRepositoryFingerprint(root));
+    const watcherFactory = dependencies.watcherFactory ?? defaultWatcherFactory;
     const emit = dependencies.emit ?? defaultEmit;
     const wait = dependencies.wait ?? defaultWait;
     const signal = dependencies.signal;
     const mode = dependencies.mode ?? 'watch';
+    const progress = dependencies.progress;
     const intervalMs = options.intervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const debounceMs = options.debounceMs ?? DEFAULT_DEBOUNCE_MS;
     let scans = 0;
     let stopped = false;
-    let currentFingerprint = await fingerprintFn(repository.root);
-    emit({
-        event: 'watching',
-        mode,
-        repository,
-        scope
-    });
+    let scanning = false;
+    let polling = false;
+    let currentFingerprint;
+    let followUpQueued = false;
+    let pendingEventPaths = new Set();
+    let failed = false;
+    let wakeWaiting;
+    const watchers = [];
+    const wake = () => {
+        const resolve = wakeWaiting;
+        wakeWaiting = undefined;
+        resolve?.();
+    };
+    const queueReconciliation = () => {
+        if (scanning) {
+            followUpQueued = true;
+        }
+        else {
+            pendingEventPaths.add('');
+        }
+        wake();
+    };
+    const usePollingFallback = () => {
+        if (polling)
+            return;
+        polling = true;
+        currentFingerprint = undefined;
+        closeWatchers(watchers);
+        reportWatchProgress(progress, { event: 'polling-fallback', mode, repository, scope, detail: 'filesystem watcher unavailable; polling fallback enabled' });
+        queueReconciliation();
+    };
+    const handleWatchEvent = (watchedDirectory, event, filename) => {
+        if (event === 'rename' || filename === null) {
+            usePollingFallback();
+            return;
+        }
+        const relativePath = relevantWatchPath(repository.root, watchedDirectory, filename);
+        if (!relativePath)
+            return;
+        pendingEventPaths.add(relativePath);
+        if (scanning)
+            followUpQueued = true;
+        wake();
+    };
+    const addWatcher = (directory, recursive) => {
+        const watcher = watcherFactory(directory, { recursive }, (event, filename) => handleWatchEvent(directory, event, filename));
+        watcher.on('error', () => usePollingFallback());
+        watchers.push(watcher);
+    };
     try {
+        try {
+            addWatcher(repository.root, true);
+        }
+        catch {
+            closeWatchers(watchers);
+            try {
+                for (const directory of watchDirectories(repository.root)) {
+                    addWatcher(directory, false);
+                }
+            }
+            catch {
+                closeWatchers(watchers);
+                polling = true;
+                reportWatchProgress(progress, { event: 'polling-fallback', mode, repository, scope, detail: 'filesystem watcher unavailable; polling fallback enabled' });
+            }
+        }
+        emit({
+            event: 'watching',
+            mode,
+            repository,
+            scope
+        });
+        reportWatchProgress(progress, { event: 'watching', mode, repository, scope, detail: 'watch session started' });
         while (!signal?.aborted) {
-            const scanStartFingerprint = currentFingerprint;
-            const summary = await scanFn({ root: repository.root, scope });
+            scanning = true;
+            const phase = scans === 0 ? 'initial-scan' : 'rescan';
+            reportWatchProgress(progress, { event: phase, mode, repository, scope, detail: scans === 0 ? 'starting initial scan' : 'starting rescan' });
+            const scanStartFingerprint = polling ? await fingerprintFn(repository.root) : undefined;
+            const structuralSummary = await scanFn({ root: repository.root, scope, progress });
+            // A watch owns in-process enrichment. Awaiting it while `scanning` is
+            // true serializes durable work with structural replacement; a filesystem
+            // event during either phase queues exactly one follow-up structural scan.
+            const enrichment = await drainEnrichment({ root: repository.root, scope });
+            reportWatchProgress(progress, { event: 'enrichment', mode, repository, scope, detail: `state=${enrichment.state} pending=${enrichment.pending} complete=${enrichment.complete} failed=${enrichment.failed}` });
+            const summary = { ...structuralSummary, enrichment };
+            scanning = false;
             scans += 1;
             emit({
                 event: 'scan',
@@ -34,44 +119,60 @@ export async function watchRepository(options = {}, dependencies = {}) {
                 scope,
                 summary: summarizeScan(summary)
             });
-            const scanEndFingerprint = await fingerprintFn(repository.root);
-            currentFingerprint = scanEndFingerprint;
+            if (polling) {
+                const scanEndFingerprint = await fingerprintFn(repository.root);
+                const changedDuringScan = scanStartFingerprint !== undefined && scanEndFingerprint !== scanStartFingerprint;
+                currentFingerprint = scanEndFingerprint;
+                if (changedDuringScan)
+                    followUpQueued = true;
+            }
             if (signal?.aborted)
                 break;
-            if (scanEndFingerprint !== scanStartFingerprint) {
-                emit({
-                    event: 'rescan-triggered',
-                    mode,
-                    reason: 'follow-up',
-                    repository,
-                    scope
-                });
+            if (followUpQueued) {
+                followUpQueued = false;
+                pendingEventPaths = new Set();
+                emitRescanTriggered('follow-up', mode, repository, scope, emit, progress);
                 continue;
             }
-            emit({
-                event: 'waiting',
-                mode,
-                repository,
-                scope
-            });
-            while (!signal?.aborted) {
-                await wait(intervalMs, signal);
-                const nextFingerprint = await fingerprintFn(repository.root);
-                if (nextFingerprint !== currentFingerprint) {
+            emit({ event: 'waiting', mode, repository, scope });
+            reportWatchProgress(progress, { event: 'waiting', mode, repository, scope, detail: polling ? 'waiting for polling interval' : 'waiting for file changes' });
+            if (polling) {
+                while (!signal?.aborted) {
+                    await wait(intervalMs, signal);
+                    const nextFingerprint = await fingerprintFn(repository.root);
+                    if (nextFingerprint === currentFingerprint)
+                        continue;
                     currentFingerprint = nextFingerprint;
-                    emit({
-                        event: 'rescan-triggered',
-                        mode,
-                        reason: 'file-change',
-                        repository,
-                        scope
-                    });
+                    emitRescanTriggered('file-change', mode, repository, scope, emit, progress);
                     break;
                 }
+                continue;
+            }
+            if (pendingEventPaths.size === 0) {
+                await waitForWatchEvent(signal, (resolve) => {
+                    wakeWaiting = resolve;
+                });
             }
+            if (signal?.aborted)
+                break;
+            if (polling)
+                continue;
+            if (pendingEventPaths.size === 0)
+                continue;
+            await wait(debounceMs, signal);
+            if (signal?.aborted)
+                break;
+            pendingEventPaths = new Set();
+            emitRescanTriggered('file-change', mode, repository, scope, emit, progress);
         }
     }
+    catch (error) {
+        failed = true;
+        reportWatchProgress(progress, { event: 'failed', mode, repository, scope, detail: error instanceof Error ? error.message : String(error) });
+        throw error;
+    }
     finally {
+        closeWatchers(watchers);
         stopped = true;
         emit({
             event: 'stopped',
@@ -80,28 +181,90 @@ export async function watchRepository(options = {}, dependencies = {}) {
             scope,
             scans
         });
+        if (!failed)
+            reportWatchProgress(progress, { event: 'stopped', mode, repository, scope, detail: `watch session stopped after ${scans} scan(s)` });
     }
-    return {
-        repository,
-        scope,
-        scans,
-        stopped
-    };
+    return { repository, scope, scans, stopped };
 }
 function resolveWatchScope(scope) {
     if (scope === undefined || scope === 'repo')
         return 'repo';
     throw new Error('watch mode supports repo scope only');
 }
+function watchDirectories(root) {
+    const directories = new Set([root]);
+    for (const relativePath of discoverSourceFiles(root)) {
+        directories.add(path.dirname(path.join(root, relativePath)));
+    }
+    // Immediate module directories contain the supported Maven/Gradle manifests
+    // and must also be watched when a module has no source files yet.
+    try {
+        for (const entry of readdirSync(root, { withFileTypes: true })) {
+            if (entry.isDirectory() && !entry.isSymbolicLink() && !IGNORED_WATCH_DIRECTORIES.has(entry.name))
+                directories.add(path.join(root, entry.name));
+        }
+    }
+    catch { /* scan will report traversal degradation */ }
+    return [...directories].sort();
+}
+function relevantWatchPath(root, watchedDirectory, filename) {
+    const filenameText = Buffer.isBuffer(filename) ? filename.toString() : filename;
+    const absolutePath = path.resolve(watchedDirectory, filenameText);
+    const relativePath = path.relative(root, absolutePath);
+    if (!relativePath || path.isAbsolute(relativePath) || relativePath === '..' || relativePath.startsWith(`..${path.sep}`))
+        return undefined;
+    const pathSegments = relativePath.split(path.sep);
+    if (pathSegments.some((segment) => IGNORED_WATCH_DIRECTORIES.has(segment)))
+        return undefined;
+    const basename = path.basename(relativePath);
+    const depth = pathSegments.length;
+    const supportedManifest = depth <= 2 && (basename === 'pom.xml' || basename === 'build.gradle' || basename === 'build.gradle.kts');
+    if (basename !== 'package.json' && !isSupportedSourceFile(absolutePath) && !supportedManifest)
+        return undefined;
+    return relativePath;
+}
+function closeWatchers(watchers) {
+    while (watchers.length > 0) {
+        watchers.pop()?.close();
+    }
+}
+function waitForWatchEvent(signal, setWake) {
+    return new Promise((resolve) => {
+        const done = () => {
+            signal?.removeEventListener('abort', done);
+            resolve();
+        };
+        if (signal?.aborted) {
+            done();
+            return;
+        }
+        setWake(done);
+        signal?.addEventListener('abort', done, { once: true });
+    });
+}
+function emitRescanTriggered(reason, mode, repository, scope, emit, progress) {
+    emit({ event: 'rescan-triggered', mode, reason, repository, scope });
+    reportWatchProgress(progress, { event: reason === 'follow-up' ? 'follow-up' : 'coalesced-change', mode, repository, scope, detail: reason === 'follow-up' ? 'change queued during scan; running follow-up' : 'coalesced file changes; running one rescan' });
+}
 function summarizeScan(summary) {
     return {
         filesDiscovered: summary.filesDiscovered,
         filesScanned: summary.filesScanned,
         nodesWritten: summary.nodesWritten,
         edgesWritten: summary.edgesWritten,
-        skippedCount: summary.skipped.length
+        skippedCount: summary.skipped.length,
+        enrichment: summary.enrichment
     };
 }
+function reportWatchProgress(progress, event) {
+    try {
+        progress?.({ kind: 'watch', ...event });
+    }
+    catch { /* progress is observational */ }
+}
+function defaultWatcherFactory(directory, options, listener) {
+    return watchFileSystem(directory, options, (event, filename) => listener(event, filename));
+}
 function defaultEmit(event) {
     console.log(JSON.stringify(event));
 }
@@ -110,9 +273,8 @@ async function defaultWait(ms, signal) {
         await sleep(ms, undefined, signal ? { signal } : undefined);
     }
     catch (error) {
-        if (!signal?.aborted) {
+        if (!signal?.aborted)
             throw error;
-        }
     }
 }
 //# sourceMappingURL=watch.js.map