@guanlin4924/devflow-pi 0.1.70 → 0.1.72

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guanlin4924/devflow-pi",
-  "version": "0.1.70",
+  "version": "0.1.72",
   "type": "module",
   "description": "Devflow 专项研发 Pi，基于固定版本 OMP Runtime 组装研发状态机、代码智能、设计、实现与质量门禁。",
   "license": "UNLICENSED",

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

@@ -7,6 +7,11 @@ class ParseResult:
     symbols: List[Dict] = field(default_factory=list)
     relations: List[Dict] = field(default_factory=list)
     diagnostics: List[Dict] = field(default_factory=list)
+    # Optional cross-layer facts.  Adapters may populate these when they have
+    # framework/type information; the indexer also derives conservative facts
+    # in a separate linker pass.
+    entities: List[Dict] = field(default_factory=list)
+    flows: List[Dict] = field(default_factory=list)
 
 
 class Adapter:
@@ -27,4 +32,3 @@ class Adapter:
     @property
     def parser_id(self) -> str:
         return f"{self.name}@{self.version()}"
-

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

@@ -30,6 +30,29 @@ LANGUAGE_BY_EXTENSION = {
     ".yml": "yaml",
     ".toml": "toml",
     ".xml": "xml",
+    ".h": "c",
+    ".hh": "cpp",
+    ".hpp": "cpp",
+    ".hxx": "cpp",
+    ".c": "c",
+    ".cc": "cpp",
+    ".cpp": "cpp",
+    ".cxx": "cpp",
+    ".cs": "csharp",
+    ".scala": "scala",
+    ".sc": "scala",
+    ".lua": "lua",
+    ".html": "html",
+    ".htm": "html",
+    ".css": "css",
+    ".scss": "css",
+    ".sass": "css",
+    ".svelte": "svelte",
+    ".graphql": "graphql",
+    ".gql": "graphql",
+    ".proto": "protobuf",
+    ".hcl": "hcl",
+    ".tf": "terraform",
 }
 
 
@@ -166,6 +189,10 @@ class GenericTextAdapter(Adapter):
 
 
 def language_for_path(path: Path) -> str:
+    if path.name.lower() == "dockerfile":
+        return "dockerfile"
+    if path.name.lower().startswith("dockerfile."):
+        return "dockerfile"
     return LANGUAGE_BY_EXTENSION.get(path.suffix.lower(), path.suffix.lower().lstrip(".") or "text")
 
 

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

@@ -5,15 +5,57 @@ from .structured_scope import StructuredScopeAdapter
 
 class AdapterRegistry:
     def __init__(self):
-        self.adapters = [PythonAstAdapter(), StructuredScopeAdapter(), GenericTextAdapter()]
+        self.python = PythonAstAdapter()
+        self.structured = StructuredScopeAdapter()
+        self.generic = GenericTextAdapter()
+        self.adapters = [self.python, self.structured, self.generic]
+
+        # Keep language selection explicit.  The parser implementation is
+        # conservative and shared for now, but every supported language has a
+        # deliberate registration instead of silently falling through to text
+        # regexes.  This is the extension point for native AST adapters.
+        self.language_adapters = {
+            "python": self.python,
+            "typescript": self.structured,
+            "javascript": self.structured,
+            "ruby": self.structured,
+            "go": self.structured,
+            "rust": self.structured,
+            "php": self.structured,
+            "java": self.structured,
+            "kotlin": self.structured,
+            "c": self.structured,
+            "cpp": self.structured,
+            "csharp": self.structured,
+            "swift": self.structured,
+            "dart": self.structured,
+            "scala": self.structured,
+            "lua": self.structured,
+            "shell": self.structured,
+            "vue": self.structured,
+            "svelte": self.structured,
+            # Data, configuration, and template types are explicitly registered too. They
+            # currently use the safe text adapter until a native parser is
+            # available; this keeps their parser provenance explicit and the
+            # unified output contract unchanged.
+            "sql": self.generic,
+            "html": self.generic,
+            "css": self.generic,
+            "json": self.generic,
+            "yaml": self.generic,
+            "toml": self.generic,
+            "xml": self.generic,
+            "graphql": self.generic,
+            "protobuf": self.generic,
+            "hcl": self.generic,
+            "terraform": self.generic,
+            "dockerfile": self.generic,
+            "markdown": self.generic,
+        }
 
     def adapter_for_file(self, codebase, file_record):
         language = file_record.get("language")
-        if language == "python":
-            return self.adapters[0]
-        if language in {"typescript", "javascript", "ruby"}:
-            return self.adapters[1]
-        return self.adapters[-1]
+        return self.language_adapters.get(language, self.generic)
 
     def adapters_for(self, codebase, files, manifests):
         scored = []

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

@@ -6,7 +6,14 @@ from adapters.base import Adapter, ParseResult
 from adapters.generic_text import GenericTextAdapter, _extract_calls, _extract_imports, _relation, _symbol
 
 
-SUPPORTED = {"typescript", "javascript", "ruby"}
+# These languages intentionally share the conservative lexical scope parser.
+# The adapter does not claim AST precision; language-native parsers can be
+# added later without changing the unified index contract.
+SUPPORTED = {
+    "typescript", "javascript", "ruby", "go", "rust", "php", "java",
+    "kotlin", "c", "cpp", "csharp", "swift", "dart", "scala", "lua",
+    "shell", "vue", "svelte",
+}
 
 
 class StructuredScopeAdapter(Adapter):
@@ -21,7 +28,14 @@ class StructuredScopeAdapter(Adapter):
         self.fallback = GenericTextAdapter()
 
     def detect(self, codebase, files, manifests) -> int:
-        return 80 if any(path.suffix.lower() in {".ts", ".tsx", ".js", ".jsx", ".rb"} for path in files) else 0
+        supported_suffixes = {
+            ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".rb", ".go",
+            ".rs", ".php", ".java", ".kt", ".kts", ".c", ".h", ".cc",
+            ".cpp", ".cxx", ".hh", ".hpp", ".hxx", ".cs", ".swift",
+            ".dart", ".scala", ".sc", ".lua", ".sh", ".bash", ".zsh",
+            ".vue", ".svelte",
+        }
+        return 80 if any(path.suffix.lower() in supported_suffixes for path in files) else 0
 
     def version(self) -> str:
         return "1"
@@ -30,13 +44,20 @@ class StructuredScopeAdapter(Adapter):
         language = file_record["language"]
         if language not in SUPPORTED:
             return self.fallback.parse_file(codebase, file_record, text)
-        return self._ruby(codebase, file_record, text) if language == "ruby" else self._brace_language(codebase, file_record, text)
+        if language == "ruby":
+            return self._ruby(codebase, file_record, text)
+        if language == "shell":
+            return self._shell(codebase, file_record, text)
+        return self._brace_language(codebase, file_record, text)
 
     def _brace_language(self, codebase, file_record, text):
         lines = text.splitlines()
         file_symbol = self._file(codebase, file_record, len(lines))
         declarations: List[Tuple[int, str, str, str]] = []
-        pattern = re.compile(r"\b(class|interface|function)\s+([A-Za-z_$][\w$]*)\s*([^\n{]*)|\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>")
+        pattern = re.compile(
+            r"\b(class|interface|struct|trait|enum|object|impl|namespace|module|function)\s+([A-Za-z_$][\w$]*)\s*([^\n{]*)"
+            r"|\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*=>"
+        )
         for number, line in enumerate(lines, 1):
             clean = _without_strings_and_comments(line)
             match = pattern.search(clean)
@@ -47,11 +68,28 @@ class StructuredScopeAdapter(Adapter):
                 continue
             keyword, named, tail, arrow = match.groups()
             name = named or arrow
-            kind = "class" if keyword == "class" else "interface" if keyword == "interface" else "function"
+            kind = {
+                "class": "class", "interface": "interface", "struct": "struct",
+                "trait": "trait", "enum": "class", "object": "module",
+                "namespace": "module", "module": "module", "impl": "class",
+                "function": "function",
+            }.get(keyword, "function")
             declarations.append((number, kind, name, line.strip()))
         symbols = self._scoped_symbols(codebase, file_record, lines, declarations, file_symbol, brace=True)
         return self._relations(codebase, file_record, lines, file_symbol, symbols)
 
+    def _shell(self, codebase, file_record, text):
+        """Index shell functions and command calls at conservative scope."""
+        lines = text.splitlines()
+        file_symbol = self._file(codebase, file_record, len(lines))
+        declarations = []
+        for number, line in enumerate(lines, 1):
+            match = re.match(r"^\s*(?:function\s+)?([A-Za-z_][\w-]*)\s*(?:\(\s*\))?\s*\{", line)
+            if match:
+                declarations.append((number, "function", match.group(1), line.strip()))
+        symbols = self._scoped_symbols(codebase, file_record, lines, declarations, file_symbol, brace=True)
+        return self._relations(codebase, file_record, lines, file_symbol, symbols)
+
     def _ruby(self, codebase, file_record, text):
         lines = text.splitlines(); file_symbol = self._file(codebase, file_record, len(lines)); declarations = []
         for number, line in enumerate(lines, 1):

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

