@dotdotgod/cli 0.6.6 → 0.7.0

package/src/graph-view/policy.cjs

@@ -0,0 +1,13 @@
+// Shared by the standalone browser and the Obsidian adapter.
+function selectTraceability(graph, { documentsOnly = false, disabledRelations = [] } = {}) {
+  const disabled = new Set(disabledRelations);
+  const active = graph.edges.filter(e => !disabled.has(e.relation) && (!documentsOnly || [e.source, e.target].every(p => /\.md$/i.test(p))));
+  const pairs = new Map();
+  for (const edge of [...active].sort((a, b) => b.weight - a.weight || a.relation.localeCompare(b.relation))) {
+    const key = `${edge.source}\0${edge.target}`;
+    if (!pairs.has(key)) pairs.set(key, edge);
+  }
+  return { edges: [...pairs.values()], paths: [...new Set(active.flatMap(e => [e.source, e.target]))] };
+}
+if (typeof module !== 'undefined') module.exports = { selectTraceability };
+else globalThis.selectTraceability = selectTraceability;

package/src/graph-view/server.mjs

@@ -1,18 +1,13 @@
 import { createServer } from 'node:http';
 import { readFileSync } from 'node:fs';
-import { dirname, extname, join } from 'node:path';
+import { dirname, extname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { buildVectorImpactOverlay } from '../impact/vector-overlay.mjs';
-import { buildImpactReport } from '../impact/report.mjs';
-import { canonicalizeChangedPath } from '../impact/vector-profile.mjs';
-import { readFreshIndex } from '../index/cache.mjs';
-import { buildImpactGraphPayload } from './payload.mjs';
+import { exportTraceability } from './traceability.mjs';
+import nodeStyle from './node-style.cjs';
 
 const ASSET_ROOT = join(dirname(fileURLToPath(import.meta.url)), 'assets');
-const CONTENT_TYPES = { '.css': 'text/css; charset=utf-8', '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.map': 'application/json; charset=utf-8' };
+const CONTENT_TYPES = { '.css': 'text/css; charset=utf-8', '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.cjs': 'text/javascript; charset=utf-8', '.map': 'application/json; charset=utf-8' };
 const VENDOR_FILES = {
-  '/vendor/sigma.js': new URL('../../node_modules/sigma/dist/sigma.min.js', import.meta.url),
-  '/vendor/graphology.js': new URL('../../node_modules/graphology/dist/graphology.umd.min.js', import.meta.url),
   '/vendor/d3.js': new URL('../../node_modules/d3/dist/d3.min.js', import.meta.url),
 };
 
@@ -32,38 +27,30 @@ function asset(response, file) {
   }
 }
 
