@guanlin4924/devflow-pi 0.1.77 → 0.1.79

package/plugins/devflow-intel/skills/workflow-code-index/scripts/adapters/tree_sitter_wasm.py

@@ -0,0 +1,253 @@
+"""Optional Tree-sitter WASM adapter.
+
+The indexer remains usable without a grammar bundle.  In that case this
+adapter deliberately returns the configured fallback and a diagnostic; it
+never labels lexical facts as Tree-sitter facts.  A grammar is supplied by the
+runtime (or DEVFLOW_TREE_SITTER_WASM_GRAMMAR_<LANG>) so the npm package does
+not silently depend on a machine-specific native installation.
+"""
+
+import json
+import hashlib
+import os
+import shutil
+import subprocess
+from pathlib import Path
+from typing import Dict, Tuple
+
+from adapters.base import Adapter, ParseResult
+from adapters.capabilities import load_capability_manifest
+from adapters.generic_text import _relation, _symbol
+
+
+HELPER = Path(__file__).resolve().parent / "helpers" / "tree_sitter_wasm_helper.mjs"
+
+
+class TreeSitterWasmAdapter(Adapter):
+    name = "tree-sitter-wasm"
+
+    def __init__(self, language: str, fallback: Adapter):
+        self.language = language
+        self.fallback = fallback
+        self.declaration = load_capability_manifest()["languages"].get(language, {})
+        self._availability: Tuple[bool, str] | None = None
+
+    def version(self) -> str:
+        return str(self.declaration.get("adapter_version", 1))
+
+    @property
+    def parser_id(self) -> str:
+        grammar = self.declaration.get("grammar", {}).get("id", self.language)
+        return f"tree-sitter-wasm:{grammar}@{self.version()}"
+
+    def parser_for_file(self, codebase, file_record) -> str:
+        available, _ = self._availability_for(codebase)
+        return self.parser_id if available else self.fallback.parser_for_file(codebase, file_record)
+
+    def check_available(self, codebase=None) -> Tuple[bool, str]:
+        grammar = self._grammar_path(codebase)
+        if not grammar:
+            return False, "Tree-sitter WASM grammar is not configured"
+        pin = self._grammar_pin()
+        if not pin["version"] or not pin["sha256"]:
+            return False, "Tree-sitter WASM grammar is unpinned; configure version and sha256"
+        actual_hash = self._sha256(grammar)
+        expected_hash = pin["sha256"].removeprefix("sha256:").lower()
+        if actual_hash != expected_hash:
+            return False, f"Tree-sitter WASM grammar hash mismatch: expected {expected_hash}, got {actual_hash}"
+        runtime = self._runtime()
+        if runtime is None:
+            return False, "Node/Bun runtime is not available"
+        if not self._module_available(runtime):
+            return False, "web-tree-sitter module is not importable"
+        if not HELPER.is_file():
+            return False, "Tree-sitter WASM helper is missing"
+        return True, f"Tree-sitter WASM grammar available: {grammar} ({pin['version']}, sha256:{actual_hash})"
+
+    def capability(self) -> Dict:
+        available, reason = self._availability_for(None)
+        grammar = dict(self.declaration.get("grammar", {}))
+        return {
+            "parser": self.parser_id,
+            "strategy": "tree-sitter-wasm",
+            "native": False,
+            "available": available,
+            "status": "implemented" if available else "parser_unavailable",
+            "support_level": "supported" if available else ("unpinned" if self._grammar_path(None) else "parser_unavailable"),
+            "pin": self._grammar_pin(),
+            "reason": reason,
+            "grammar": grammar,
+            "fallback": self.fallback.parser_id,
+            "scope": "Tree-sitter WASM syntax tree; framework semantics remain a separate linker stage",
+        }
+
+    def parse_file(self, codebase, file_record, text) -> ParseResult:
+        if file_record.get("language") != self.language:
+            return self.fallback.parse_file(codebase, file_record, text)
+        available, reason = self._availability_for(codebase)
+        if not available:
+            result = self.fallback.parse_file(codebase, file_record, text)
+            result.diagnostics.append({
+                "codebase": codebase.name,
+                "path": file_record["path"],
+                "line": 1,
+                "severity": "warning",
+                "kind": "parser_unavailable",
+                "message": f"Tree-sitter WASM unavailable for {self.language}; fallback used: {reason}",
+                "parser": self.parser_id,
+                "metadata": {"support_level": "parser_unavailable", "fallback_parser": self.fallback.parser_id},
+            })
+            return result
+        try:
+            payload = self._parse(codebase, file_record, text)
+        except Exception as error:
+            result = self.fallback.parse_file(codebase, file_record, text)
+            result.diagnostics.append({
+                "codebase": codebase.name, "path": file_record["path"], "line": 1,
+                "severity": "error", "kind": "parse_failed",
+                "message": f"Tree-sitter WASM parse failed; fallback used: {error}",
+                "parser": self.parser_id,
+            })
+            return result
+        return self._convert(codebase, file_record, text, payload)
+
+    def _availability_for(self, codebase=None):
+        # A grammar/runtime is global for a scan.  Codebase-specific grammar
+        # overrides are intentionally checked only when parsing that codebase.
+        if codebase is not None:
+            return self.check_available(codebase)
+        if self._availability is None:
+            self._availability = self.check_available(None)
+        return self._availability
+
+    def _grammar_path(self, codebase=None):
+        key = f"DEVFLOW_TREE_SITTER_WASM_GRAMMAR_{self.language.upper().replace('-', '_')}"
+        configured = os.environ.get(key) or self.declaration.get("grammar", {}).get("path")
+        if configured:
+            path = Path(configured)
+            if not path.is_absolute() and codebase is not None:
+                path = Path(codebase.root) / path
+            return str(path.resolve()) if path.is_file() else None
+        package = self.declaration.get("grammar", {}).get("package")
+        package_path = self._resolve_package_grammar(package) if package else None
+        return package_path
+
+    @staticmethod
+    def _resolve_package_grammar(package):
+        """Resolve a declared npm grammar without downloading at runtime.
+
+        The package is an installation-time dependency.  Searching the
+        workspace and adapter ancestors keeps this working from both a
+        checkout and an installed plugin while ensuring no network fallback
+        can occur during indexing.
+        """
+        if not package:
+            return None
+        roots = [Path.cwd(), Path(__file__).resolve()]
+        seen = set()
+        for root in roots:
+            for candidate in [root, *root.parents]:
+                package_root = candidate / "node_modules" / package
+                candidates = [package_root / "grammar.wasm"]
+                if package_root.is_dir():
+                    candidates.extend(sorted(package_root.glob("*.wasm")))
+                for node_modules in candidates:
+                    key = str(node_modules)
+                    if key in seen:
+                        continue
+                    seen.add(key)
+                    if node_modules.is_file():
+                        return str(node_modules.resolve())
+        return None
+
+    def _grammar_pin(self):
+        grammar = self.declaration.get("grammar", {})
+        prefix = f"DEVFLOW_TREE_SITTER_GRAMMAR_{self.language.upper().replace('-', '_')}"
+        return {
+            "version": os.environ.get(f"{prefix}_VERSION") or grammar.get("version"),
+            "sha256": os.environ.get(f"{prefix}_SHA256") or grammar.get("sha256"),
+        }
+
+    @staticmethod
+    def _sha256(path):
+        digest = hashlib.sha256()
+        with Path(path).open("rb") as handle:
+            for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+                digest.update(chunk)
+        return digest.hexdigest()
+
+    @staticmethod
+    def _module_available(runtime):
+        # Probe the module before claiming availability.  The helper import is
+        # deliberately not the first place this is discovered: otherwise the
+        # snapshot would advertise a parser which only fails per file.
+        try:
+            probe = subprocess.run(
+                [runtime, "--input-type=module", "-e",
+                 "import('web-tree-sitter').then(()=>process.exit(0)).catch(()=>process.exit(1))"],
+                stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL,
+                timeout=5, check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+        return probe.returncode == 0
+
+    @staticmethod
+    def _runtime():
+        configured = os.environ.get("DEVFLOW_TREE_SITTER_WASM_RUNTIME")
+        if configured:
+            return configured if shutil.which(configured) else None
+        return shutil.which("bun") or shutil.which("node")
+
+    def _parse(self, codebase, record, text):
+        runtime = self._runtime()
+        grammar = self._grammar_path(codebase)
+        max_bytes = int(os.environ.get("DEVFLOW_TREE_SITTER_WASM_MAX_BYTES", str(2 * 1024 * 1024)))
+        source_bytes = len(text.encode("utf-8"))
+        if source_bytes > max_bytes:
+            raise RuntimeError(f"source exceeds Tree-sitter WASM limit ({source_bytes} > {max_bytes} bytes)")
+        timeout = float(os.environ.get("DEVFLOW_TREE_SITTER_WASM_TIMEOUT", "10"))
+        proc = subprocess.run(
+            [runtime, str(HELPER), grammar],
+            input=json.dumps({"path": record["path"], "source": text}, ensure_ascii=False) + "\n",
+            text=True, encoding="utf-8", stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            timeout=timeout, check=False,
+        )
+        if proc.returncode != 0:
+            raise RuntimeError(proc.stderr.strip()[:500] or f"helper exited {proc.returncode}")
+        payload = json.loads(proc.stdout.splitlines()[-1])
+        if not payload.get("ok"):
+            raise RuntimeError(payload.get("error") or "Tree-sitter helper returned no result")
+        return payload
+
+    def _convert(self, codebase, record, text, payload):
+        path, content_hash = record["path"], record["content_hash"]
+        file_symbol = _symbol(codebase.name, record["language"], "file", Path(path).name, path, 1,
+                              max(1, len(text.splitlines())), content_hash, qualified_name=path,
+                              parser=self.parser_id)
+        symbols = [file_symbol]
+        by_key = {"": file_symbol}
+        for item in payload.get("declarations", []):
+            parent = by_key.get(str(item.get("parent") or ""), file_symbol)
+            symbol = _symbol(codebase.name, record["language"], item.get("kind", "symbol"),
+                             item.get("name", "anonymous"), path, max(1, int(item.get("line_start", 1))),
+                             max(1, int(item.get("line_end", item.get("line_start", 1)))), content_hash,
+                             qualified_name=item.get("qualified_name") or f"{parent['qualified_name']}::{item.get('name', 'anonymous')}",
+                             parser=self.parser_id)
+            symbol["container_id"] = parent["id"]
+            symbol["metadata"].update({"parse_status": payload.get("parse_status", "complete"), "grammar": self.declaration.get("grammar", {})})
+            symbols.append(symbol)
+            by_key[str(item.get("key"))] = symbol
+        relations = []
+        for symbol in symbols[1:]:
+            relations.append(_relation(symbol["container_id"], "contains", path, symbol["line_start"], self.parser_id, "exact", to_id=symbol["id"]))
+        for item in payload.get("calls", []):
+            owner = by_key.get(str(item.get("owner") or ""), file_symbol)
+            relations.append(_relation(owner["id"], "calls", path, max(1, int(item.get("line", 1))), self.parser_id,
+                                        "heuristic", to_external=f"call:{item.get('target', 'unknown')}"))
+        diagnostics = list(payload.get("diagnostics", []))
+        if payload.get("parse_status") != "complete":
+            diagnostics.append({"codebase": codebase.name, "path": path, "line": 1, "severity": "warning",
+                                "kind": "parse_partial", "message": "Tree-sitter grammar produced a partial tree",
+                                "parser": self.parser_id, "metadata": payload.get("metadata", {})})
+        return ParseResult(symbols=symbols, relations=relations, diagnostics=diagnostics, actual_parser=self.parser_id)

package/plugins/devflow-intel/skills/workflow-code-index/scripts/code_index.py

@@ -22,6 +22,7 @@ if str(SCRIPT_DIR) not in sys.path:
     sys.path.insert(0, str(SCRIPT_DIR))
 
 from adapters.generic_text import language_for_path
+from adapters.capabilities import confidence_for_parser
 from adapters.registry import AdapterRegistry
 from semantic import SEMANTIC_EXTRACTOR_VERSION, build_semantic_facts
 from core.discovery import discover_codebases
@@ -64,7 +65,17 @@ def _publish_snapshot(staging: Path, output: Path, counts: Dict[str, int], works
     generation = generation or str(uuid.uuid4())
     immutable_relative = f"snapshots/{generation}"
     snapshot = {
+        # Keep the public snapshot schema stable while exposing the richer
+        # SQLite schema separately.  Older consumers only know schemaVersion=1.
         "schemaVersion": 1,
+        "indexSchemaVersion": 3,
+        "capabilities": {
+            "structural": True,
+            "semantic": True,
+            "fts": True,
+            "relations": True,
+            "provenance": True,
+        },
         "generation": generation,
         "generatedAt": datetime.now(timezone.utc).isoformat(),
         "counts": counts,
@@ -188,11 +199,13 @@ def main(argv=None) -> int:
 
     validate = sub.add_parser("validate", help="Validate JSONL schema.")
     validate.add_argument("--index", default=".planning/code-index", help="Index directory.")
+    validate.add_argument("--snapshot", help="Immutable generation id.")
 
     audit = sub.add_parser("audit", help="Audit stale files and relation integrity.")
     audit.add_argument("--root", default=".", help="Project root.")
     audit.add_argument("--index", default=".planning/code-index", help="Index directory.")
     audit.add_argument("--skill-root", default=".skills", help="Optional skill root for project-binding checks.")
+    audit.add_argument("--snapshot", help="Immutable generation id.")
 
     query = sub.add_parser("query", help="Search symbols using SQLite FTS or LIKE fallback.")
     query.add_argument("--index", default=".planning/code-index", help="Index directory.")
@@ -286,15 +299,27 @@ def command_scan(args) -> int:
                         "parser": "pending",
                     }
                     adapter = registry.adapter_for_file(codebase, file_record)
-                    file_record["parser"] = adapter.parser_for_file(codebase, file_record)
+                    parser_for_file = getattr(adapter, "parser_for_file", None)
+                    file_record["parser"] = parser_for_file(codebase, file_record) if parser_for_file else adapter.parser_id
                     result = adapter.parse_file(codebase, file_record, text)
                     file_record["parser"] = result.actual_parser or file_record["parser"]
                     files.append(file_record)
                     symbols.extend(result.symbols)
                     relations.extend(result.relations)
                     diagnostics.extend(result.diagnostics)
-                    adapter_entities.extend(getattr(result, "entities", []) or [])
-                    adapter_flows.extend(getattr(result, "flows", []) or [])
+                    for entity in getattr(result, "entities", []) or []:
+                        entity = dict(entity)
+                        entity.setdefault("extractor", file_record["parser"])
+                        entity.setdefault("confidence", confidence_for_parser(file_record["parser"], "symbol"))
+                        entity.setdefault("metadata", {})
+                        adapter_entities.append(entity)
+                    for flow in getattr(result, "flows", []) or []:
+                        flow = dict(flow)
+                        flow.setdefault("extractor", file_record["parser"])
+                        flow.setdefault("confidence", "heuristic")
+                        flow.setdefault("evidence_level", "syntax")
+                        flow.setdefault("metadata", {})
+                        adapter_flows.append(flow)
                     parsed += 1
                     if parsed == 1 or parsed % 250 == 0 or parsed == len(all_files):
                         progress.emit("parse", f"parsed {parsed}/{len(all_files)} files in {codebase.name}", codebase=codebase.name, parsed=parsed, total=len(all_files))
@@ -316,12 +341,25 @@ def command_scan(args) -> int:
         staging = Path(tempfile.mkdtemp(prefix=f".{output.name}.build-", dir=str(output.parent)))
         try:
             generation = str(uuid.uuid4())
-            workspace_state = _workspace_state(root, files, changed, discovered_paths, registry.capabilities())
+            registry_capabilities = getattr(registry, "capabilities", None)
+            workspace_state = _workspace_state(
+                root, files, changed, discovered_paths,
+                registry_capabilities() if registry_capabilities else {},
+            )
             workspace_state["generatedAt"] = datetime.now(timezone.utc).isoformat()
+            workspace_state["scanScope"] = {
+                "exclude": sorted(set(args.exclude)),
+                "codebases": [
+                    {"name": item.name, "path": str(item.root)} for item in codebases
+                ],
+            }
             workspace_state["semanticExtractor"] = SEMANTIC_EXTRACTOR_VERSION
             workspace_state["extractorSetHash"] = _hash_lines([*workspace_state.get("extractors", []), SEMANTIC_EXTRACTOR_VERSION])
             progress.emit("semantic", "building semantic facts")
-            semantic_entities, semantic_flows, feature_bindings = build_semantic_facts(root, files, symbols, relations)
+            semantic_stats = {}
+            semantic_entities, semantic_flows, feature_bindings = build_semantic_facts(root, files, symbols, relations, stats=semantic_stats)
+            workspace_state["semanticScan"] = semantic_stats
+            progress.emit("semantic", "semantic facts completed", **semantic_stats)
             semantic_entities.extend(adapter_entities)
             semantic_flows.extend(adapter_flows)
             write_jsonl(staging / INDEX_FILES["files"], files)
@@ -369,19 +407,27 @@ def command_scan(args) -> int:
 
 def command_validate(args) -> int:
     output = Path(args.index).resolve()
-    selected = _selected_generation(output, None)
+    selected = _selected_generation(output, getattr(args, "snapshot", None))
     errors = []
     try:
         snapshot = _load_snapshot(selected)
+        errors.extend(_validate_snapshot_bundle(selected, snapshot))
         files, symbols, relations, diagnostics = _load_tuple(selected)
         errors.extend(validate_index(files, symbols, relations, diagnostics))
         conn = sqlite3.connect(str(selected / "index.sqlite"))
         try:
             snapshot_id = snapshot.get("generation")
-            row = conn.execute("SELECT snapshot_id FROM analysis_snapshots WHERE snapshot_id=?", (snapshot_id,)).fetchone()
-            if not row:
-                errors.append(f"semantic schema missing snapshot {snapshot_id}")
-            dangling = conn.execute("""
+            tables = _table_names(conn)
+            if "analysis_snapshots" in tables:
+                row = conn.execute("SELECT snapshot_id FROM analysis_snapshots WHERE snapshot_id=?", (snapshot_id,)).fetchone()
+                if not row:
+                    errors.append(f"snapshot metadata missing generation {snapshot_id}")
+            semantic_tables = {"semantic_flows", "entity_versions", "feature_bindings", "coverage_metrics"}
+            if not semantic_tables.issubset(tables):
+                # Structural-only historical snapshots remain valid.
+                snapshot.setdefault("capabilities", {})["semantic"] = False
+            else:
+                dangling = conn.execute("""
               SELECT COUNT(*) FROM semantic_flows f
               WHERE f.snapshot_id=? AND (
                 (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.source_id)
@@ -390,18 +436,18 @@ def command_validate(args) -> int:
                 (NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=f.snapshot_id AND e.logical_id=f.target_id)
                  AND NOT EXISTS (SELECT 1 FROM symbols s WHERE s.id=f.target_id))
               )
-            """, (snapshot_id,)).fetchone()[0]
-            if dangling:
-                errors.append(f"semantic flows have {dangling} dangling source or target nodes")
-            binding_dangling = conn.execute("""
+                """, (snapshot_id,)).fetchone()[0]
+                if dangling:
+                    errors.append(f"semantic flows have {dangling} dangling source or target nodes")
+                binding_dangling = conn.execute("""
               SELECT COUNT(*) FROM feature_bindings b
               WHERE b.snapshot_id=? AND (
                 NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.feature_id)
                 OR NOT EXISTS (SELECT 1 FROM entity_versions e WHERE e.snapshot_id=b.snapshot_id AND e.logical_id=b.entity_id)
               )
-            """, (snapshot_id,)).fetchone()[0]
-            if binding_dangling:
-                errors.append(f"feature bindings have {binding_dangling} dangling feature or entity nodes")
+                """, (snapshot_id,)).fetchone()[0]
+                if binding_dangling:
+                    errors.append(f"feature bindings have {binding_dangling} dangling feature or entity nodes")
         finally:
             conn.close()
     except (OSError, sqlite3.Error, ValueError) as exc:
@@ -418,6 +464,11 @@ def command_query(args) -> int:
             print(f"Missing index: {index}", file=sys.stderr)
             return 1
         snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr)
+            return 1
+        limit = _bounded_limit(getattr(args, "limit", 20), 1000)
         files = read_jsonl(selected / INDEX_FILES["files"])
         if not getattr(args, "snapshot", None) and not _query_is_fresh(output.parent.parent, snapshot, files):
             print("Stale code index: refresh required before query.", file=sys.stderr)
@@ -425,30 +476,38 @@ def command_query(args) -> int:
         conn = sqlite3.connect(str(index))
         conn.row_factory = sqlite3.Row
         try:
+            symbol_columns = {row[1] for row in conn.execute("PRAGMA table_info(symbols)")}
+            provenance = ", parser, content_hash, metadata_json" if {"parser", "content_hash", "metadata_json"}.issubset(symbol_columns) else ", NULL AS parser, NULL AS content_hash, NULL AS metadata_json"
             try:
                 rows = conn.execute(
-                    """
-                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end
+                    f"""
+                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end,
+                           {provenance[2:]}
                     FROM symbols_fts
                     JOIN symbols USING(id)
                     WHERE symbols_fts MATCH ?
                     LIMIT ?
                     """,
-                    (args.term, args.limit),
+                    (args.term, limit),
                 ).fetchall()
             except sqlite3.OperationalError:
                 like = f"%{args.term}%"
                 rows = conn.execute(
-                    """
-                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end
+                    f"""
+                    SELECT id, codebase, kind, name, qualified_name, path, line_start, line_end,
+                           {provenance[2:]}
                     FROM symbols
                     WHERE name LIKE ? OR qualified_name LIKE ? OR path LIKE ?
                     LIMIT ?
                     """,
-                    (like, like, like, args.limit),
+                    (like, like, like, limit),
                 ).fetchall()
             for row in rows:
-                print(json.dumps(dict(row), ensure_ascii=False, sort_keys=True))
+                item = dict(row)
+                item["snapshot"] = snapshot.get("generation")
+                item["parser"] = item.get("parser") or "unknown"
+                item["confidence"] = item.get("confidence") or confidence_for_parser(item["parser"], "symbol")
+                print(json.dumps(item, ensure_ascii=False, sort_keys=True))
         finally:
             conn.close()
     return 0
@@ -456,14 +515,22 @@ def command_query(args) -> int:
 
 def command_relations(args) -> int:
     output = Path(args.index).resolve()
-    depth = max(0, min(args.depth, 20)); limit = max(1, min(args.limit, 1000))
+    depth = max(0, min(args.depth, 20)); limit = _bounded_limit(args.limit, 1000)
     with _index_lock(output, exclusive=False):
         selected = _selected_generation(output, getattr(args, "snapshot", None))
         snapshot = _load_snapshot(selected); files = read_jsonl(selected / INDEX_FILES["files"])
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr); return 1
         if not getattr(args, "snapshot", None) and not _query_is_fresh(output.parent.parent, snapshot, files):
             print("Stale code index: refresh required before query.", file=sys.stderr); return 1
         conn = sqlite3.connect(str(selected / "index.sqlite")); conn.row_factory = sqlite3.Row
         try:
+            symbol_columns = {row[1] for row in conn.execute("PRAGMA table_info(symbols)")}
+            parser_expr = "s.parser" if "parser" in symbol_columns else "NULL"
+            hash_expr = "s.content_hash" if "content_hash" in symbol_columns else "NULL"
+            to_parser_expr = "t.parser" if "parser" in symbol_columns else "NULL"
+            to_hash_expr = "t.content_hash" if "content_hash" in symbol_columns else "NULL"
             if depth == 0:
                 print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "depthLimit": 0, "resultLimit": limit, "truncated": False}}, ensure_ascii=False, sort_keys=True))
                 return 0
@@ -476,14 +543,21 @@ def command_relations(args) -> int:
                 SELECT r.from_id,r.relation_type,r.to_id,r.to_external,r.evidence_path,r.evidence_line,r.confidence,g.depth+1,g.visited || COALESCE(r.to_id,'') || ','
                 FROM graph g JOIN relations r ON r.from_id=g.to_id
                 WHERE g.depth < ? AND r.to_id IS NOT NULL {confidence} AND instr(g.visited, ',' || r.to_id || ',')=0
-              ) SELECT * FROM graph ORDER BY depth,from_id,relation_type,to_id LIMIT ?
+              ) SELECT graph.*, s.path AS from_path, s.name AS from_name, {parser_expr} AS from_parser,
+                       {hash_expr} AS from_content_hash, t.path AS to_path, t.name AS to_name,
+                       {to_parser_expr} AS to_parser, {to_hash_expr} AS to_content_hash
+                  FROM graph
+                  LEFT JOIN symbols s ON s.id=graph.from_id
+                  LEFT JOIN symbols t ON t.id=graph.to_id
+                  ORDER BY depth,from_id,relation_type,to_id LIMIT ?
             """, (args.object, depth, limit + 1)).fetchall()
             truncated = len(rows) > limit
             for row in rows[:limit]:
                 item = dict(row)
-                if args.change_type:
+                item["snapshot"] = snapshot.get("generation")
+                if getattr(args, "change_type", None):
                     item["impact_kind"] = args.change_type
-                    item["severity"] = _impact_severity(args.change_type, item["flow_type"])
+                    item["severity"] = _impact_severity(args.change_type, item.get("flow_type", "relation"))
                 print(json.dumps(item, ensure_ascii=False, sort_keys=True))
             print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "depthLimit": depth, "resultLimit": limit, "truncated": truncated}}, ensure_ascii=False, sort_keys=True))
         finally: conn.close()
@@ -503,10 +577,13 @@ def _impact_severity(change_type: str, flow_type: str) -> str:
 
 def command_impact(args) -> int:
     output = Path(args.index).resolve()
-    depth = max(0, min(args.depth, 20)); limit = max(1, min(args.limit, 2000))
+    depth = max(0, min(args.depth, 20)); limit = _bounded_limit(args.limit, 2000)
     with _index_lock(output, exclusive=False):
         selected = _selected_generation(output, getattr(args, "snapshot", None))
         snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            print(bundle_errors[0], file=sys.stderr); return 1
         if not getattr(args, "snapshot", None):
             files = read_jsonl(selected / INDEX_FILES["files"])
             if not _query_is_fresh(output.parent.parent, snapshot, files):
@@ -514,6 +591,11 @@ def command_impact(args) -> int:
                 return 1
         conn = sqlite3.connect(str(selected / "index.sqlite")); conn.row_factory = sqlite3.Row
         try:
+            tables = _table_names(conn)
+            semantic_tables = {"semantic_flows", "entity_versions", "feature_bindings", "coverage_metrics"}
+            if not semantic_tables.issubset(tables):
+                print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "status": "unavailable", "reason": "semantic_capability_unavailable", "coverage": {"status": "unknown"}, "truncated": False}}, ensure_ascii=False, sort_keys=True))
+                return 0
             rows = conn.execute("""
               WITH RECURSIVE graph(node_id, flow_type, source_path, line_start, confidence, depth, visited) AS (
                 SELECT CASE WHEN source_id=? THEN target_id ELSE source_id END, flow_type, source_path, line_start, confidence, 1, ',' || ? || ','
@@ -525,7 +607,12 @@ def command_impact(args) -> int:
                 WHERE g.depth < ? AND instr(g.visited, ',' || CASE WHEN f.source_id=g.node_id THEN f.target_id ELSE f.source_id END || ',')=0
               ) SELECT * FROM graph LIMIT ?
             """, (args.entity, args.entity, snapshot.get("generation"), args.entity, args.entity, snapshot.get("generation"), depth, limit + 1)).fetchall()
-            for row in rows[:limit]: print(json.dumps(dict(row), ensure_ascii=False, sort_keys=True))
+            for row in rows[:limit]:
+                item = dict(row); item["snapshot"] = snapshot.get("generation")
+                if getattr(args, "change_type", None):
+                    item["impact_kind"] = args.change_type
+                    item["severity"] = _impact_severity(args.change_type, item.get("flow_type", "relation"))
+                print(json.dumps(item, ensure_ascii=False, sort_keys=True))
             coverage_row = conn.execute("SELECT * FROM coverage_metrics WHERE snapshot_id=?", (snapshot.get("generation"),)).fetchone()
             coverage = dict(coverage_row) if coverage_row else {"status": "unknown"}
             print(json.dumps({"_meta": {"snapshot": snapshot.get("generation"), "coverage": coverage, "depthLimit": depth, "truncated": len(rows) > limit}}, ensure_ascii=False, sort_keys=True))
@@ -536,6 +623,13 @@ def command_impact(args) -> int:
 
 def _selected_generation(output: Path, generation: str | None) -> Path:
     if not generation:
+        root_snapshot = _load_snapshot(output)
+        current = root_snapshot.get("generation") if root_snapshot else None
+        if current and re.fullmatch(r"[0-9a-f-]{36}", str(current), re.I):
+            selected = output / "snapshots" / str(current)
+            if selected.is_dir():
+                return selected
+        # Legacy indexes predating immutable snapshots remain readable.
         return output
     if not re.fullmatch(r"[0-9a-f-]{36}", generation, re.I):
         raise ValueError("invalid snapshot generation")
@@ -553,6 +647,44 @@ def _load_snapshot(output: Path) -> Dict[str, object]:
     return json.loads(path.read_text(encoding="utf-8"))
 
 
+def _bounded_limit(value, maximum: int) -> int:
+    try:
+        value = int(value)
+    except (TypeError, ValueError):
+        value = 20
+    return max(1, min(value, maximum))
+
+
+def _table_names(conn: sqlite3.Connection) -> set[str]:
+    return {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type IN ('table','virtual table')")}
+
+
+def _validate_snapshot_bundle(selected: Path, snapshot: Dict[str, object]) -> List[str]:
+    errors: List[str] = []
+    generation = snapshot.get("generation")
+    if not generation:
+        return [f"snapshot metadata missing generation in {selected}"]
+    required = [SNAPSHOT_FILE, "index.sqlite", *INDEX_FILES.values()]
+    for name in required:
+        if not (selected / name).is_file():
+            errors.append(f"snapshot {generation} missing artifact {name}")
+    index = selected / "index.sqlite"
+    if index.is_file():
+        try:
+            conn = sqlite3.connect(str(index))
+            try:
+                tables = _table_names(conn)
+                if "analysis_snapshots" in tables:
+                    row = conn.execute("SELECT snapshot_id FROM analysis_snapshots LIMIT 1").fetchone()
+                    if row and row[0] != generation:
+                        errors.append(f"snapshot generation mismatch: metadata={generation}, sqlite={row[0]}")
+            finally:
+                conn.close()
+        except sqlite3.Error as exc:
+            errors.append(f"invalid sqlite snapshot {generation}: {exc}")
+    return errors
+
+
 def _query_is_fresh(root: Path, snapshot: Dict[str, object], files: List[dict]) -> bool:
     workspace = snapshot.get("workspace") if isinstance(snapshot, dict) else None
     if not isinstance(workspace, dict):
@@ -571,7 +703,9 @@ def _query_is_fresh(root: Path, snapshot: Dict[str, object], files: List[dict])
             return False
     indexed_paths = sorted(record["path"] for record in files)
     if not any(path.startswith("../") for path in indexed_paths):
-        current_paths = sorted(_workspace_rel(root, item) for item in scan_files(root))
+        scope = workspace.get("scanScope") if isinstance(workspace.get("scanScope"), dict) else {}
+        excludes = scope.get("exclude", []) if isinstance(scope, dict) else []
+        current_paths = sorted(_workspace_rel(root, item) for item in scan_files(root, excludes=excludes))
         expected_paths_hash = workspace.get("discoveredPathsHash") or workspace.get("indexedPathsHash")
         if _hash_lines(current_paths) != expected_paths_hash:
             return False
@@ -583,7 +717,14 @@ def command_audit(args) -> int:
     root = Path(args.root).resolve()
     output = Path(args.index).resolve()
     with _index_lock(output, exclusive=True):
-        files, symbols, relations, diagnostics = _load_tuple(output)
+        selected = _selected_generation(output, getattr(args, "snapshot", None))
+        snapshot = _load_snapshot(selected)
+        bundle_errors = _validate_snapshot_bundle(selected, snapshot)
+        if bundle_errors:
+            for error in bundle_errors:
+                print(error, file=sys.stderr)
+            return 1
+        files, symbols, relations, diagnostics = _load_tuple(selected)
         findings = []
         findings.extend(audit_stale(root, files))
         findings.extend(audit_relations(symbols, relations))