@ngockhoale/ukit 2.6.7 → 2.6.8

package/src/core/codeintel/freshness.js

@@ -0,0 +1,295 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { getIndexDir, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+
+const GIT_TIMEOUT_MS = 3000;
+const NON_GIT_MANIFEST_CAP = 2000;
+const LEVELS = ['L0', 'L1', 'L2', 'L3', 'L4'];
+const SNAPSHOT_FILE = 'freshness.json';
+const DIRTY_FILE = 'dirty.json';
+
+function sha1(input) {
+  return crypto.createHash('sha1').update(input).digest('hex');
+}
+
+// Deterministic JSON: object keys sorted recursively so equal values hash equal.
+function canonicalJson(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(',')}}`;
+}
+
+// Git spawns must never throw (SPEC §7): any failure/timeout yields null.
+function runGit(rootDir, args) {
+  try {
+    const result = spawnSync('git', args, {
+      cwd: rootDir,
+      encoding: 'utf8',
+      timeout: GIT_TIMEOUT_MS,
+      maxBuffer: 16 * 1024 * 1024,
+    });
+    if (result.error || result.status !== 0) return null;
+    return result.stdout ?? '';
+  } catch {
+    return null;
+  }
+}
+
+export function getHeadSha(rootDir) {
+  const out = runGit(rootDir, ['rev-parse', 'HEAD']);
+  const sha = (out || '').trim();
+  return /^[0-9a-f]{40}$/i.test(sha) ? sha.toLowerCase() : 'nogit';
+}
+
+// Branch key for per-branch snapshot isolation (SPEC §5):
+// sanitized branch name | 'detached-<head8>' | 'nogit'. Never throws.
+export function getBranchKey(rootDir) {
+  const out = runGit(rootDir, ['branch', '--show-current']);
+  const branch = (out || '').trim();
+  if (branch) return branch.replace(/[^A-Za-z0-9._-]/g, '-');
+  const head = (runGit(rootDir, ['rev-parse', 'HEAD']) || '').trim();
+  if (/^[0-9a-f]{40}$/i.test(head)) return `detached-${head.slice(0, 8).toLowerCase()}`;
+  return 'nogit';
+}
+
+function parsePorcelainPaths(output) {
+  const paths = [];
+  for (const line of output.split('\n')) {
+    if (!line.trim()) continue;
+    let p = line.slice(3);
+    // rename entries: "old -> new" — track the new path
+    const arrow = p.indexOf(' -> ');
+    if (arrow !== -1) p = p.slice(arrow + 4);
+    p = p.trim();
+    if (p.startsWith('"') && p.endsWith('"')) p = p.slice(1, -1);
+    if (p) paths.push(p);
+  }
+  return paths;
+}
+
+async function statEntry(rootDir, rel) {
+  try {
+    const stat = await fs.stat(path.join(rootDir, rel));
+    return `${stat.mtimeMs}:${stat.size}`;
+  } catch {
+    return 'deleted:0';
+  }
+}
+
+// Read dirty.json on-disk contract {paths[], saturated} (SPEC §6).
+// Returns null when the file is missing/corrupt — dirty tracking inactive.
+async function readDirtySet(rootDir) {
+  try {
+    const raw = await fs.readFile(path.join(getIndexDir(rootDir), DIRTY_FILE), 'utf8');
+    const dirty = JSON.parse(raw);
+    if (!dirty || typeof dirty !== 'object') return null;
+    const paths = Array.isArray(dirty.paths)
+      ? dirty.paths.filter((p) => typeof p === 'string' && p.length > 0)
+      : [];
+    return { paths, saturated: dirty.saturated === true };
+  } catch {
+    return null;
+  }
+}
+
+async function overlayEntriesGit(rootDir, statusOutput, extraPaths = []) {
+  const entries = {};
+  const seen = new Set();
+  for (const rel of [...parsePorcelainPaths(statusOutput), ...extraPaths]) {
+    // Skip index-internal artifacts (.cache/) — snapshot/dirty writes must not
+    // self-invalidate the overlay.
+    if (!rel || rel.startsWith('.cache/') || seen.has(rel)) continue;
+    seen.add(rel);
+    entries[rel] = await statEntry(rootDir, rel);
+  }
+  return entries;
+}
+
+// Non-git fallback: hash LIVE mtimes for index-covered files (files.json),
+// capped at NON_GIT_MANIFEST_CAP entries. Stored mtimeMs from files.json is
+// stale by definition — only live fs.stat detects post-index edits.
+// Incremental mode: only when dirty-set tracking is active (dirty.json exists,
+// not saturated) AND a prior snapshot carries overlayEntries — reuse stored
+// entries for paths proven unchanged by the dirty set; live-stat dirty,
+// added, and unknown paths. Stored files.json mtimes are never trusted.
+async function overlayEntriesManifest(rootDir, { incremental, snapshot, dirty } = {}) {
+  let items = [];
+  try {
+    const raw = await fs.readFile(path.join(getIndexDir(rootDir), INDEX_ARTIFACTS.files), 'utf8');
+    const manifest = JSON.parse(raw);
+    items = Array.isArray(manifest?.items) ? manifest.items : [];
+  } catch {
+    return {};
+  }
+  const manifestPaths = [];
+  const seen = new Set();
+  for (const item of items.slice(0, NON_GIT_MANIFEST_CAP)) {
+    const rel = typeof item?.filePath === 'string' ? item.filePath : null;
+    if (!rel || seen.has(rel)) continue;
+    seen.add(rel);
+    manifestPaths.push(rel);
+  }
+
+  const stored = snapshot && typeof snapshot.overlayEntries === 'object' && snapshot.overlayEntries !== null
+    ? snapshot.overlayEntries
+    : null;
+  const dirtyPaths = dirty && !dirty.saturated ? new Set(dirty.paths) : null;
+  const canReuse = incremental === true && stored !== null && dirtyPaths !== null;
+
+  const entries = {};
+  for (const rel of manifestPaths) {
+    // Reuse only when dirty tracking proves the path unchanged and a stored
+    // entry exists; otherwise stat live (never trust files.json mtimeMs).
+    if (canReuse && !dirtyPaths.has(rel) && typeof stored[rel] === 'string') {
+      entries[rel] = stored[rel];
+      continue;
+    }
+    entries[rel] = await statEntry(rootDir, rel);
+  }
+  // Dirty paths outside the manifest still affect identity (stat live);
+  // index-internal artifacts are skipped.
+  if (dirtyPaths) {
+    for (const rel of dirtyPaths) {
+      if (rel.startsWith('.cache/')) continue;
+      if (entries[rel] === undefined) entries[rel] = await statEntry(rootDir, rel);
+    }
+  }
+  return entries;
+}
+
+function hashEntries(entries) {
+  const lines = Object.keys(entries)
+    .sort()
+    .map((rel) => `${rel}:${entries[rel]}`);
+  return sha1(lines.join('\n'));
+}
+
+async function computeOverlayEntries(rootDir, headSha, { incremental = true, snapshot } = {}) {
+  const dirty = await readDirtySet(rootDir);
+  if (headSha !== 'nogit') {
+    const status = runGit(rootDir, ['status', '--porcelain']);
+    if (status !== null) {
+      // Git mode: porcelain output IS the diff — dirty.json unioned defensively.
+      const extra = dirty && !dirty.saturated ? dirty.paths : [];
+      return overlayEntriesGit(rootDir, status, extra);
+    }
+  }
+  return overlayEntriesManifest(rootDir, { incremental, snapshot, dirty });
+}
+
+export async function computeOverlayHash(rootDir, headSha, { incremental = true, snapshot } = {}) {
+  const entries = await computeOverlayEntries(rootDir, headSha, { incremental, snapshot });
+  return hashEntries(entries);
+}
+
+export async function computeConfigHash(rootDir) {
+  const config = await loadRuntimeConfig(rootDir);
+  return sha1(canonicalJson({
+    codeIntel: config?.codeIntel ?? null,
+    memoryV2: config?.memoryV2 ?? null,
+    compact: { enabled: config?.compact?.enabled ?? null },
+    INDEX_SCHEMA_VERSION,
+  }));
+}
+
+export async function computeIdentity(rootDir, { incremental } = {}) {
+  const headSha = getHeadSha(rootDir);
+  const config = await loadRuntimeConfig(rootDir);
+  const useIncremental = incremental ?? (config?.codeIntel?.freshness?.incremental !== false);
+  const configHash = sha1(canonicalJson({
+    codeIntel: config?.codeIntel ?? null,
+    memoryV2: config?.memoryV2 ?? null,
+    compact: { enabled: config?.compact?.enabled ?? null },
+    INDEX_SCHEMA_VERSION,
+  }));
+  const snapshot = await readSnapshot(rootDir);
+  const overlayEntries = await computeOverlayEntries(rootDir, headSha, {
+    incremental: useIncremental,
+    snapshot,
+  });
+  const overlayHash = hashEntries(overlayEntries);
+  const identity = sha1(`${headSha}|${overlayHash}|${configHash}`);
+  return {
+    identity,
+    headSha,
+    overlayHash,
+    configHash,
+    branch: getBranchKey(rootDir),
+    overlayEntries,
+  };
+}
+
+export function getSnapshotPath(rootDir, { branch } = {}) {
+  const key = branch ?? getBranchKey(rootDir);
+  return path.join(getIndexDir(rootDir), `freshness-${key}.json`);
+}
+
+async function readSnapshotFile(snapshotPath) {
+  try {
+    const raw = await fs.readFile(snapshotPath, 'utf8');
+    const snapshot = JSON.parse(raw);
+    if (!snapshot || typeof snapshot !== 'object' || typeof snapshot.identity !== 'string') {
+      return null;
+    }
+    return snapshot;
+  } catch {
+    return null;
+  }
+}
+
+export async function readSnapshot(rootDir) {
+  // Current branch's file first, then legacy freshness.json (C26 read-compat).
+  const branchSnapshot = await readSnapshotFile(getSnapshotPath(rootDir));
+  if (branchSnapshot) return branchSnapshot;
+  return readSnapshotFile(path.join(getIndexDir(rootDir), SNAPSHOT_FILE));
+}
+
+export async function writeSnapshot(rootDir, snapshot) {
+  const snapshotPath = getSnapshotPath(rootDir);
+  const legacyPath = path.join(getIndexDir(rootDir), SNAPSHOT_FILE);
+  await fs.mkdir(path.dirname(snapshotPath), { recursive: true });
+  const payload = JSON.stringify(snapshot, null, 2);
+  await fs.writeFile(snapshotPath, payload);
+  // Legacy alias: older readers still look at freshness.json.
+  if (legacyPath !== snapshotPath) {
+    await fs.writeFile(legacyPath, payload);
+  }
+}
+
+function levelIndex(level) {
+  return LEVELS.indexOf(level);
+}
+
+function clampLevel(level, maxLevel) {
+  const cap = levelIndex(maxLevel);
+  if (cap === -1) return level;
+  return levelIndex(level) > cap ? maxLevel : level;
+}
+
+// Lowest L that repairs the staleness:
+// - no usable snapshot → L2 (batch incremental over unknown state)
+// - configHash changed → L4 (schema/config drift needs full rebuild)
+// - headSha changed → L2 (batch incremental)
+// - overlayHash only → L1 (dirty-file refresh)
+function repairLevel(snapshot, current) {
+  if (!snapshot) return 'L2';
+  if (snapshot.configHash !== current.configHash) return 'L4';
+  if (snapshot.headSha !== current.headSha) return 'L2';
+  return 'L1';
+}
+
+export async function guardLevel(rootDir, { maxLevel = 'L4' } = {}) {
+  const [identity, snapshot] = await Promise.all([
+    computeIdentity(rootDir),
+    readSnapshot(rootDir),
+  ]);
+  const stale = !snapshot || snapshot.identity !== identity.identity;
+  const recommendedLevel = stale
+    ? clampLevel(repairLevel(snapshot, identity), maxLevel)
+    : 'L0';
+  return { identity, snapshot, stale, recommendedLevel };
+}

package/src/core/codeintel/impact.js

@@ -0,0 +1,251 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+import { getArtifactPath, INDEX_ARTIFACTS, INDEX_SCHEMA_VERSION } from '../../index/paths.js';
+import { loadRuntimeConfig } from '../runtimeConfig.js';
+
+// Multi-hop impact/trace engine (SPEC §4) — cycle-safe BFS over imports.json +
+// calls.json edges. `dependents` walks reverse edges (who imports the seed),
+// `dependencies` walks forward edges (what the seed imports/calls), `both`
+// unions the two with signed hops. Never throws: missing artifacts degrade to
+// an empty result with an `omitted` reason.
+
+const DEFAULT_DEPTH = 2;
+const DEFAULT_MAX_DEPTH = 4;
+const DEFAULT_MAX_NODES = 200;
+
+async function readArtifact(rootDir, name) {
+  try {
+    const raw = await fs.readFile(getArtifactPath(rootDir, name), 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed?.schemaVersion !== undefined && parsed.schemaVersion !== INDEX_SCHEMA_VERSION) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+// Local copy of the specifier resolver (SPEC §4 — do NOT import retriever.js,
+// a same-wave file). Resolves a relative/bare import specifier against the
+// indexed file set.
+function resolveRelativeSpecifier(fromFile, specifier, fileSet) {
+  const candidates = [];
+  if (specifier.startsWith('.')) {
+    const base = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), specifier));
+    candidates.push(base, `${base}.js`, `${base}.ts`, `${base}.mjs`, `${base}.jsx`, `${base}.tsx`, `${base}/index.js`, `${base}/index.ts`);
+  } else {
+    candidates.push(specifier);
+  }
+  for (const candidate of candidates) {
+    if (fileSet.has(candidate)) return candidate;
+  }
+  return null;
+}
+
+function impactDefaults(config) {
+  const impact = config?.codeIntel?.impact;
+  return {
+    defaultDepth: typeof impact?.defaultDepth === 'number' ? impact.defaultDepth : DEFAULT_DEPTH,
+    maxDepth: typeof impact?.maxDepth === 'number' ? impact.maxDepth : DEFAULT_MAX_DEPTH,
+    maxNodes: typeof impact?.maxNodes === 'number' ? impact.maxNodes : DEFAULT_MAX_NODES,
+  };
+}
+
+function clampInt(value, min, max) {
+  const n = Math.floor(Number(value));
+  if (!Number.isFinite(n)) return min;
+  return Math.min(Math.max(n, min), max);
+}
+
+function addAdjacency(map, key, edge) {
+  let list = map.get(key);
+  if (!list) {
+    list = [];
+    map.set(key, list);
+  }
+  list.push(edge);
+}
+
+/**
+ * impactSet(projectRoot, seeds, { depth?, direction?, maxDepth?, maxNodes? })
+ *   → { nodes: [{ file, hop, via: edge[] }],
+ *       edges: [{ from, to, kind:'import'|'call', symbol? }],
+ *       truncated: boolean,
+ *       omitted: [{ what, why }] }
+ */
+export async function impactSet(projectRoot, seeds, {
+  depth,
+  direction = 'dependents',
+  maxDepth,
+  maxNodes,
+} = {}) {
+  const rootDir = path.resolve(projectRoot ?? process.cwd());
+  const omitted = [];
+  const empty = { nodes: [], edges: [], truncated: false, omitted };
+
+  let config = null;
+  try {
+    config = await loadRuntimeConfig(rootDir);
+  } catch {
+    config = null;
+  }
+  const defaults = impactDefaults(config);
+
+  const maxDepthCap = clampInt(maxDepth ?? defaults.maxDepth, 1, Number.MAX_SAFE_INTEGER);
+  const nodeCap = clampInt(maxNodes ?? defaults.maxNodes, 1, Number.MAX_SAFE_INTEGER);
+  const requestedDepth = typeof depth === 'number' ? depth : defaults.defaultDepth;
+  const depthLimit = clampInt(requestedDepth, 1, maxDepthCap);
+  const depthClamped = requestedDepth > depthLimit;
+
+  const seedList = Array.isArray(seeds) ? seeds.filter((s) => typeof s === 'string' && s.length > 0) : [];
+  if (seedList.length === 0) {
+    omitted.push({ what: 'impact', why: 'empty-seeds' });
+    return empty;
+  }
+
+  const [filesArtifact, importsArtifact, callsArtifact] = await Promise.all([
+    readArtifact(rootDir, INDEX_ARTIFACTS.files),
+    readArtifact(rootDir, INDEX_ARTIFACTS.imports),
+    readArtifact(rootDir, INDEX_ARTIFACTS.calls),
+  ]);
+
+  if (!importsArtifact && !callsArtifact) {
+    omitted.push({ what: 'impact', why: 'index-missing' });
+    return empty;
+  }
+
+  // File set for specifier resolution — files.json first, with imports' `from`
+  // endpoints as fallback so a partial index still resolves.
+  const fileSet = new Set((filesArtifact?.items ?? []).map((f) => f.filePath).filter(Boolean));
+  for (const imp of importsArtifact?.items ?? []) {
+    if (imp?.from) fileSet.add(imp.from);
+  }
+
+  // Adjacency: forward = dependencies (from → to), reverse = dependents (to → from).
+  const forward = new Map();
+  const reverse = new Map();
+  for (const imp of importsArtifact?.items ?? []) {
+    if (!imp?.from || !imp?.to) continue;
+    const target = resolveRelativeSpecifier(imp.from, imp.to, fileSet);
+    if (!target || target === imp.from) continue;
+    const edge = { from: imp.from, to: target, kind: 'import' };
+    addAdjacency(forward, edge.from, edge);
+    // Reverse edges are flipped so `from`/`to` always read seed→impacted.
+    addAdjacency(reverse, edge.to, { from: edge.to, to: edge.from, kind: 'import' });
+  }
+
+  // calls.json → symbol map; call edges are forward-only (dependencies side).
+  const symbolToFile = new Map();
+  for (const call of callsArtifact?.items ?? []) {
+    if (call?.filePath && call?.symbol && !symbolToFile.has(call.symbol)) {
+      symbolToFile.set(call.symbol, call.filePath);
+    }
+  }
+  const wantDeps = direction === 'dependencies' || direction === 'both';
+  const wantRev = direction === 'dependents' || direction === 'both';
+  if (wantDeps) {
+    for (const call of callsArtifact?.items ?? []) {
+      if (!call?.filePath) continue;
+      for (const name of call.calls ?? []) {
+        const target = symbolToFile.get(name);
+        if (!target || target === call.filePath) continue;
+        addAdjacency(forward, call.filePath, { from: call.filePath, to: target, kind: 'call', symbol: name });
+      }
+    }
+  }
+
+  // Resolve seeds → files. File seeds match indexed paths; symbol seeds match
+  // calls.json `symbol` fields (their filePath becomes the node).
+  const seedFiles = [];
+  for (const seed of seedList) {
+    if (fileSet.has(seed) || forward.has(seed) || reverse.has(seed)) {
+      seedFiles.push(seed);
+      continue;
+    }
+    const viaSymbol = symbolToFile.get(seed);
+    if (viaSymbol) {
+      seedFiles.push(viaSymbol);
+    }
+  }
+  if (seedFiles.length === 0) {
+    omitted.push({ what: 'impact', why: 'seeds-unmatched' });
+    return empty;
+  }
+
+  const nodes = new Map(); // file → { file, hop, via }
+  const edges = [];
+  const edgeKeys = new Set();
+  const visited = new Set(); // `${file}|${side}`
+  const sideHop = new Map(); // `${file}|${side}` → unsigned hop
+  let truncated = false;
+
+  const emitEdge = (edge) => {
+    const key = `${edge.from}|${edge.to}|${edge.kind}|${edge.symbol ?? ''}`;
+    if (edgeKeys.has(key)) return;
+    edgeKeys.add(key);
+    edges.push(edge);
+  };
+
+  // side: 'rev' (dependents, positive hop) | 'fwd' (dependencies, negative hop)
+  const bfs = (side) => {
+    const adjacency = side === 'rev' ? reverse : forward;
+    const sign = side === 'rev' ? 1 : -1;
+    const queue = [];
+    for (const seed of seedFiles) {
+      const key = `${seed}|${side}`;
+      if (!visited.has(key)) {
+        visited.add(key);
+        sideHop.set(key, 0);
+        queue.push({ file: seed, hop: 0 });
+      }
+    }
+    while (queue.length > 0) {
+      const { file, hop } = queue.shift();
+      if (hop >= depthLimit) continue;
+      for (const edge of adjacency.get(file) ?? []) {
+        const next = edge.to;
+        emitEdge(edge);
+        const visitKey = `${next}|${side}`;
+        if (visited.has(visitKey)) continue;
+        visited.add(visitKey);
+        const nextHop = hop + 1;
+        sideHop.set(visitKey, nextHop);
+        if (nodes.size >= nodeCap && !nodes.has(next)) {
+          truncated = true;
+          continue;
+        }
+        const existing = nodes.get(next);
+        if (!existing || Math.abs(nextHop) < Math.abs(existing.hop)) {
+          nodes.set(next, { file: next, hop: sign * nextHop, via: [edge] });
+        } else if (Math.abs(nextHop) === Math.abs(existing.hop)) {
+          existing.via.push(edge);
+        }
+        queue.push({ file: next, hop: nextHop });
+      }
+    }
+  };
+
+  if (wantRev) bfs('rev');
+  if (wantDeps) bfs('fwd');
+
+  // Detect hop-clamp truncation: any visited node at the cap whose adjacency
+  // still has unvisited neighbors would have produced more nodes.
+  const frontierCheck = (side) => {
+    const adjacency = side === 'rev' ? reverse : forward;
+    for (const [key, hop] of sideHop) {
+      if (hop !== depthLimit) continue;
+      const sep = key.lastIndexOf('|');
+      const file = key.slice(0, sep);
+      if (key.slice(sep + 1) !== side) continue;
+      for (const edge of adjacency.get(file) ?? []) {
+        if (!visited.has(`${edge.to}|${side}`)) return true;
+      }
+    }
+    return false;
+  };
+  if (frontierCheck('rev') || (wantDeps && frontierCheck('fwd'))) truncated = true;
+
+  return { nodes: [...nodes.values()], edges, truncated, omitted };
+}

package/src/core/codeintel/invalidation.js

@@ -0,0 +1,150 @@
+import path from 'node:path';
+import { getIndexDir } from '../../index/paths.js';
+import { ensureDir, readJsonIfExists, withFileLock, writeJson } from '../fileOps.js';
+
+/**
+ * Post-edit invalidation (SPEC §6 — CI-205).
+ *
+ * `.cache/index/dirty.json` is the shared on-disk contract between the edit
+ * lane (`notifyEdit`), the freshness lane (TASK-204 reads the file directly),
+ * the compiler (TASK-206 reads via `readDirty`, non-destructive), and the
+ * index-refresh lane (`drainDirty`).
+ *
+ * File shape: `{ schemaVersion: 1, paths: string[], saturated: boolean, updatedAt: string }`
+ * - `paths`: sorted, deduped, posix repo-relative paths.
+ * - `saturated`: true once the set hits `DIRTY_MAX_PATHS`; consumers treat a
+ *   saturated set as full invalidation (freshness falls back to full scan).
+ *
+ * Writes are atomic (tmp+rename via `writeJson`). `notifyEdit` merges via
+ * set-union inside a file lock (`withFileLock`) so concurrent callers never
+ * lose updates; read-merge-write retry (max 3) is kept as a fallback when the
+ * lock itself cannot be acquired. Missing/corrupt file → `[]`, never throws.
+ */
+
+export const DIRTY_SCHEMA_VERSION = 1;
+export const DIRTY_MAX_PATHS = 5000;
+
+const MERGE_MAX_ATTEMPTS = 3;
+
+export function getDirtyPath(projectRoot) {
+  return path.join(getIndexDir(projectRoot), 'dirty.json');
+}
+
+/**
+ * Normalize a candidate dirty path to a posix repo-relative form.
+ * Returns null for unsafe input: absolute paths, `..` escapes, empties.
+ */
+function normalizeDirtyPath(relPath) {
+  if (typeof relPath !== 'string') return null;
+  let p = relPath.trim().replace(/\\/g, '/');
+  if (!p) return null;
+  if (p.startsWith('/') || /^[A-Za-z]:\//.test(p)) return null; // absolute
+  while (p.startsWith('./')) p = p.slice(2);
+  if (!p || p === '.' ) return null;
+  const segments = p.split('/');
+  if (segments.some((s) => s === '..')) return null;
+  const normalized = path.posix.normalize(p);
+  if (!normalized || normalized === '.' || normalized.startsWith('../') || normalized === '..') {
+    return null;
+  }
+  return normalized;
+}
+
+function parseDirtyData(data) {
+  if (!data || typeof data !== 'object') return { paths: [], saturated: false };
+  const paths = Array.isArray(data.paths)
+    ? data.paths.filter((p) => typeof p === 'string')
+    : [];
+  return { paths, saturated: data.saturated === true };
+}
+
+async function readDirtyData(projectRoot) {
+  try {
+    const data = await readJsonIfExists(getDirtyPath(projectRoot));
+    return parseDirtyData(data);
+  } catch {
+    return { paths: [], saturated: false };
+  }
+}
+
+async function writeDirtyData(projectRoot, paths, saturated) {
+  const dirtyPath = getDirtyPath(projectRoot);
+  await ensureDir(path.dirname(dirtyPath));
+  await writeJson(dirtyPath, {
+    schemaVersion: DIRTY_SCHEMA_VERSION,
+    paths,
+    saturated,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+/**
+ * Merge `relPaths` into the dirty set. Atomic, merge-safe (read-merge-write,
+ * retry max 3 on write failure), saturating at DIRTY_MAX_PATHS.
+ * @returns {Promise<{ dirty: string[] }>} sorted resulting set
+ */
+export async function notifyEdit(projectRoot, relPaths) {
+  const incoming = new Set();
+  for (const relPath of Array.isArray(relPaths) ? relPaths : []) {
+    const normalized = normalizeDirtyPath(relPath);
+    if (normalized) incoming.add(normalized);
+  }
+
+  const mergeOnce = async () => {
+    const current = await readDirtyData(projectRoot);
+    const merged = new Set(current.paths);
+    for (const p of incoming) merged.add(p);
+    const saturated = merged.size > DIRTY_MAX_PATHS;
+    const paths = [...merged].sort().slice(0, DIRTY_MAX_PATHS);
+    await writeDirtyData(projectRoot, paths, saturated);
+    return paths;
+  };
+
+  const dirtyPath = getDirtyPath(projectRoot);
+  let lastError = null;
+  for (let attempt = 0; attempt < MERGE_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const paths = await withFileLock(dirtyPath, mergeOnce);
+      return { dirty: paths };
+    } catch (error) {
+      lastError = error;
+      // Fall back to unlocked merge if locking is unavailable on this fs.
+      if (attempt === MERGE_MAX_ATTEMPTS - 1) break;
+      try {
+        const paths = await mergeOnce();
+        return { dirty: paths };
+      } catch (error2) {
+        lastError = error2;
+      }
+    }
+  }
+  // Retry budget exhausted — surface the last write error's message without
+  // throwing past the never-throw contract boundary: return current state.
+  void lastError;
+  const current = await readDirtyData(projectRoot);
+  return { dirty: [...current.paths].sort() };
+}
+
+/**
+ * Non-destructive read of the dirty set (compiler lane uses this).
+ * @returns {Promise<string[]>} sorted paths, `[]` on missing/corrupt.
+ */
+export async function readDirty(projectRoot) {
+  const { paths } = await readDirtyData(projectRoot);
+  return [...paths].sort();
+}
+
+/**
+ * Return the accumulated dirty set and clear the file (index-refresh lane).
+ * @returns {Promise<string[]>} sorted paths, `[]` on missing/corrupt.
+ */
+export async function drainDirty(projectRoot) {
+  const { paths, saturated } = await readDirtyData(projectRoot);
+  if (paths.length === 0 && !saturated) return [];
+  try {
+    await writeDirtyData(projectRoot, [], false);
+  } catch {
+    // never throw — drained set is still returned
+  }
+  return [...paths].sort();
+}