-export async function buildServedImpact(root, changedPaths) {
-  const normalized = [...new Set(changedPaths.map((path) => canonicalizeChangedPath(root, path)).filter(Boolean))];
-  const { status, index, metadata } = readFreshIndex(root);
-  const overlay = await buildVectorImpactOverlay(root, index, normalized);
-  const impact = buildImpactReport(index, normalized, { root, overlay, verboseSemantic: false, related: 40 });
-  const graph = buildImpactGraphPayload(index, impact);
-  const graphIds = new Set(graph.nodes.map((node) => node.id));
-  const explorerImpact = {
-    ...impact,
-    related: impact.related.filter((item) => graphIds.has(item.id)),
-  };
-  return { ok: status.ok, status, metadata, impact: explorerImpact, graph };
-}
-
 export async function startImpactGraphServer({ root, changed, host = '127.0.0.1', port = 0 }) {
-  let payload = await buildServedImpact(root, changed);
+  root = resolve(root);
+  if (!['127.0.0.1', 'localhost', '::1'].includes(host)) throw new Error('Graph UI is local-only; use a loopback host.');
+  const build = async () => {
+    const data = await exportTraceability(root);
+    const paths = [...new Set(data.edges.flatMap(e => [e.source, e.target]))];
+    return { ...data, projectRoot: undefined, nodes: paths.map(path => ({ id: path, ...nodeStyle.describeNode(path, data.config.documentation.root) })) };
+  };
+  let payload = await build();
   const server = createServer(async (request, response) => {
     const url = new URL(request.url ?? '/', `http://${request.headers.host ?? host}`);
-    if (url.pathname === '/api/impact') return json(response, 200, payload);
-    if (url.pathname === '/api/reroot') {
-      const paths = url.searchParams.getAll('changed');
-      if (paths.length === 0) return json(response, 400, { ok: false, error: { code: 'MISSING_CHANGED', message: 'At least one changed path is required.' } });
+    if (!['GET', 'HEAD'].includes(request.method)) return json(response, 405, { error: 'Method not allowed' });
+    if (url.pathname === '/api/graph') {
       try {
-        payload = await buildServedImpact(root, paths);
+        payload = await build();
         return json(response, 200, payload);
       } catch (error) {
         return json(response, 500, { ok: false, error: { code: 'GRAPH_SERVE_FAILED', message: error instanceof Error ? error.message : String(error) } });
       }
     }
     if (VENDOR_FILES[url.pathname]) return asset(response, fileURLToPath(VENDOR_FILES[url.pathname]));
+    if (url.pathname === '/policy.js') return asset(response, join(ASSET_ROOT, '../policy.cjs'));
     const relative = url.pathname === '/' ? 'index.html' : url.pathname.slice(1);
-    if (!['index.html', 'app.css', 'app.js'].includes(relative)) {
+    if (!['index.html', 'app.css', 'app.js', 'file-list.js', 'graph-client.js', 'layout.js'].includes(relative)) {
       response.writeHead(404);
       return response.end('Not found');
     }
@@ -75,5 +62,5 @@ export async function startImpactGraphServer({ root, changed, host = '127.0.0.1'
   });
   const address = server.address();
   const actualPort = typeof address === 'object' && address ? address.port : port;
-  return { server, url: `http://${host}:${actualPort}`, payload };
+  return { server, url: `http://${host.includes(':') ? `[${host}]` : host}:${actualPort}`, payload };
 }

package/src/graph-view/traceability.mjs

@@ -0,0 +1,30 @@
+import { resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { readMemoryConfig, memoryConfigSummary, resolveMemoryArea } from '../memory/config.mjs';
+import { readFreshIndex } from '../index/cache.mjs';
+
+export async function exportTraceability(root) {
+  const config = readMemoryConfig(root);
+  if (config.errors?.length) throw new Error(JSON.stringify(config.errors));
+  const { index } = readFreshIndex(root);
+  const nodes = new Map(index.graph.nodes.map(n => [n.id, n]));
+  const colors = ['#b9a3ff', '#70c9a2', '#72b9e6', '#d6b879', '#e393a9', '#78c9cd'];
+  const types = config.traceability.keys.map((k, i) => ({ ...k, color: colors[i % colors.length] }));
+  const typesByRelation = new Map(types.map(t => [t.relation, t]));
+  const edges = [];
+  for (const edge of index.graph.edges) {
+    const type = typesByRelation.get(edge.relation);
+    const source = nodes.get(edge.source)?.path;
+    const target = nodes.get(edge.target)?.path;
+    if (!type || !source || !target || source === target) continue;
+    if ([source, target].some(p => resolveMemoryArea(p, config)?.scope === 'local')) continue;
+    if (!(await Promise.all([source, target].map(async p => {
+      const absolute = resolve(root, p);
+      if (!absolute.startsWith(resolve(root) + '/')) return false;
+      try { return (await stat(absolute)).isFile(); } catch { return false; }
+    }))).every(Boolean)) continue;
+    edges.push({ source, target, relation: type.relation, weight: type.weight, color: type.color });
+  }
+  return { version: 1, projectRoot: resolve(root), config: memoryConfigSummary(config), types,
+    edges: [...new Map(edges.map(e => [`${e.source}\0${e.target}\0${e.relation}`, e])).values()] };
+}

package/src/init.mjs

@@ -14,11 +14,10 @@ function formatAction(item) {
 }
 
 function parseInitOptions(argv) {
-  const options = { root: null, projectName: '', dotdotSetting: false, dryRun: false, json: false, template: null, documentationRoot: 'docs', documentationRootExplicit: false };
+  const options = { root: null, projectName: '', dryRun: false, json: false, template: null, documentationRoot: 'docs', documentationRootExplicit: false };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--json') options.json = true;
-    else if (arg === '--dotdot-setting') options.dotdotSetting = true;
     else if (arg === '--dry-run') options.dryRun = true;
     else if (arg === '--claude-plans') options.claudePlans = true;
     else if (arg === '--project-name' || arg === '--template' || arg === '--documentation-root') {
@@ -100,8 +99,7 @@ function ensureGitignoreEntry(options, entry, actions) {
   actions.push(action(existed ? 'updated' : 'created', target, { add: entry }));
 }
 
-function agentContent(projectName, dotdotSetting) {
-  const dotdotAgentRule = dotdotSetting ? '\n- Follow the project documentation structure in `docs/arch/DOCS_STRUCTURE.md` and code conventions in `docs/arch/CODE_CONVENTIONS.md`.' : '';
+function agentContent(projectName, domainMap) {
   return `# AGENTS.md
 
 Canonical instructions for AI coding agents working in this repository.
@@ -119,7 +117,7 @@ Canonical instructions for AI coding agents working in this repository.
 - Preserve user edits and unrelated dirty worktree changes.
 - Prefer existing local patterns over introducing new abstractions.
 - Update docs when behavior, architecture, or test strategy changes.
-- When using the dotdotgod CLI, run \`dotdotgod validate\` after docs changes and follow its traceability guidance for behavior specs.${dotdotAgentRule}
+- When using the dotdotgod CLI, run \`dotdotgod validate\` after docs changes and follow its traceability guidance.
 
 ## dotdotgod
 
@@ -144,15 +142,12 @@ TODO
 
 ## Documentation Map
 
-- \`docs/spec/\`: product behavior, API contracts, user-facing requirements.
-- \`docs/test/\`: test strategy, regression cases, manual verification notes.
-- \`docs/arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
+${domainMap}
 - \`docs/\`: all directories use kebab-case; all markdown file names use UPPER_SNAKE_CASE, including \`README.md\`.
 - \`docs/\`: prefer keeping individual markdown files under the configured markdown validation budgets (default 200 lines and 10,000 characters); split larger docs into focused UPPER_SNAKE_CASE files and keep \`README.md\` as the index/overview unless a narrow size-check exception is configured.
 - \`docs/\`: when adding, renaming, splitting, moving, or archiving docs, update the nearest relevant \`README.md\` index/table of contents in the same change.
 - \`docs/\`: each docs subdirectory \`README.md\` acts as the local table of contents; list important files, task directories, status, and a one-line purpose for each entry.
 - \`docs/\`: start small with a single focused markdown file; when one domain grows into multiple docs, promote it to \`docs/<area>/<domain>/README.md\` plus related UPPER_SNAKE_CASE files in that directory.
-- \`docs/arch/\`: code conventions may start as \`CODE_CONVENTIONS.md\`; when they grow across multiple topics, use \`docs/arch/conventions/README.md\` as the index with supporting UPPER_SNAKE_CASE files.
 - \`docs/plan/\`: local active implementation plans. Create one kebab-case directory per task (\`docs/plan/<task-slug>/\`), keep the task overview/index in that directory's \`README.md\`, and add supporting UPPER_SNAKE_CASE plan files alongside it. Ignored by git by default.
 - \`docs/archive/\`: local completed plans, temporary reports, historical notes, payload captures. Move completed plan task directories to \`docs/archive/plan/<task-slug>/\`; put temporary reports and investigations under \`docs/archive/report/<report-slug>/\`. Ignored by git by default.
 
@@ -164,7 +159,7 @@ TODO
 Keep long-lived instructions here so agent-specific files do not drift.`;
 }
 
-function docsReadmeContent() {
+function docsReadmeContent(domainMap) {
   return `# Docs
 
 This directory keeps project knowledge close to the code.
@@ -183,115 +178,21 @@ This directory keeps project knowledge close to the code.
 
 ## Map
 
-- \`spec/\`: product behavior, API contracts, user-facing requirements.
-- \`test/\`: test strategy, regression cases, manual verification notes.
-- \`arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
+${domainMap.replaceAll('`docs/', '`')}
 - \`plan/\`: local active implementation plans. Create one kebab-case directory per task (\`plan/<task-slug>/\`), keep the task overview/index in that directory's \`README.md\`, and add supporting UPPER_SNAKE_CASE plan files alongside it. Ignored by git by default.
 - \`archive/\`: local completed plans, temporary reports, historical notes, payload captures. Move completed plan task directories to \`archive/plan/<task-slug>/\`; put temporary reports and investigations under \`archive/report/<report-slug>/\`. Ignored by git by default.`;
 }
 
-function docsStructureContent() {
-  return `# Docs Structure
-
-Long-term documentation structure for this project.
-
-## Top-Level Areas
-
-- \`docs/spec/\`: product behavior, API contracts, user-facing requirements, and feature contracts.
-- \`docs/test/\`: test strategy, coverage notes, regression cases, and manual verification records.
-- \`docs/arch/\`: architecture decisions, code conventions, module boundaries, data flow, infrastructure/runtime dependencies, integration boundaries, and migration design.
-- \`docs/plan/\`: local active implementation plans.
-- \`docs/archive/\`: local completed plans, historical notes, payload captures, and investigation notes.
-
-## Naming
-
-- Directories under \`docs/\` use kebab-case.
-- Markdown files under \`docs/\` use UPPER_SNAKE_CASE.
-- \`README.md\` is the only mixed-case markdown filename exception and is required for index/overview files.
-
-## File Size Guideline
-
-Prefer keeping individual markdown files under 200 lines and 10,000 characters. When either guideline is exceeded, split the document into focused UPPER_SNAKE_CASE files and keep \`README.md\` as the index/overview. Configured validation exceptions should stay narrow and intentional.
-
-## README Indexes
-
-Each docs subdirectory \`README.md\` acts as the local table of contents. It should list important files, task directories, status, and a one-line purpose for each entry.
-
-When adding, renaming, splitting, moving, or archiving docs, update the nearest relevant \`README.md\` in the same change.
-
-## Domain Directory Promotion
-
-Start small with one focused markdown file. When one domain grows into multiple docs, promote it to \`docs/<area>/<domain>/README.md\` and place related UPPER_SNAKE_CASE markdown files in that directory.
-
-## Spec Writing Contract
-
-Behavior specs describe the current product contract: supported commands, API shapes, user-visible behavior, defaults, constraints, and validation outcomes.
-
-Specs should not describe how behavior changed over time. Rewrite historical-change wording into direct current-state rules. Historical context, migration rationale, future extension ideas, and completed-plan notes belong in \`docs/arch/\`, \`docs/test/\`, \`docs/archive/\`, or active \`docs/plan/\` files rather than behavior specs. If compatibility behavior is still user-visible, keep it in the spec but phrase it as a current supported or unsupported rule.
-
-Config/action terms such as \`remove\`, \`exclude\`, \`fallback\`, and \`replacement semantics\` are allowed when they name current behavior precisely.
-
-## Traceability Blocks
-
-Behavior specs may include fenced \`json dotdotgod\` traceability blocks as the final section to connect specs to source, tests, related docs, and verification commands. The dotdotgod CLI owns the schema and validation behavior.
-
-## Plan and Archive Directories
-
-Active task plans use \`docs/plan/<task-slug>/README.md\`. Completed or superseded plan task directories move to \`docs/archive/plan/<task-slug>/\`. Temporary investigations, reports, payload captures, and historical notes move to \`docs/archive/report/<report-slug>/\`.
-
-\`docs/plan\` and \`docs/archive\` are ignored by git by default.`;
-}
-
-function codeConventionsContent() {
-  return `# Code Conventions
-
-Dotdot code conventions for keeping implementation simple and maintainable.
-
-## Abstraction Boundaries
-
-- Do not introduce unnecessary abstractions.
-- Do not abstract code that is not reused.
-- Do not abstract reused code when the reused behavior is likely to split into separate features or flows later.
-- Prefer local, explicit code until a stable reuse pattern appears.
-
-## Source File Size
-
-- Keep source files small enough to read in one focused pass by humans and coding agents.
-- If code grows beyond 150 lines, consider splitting or extracting focused units even when it is not reused.
-- Review files approaching 250 lines for focused extraction by responsibility.
-- Split by behavior or responsibility, not by arbitrary layers.
-
-## Dotdotgod Impact Hotspots
-
-- Treat repeated \`dotdotgod graph impact\` results that collapse onto one large file as a design signal, not as normal precision.
-- Dotdotgod impact reveals mixed-responsibility hotspots; it does not replace focused module boundaries.
-- When unrelated changes keep pointing to the same source file, split the file by behavior so impact results, tests, and docs can map to narrower responsibilities.
-
-## Extraction and Testability
-
-- Prefer extracting pure helpers when behavior can be tested without runtime dependencies.
-- Keep runtime integration explicit and local until reuse is stable.
-- Put testable logic in focused modules before adding broad framework abstractions.
-- Preserve plain-text readability: avoid dense clever code, hidden control flow, and large mixed-responsibility files.`;
-}
-
-function initFiles(options) {
-  const archReadmeExtra = options.dotdotSetting ? '\n\n## Index\n\n- `DOCS_STRUCTURE.md`: documentation layout, naming, README index, spec current-state writing contract, and domain directory promotion rules.\n- `CODE_CONVENTIONS.md`: dotdot code conventions, including abstraction boundaries, source file size guidance, impact hotspot handling, and extraction/testability rules. If conventions grow across multiple topics, promote them to `conventions/README.md` with supporting UPPER_SNAKE_CASE files.' : '';
+function initFiles(options, scaffold) {
+  const domainMap = scaffold.filter(item => item.type === 'file').map(item => `- \`${item.path.replace(/README\.md$/, '')}\`: ${item.content.split('\n\n')[1]}`).join('\n');
   const files = [
-    ['AGENTS.md', agentContent(options.projectName, options.dotdotSetting)],
+    ['AGENTS.md', agentContent(options.projectName, domainMap)],
     ['CLAUDE.md', '# CLAUDE.md\n\n@AGENTS.md'],
     ['CODEX.md', '# CODEX.md\n\nSee [AGENTS.md](./AGENTS.md).'],
-    ['docs/README.md', docsReadmeContent()],
-    ['docs/spec/README.md', '# Specs\n\nUse this area for behavior specs, API contracts, and product requirements.\n\nFor projects using the dotdotgod CLI, behavior specs may be required by `dotdotgod validate` to include fenced `json dotdotgod` traceability blocks as the final section. The CLI owns the schema and prints property-level repair guidance when validation fails.'],
-    ['docs/test/README.md', '# Tests\n\nUse this area for test strategy, coverage notes, regression cases, and manual verification records.'],
-    ['docs/arch/README.md', `# Architecture\n\nUse this area for architecture decisions, code conventions, module boundaries, data flow notes, infrastructure/runtime dependencies, integration boundaries, and migration design.${archReadmeExtra}`],
+    ['docs/README.md', docsReadmeContent(domainMap)],
     ['docs/plan/README.md', '# Plans\n\nUse this area for active implementation plans.\n\n## Naming\n\n- Task directories use kebab-case: `docs/plan/<task-slug>/`.\n- Markdown file names use UPPER_SNAKE_CASE: `README.md`, `RESEARCH_NOTES.md`, `VERIFICATION.md`.\n\n## Structure\n\n- Create one directory per task: `docs/plan/<task-slug>/`.\n- Put the task overview, index, scope, status, and main plan in `docs/plan/<task-slug>/README.md`.\n- Add supporting research, checklists, payload captures, or verification notes as additional UPPER_SNAKE_CASE markdown files in the same task directory.\n- Move completed or superseded task directories to `docs/archive/plan/<task-slug>/`.\n\nThis directory is local-only and ignored by git by default.'],
     ['docs/archive/README.md', '# Archive\n\nUse this area for local completed plans, temporary reports, historical notes, payload captures, and investigation notes.\n\n## Naming\n\n- Archived plan task directories preserve their kebab-case task slug.\n- Archived report directories use a focused kebab-case report slug.\n- Markdown file names use UPPER_SNAKE_CASE, including `README.md`.\n\n## Structure\n\n- Move completed plan task directories from `docs/plan/<task-slug>/` to `docs/archive/plan/<task-slug>/`.\n- Put temporary investigations, reports, payload captures, and historical notes under `docs/archive/report/<report-slug>/`.\n- Preserve each archive directory\'s `README.md` overview/index and supporting UPPER_SNAKE_CASE markdown files.\n- Additional archive categories can be added later as focused kebab-case subdirectories when needed.\n\nThis directory is local-only and ignored by git by default.'],
   ];
-  if (options.dotdotSetting) {
-    files.push(['docs/arch/DOCS_STRUCTURE.md', docsStructureContent()]);
-    files.push(['docs/arch/CODE_CONVENTIONS.md', codeConventionsContent()]);
-  }
   return files.map(([path, content]) => [path.replace(/^docs(?=\/|$)/, options.documentationRoot), content.replaceAll('docs/', `${options.documentationRoot}/`).replaceAll('`docs`', `\`${options.documentationRoot}\``)]);
 }
 
@@ -334,7 +235,8 @@ export function runInit(argv, usage) {
   if (template?.source === 'bundled') { const data = builtInTemplateData(template.name, { documentationRoot: options.documentationRoot }); template = { ...template, data, text: `${JSON.stringify(data, null, 2)}\n` }; }
 
   const actions = [];
-  for (const [relativePath, content] of initFiles(options)) writeInitFile(options, relativePath, content, actions);
+  const scaffold = template?.source === 'bundled' ? builtInTemplateScaffold(template.name) : [];
+  for (const [relativePath, content] of initFiles(options, scaffold)) writeInitFile(options, relativePath, content, actions);
   if (template?.source === 'bundled') {
     for (const item of builtInTemplateScaffold(template.name, { documentationRoot: options.documentationRoot }) ?? []) {
       if (item.type === 'directory') ensureInitDirectory(options, item.path, actions);
@@ -351,7 +253,7 @@ export function runInit(argv, usage) {
     catch (error) { initError(options, 'CLAUDE_SETTINGS_CHANGED', error.message); }
   }
 
-  const payload = { ok: true, command: 'init', root: options.root, projectName: options.projectName, documentationRoot: options.documentationRoot, dryRun: options.dryRun, dotdotSetting: options.dotdotSetting, template: template ? { name: template.name, source: template.source, selectedBy: template.selectedBy } : null, actions };
+  const payload = { ok: true, command: 'init', root: options.root, projectName: options.projectName, documentationRoot: options.documentationRoot, dryRun: options.dryRun, template: template ? { name: template.name, source: template.source, selectedBy: template.selectedBy } : null, actions };
   if (options.json) console.log(JSON.stringify(payload, null, 2));
   else {
     if (template) console.log(`template      ${template.source}:${template.name} (${template.selectedBy})`);

package/src/query/cache-session.mjs

@@ -0,0 +1,82 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, openSync, closeSync, readFileSync, writeFileSync, renameSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { isValidNormalizedVectorValues, readVectorCache, profileFingerprint } from './store.mjs';
+
+// One atomic state file keeps completed snapshots and unfinished batches consistent.
+export async function vectorCacheSession(root, identity, action) {
+  const directory = join(root, '.dotdotgod', 'vectors');
+  mkdirSync(directory, { recursive: true });
+  const lock = join(directory, 'build.lock');
+  const token = randomUUID();
+  const started = Date.now();
+  let waited = false;
+  while (true) {
+    try {
+      const fd = openSync(lock, 'wx');
+      try { writeFileSync(fd, JSON.stringify({ pid: process.pid, token })); } finally { closeSync(fd); }
+      break;
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      waited = true;
+      if (Date.now() - started >= 30000) throw new Error('Vector cache lock timed out; another build may be running or the lock needs inspection.');
+      try {
+        const owner = JSON.parse(readFileSync(lock, 'utf8'));
+        if (!Number.isInteger(owner.pid) || owner.pid < 1) throw new Error('Invalid lock owner.');
+        try { process.kill(owner.pid, 0); }
+        catch (probe) {
+          if (probe.code !== 'ESRCH') throw probe;
+          const recovery = `${lock}.recovery`;
+          try { mkdirSync(recovery); }
+          catch (claim) { if (claim.code === 'EEXIST') { await sleep(50); continue; } throw claim; }
+          try {
+            const current = JSON.parse(readFileSync(lock, 'utf8'));
+            if (current.token === owner.token && current.pid === owner.pid) rmSync(lock);
+          } finally { rmSync(recovery, { recursive: true, force: true }); }
+          continue;
+        }
+      } catch (probe) { if (probe.code === 'ENOENT') continue; }
+      await sleep(50);
+    }
+  }
+  try {
+    const path = join(directory, 'snapshots.json');
+    const fingerprint = profileFingerprint(identity);
+    let state; let reason = 'missing';
+    try {
+      state = JSON.parse(readFileSync(path, 'utf8'));
+      if (state.schema !== 1) { reason = 'schema-mismatch'; state = null; }
+      else if (state.profile !== fingerprint) { reason = 'profile-mismatch'; state = null; }
+      else {
+        if (state.dimensions !== null && (!Number.isInteger(state.dimensions) || state.dimensions < 1)) throw new Error('Invalid cache dimensions.');
+        for (const rows of [state.docs, state.code, state.pending]) {
+          if (!Array.isArray(rows) || rows.some((row) => typeof row.chunk?.fingerprint !== 'string' || !Array.isArray(row.vector) || row.vector.length !== state.dimensions || !isValidNormalizedVectorValues(row.vector, state.dimensions))) throw new Error('Invalid cache rows.');
+        }
+        reason = 'valid';
+      }
+    } catch (error) { state = null; reason = error.code === 'ENOENT' ? 'missing' : 'corrupt'; }
+    if (!state) {
+      state = { schema: 1, profile: fingerprint, dimensions: null, docs: [], code: [], pending: [] };
+      if (reason === 'missing') {
+        const legacyDiagnostics = {};
+        const legacy = readVectorCache(root, identity, legacyDiagnostics);
+        reason = legacyDiagnostics.reason;
+        if (legacy) {
+          state.dimensions = legacy.manifest.dimensions;
+          legacy.chunks.forEach((chunk, i) => state[chunk.kind === 'symbol' ? 'code' : 'docs'].push({ chunk, vector: Array.from(legacy.vectors.subarray(i * state.dimensions, (i + 1) * state.dimensions)) }));
+          reason = 'legacy-migrated';
+        }
+      }
+    }
+    const save = () => {
+      const temporary = `${path}.tmp-${token}`;
+      try { writeFileSync(temporary, JSON.stringify(state)); renameSync(temporary, path); }
+      finally { rmSync(temporary, { force: true }); }
+    };
+    return await action(state, save, { reason, lockWaitMs: waited ? Date.now() - started : 0 });
+  } finally {
+    try { if (JSON.parse(readFileSync(lock, 'utf8')).token === token) rmSync(lock); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}

package/src/query/store.mjs

@@ -29,20 +29,25 @@ export function vectorCachePaths(root) {
   return { directory, manifest: join(directory, 'manifest.json'), chunks: join(directory, 'chunks.jsonl'), embeddings: join(directory, 'embeddings.f32') };
 }
 
-export function readVectorCache(root, identity = null) {
+export function readVectorCache(root, identity = null, diagnostics = {}) {
+  diagnostics.reason = 'missing';
   const paths = vectorCachePaths(root);
   if (!existsSync(paths.manifest) || !existsSync(paths.chunks) || !existsSync(paths.embeddings)) return null;
   try {
     const manifest = JSON.parse(readFileSync(paths.manifest, 'utf8'));
+    diagnostics.reason = 'schema-mismatch';
     if (manifest.schemaVersion !== VECTOR_SCHEMA_VERSION || !Number.isInteger(manifest.dimensions) || manifest.dimensions < 1) return null;
+    diagnostics.reason = 'profile-mismatch';
     if (identity && manifest.profileFingerprint !== profileFingerprint(identity)) return null;
+    diagnostics.reason = 'corrupt';
     const chunks = readFileSync(paths.chunks, 'utf8').split('\n').filter(Boolean).map((line) => JSON.parse(line));
     const buffer = readFileSync(paths.embeddings);
     if (buffer.byteLength !== chunks.length * manifest.dimensions * 4) return null;
     const vectors = new Float32Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 4);
     if (!isValidNormalizedVectorValues(vectors, manifest.dimensions)) return null;
+    diagnostics.reason = 'valid';
     return { manifest, chunks, vectors: new Float32Array(vectors) };
-  } catch { return null; }
+  } catch { diagnostics.reason = 'corrupt'; return null; }
 }
 
 function atomicWrite(path, data) {

package/src/graph-view/payload.mjs

@@ -1,114 +0,0 @@
-import { resolveMemoryArea } from '../memory/config.mjs';
-
-function edgeKey(edge) {
-  return `${edge.source}\0${edge.target}\0${edge.relation}`;
-}
-
-function labelForNode(node) {
-  if (node.type === 'contract') return node.title ?? node.contractId ?? node.id;
-  return node.path ?? node.command ?? node.name ?? node.target ?? node.id;
-}
-
-function adjacencyFor(nodes, edges) {
-  const adjacency = new Map(nodes.map((node) => [node.id, new Set()]));
-  for (const edge of edges) {
-    adjacency.get(edge.source)?.add(edge.target);
-    adjacency.get(edge.target)?.add(edge.source);
-  }
-  return adjacency;
-}
-
-function rootReachability(nodes, edges, seedIds) {
-  const adjacency = adjacencyFor(nodes, edges);
-  const reachable = new Set();
-  const depthByNode = new Map();
-  const nearestRootByNode = new Map();
-  const queue = [];
-  for (const node of nodes) {
-    if (!seedIds.has(node.id)) continue;
-    reachable.add(node.id);
-    depthByNode.set(node.id, 0);
-    nearestRootByNode.set(node.id, node.id);
-    queue.push(node.id);
-  }
-  for (let cursor = 0; cursor < queue.length; cursor += 1) {
-    const current = queue[cursor];
-    for (const neighbor of adjacency.get(current) ?? []) {
-      if (reachable.has(neighbor)) continue;
-      reachable.add(neighbor);
-      depthByNode.set(neighbor, (depthByNode.get(current) ?? 0) + 1);
-      nearestRootByNode.set(neighbor, nearestRootByNode.get(current));
-      queue.push(neighbor);
-    }
-  }
-  return { reachable, depthByNode, nearestRootByNode };
-}
-
-export function buildImpactGraphPayload(index, impact) {
-  const graph = impact.structuralGraph ?? index?.graph ?? { nodes: [], edges: [] };
-  const config = index?.memoryConfig;
-  const seedIds = new Set((impact.changedFiles ?? [impact.changed]).map((path) => `file:${path}`));
-  const impactItems = new Map((impact.related ?? []).map((item) => [item.id, item]));
-  const isAllowedNode = (node) => {
-    if (!node) return false;
-    if (node.path && resolveMemoryArea(node.path, config)?.scope === 'local') return false;
-    return true;
-  };
-  const sourceNodes = (graph.nodes ?? []).filter(isAllowedNode);
-  const indexedNodes = new Map(sourceNodes.map((node) => [node.id, node]));
-
-  const seenEdges = new Set();
-  const edges = [];
-  for (const edge of graph.edges ?? []) {
-    if (!indexedNodes.has(edge.source) || !indexedNodes.has(edge.target)) continue;
-    const key = edgeKey(edge);
-    if (seenEdges.has(key)) continue;
-    seenEdges.add(key);
-    edges.push({ source: edge.source, target: edge.target, relation: edge.relation, confidence: edge.confidence, weight: edge.weight ?? edge.relationWeight, score: edge.score, traceabilityKey: edge.traceabilityKey });
-  }
-  const { reachable, depthByNode, nearestRootByNode } = rootReachability(sourceNodes, edges, seedIds);
-  const retainedNodes = sourceNodes.filter((node) => reachable.has(node.id));
-  const retainedEdges = edges.filter((edge) => reachable.has(edge.source) && reachable.has(edge.target));
-  const nodes = retainedNodes.map((source) => {
-    const item = impactItems.get(source.id);
-    const seed = seedIds.has(source.id);
-    return {
-      id: source.id,
-      type: source.type ?? item?.type ?? 'file',
-      path: source.path ?? item?.path,
-      label: labelForNode({ ...source, ...item }),
-      seed,
-      ranked: Boolean(item),
-      depth: depthByNode.get(source.id) ?? 0,
-      nearestRoot: nearestRootByNode.get(source.id),
-      component: 0,
-      seededComponent: true,
-      impactScore: seed ? 100 : item?.impactScore ?? 0,
-      reasons: seed ? ['changed-file'] : item?.reasons ?? [],
-      scoreBreakdown: seed ? { seed: 100 } : item?.scoreBreakdown,
-      retrieval: item?.retrieval ?? source.retrieval,
-      contractId: item?.contractId ?? source.contractId,
-      title: item?.title ?? source.title,
-      sections: item?.sections ?? source.sections,
-      vectorEvidence: item?.vectorEvidence,
-    };
-  });
-
-  return {
-    changed: impact.changed,
-    changedFiles: impact.changedFiles ?? [impact.changed],
-    ranking: impact.ranking,
-    semantic: impact.semantic,
-    complete: true,
-    nodes,
-    edges: retainedEdges,
-    components: retainedNodes.length > 0 ? [{ id: 0, size: retainedNodes.length, seeded: true }] : [],
-    diagnostics: {
-      rootNodes: retainedNodes.filter((node) => seedIds.has(node.id)).length,
-      connectedNodes: retainedNodes.length,
-      disconnectedNodesOmitted: sourceNodes.length - retainedNodes.length,
-      maximumDepth: Math.max(0, ...depthByNode.values()),
-    },
-    omittedRelated: impact.omittedRelated ?? 0,
-  };
-}