@@ -22,6 +22,7 @@ if str(SCRIPT_DIR) not in sys.path:
 
 from adapters.generic_text import language_for_path
 from adapters.registry import AdapterRegistry
+from semantic import SEMANTIC_EXTRACTOR_VERSION, build_semantic_facts
 from core.discovery import discover_codebases
 from core.hashing import file_sha256
 from core.scanner import scan_files
@@ -58,8 +59,8 @@ def _index_lock(output: Path, exclusive: bool):
             fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
 
 
-def _publish_snapshot(staging: Path, output: Path, counts: Dict[str, int], workspace_state: Dict[str, object]) -> None:
-    generation = str(uuid.uuid4())
+def _publish_snapshot(staging: Path, output: Path, counts: Dict[str, int], workspace_state: Dict[str, object], generation: str | None = None) -> None:
+    generation = generation or str(uuid.uuid4())
     immutable_relative = f"snapshots/{generation}"
     snapshot = {
         "schemaVersion": 1,
@@ -101,13 +102,15 @@ def _workspace_state(root: Path, files: List[dict], changed: Set[str], discovere
     indexed_paths = sorted(record["path"] for record in files)
     discovered = sorted(set(discovered_paths or indexed_paths))
     source_manifest_hash = _hash_lines(f"{record['path']}\0{record['content_hash']}" for record in files)
+    extractors = sorted(set(record.get("parser", "unknown") for record in files))
     return {
         "repositoryRevision": _git_output(root, ["rev-parse", "HEAD"]),
         "contentManifestHash": source_manifest_hash,
         "indexedPathsHash": _hash_lines(indexed_paths),
         "discoveredPathsHash": _hash_lines(discovered),
         "dirtyPathsAtBuild": sorted(changed),
-        "extractors": sorted(set(record.get("parser", "unknown") for record in files)),
+        "extractors": extractors,
+        "extractorSetHash": _hash_lines(extractors),
         "capabilities": {
             "python-ast@1": {"scope": "exact syntax tree", "targets": "lexical names; dynamic dispatch unresolved"},
             "structured-scope@1": {"scope": "inferred lexical braces/end blocks", "targets": "name-only heuristic"},
@@ -185,6 +188,14 @@ def main(argv=None) -> int:
     relations.add_argument("--snapshot")
     relations.add_argument("--include-heuristic", action="store_true")
 
+    impact = sub.add_parser("impact", help="Traverse cross-layer semantic facts in a fixed snapshot.")
+    impact.add_argument("--index", default=".planning/code-index")
+    impact.add_argument("--entity", required=True, help="Logical entity id, feature id, API id, or symbol id.")
+    impact.add_argument("--depth", type=int, default=5)
+    impact.add_argument("--limit", type=int, default=200)
+    impact.add_argument("--snapshot")
+    impact.add_argument("--change-type", choices=["remove_field", "rename_field", "change_type", "optional_to_required", "required_to_optional", "change_nullability", "change_enum"], help="Optional proposed change classification.")
+
     args = parser.parse_args(argv)
     if args.command == "scan":
         return command_scan(args)
@@ -196,6 +207,8 @@ def main(argv=None) -> int:
         return command_query(args)
     if args.command == "relations":
         return command_relations(args)
+    if args.command == "impact":
+        return command_impact(args)
     return 2
 
 
@@ -213,6 +226,8 @@ def command_scan(args) -> int:
         files, symbols, relations, diagnostics = _existing_after_removal(existing, changed)
         indexed_paths = {record["path"] for record in files}
         discovered_paths: Set[str] = set()
+        adapter_entities: List[dict] = []
+        adapter_flows: List[dict] = []
 
         for codebase in codebases:
             if not codebase.root.exists():
@@ -249,6 +264,8 @@ def command_scan(args) -> int:
                     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 [])
                 except Exception as exc:  # keep indexing useful even when one file fails
                     diagnostics.append(_diagnostic(codebase.name, rel_path, 1, "error", "parse_failed", str(exc), adapter.parser_id))
 
@@ -263,11 +280,26 @@ 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)
+            workspace_state["generatedAt"] = datetime.now(timezone.utc).isoformat()
+            workspace_state["semanticExtractor"] = SEMANTIC_EXTRACTOR_VERSION
+            workspace_state["extractorSetHash"] = _hash_lines([*workspace_state.get("extractors", []), SEMANTIC_EXTRACTOR_VERSION])
+            semantic_entities, semantic_flows, feature_bindings = build_semantic_facts(root, files, symbols, relations)
+            semantic_entities.extend(adapter_entities)
+            semantic_flows.extend(adapter_flows)
             write_jsonl(staging / INDEX_FILES["files"], files)
             write_jsonl(staging / INDEX_FILES["symbols"], symbols)
             write_jsonl(staging / INDEX_FILES["relations"], relations)
             write_jsonl(staging / INDEX_FILES["diagnostics"], diagnostics)
-            write_sqlite(staging / "index.sqlite", files, symbols, relations, diagnostics)
+            write_sqlite(
+                staging / "index.sqlite", files, symbols, relations, diagnostics,
+                snapshot_id=generation,
+                workspace_state=workspace_state,
+                semantic_entities=semantic_entities,
+                semantic_flows=semantic_flows,
+                feature_bindings=feature_bindings,
+            )
             write_markdown(staging, files, symbols, relations, diagnostics)
             staged_errors = validate_index(*_load_tuple(staging))
             if staged_errors:
@@ -284,7 +316,8 @@ def command_scan(args) -> int:
                     "relations": len(relations),
                     "diagnostics": len(diagnostics),
                 },
-                _workspace_state(root, files, changed, discovered_paths),
+                workspace_state,
+                generation=generation,
             )
         finally:
             shutil.rmtree(staging, ignore_errors=True)
@@ -296,6 +329,46 @@ def command_scan(args) -> int:
 
 def command_validate(args) -> int:
     output = Path(args.index).resolve()
+    selected = _selected_generation(output, None)
+    errors = []
+    try:
+        snapshot = _load_snapshot(selected)
+        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("""
+              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)
+                 AND NOT EXISTS (SELECT 1 FROM symbols s WHERE s.id=f.source_id))
+                OR
+                (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("""
+              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")
+        finally:
+            conn.close()
+    except (OSError, sqlite3.Error, ValueError) as exc:
+        errors.append(str(exc))
+    for error in errors:
+        print(error, file=sys.stderr)
+    return 1 if errors else 0
 def command_query(args) -> int:
     output = Path(args.index).resolve()
     with _index_lock(output, exclusive=False):
@@ -366,12 +439,61 @@ def command_relations(args) -> int:
               ) SELECT * FROM graph 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]: print(json.dumps(dict(row), ensure_ascii=False, sort_keys=True))
+            for row in rows[:limit]:
+                item = dict(row)
+                if args.change_type:
+                    item["impact_kind"] = args.change_type
+                    item["severity"] = _impact_severity(args.change_type, item["flow_type"])
+                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()
     return 0
 
 
+def _impact_severity(change_type: str, flow_type: str) -> str:
+    """Conservative compatibility rules for an observed impact edge."""
+    if change_type in {"remove_field", "change_type", "change_nullability", "change_enum"}:
+        return "high" if flow_type in {"returns_field", "accepts_field", "state_reads", "renders_when", "depends_on"} else "medium"
+    if change_type == "optional_to_required":
+        return "high" if flow_type in {"api_declares_or_calls", "accepts_field"} else "medium"
+    if change_type == "rename_field":
+        return "high" if flow_type in {"returns_field", "accepts_field", "maps_to", "state_reads"} else "medium"
+    return "low"
+
+
+def command_impact(args) -> int:
+    output = Path(args.index).resolve()
+    depth = max(0, min(args.depth, 20)); limit = max(1, min(args.limit, 2000))
+    with _index_lock(output, exclusive=False):
+        selected = _selected_generation(output, getattr(args, "snapshot", None))
+        snapshot = _load_snapshot(selected)
+        if not getattr(args, "snapshot", None):
+            files = read_jsonl(selected / INDEX_FILES["files"])
+            if not _query_is_fresh(output.parent.parent, snapshot, files):
+                print("Stale code index: refresh required before impact query.", file=sys.stderr)
+                return 1
+        conn = sqlite3.connect(str(selected / "index.sqlite")); conn.row_factory = sqlite3.Row
+        try:
+            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, ',' || ? || ','
+                FROM semantic_flows WHERE snapshot_id=? AND (source_id=? OR target_id=?)
+                UNION ALL
+                SELECT CASE WHEN f.source_id=g.node_id THEN f.target_id ELSE f.source_id END,
+                       f.flow_type, f.source_path, f.line_start, f.confidence, g.depth+1, g.visited || g.node_id || ','
+                FROM graph g JOIN semantic_flows f ON f.snapshot_id=? AND (f.source_id=g.node_id OR f.target_id=g.node_id)
+                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))
+            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))
+        finally:
+            conn.close()
+    return 0
+
+
 def _selected_generation(output: Path, generation: str | None) -> Path:
     if not generation:
         return output

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

@@ -0,0 +1,187 @@
+"""Conservative cross-layer fact extraction.
+
+This module intentionally emits candidates with evidence and confidence.  It
+does not replace framework parsers; it gives the relational index a stable
+schema so API, database, UI and feature facts can be linked incrementally.
+"""
+import re
+from pathlib import Path
+from typing import Dict, Iterable, List, Tuple
+
+from core.schema import short_hash, stable_key
+from core.hashing import file_sha256
+
+SEMANTIC_EXTRACTOR_VERSION = "semantic-linker@1"
+
+
+def build_semantic_facts(root: Path, files: Iterable[dict], symbols: Iterable[dict],
+                         relations: Iterable[dict]) -> Tuple[List[dict], List[dict], List[dict]]:
+    entities: List[dict] = []
+    flows: List[dict] = []
+    bindings: List[dict] = []
+    symbol_by_path = {}
+    for symbol in symbols:
+        symbol_by_path.setdefault(symbol.get("path"), []).append(symbol)
+
+    for file_record in files:
+        path = file_record["path"]
+        source = _read(root, path)
+        if source is None:
+            continue
+        try:
+            if file_sha256(root / path) != file_record.get("content_hash"):
+                # Never mix a newly-read working-tree file with an older
+                # structural record in the same immutable snapshot.
+                continue
+        except OSError:
+            continue
+        language = file_record.get("language", "")
+        feature = _feature_from_path(path)
+        if feature:
+            feature_id = f"feature:{stable_key(feature)}"
+            entities.append(_entity(feature_id, "feature", feature, file_record, 1, 1,
+                                    "heuristic", "path_feature_inference"))
+            for symbol in symbol_by_path.get(path, []):
+                if symbol.get("kind") in {"route", "component", "class", "function", "method"}:
+                    bindings.append(_binding(feature_id, symbol["id"], "static_inferred", "heuristic", path, symbol.get("line_start", 1)))
+
+        for line_no, line in enumerate(source.splitlines(), 1):
+            _extract_api(line, path, file_record, line_no, entities, flows)
+            _extract_db(line, path, file_record, line_no, entities, flows)
+            _extract_ui(line, path, file_record, line_no, entities, flows)
+
+    # Existing structural relations remain the source of method call edges;
+    # expose them in the semantic graph without changing their meaning.
+    for relation in relations:
+        if relation.get("to_id") and relation.get("relation_type") in {"calls", "contains", "routes_to"}:
+            flows.append({
+                "source_id": relation.get("from_id"),
+                "target_id": relation.get("to_id"),
+                "flow_type": relation.get("relation_type"),
+                "mapping_kind": "structural_relation",
+                "source_path": relation.get("evidence_path"),
+                "line_start": relation.get("evidence_line"),
+                "confidence": relation.get("confidence", "heuristic"),
+                "evidence_level": "syntax",
+                "metadata": relation.get("metadata", {}),
+            })
+    return _dedupe_entities(entities), _dedupe_flows(flows), _dedupe_bindings(bindings)
+
+
+def _extract_api(line, path, record, line_no, entities, flows):
+    # Framework-neutral route declarations and client URLs.
+    match = re.search(r"(?:@(?:app|router|api)\.(get|post|put|patch|delete)\s*\(|(?:GET|POST|PUT|PATCH|DELETE)\s+)(['\"])(/[^'\"]+)\2", line, re.I)
+    if not match:
+        match = re.search(r"(?:fetch|axios\.(?:get|post|put|patch|delete)|client\.(?:get|post|put|patch|delete))\s*\(\s*(['\"])(/[^'\"]+)\1", line, re.I)
+    if not match:
+        return
+    route = match.group(3) if match.lastindex and match.lastindex >= 3 else match.group(2)
+    method_match = re.search(r"@(?:app|router|api)\.(get|post|put|patch|delete)\b|\b(GET|POST|PUT|PATCH|DELETE)\b|\b(?:fetch|axios\.|client\.)(get|post|put|patch|delete)\b", line, re.I)
+    method = next((value.upper() for value in (method_match.groups() if method_match else ()) if value), "UNKNOWN")
+    if method == "UNKNOWN" and re.search(r"\bfetch\s*\(", line, re.I):
+        method = "GET"
+    endpoint_id = f"api:{method}:{stable_key(route)}"
+    entity_type = "api_endpoint"
+    entities.append(_entity(endpoint_id, entity_type, f"{method} {route}", record, line_no, line_no, "heuristic", "route_or_client_regex", {"http_method": method, "path": route}))
+    flows.append(_flow(f"file:{record['codebase']}:{path}", endpoint_id, "api_declares_or_calls", path, line_no, "heuristic", "framework_neutral_route"))
+    for field in re.findall(r"(?:response|payload|data|body)\s*[.\[]\s*['\"]?([A-Za-z_][A-Za-z0-9_]*)", line):
+        field_id = f"api-field:{endpoint_id}:response:{field}"
+        entities.append(_entity(field_id, "api_field", field, record, line_no, line_no, "heuristic", "field_access_regex", {"endpoint_id": endpoint_id, "direction": "response", "field_path": field}))
+        flows.append(_flow(endpoint_id, field_id, "returns_field", path, line_no, "heuristic", "field_access_regex"))
+
+
+def _extract_db(line, path, record, line_no, entities, flows):
+    # SQL and common ORM spellings.  Dynamic identifiers are deliberately not
+    # resolved to a concrete column.
+    table_match = re.search(r"\b(?:FROM|JOIN|INTO|UPDATE|TABLE)\s+[`\"]?([A-Za-z_][\w$]*)", line, re.I)
+    orm_match = re.search(r"\b([A-Z][A-Za-z0-9_]*)\.(?:query|objects|select|filter|where)\b", line)
+    if not table_match and not orm_match:
+        return
+    table = table_match.group(1) if table_match else orm_match.group(1)
+    table_id = f"db-table:{stable_key(table)}"
+    entities.append(_entity(table_id, "db_table", table, record, line_no, line_no, "heuristic", "sql_or_orm_regex"))
+    operation = "writes" if re.search(r"\b(?:INSERT|UPDATE|DELETE)\b|\.update\s*\(", line, re.I) else "reads"
+    flows.append(_flow(f"file:{record['codebase']}:{path}", table_id, operation, path, line_no, "heuristic", "sql_or_orm_regex"))
+    for column in re.findall(r"\b([A-Za-z_][A-Za-z0-9_]*)\s*(?:=|,|FROM|$)", line):
+        if column.lower() in {"select", "from", "where", "set", "values", "into", "update", "join", "and", "or"}:
+            continue
+        column_id = f"db-column:{stable_key(table)}:{stable_key(column)}"
+        entities.append(_entity(column_id, "db_column", column, record, line_no, line_no, "heuristic", "sql_column_regex", {"table_id": table_id, "column": column}))
+        flows.append(_flow(table_id, column_id, f"{operation}_column", path, line_no, "heuristic", "sql_column_regex"))
+
+
+def _extract_ui(line, path, record, line_no, entities, flows):
+    component = re.search(r"\b(?:function|class)\s+([A-Z][A-Za-z0-9_]*)|<([A-Z][A-Za-z0-9_.]*)\b", line)
+    state = re.search(r"\b(?:useState|ref|reactive|computed|createSignal)\s*\(.*?\)|\b(?:const|let|var)\s+([A-Za-z_][\w]*(?:State|Store|Status|Loading|Error))\s*=", line)
+    condition = re.search(r"\b(?:v-if|v-show)\s*=\s*['\"]([^'\"]+)['\"]|(?:\{\s*)?([^{}\n]+?)\s*&&\s*<", line)
+    if component:
+        name = component.group(1) or component.group(2)
+        component_id = f"ui-component:{stable_key(path)}:{stable_key(name)}"
+        entities.append(_entity(component_id, "ui_component", name, record, line_no, line_no, "inferred", "component_pattern"))
+    else:
+        component_id = f"ui-file:{stable_key(path)}"
+        entities.append(_entity(component_id, "ui_component", Path(path).stem, record, line_no, line_no, "heuristic", "ui_file_scope"))
+    if state:
+        name = state.group(1) or "anonymous_state"
+        state_id = f"ui-state:{stable_key(path)}:{stable_key(name)}"
+        entities.append(_entity(state_id, "ui_state", name, record, line_no, line_no, "heuristic", "state_pattern"))
+        flows.append(_flow(component_id, state_id, "state_reads", path, line_no, "heuristic", "state_pattern"))
+    if condition:
+        expression = condition.group(1) or condition.group(2)
+        cond_id = f"render-condition:{stable_key(path)}:{short_hash(expression)}"
+        entities.append(_entity(cond_id, "render_condition", expression, record, line_no, line_no, "heuristic", "template_condition"))
+        flows.append(_flow(component_id, cond_id, "renders_when", path, line_no, "heuristic", "template_condition"))
+        known_ids = {item["id"] for item in entities if item.get("entity_type") == "ui_state"}
+        for name in re.findall(r"\b[A-Za-z_][A-Za-z0-9_]*\b", expression):
+            state_id = f"ui-state:{stable_key(path)}:{stable_key(name)}"
+            if state_id in known_ids:
+                flows.append(_flow(cond_id, state_id, "depends_on", path, line_no, "heuristic", "condition_identifier"))
+
+
+def _entity(entity_id, entity_type, name, record, start, end, confidence, extractor, metadata=None):
+    return {"id": entity_id, "entity_type": entity_type, "name": name, "codebase": record["codebase"], "path": record["path"], "line_start": start, "line_end": end, "content_hash": record["content_hash"], "confidence": confidence, "extractor": extractor, "metadata": metadata or {}}
+
+
+def _flow(source_id, target_id, flow_type, path, line, confidence, extractor, metadata=None):
+    return {"source_id": source_id, "target_id": target_id, "flow_type": flow_type, "source_path": path, "line_start": line, "confidence": confidence, "evidence_level": "static_source", "extractor": extractor, "metadata": metadata or {}}
+
+
+def _binding(feature_id, entity_id, source, confidence, path, line):
+    return {"feature_id": feature_id, "entity_id": entity_id, "binding_type": source, "confidence": confidence, "source_path": path, "line_start": line}
+
+
+def _read(root, path):
+    try:
+        return (root / path).read_text(encoding="utf-8", errors="ignore")
+    except OSError:
+        return None
+
+
+def _feature_from_path(path):
+    parts = [part for part in Path(path).parts if part not in {"src", "app", "lib", "components", "services", "pages", "api", "tests"}]
+    if not parts:
+        return None
+    token = re.sub(r"[^A-Za-z0-9_-]+", "-", parts[0]).strip("-")
+    return token if token and token.lower() not in {"index", "main", "common", "shared"} else None
+
+
+def _dedupe_entities(items):
+    result = {}
+    for item in items:
+        result[item["id"]] = item
+    return list(result.values())
+
+
+def _dedupe_flows(items):
+    result = {}
+    for item in items:
+        key = (item.get("source_id"), item.get("target_id"), item.get("flow_type"), item.get("source_path"), item.get("line_start"))
+        result[key] = item
+    return list(result.values())
+
+
+def _dedupe_bindings(items):
+    result = {}
+    for item in items:
+        result[(item["feature_id"], item["entity_id"])] = item
+    return list(result.values())

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

@@ -58,6 +58,119 @@ CREATE TABLE IF NOT EXISTS diagnostics (
   parser TEXT
 );
 
+CREATE TABLE IF NOT EXISTS analysis_snapshots (
+  snapshot_id TEXT PRIMARY KEY,
+  schema_version INTEGER NOT NULL,
+  source_revision TEXT,
+  content_manifest_hash TEXT,
+  extractor_set_hash TEXT,
+  created_at TEXT NOT NULL,
+  status TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS logical_entities (
+  logical_id TEXT PRIMARY KEY,
+  entity_type TEXT NOT NULL,
+  stable_key TEXT NOT NULL,
+  metadata_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS entity_versions (
+  entity_version_id TEXT PRIMARY KEY,
+  snapshot_id TEXT NOT NULL,
+  logical_id TEXT NOT NULL,
+  entity_type TEXT NOT NULL,
+  name TEXT NOT NULL,
+  codebase TEXT,
+  path TEXT,
+  line_start INTEGER,
+  line_end INTEGER,
+  content_hash TEXT,
+  confidence TEXT NOT NULL,
+  extractor TEXT NOT NULL,
+  metadata_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS semantic_flows (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  snapshot_id TEXT NOT NULL,
+  source_id TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  flow_type TEXT NOT NULL,
+  source_path TEXT,
+  line_start INTEGER,
+  confidence TEXT NOT NULL,
+  evidence_level TEXT NOT NULL,
+  extractor TEXT NOT NULL,
+  metadata_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS feature_bindings (
+  snapshot_id TEXT NOT NULL,
+  feature_id TEXT NOT NULL,
+  entity_id TEXT NOT NULL,
+  binding_type TEXT NOT NULL,
+  confidence TEXT NOT NULL,
+  source_path TEXT,
+  line_start INTEGER,
+  PRIMARY KEY(snapshot_id, feature_id, entity_id)
+);
+
+CREATE TABLE IF NOT EXISTS coverage_metrics (
+  snapshot_id TEXT PRIMARY KEY,
+  files_scanned INTEGER NOT NULL,
+  files_parsed INTEGER NOT NULL,
+  diagnostics INTEGER NOT NULL,
+  semantic_entities INTEGER NOT NULL,
+  semantic_flows INTEGER NOT NULL,
+  dynamic_limitations INTEGER NOT NULL,
+  metadata_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS design_entities (
+  artifact_revision TEXT NOT NULL,
+  design_entity_id TEXT NOT NULL,
+  entity_type TEXT NOT NULL,
+  name TEXT NOT NULL,
+  field_path TEXT,
+  direction TEXT,
+  status TEXT NOT NULL,
+  metadata_json TEXT,
+  PRIMARY KEY(artifact_revision, design_entity_id)
+);
+
+CREATE TABLE IF NOT EXISTS design_observation_links (
+  artifact_revision TEXT NOT NULL,
+  design_entity_id TEXT NOT NULL,
+  observed_entity_id TEXT NOT NULL,
+  result TEXT NOT NULL, -- matches / drift / gap / unknown
+  confidence TEXT NOT NULL,
+  evidence_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS proposed_changes (
+  change_id TEXT PRIMARY KEY,
+  snapshot_id TEXT NOT NULL,
+  artifact_revision TEXT,
+  change_type TEXT NOT NULL,
+  target_entity_id TEXT NOT NULL,
+  before_json TEXT,
+  after_json TEXT,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS impact_findings (
+  impact_run_id TEXT NOT NULL,
+  snapshot_id TEXT NOT NULL,
+  change_id TEXT,
+  entity_id TEXT NOT NULL,
+  impact_kind TEXT NOT NULL,
+  severity TEXT NOT NULL,
+  confidence TEXT NOT NULL,
+  evidence_json TEXT,
+  PRIMARY KEY(impact_run_id, entity_id, impact_kind)
+);
+
 CREATE VIRTUAL TABLE IF NOT EXISTS symbols_fts USING fts5(
   id UNINDEXED,
   codebase UNINDEXED,
@@ -78,13 +191,69 @@ CREATE INDEX IF NOT EXISTS idx_relations_external ON relations(to_external);
 """
 
 
-def write_sqlite(path: Path, files, symbols, relations, diagnostics) -> None:
+def write_sqlite(path: Path, files, symbols, relations, diagnostics, snapshot_id="pending",
+                 workspace_state=None, semantic_entities=None, semantic_flows=None, feature_bindings=None) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     if path.exists():
         path.unlink()
     conn = sqlite3.connect(str(path))
     try:
         conn.executescript(SCHEMA)
+        workspace_state = workspace_state or {}
+        semantic_entities = list(semantic_entities or [])
+        semantic_flows = semantic_flows or []
+        feature_bindings = feature_bindings or []
+        parse_failed_paths = {item.get("path") for item in diagnostics if item.get("kind") == "parse_failed"}
+        parsed_count = sum(1 for item in files if item.get("path") not in parse_failed_paths)
+        conn.execute(
+            "INSERT INTO analysis_snapshots(snapshot_id, schema_version, source_revision, content_manifest_hash, extractor_set_hash, created_at, status) VALUES(?,?,?,?,?,?,?)",
+            (snapshot_id, 2, workspace_state.get("repositoryRevision", ""), workspace_state.get("contentManifestHash", ""),
+             workspace_state.get("extractorSetHash", ""), workspace_state.get("generatedAt", ""), "current"),
+        )
+        # Structural symbols and files are first-class graph nodes as well.
+        # This prevents semantic flows and feature bindings from dangling when
+        # a framework linker points at an existing code symbol.
+        structural_entities = [
+            {"id": item["id"], "entity_type": item.get("kind", "symbol"), "name": item.get("name", item["id"]),
+             "codebase": item.get("codebase"), "path": item.get("path"), "line_start": item.get("line_start"),
+             "line_end": item.get("line_end"), "content_hash": item.get("content_hash"), "confidence": "exact",
+             "extractor": item.get("parser", "index"), "metadata": item.get("metadata", {})}
+            for item in [*files, *symbols]
+        ]
+        by_id = {item["id"]: item for item in semantic_entities}
+        for item in structural_entities:
+            by_id.setdefault(item["id"], item)
+        semantic_entities = list(by_id.values())
+        valid_ids = set(by_id)
+        invalid_flows = [item for item in semantic_flows if item.get("source_id") not in valid_ids or item.get("target_id") not in valid_ids]
+        invalid_bindings = [item for item in feature_bindings if item.get("feature_id") not in valid_ids or item.get("entity_id") not in valid_ids]
+        if invalid_flows or invalid_bindings:
+            raise ValueError(
+                f"semantic graph contains dangling references: flows={len(invalid_flows)}, bindings={len(invalid_bindings)}"
+            )
+        for entity in semantic_entities:
+            logical_id = entity["id"]
+            entity_version_id = f"{snapshot_id}:{logical_id}"
+            conn.execute(
+                "INSERT OR IGNORE INTO logical_entities(logical_id, entity_type, stable_key, metadata_json) VALUES(?,?,?,?)",
+                (logical_id, entity["entity_type"], logical_id, json_dumps(entity.get("metadata", {}))),
+            )
+            conn.execute(
+                "INSERT INTO entity_versions(entity_version_id, snapshot_id, logical_id, entity_type, name, codebase, path, line_start, line_end, content_hash, confidence, extractor, metadata_json) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)",
+                (entity_version_id, snapshot_id, logical_id, entity["entity_type"], entity["name"], entity.get("codebase"), entity.get("path"), entity.get("line_start"), entity.get("line_end"), entity.get("content_hash"), entity["confidence"], entity["extractor"], json_dumps(entity.get("metadata", {}))),
+            )
+        conn.executemany(
+            "INSERT INTO semantic_flows(snapshot_id, source_id, target_id, flow_type, source_path, line_start, confidence, evidence_level, extractor, metadata_json) VALUES(?,?,?,?,?,?,?,?,?,?)",
+            [(snapshot_id, item["source_id"], item["target_id"], item["flow_type"], item.get("source_path"), item.get("line_start"), item["confidence"], item.get("evidence_level", "static_source"), item.get("extractor", "unknown"), json_dumps(item.get("metadata", {}))) for item in semantic_flows],
+        )
+        conn.executemany(
+            "INSERT INTO feature_bindings(snapshot_id, feature_id, entity_id, binding_type, confidence, source_path, line_start) VALUES(?,?,?,?,?,?,?)",
+            [(snapshot_id, item["feature_id"], item["entity_id"], item["binding_type"], item["confidence"], item.get("source_path"), item.get("line_start")) for item in feature_bindings],
+        )
+        conn.execute(
+            "INSERT INTO coverage_metrics(snapshot_id, files_scanned, files_parsed, diagnostics, semantic_entities, semantic_flows, dynamic_limitations, metadata_json) VALUES(?,?,?,?,?,?,?,?)",
+            (snapshot_id, len(files), parsed_count, len(diagnostics), len(semantic_entities), len(semantic_flows), sum(1 for item in semantic_flows if item.get("metadata", {}).get("dynamic_limitations") or item.get("confidence") in {"heuristic", "unknown"}), json_dumps({"capabilities": workspace_state.get("capabilities", {}), "semantic_extractor": workspace_state.get("semanticExtractor")})),
+        )
         conn.executemany(
             """
             INSERT INTO code_files(id, codebase, path, language, size_bytes, content_hash, indexed_at, parser)

package/src/constants.ts

@@ -1,5 +1,5 @@
 export const PRODUCT_NAME = "Devflow Pi";
-export const PRODUCT_VERSION = "0.1.70";
+export const PRODUCT_VERSION = "0.1.72";
 export const PROJECT_SCHEMA_VERSION = 1;
 export const OMP_RUNTIME_VERSION = "17.2.7";
 

package/src/initialization-store.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { copyFile, cp, mkdir, readFile, realpath, stat, writeFile, rename, rm } from "node:fs/promises";
+import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { Database } from "bun:sqlite";
 
@@ -263,12 +264,33 @@ export class InitializationStore {
         await writeFile(migrationBackup, db.serialize(), { flag: "wx" });
       }
     }
-    db.transaction(() => {
+    const migrate = db.transaction(() => {
       db.exec(SCHEMA);
+      const ensureColumn = (table: string, column: string, definition: string) => {
+        const columns = db.query(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>;
+        if (!columns.some(item => item.name === column)) db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+      };
+      ensureColumn("context_snapshots", "index_ref_json", "TEXT");
+      ensureColumn("document_jobs", "model_role", "TEXT");
+      ensureColumn("document_jobs", "output_hash", "TEXT");
+      ensureColumn("document_jobs", "conflict_path", "TEXT");
+      ensureColumn("document_jobs", "error", "TEXT");
       const meta = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number } | null;
-      if (!meta) db.query("INSERT INTO schema_meta(version) VALUES (?)").run(INITIALIZATION_SCHEMA_VERSION);
-      else if (meta.version < INITIALIZATION_SCHEMA_VERSION) db.query("UPDATE schema_meta SET version=?").run(INITIALIZATION_SCHEMA_VERSION);
-    })();
+      if (!meta) {
+        db.query("INSERT INTO schema_meta(version) VALUES (?)").run(INITIALIZATION_SCHEMA_VERSION);
+      } else {
+        let version = meta.version;
+        if (version < 2) {
+          db.exec("CREATE INDEX IF NOT EXISTS idx_input_snapshots_project ON input_snapshots(project_id, workspace_id, config_id)");
+          db.exec("CREATE INDEX IF NOT EXISTS idx_document_jobs_status ON document_jobs(status, updated_at)");
+          version = 2;
+        }
+        db.query("UPDATE schema_meta SET version=?").run(version);
+      }
+      const verified = db.query("SELECT version FROM schema_meta LIMIT 1").get() as { version: number };
+      if (verified.version !== INITIALIZATION_SCHEMA_VERSION) throw new Error(`Initialization schema migration stopped at ${verified.version}`);
+    });
+    try { migrate(); } catch (error) { db.close(); throw new Error(`Initialization database migration failed: ${error instanceof Error ? error.message : String(error)}`); }
     db.query("INSERT OR IGNORE INTO projects(id,name,created_at) VALUES (?,?,?)").run(context.manifest.projectId, context.manifest.name, now());
     db.query("INSERT OR IGNORE INTO authority_state(project_id,authority,revision,switched_at) VALUES (?,?,?,?)").run(context.manifest.projectId, "legacy", 0, now());
     return new InitializationStore(context, databasePath, db);
@@ -311,13 +333,23 @@ export class InitializationStore {
     return { id, revision: row.revision, created: true };
   }
 
-  createInputSnapshot(workspaceId: string, configId: string, files: Array<{ repository: string; path: string; contentHash: string; size?: number }>, stable = true): { id: string; fingerprint: string; created: boolean } {
+  createInputSnapshot(workspaceId: string, configId: string, files: Array<{ repository: string; path: string; contentHash: string; size?: number }>, stable = false): { id: string; fingerprint: string; created: boolean } {
+    const binding = this.db.query(`SELECT w.id AS workspaceId,c.id AS configId,w.project_id AS workspaceProject,c.project_id AS configProject,c.config_json AS config
+      FROM workspaces w JOIN scan_configs c ON c.project_id=w.project_id
+      WHERE w.id=? AND c.id=? AND w.project_id=?`).get(workspaceId, configId, this.context.manifest.projectId) as { workspaceId: string; configId: string; workspaceProject: string; configProject: string; config: string } | null;
+    if (!binding) throw new Error("Input snapshot workspace and scan config do not belong to the same project boundary");
+    const configured = new Map((parse<ScanConfigInput>(binding.config).repositories ?? []).map(repository => [repository.name, repository.relativePath]));
+    for (const file of files) {
+      if (!configured.has(file.repository)) throw new Error(`Input snapshot repository is not configured: ${file.repository}`);
+      const base = configured.get(file.repository)!;
+      if (base !== "." && !path.isAbsolute(base) && file.path !== base && !file.path.startsWith(`${base.replace(/\\/g, "/").replace(/\/$/, "")}/`)) throw new Error(`Input snapshot path is outside repository: ${file.repository}/${file.path}`);
+    }
     const normalized = files.map(file => ({ ...file, path: validateRelative(file.path) })).sort((a, b) => `${a.repository}/${a.path}`.localeCompare(`${b.repository}/${b.path}`));
     const manifestJson = canonicalJson(normalized);
     const fingerprint = hash(manifestJson);
     const existing = this.db.query("SELECT id,stable FROM input_snapshots WHERE workspace_id=? AND config_id=? AND fingerprint=?").get(workspaceId, configId, fingerprint) as { id: string; stable: number } | null;
     if (existing) {
-      if (stable && !existing.stable) this.db.query("UPDATE input_snapshots SET stable=1 WHERE id=?").run(existing.id);
+      if (stable && !existing.stable) throw new Error("Existing input snapshot is unstable; confirm it explicitly before publishing");
       return { id: existing.id, fingerprint, created: false };
     }
     const id = randomUUID();
@@ -369,27 +401,39 @@ export class InitializationStore {
   recordCollection(runId: string, leaseToken: string, input: { repository?: string; kind: FactKind; status: CoverageStatus; adapter: string; capability?: Record<string, unknown>; diagnostics?: unknown[]; facts?: FactInput[] }): void {
     this.assertWritableRun(runId, leaseToken);
     const transaction = this.db.transaction(() => {
-      this.db.query("INSERT INTO collection_results(id,run_id,repository,kind,status,adapter,capability_json,diagnostics_json,created_at) VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,repository,kind) DO UPDATE SET status=excluded.status,adapter=excluded.adapter,capability_json=excluded.capability_json,diagnostics_json=excluded.diagnostics_json").run(randomUUID(), runId, input.repository ?? "", input.kind, input.status, input.adapter, canonicalJson(input.capability ?? {}), canonicalJson(input.diagnostics ?? []), now());
+      const repository = input.repository ?? "";
+      this.db.query("DELETE FROM evidence WHERE fact_id IN (SELECT id FROM facts WHERE run_id=? AND repository=? AND kind=?)").run(runId, repository, input.kind);
+      this.db.query("DELETE FROM facts WHERE run_id=? AND repository=? AND kind=?").run(runId, repository, input.kind);
+      this.db.query("INSERT INTO collection_results(id,run_id,repository,kind,status,adapter,capability_json,diagnostics_json,created_at) VALUES (?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,repository,kind) DO UPDATE SET status=excluded.status,adapter=excluded.adapter,capability_json=excluded.capability_json,diagnostics_json=excluded.diagnostics_json,created_at=excluded.created_at").run(randomUUID(), runId, repository, input.kind, input.status, input.adapter, canonicalJson(input.capability ?? {}), canonicalJson(input.diagnostics ?? []), now());
       for (const fact of input.facts ?? []) {
         if (fact.kind !== input.kind) throw new Error(`Fact kind ${fact.kind} does not match collection ${input.kind}`);
         if (!fact.objectKey || !fact.extractor) throw new Error("Facts require objectKey and extractor");
         if (fact.evidenceLevel === "observed" && !fact.sourcePath) throw new Error("Observed facts require source evidence");
         validateFactShape(fact);
         const factId = randomUUID();
-        this.db.query("INSERT INTO facts(id,run_id,kind,object_key,repository,value_json,evidence_level,extractor,confidence,created_at) VALUES (?,?,?,?,?,?,?,?,?,?) ON CONFLICT(run_id,kind,repository,object_key) DO UPDATE SET value_json=excluded.value_json,evidence_level=excluded.evidence_level,extractor=excluded.extractor,confidence=excluded.confidence").run(factId, runId, fact.kind, fact.objectKey, fact.repository ?? input.repository ?? "", canonicalJson(fact.value), fact.evidenceLevel, fact.extractor, fact.confidence ?? "inferred", now());
-        const stored = this.db.query("SELECT id FROM facts WHERE run_id=? AND kind=? AND repository=? AND object_key=?").get(runId, fact.kind, fact.repository ?? input.repository ?? "", fact.objectKey) as { id: string };
+        this.db.query("INSERT INTO facts(id,run_id,kind,object_key,repository,value_json,evidence_level,extractor,confidence,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(factId, runId, fact.kind, fact.objectKey, fact.repository ?? repository, canonicalJson(fact.value), fact.evidenceLevel, fact.extractor, fact.confidence ?? "inferred", now());
+        const stored = { id: factId };
         if (fact.sourcePath) this.db.query("INSERT OR IGNORE INTO evidence(id,fact_id,source_path,source_line,source_fingerprint,method,created_at) VALUES (?,?,?,?,?,?,?)").run(randomUUID(), stored.id, validateRelative(fact.sourcePath), fact.sourceLine ?? null, fact.sourceFingerprint ?? "unavailable", fact.extractor, now());
       }
     });
     transaction();
   }
 
-  cancelRun(runId: string): boolean {
-    return this.db.query("UPDATE initialization_runs SET status='cancelled',updated_at=? WHERE id=? AND status IN ('preparing','collecting','validating')").run(now(), runId).changes === 1;
+  cancelRun(runId: string, leaseToken: string, expectedRevision: number): boolean {
+    const row = this.db.query("SELECT status,lease_token AS leaseToken,lease_expires_at AS expires,workspace_id AS workspaceId,config_id AS configId FROM initialization_runs WHERE id=?").get(runId) as { status: RunStatus; leaseToken: string; expires: string; workspaceId: string; configId: string } | null;
+    if (!row) throw new Error(`Unknown initialization run: ${runId}`);
+    if (row.leaseToken !== leaseToken) throw new Error("Initialization lease token mismatch");
+    if (Date.parse(row.expires) < Date.now()) throw new Error("Initialization lease expired; recover the run before cancelling");
+    const current = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(row.workspaceId, row.configId) as { revision: number } | null;
+    if (expectedRevision !== (current?.revision ?? 0)) throw new Error("Initialization run revision conflict");
+    const timestamp = now();
+    return this.db.query("UPDATE initialization_runs SET status='cancelled',updated_at=? WHERE id=? AND lease_token=? AND lease_expires_at>? AND status IN ('preparing','collecting','validating')").run(timestamp, runId, leaseToken, timestamp).changes === 1;
   }
 
   failRun(runId: string, leaseToken: string, error: string): boolean {
-    return this.db.query("UPDATE initialization_runs SET status='failed',error=?,updated_at=? WHERE id=? AND lease_token=? AND status IN ('preparing','collecting','validating')").run(error.slice(0, 4000), now(), runId, leaseToken).changes === 1;
+    this.assertWritableRun(runId, leaseToken);
+    const timestamp = now();
+    return this.db.query("UPDATE initialization_runs SET status='failed',error=?,updated_at=? WHERE id=? AND lease_token=? AND lease_expires_at>? AND status IN ('preparing','collecting','validating')").run(error.slice(0, 4000), timestamp, runId, leaseToken, timestamp).changes === 1;
   }
 
   recoverRun(runId: string, leaseMs = 15 * 60_000): { leaseToken: string } {
@@ -399,11 +443,12 @@ export class InitializationStore {
     if (["failed", "finished"].includes(row.status)) throw new Error(`Run cannot be recovered from ${row.status}`);
     if (Date.parse(row.expires) >= Date.now()) throw new Error("Run lease is still active");
     const leaseToken = randomUUID();
-    this.db.query("UPDATE initialization_runs SET lease_token=?,lease_expires_at=?,updated_at=? WHERE id=?").run(leaseToken, new Date(Date.now() + leaseMs).toISOString(), now(), runId);
+    const changed = this.db.query("UPDATE initialization_runs SET lease_token=?,lease_expires_at=?,updated_at=? WHERE id=? AND lease_expires_at<? AND status IN ('preparing','collecting','validating')").run(leaseToken, new Date(Date.now() + leaseMs).toISOString(), now(), runId, now());
+    if (changed.changes !== 1) throw new Error("Initialization run recovery conflict");
     return { leaseToken };
   }
 
-  publishRun(runId: string, leaseToken: string, options: { expectedRevision?: number; completeness?: "complete" | "partial"; indexRef?: Record<string, unknown>; updateCurrent?: boolean } = {}): { snapshotId: string; revision: number } {
+  publishRun(runId: string, leaseToken: string, options: { expectedRevision: number; completeness?: "complete" | "partial"; indexRef?: Record<string, unknown>; updateCurrent?: boolean }): { snapshotId: string; revision: number } {
     const run = this.assertWritableRun(runId, leaseToken);
     const input = this.db.query("SELECT stable,fingerprint FROM input_snapshots WHERE id=?").get(run.inputSnapshotId) as { stable: number; fingerprint: string };
     if (!input.stable) throw new Error("Cannot publish an unstable input snapshot");
@@ -422,12 +467,31 @@ export class InitializationStore {
     if (completeness === "complete" && blockers.length) throw new Error(`Required collection coverage is incomplete: ${blockers.join(", ")}`);
     const current = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(run.workspaceId, run.configId) as { revision: number } | null;
     const revision = (current?.revision ?? 0) + 1;
-    if (options.expectedRevision !== undefined && options.expectedRevision !== (current?.revision ?? 0)) throw new Error(`Current context revision conflict: expected ${options.expectedRevision}, actual ${current?.revision ?? 0}`);
+    if (options.expectedRevision !== (current?.revision ?? 0)) throw new Error(`Current context revision conflict: expected ${options.expectedRevision}, actual ${current?.revision ?? 0}`);
+    if (options.indexRef) {
+      if (options.indexRef.inputFingerprint !== input.fingerprint || options.indexRef.workspaceId !== run.workspaceId || options.indexRef.configId !== run.configId) throw new Error("Index reference does not match initialization input snapshot");
+      if (options.indexRef.status === "complete" && (typeof options.indexRef.generation !== "string" || typeof options.indexRef.snapshotHash !== "string")) throw new Error("Complete index references require generation and snapshot hash");
+      if (options.indexRef.status === "complete") {
+        if (typeof options.indexRef.contentManifestHash !== "string" || typeof options.indexRef.repositoryRevision !== "string") throw new Error("Complete index references require content manifest and repository revision");
+        const indexRoot = path.resolve(this.context.root, String(options.indexRef.stagingPath ?? options.indexRef.path ?? ".planning/code-index"));
+        const immutable = path.resolve(indexRoot, String(options.indexRef.immutablePath ?? `snapshots/${options.indexRef.generation}`));
+        const snapshotFile = path.join(immutable, "SNAPSHOT.json");
+        if (!existsSync(snapshotFile)) throw new Error("Complete index reference does not point to an immutable generation");
+        const actual = hash(readFileSync(snapshotFile));
+        if (actual !== options.indexRef.snapshotHash) throw new Error("Code index snapshot hash does not match index reference");
+        const payload = JSON.parse(readFileSync(snapshotFile, "utf8")) as { generation?: string };
+        if (payload.generation !== options.indexRef.generation) throw new Error("Code index generation does not match SNAPSHOT.json");
+        const workspace = (payload as any).workspace ?? {};
+        if (workspace.contentManifestHash !== options.indexRef.contentManifestHash) throw new Error("Code index content manifest does not match index reference");
+        if (workspace.repositoryRevision !== options.indexRef.repositoryRevision) throw new Error("Code index repository revision does not match index reference");
+      }
+    }
     const facts = this.db.query("SELECT kind,repository,object_key,value_json,evidence_level,extractor,confidence FROM facts WHERE run_id=? ORDER BY kind,repository,object_key").all(runId);
     const snapshotId = randomUUID();
     const transaction = this.db.transaction(() => {
       this.db.query("UPDATE initialization_runs SET status='validating',updated_at=? WHERE id=? AND lease_token=?").run(now(), runId, leaseToken);
-      this.db.query("INSERT INTO context_snapshots(id,project_id,workspace_id,config_id,input_snapshot_id,run_id,completeness,content_hash,index_ref_json,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(snapshotId, this.context.manifest.projectId, run.workspaceId, run.configId, run.inputSnapshotId, runId, completeness, hash(canonicalJson(facts)), options.indexRef ? canonicalJson(options.indexRef) : null, now());
+      const persistedIndexRef = options.indexRef ? Object.fromEntries(Object.entries(options.indexRef).filter(([key]) => key !== "stagingPath")) : null;
+      this.db.query("INSERT INTO context_snapshots(id,project_id,workspace_id,config_id,input_snapshot_id,run_id,completeness,content_hash,index_ref_json,created_at) VALUES (?,?,?,?,?,?,?,?,?,?)").run(snapshotId, this.context.manifest.projectId, run.workspaceId, run.configId, run.inputSnapshotId, runId, completeness, hash(canonicalJson(facts)), persistedIndexRef ? canonicalJson(persistedIndexRef) : null, now());
       if (options.updateCurrent === false) {
         // Shadow imports are immutable and queryable without becoming current.
       } else if (current) {
@@ -484,6 +548,11 @@ export class InitializationStore {
     return this.queryContext({ workspaceId, configId: current.configId, ...input });
   }
 
+  currentRevision(workspaceId: string, configId: string): number {
+    const row = this.db.query("SELECT revision FROM current_context WHERE workspace_id=? AND config_id=?").get(workspaceId, configId) as { revision: number } | null;
+    return row?.revision ?? 0;
+  }
+
   getInitializationConfiguration(workspaceId: string): Record<string, unknown> {
     const row = this.db.query(`SELECT c.id,c.revision,c.content_hash AS contentHash,c.config_json AS config
       FROM scan_configs c LEFT JOIN current_context p ON p.config_id=c.id AND p.workspace_id=?
@@ -498,11 +567,14 @@ export class InitializationStore {
 
   compareSnapshots(fromSnapshotId: string, toSnapshotId: string): Record<string, unknown> {
     if (fromSnapshotId === toSnapshotId) return { comparable: true, fromSnapshotId, toSnapshotId, added: [], changed: [], disappeared: [] };
-    const snapshots = this.db.query("SELECT id,config_id AS configId FROM context_snapshots WHERE id IN (?,?)").all(fromSnapshotId, toSnapshotId) as Array<{ id: string; configId: string }>;
+    const snapshots = this.db.query("SELECT id,project_id AS projectId,workspace_id AS workspaceId,config_id AS configId,input_snapshot_id AS inputSnapshotId FROM context_snapshots WHERE id IN (?,?)").all(fromSnapshotId, toSnapshotId) as Array<{ id: string; projectId: string; workspaceId: string; configId: string; inputSnapshotId: string }>;
     if (snapshots.length !== 2) throw new Error("Both context snapshots must exist");
     const fromMeta = snapshots.find(item => item.id === fromSnapshotId)!;
     const toMeta = snapshots.find(item => item.id === toSnapshotId)!;
+    if (fromMeta.projectId !== toMeta.projectId || fromMeta.workspaceId !== toMeta.workspaceId) return { comparable: false, reason: "workspace_changed", added: [], changed: [], disappeared: [] };
     if (fromMeta.configId !== toMeta.configId) return { comparable: false, reason: "scan_config_changed", added: [], changed: [], disappeared: [] };
+    const manifests = this.db.query("SELECT id,manifest_json AS manifest FROM input_snapshots WHERE id IN (?,?)").all(fromMeta.inputSnapshotId, toMeta.inputSnapshotId) as Array<{ id: string; manifest: string }>;
+    if (manifests.length !== 2) return { comparable: false, reason: "input_snapshot_missing", added: [], changed: [], disappeared: [] };
     const rows = (snapshotId: string) => this.db.query(`SELECT f.kind,f.repository,f.object_key AS objectKey,f.value_json AS value
       FROM facts f JOIN context_snapshots s ON s.run_id=f.run_id WHERE s.id=?`).all(snapshotId) as Array<{ kind: string; repository: string; objectKey: string; value: string }>;
     const key = (row: { kind: string; repository: string; objectKey: string }) => `${row.kind}\0${row.repository}\0${row.objectKey}`;
@@ -539,7 +611,8 @@ export class InitializationStore {
     const job = this.db.query("SELECT target_path AS targetPath,ownership,status FROM document_jobs WHERE id=?").get(jobId) as { targetPath: string; ownership: string; status: string } | null;
     if (!job) throw new Error(`Unknown document job: ${jobId}`);
     if (job.ownership === "human") throw new Error("Human-owned documents cannot be generated");
-    this.db.query("UPDATE document_jobs SET status='generating',error=NULL,updated_at=? WHERE id=? AND status IN ('queued','failed','pending_review')").run(now(), jobId);
+    const claimed = this.db.query("UPDATE document_jobs SET status='generating',error=NULL,updated_at=? WHERE id=? AND status IN ('queued','failed','pending_review')").run(now(), jobId);
+    if (claimed.changes !== 1) throw new Error(`Document job is no longer writable: ${jobId}`);
     const target = path.resolve(this.context.root, job.targetPath);
     if (target !== this.context.root && !target.startsWith(`${this.context.root}${path.sep}`)) throw new Error("Document path escapes project root");
     let existing: string | null = null;
@@ -559,7 +632,8 @@ export class InitializationStore {
     }
     await mkdir(path.dirname(target), { recursive: true });
     const temporary = `${target}.${randomUUID()}.tmp`; await writeFile(temporary, output, { encoding: "utf8", flag: "wx" }); await rename(temporary, target);
-    this.db.query("UPDATE document_jobs SET status='complete',output_hash=?,updated_at=? WHERE id=?").run(hash(output), now(), jobId);
+    const completed = this.db.query("UPDATE document_jobs SET status='complete',output_hash=?,updated_at=? WHERE id=? AND status='generating'").run(hash(output), now(), jobId);
+    if (completed.changes !== 1) throw new Error(`Document job completion conflict: ${jobId}`);
     return { status: "complete", path: target };
   }
 

package/src/project-context.ts

@@ -136,15 +136,17 @@ export async function loadProjectContext(root: string): Promise<ProjectContext>
   const manifestPath = path.join(canonicalRoot, ".devflow", "project.json");
   const manifest = validateManifest(JSON.parse(await readFile(manifestPath, "utf8")), manifestPath);
   const planningRoot = await assertPlanningBoundary(canonicalRoot);
+  if (!(await exists(projectControlDatabasePath(manifest.projectId)))) throw new Error("Project initialization database is not registered; run explicit project initialization first");
   return attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot });
 }
 
 async function attachInitializationStore(context: Omit<ProjectContext, "workspaceId" | "controlDatabasePath">): Promise<ProjectContext> {
   const store = await InitializationStore.open(context);
   try {
-    const workspace = await store.registerWorkspace();
-    store.putScanConfig({ mode: "full", repositories: [{ name: context.manifest.name, relativePath: ".", role: "other" }] });
-    return { ...context, workspaceId: workspace.id, controlDatabasePath: projectControlDatabasePath(context.manifest.projectId) };
+    const location = await realpath(context.root);
+    const workspace = store.listWorkspaces().find(item => item.location === location);
+    if (!workspace) throw new Error("Project workspace is not registered; run explicit project initialization first");
+    return { ...context, workspaceId: String(workspace.id), controlDatabasePath: projectControlDatabasePath(context.manifest.projectId) };
   } finally {
     store.close();
   }
@@ -174,6 +176,8 @@ export async function initializeProject(root: string): Promise<{ context: Projec
     createdAt: new Date().toISOString(),
   };
   await atomicWriteJson(manifestPath, manifest);
+  const bootstrapStore = await InitializationStore.open({ root: canonicalRoot, manifest });
+  try { await bootstrapStore.registerWorkspace(); } finally { bootstrapStore.close(); }
   return {
     context: await attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot }),
     created: true,

package/src/project-documents.ts

@@ -77,6 +77,10 @@ function table(headers: string[], rows: unknown[][]): string {
 }
 function yamlString(value: string): string { return JSON.stringify(value); }
 function frontmatter(fields: Record<string, string | boolean | string[] | null | undefined>): string {
+  if (fields.source_snapshot && !fields.snapshot_id) fields.snapshot_id = fields.source_snapshot;
+  if (fields.source_snapshot) fields.generated = true;
+  if (fields.source_snapshot && !fields.generated_at) fields.generated_at = new Date().toISOString();
+  if (fields.source_snapshot && !fields.source_revision) fields.source_revision = fields.code_index_generation ?? "unknown";
   const lines = ["---"];
   for (const [key, value] of Object.entries(fields)) {
     if (value === undefined || value === null) continue;

package/src/project-initializer.ts

@@ -1,5 +1,5 @@
-import { createHash } from "node:crypto";
-import { readFile, readdir, stat } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, readdir, stat, rename, rm } from "node:fs/promises";
 import path from "node:path";
 
 import { FACT_KINDS, InitializationStore, type FactInput, type FactKind, type ScanConfigInput } from "./initialization-store.ts";
@@ -177,7 +177,7 @@ async function runProcess(argv: string[], cwd: string): Promise<{ stdout: string
 
 async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput): Promise<Record<string, unknown>> {
   const script = path.resolve(import.meta.dir, "../plugins/devflow-intel/skills/workflow-code-index/scripts/code_index.py");
-  const output = ".planning/code-index";
+  const output = `.planning/.code-index-pending-${randomUUID()}`;
   const codebases = config.repositories.flatMap(repository => ["--codebase", `${repository.name}:${path.resolve(context.root, repository.relativePath)}:${repository.role}`]);
   await runProcess(["python3", script, "scan", "--root", context.root, "--output", output, ...codebases], context.root);
   await runProcess(["python3", script, "validate", "--index", output], context.root);
@@ -185,7 +185,29 @@ async function buildCodeIndex(context: ProjectContext, config: ScanConfigInput):
   const snapshotPath = path.join(context.root, output, "SNAPSHOT.json");
   const bytes = await readFile(snapshotPath); const snapshot = JSON.parse(bytes.toString("utf8")) as Record<string, unknown>;
   if (!snapshot.generation || !snapshot.immutablePath) throw new Error("Code index did not publish an immutable generation");
-  return { path: output, generation: snapshot.generation, immutablePath: snapshot.immutablePath, snapshotHash: digest(bytes), status: "complete" };
+  const workspace = (snapshot.workspace ?? {}) as Record<string, unknown>;
+  return { path: ".planning/code-index", stagingPath: output, generation: snapshot.generation, immutablePath: snapshot.immutablePath, snapshotHash: digest(bytes), contentManifestHash: workspace.contentManifestHash, repositoryRevision: workspace.repositoryRevision, status: "complete" };
+}
+
+async function promoteCodeIndex(context: ProjectContext, indexRef: Record<string, unknown>): Promise<() => Promise<void>> {
+  const stagingPath = typeof indexRef.stagingPath === "string" ? path.resolve(context.root, indexRef.stagingPath) : null;
+  const target = path.resolve(context.root, ".planning/code-index");
+  if (!stagingPath) return async () => {};
+  const previous = `${target}.previous-${randomUUID()}`;
+  const existing = await stat(target).catch(() => null);
+  if (existing) await rename(target, previous);
+  try {
+    await rename(stagingPath, target);
+    delete indexRef.stagingPath;
+    return async () => {
+      await rm(target, { recursive: true, force: true });
+      if (existing) await rename(previous, target);
+    };
+  } catch (error) {
+    await rm(target, { recursive: true, force: true }).catch(() => {});
+    if (existing) await rename(previous, target).catch(() => {});
+    throw error;
+  }
 }
 
 export async function runProjectInitialization(context: ProjectContext, input: { config?: ScanConfigInput; requestId?: string; documentMode?: "low-tier-model" | "template" | "none"; organizer?: import("./project-documents.ts").LowTierDocumentOrganizer; switchAuthority?: boolean } = {}): Promise<InitializationProgress> {
@@ -236,13 +258,22 @@ export async function runProjectInitialization(context: ProjectContext, input: {
         facts: status === "complete" ? repositoryFacts : [],
       });
     }
-    const indexRef = config.mode === "full" ? await buildCodeIndex(context, config) : { status: "skipped", reason: "explicit_fast_mode" };
+    const indexRef = config.mode === "full"
+      ? { ...(await buildCodeIndex(context, config)), inputFingerprint: inputSnapshot.fingerprint, workspaceId: workspace.id, configId: storedConfig.id }
+      : { status: "skipped", reason: "explicit_fast_mode", inputFingerprint: inputSnapshot.fingerprint, workspaceId: workspace.id, configId: storedConfig.id };
     const after = await scan(context, config);
     const afterManifest = frozenManifest(after);
     const verified = store.createInputSnapshot(workspace.id, storedConfig.id, afterManifest, false);
     if (verified.fingerprint !== inputSnapshot.fingerprint) throw new Error("Source changed during initialization; refusing to publish mixed input");
     store.confirmInputSnapshot(inputSnapshot.id, inputSnapshot.fingerprint);
-    const published = store.publishRun(run.id, run.leaseToken, { expectedRevision: undefined, indexRef });
+    const rollbackIndex = await promoteCodeIndex(context, indexRef);
+    let published: { snapshotId: string; revision: number };
+    try {
+      published = store.publishRun(run.id, run.leaseToken, { expectedRevision: store.currentRevision(workspace.id, storedConfig.id), indexRef });
+    } catch (error) {
+      await rollbackIndex();
+      throw error;
+    }
     if (input.switchAuthority !== false) {
       const authority = store.getAuthority();
       if (authority.authority === "legacy") store.switchAuthority("database", authority.revision);

package/src/project-migration.ts

@@ -22,7 +22,8 @@ export async function importLegacyInitialization(context: ProjectContext, source
   try {
     const workspace = await store.registerWorkspace();
     const config = store.putScanConfig({ mode: "fast", repositories: [{ name: "legacy-materials", relativePath: ".", role: "other" }], requiredKinds: ["evidence"], adapterVersions: { "legacy-import": "1" } });
-    const input = store.createInputSnapshot(workspace.id, config.id, documents.map(item => ({ repository: "legacy-materials", path: item.relative, contentHash: item.contentHash, size: item.size })), true);
+    const input = store.createInputSnapshot(workspace.id, config.id, documents.map(item => ({ repository: "legacy-materials", path: item.relative, contentHash: item.contentHash, size: item.size })), false);
+    store.confirmInputSnapshot(input.id, input.fingerprint);
     const run = store.startRun({ workspaceId: workspace.id, configId: config.id, inputSnapshotId: input.id, requestId });
     if (!run.reused) store.recordCollection(run.id, run.leaseToken, {
       kind: "evidence", status: "complete", adapter: "legacy-import@1",
@@ -30,7 +31,7 @@ export async function importLegacyInitialization(context: ProjectContext, source
     });
     const snapshot = run.reused && store.getRun(run.id)?.publishedSnapshotId
       ? { snapshotId: String(store.getRun(run.id)!.publishedSnapshotId) }
-      : store.publishRun(run.id, run.leaseToken, { completeness: "partial", updateCurrent: false });
+      : store.publishRun(run.id, run.leaseToken, { expectedRevision: 0, completeness: "partial", updateCurrent: false });
     const imports = documents.map(item => store.registerHistoricalImport(workspace.id, item.relative, item.contentHash, snapshot.snapshotId));
     const authority = store.getAuthority();
     if (authority.authority === "legacy") store.switchAuthority("shadow", authority.revision);