wikifier 4.6.3__tar.gz → 4.6.4__tar.gz

{wikifier-4.6.3/wikifier.egg-info → wikifier-4.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.3
+Version: 4.6.4
 Summary: Zero-dependency agent-to-agent codebase wiki for LLMs and AI agents. Autonomously maintained via record-change and mark-green for token-efficient lookup of files, dependencies, health, and summaries — across tiny scripts to 50k+ monorepos. Optional MCP server with rich tools for agents.
 Author-email: Aron Amos <aron@example.com>
 Maintainer: Aron Amos
@@ -109,8 +109,9 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba
 
 - **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Warm agent maps (4.6.3+)** — zero-dirty fast path skips full graph/`library.md` rewrite when nothing reparsed; content-hash dirty so mtime thrash ≠ reparse; `--directory=` scopes the candidate walk (monorepo budgets)
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal` (`skip`|`investigate`); prefer `actionable_low_conf_edges` over raw low-conf noise
+- **Warm agent maps (4.6.3+ / 4.6.4+)** — zero-dirty fast path skips full graph/`library.md` rewrite; **stdlib SQLite** import cache (dual-read legacy JSON) so warm dirty scans use mtime/hash index not multi‑MB pair JSON; content-hash dirty; `--directory=` scopes walks
+- **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap (`complete`, `files_remaining_dirty`, `acs_version`, `cache_backend`); budgeted runs are not “done”
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
 - **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top

{wikifier-4.6.3 → wikifier-4.6.4}/README.md

@@ -77,8 +77,9 @@ Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, ba
 
 - **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Warm agent maps (4.6.3+)** — zero-dirty fast path skips full graph/`library.md` rewrite when nothing reparsed; content-hash dirty so mtime thrash ≠ reparse; `--directory=` scopes the candidate walk (monorepo budgets)
-- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal` (`skip`|`investigate`); prefer `actionable_low_conf_edges` over raw low-conf noise
+- **Warm agent maps (4.6.3+ / 4.6.4+)** — zero-dirty fast path skips full graph/`library.md` rewrite; **stdlib SQLite** import cache (dual-read legacy JSON) so warm dirty scans use mtime/hash index not multi‑MB pair JSON; content-hash dirty; `--directory=` scopes walks
+- **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap (`complete`, `files_remaining_dirty`, `acs_version`, `cache_backend`); budgeted runs are not “done”
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
 - **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top

{wikifier-4.6.3 → wikifier-4.6.4}/skills/run.md

@@ -11,7 +11,8 @@
 - File Tree + `wikifier serve`; MCP status/attention use library + emoji (not `[GREEN]` tags).
 - **First-run:** `init` → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
 - **Map-first ≠ wiki-done:** `health_score` **Map Ready** + many 🟡 *Initial stubs* means structural coverage only. Do **not** bulk-wiki stubs. Wiki a file when you edit it, then `mark-green`. Prefer `actionable_yellow` / 🔴 over raw yellow counts.
-- **Steady-state selective work:** only 🔴 and *actionable* 🟡 (never re-wiki 🟢; never re-wiki the whole stub set). ACS uses `actionable_low_conf_edges`.
+- **Steady-state selective work:** only 🔴 and *actionable* 🟡 (never re-wiki 🟢; never re-wiki the whole stub set). **ACS v1.3:** use `actionable_low_conf_edges` + `reason_code_counts` / `agent_signal` (`skip`|`investigate`). Do **not** thrash on raw `low_conf_edges` (includes external/bare scores ~0.48). Prefer `map_coverage.complete` / `files_remaining_dirty` after budgeted `update-maps` — `success: true` ≠ map complete.
+- **Warm maps:** import cache prefers stdlib SQLite (`.wikifier_staging/import_cache.sqlite`); zero-dirty path uses mtime index + meta, not full pair payload.
 - **Dual scope:** `monitored_paths` = check-changes/health scope (keep lean). `update-maps --directory=` / `--max-files=` = map walk. Never set `project_root` to a multi-repo parent (e.g. `cloned_sample_projects`).
 - **CLI target:** `wikifier --target /abs/project health --summary` (flags stripped before the command). Or `WIKIFIER_PROJECT_ROOT=…`.
 - **Long-horizon:** `wikifier autonomous-status` (or `readiness`) before unattended runs; daemon writes `.wikifier_staging/daemon_heartbeat.json`. Soak ≥72h is still evidence work, not automatic.

wikifier-4.6.4/tests/test_cache_store.py

@@ -0,0 +1,193 @@
+"""SQLite cache store + map_coverage + warm path (shipped APIs, zero-dep)."""
+
+from __future__ import annotations
+
+import os
+import time
+import unittest
+from pathlib import Path
+
+from tests._base import TempProjectTestCase
+
+from wikifier import cli
+from wikifier import import_cache as ic
+from wikifier import cache_store as cs
+
+
+class TestSqliteCacheRoundTrip(TempProjectTestCase):
+    def test_save_load_sqlite_primary(self):
+        self.write("a.py", "import os\n")
+        r = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r.get("success"), r)
+        self.assertTrue(cs.has_sqlite(self.root), "sqlite should exist after save")
+        cache = ic.load_cache(self.root)
+        self.assertIn("a.py", cache)
+        self.assertIsInstance(cache["a.py"].get("mtime"), int)
+        # light index works without requiring pairs field presence
+        idx = ic.load_mtime_index(self.root)
+        self.assertIn("a.py", idx)
+        self.assertEqual(idx["a.py"]["mtime"], cache["a.py"]["mtime"])
+
+    def test_legacy_json_dual_read_then_migrate(self):
+        # Plant legacy JSON only (no sqlite)
+        staging = self.root / ".wikifier_staging"
+        staging.mkdir(parents=True, exist_ok=True)
+        import json
+        legacy = {
+            "x.py": {
+                "mtime": 1,
+                "content_hash": "sha256:abc",
+                "imports": ["os"],
+                "resolved": [],
+                "resolved_pairs": [{"raw": "os", "resolved": "", "confidence_score": 0.48}],
+            },
+            "_acs_summary": {
+                "acs_version": "1.2",
+                "total_scored_edges": 1,
+                "actionable_low_conf_edges": 0,
+                "low_conf_edges": 1,
+            },
+        }
+        (staging / "import_cache.json").write_text(
+            json.dumps(legacy), encoding="utf-8"
+        )
+        loaded = ic.load_cache(self.root)
+        self.assertIn("x.py", loaded)
+        # update_maps migrates
+        self.write("x.py", "import os\n")
+        r = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r.get("success"), r)
+        self.assertTrue(cs.has_sqlite(self.root))
+
+
+class TestWarmPathNoFullJsonTax(TempProjectTestCase):
+    def test_zero_dirty_reports_sqlite_backend_and_coverage(self):
+        self.write("m.py", "print(1)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        self.assertIn(r2.get("cache_backend"), ("sqlite", "sqlite+json", "json"))
+        cov = r2.get("map_coverage") or {}
+        self.assertTrue(cov.get("complete"), cov)
+        self.assertIn("files_remaining_dirty", cov)
+        self.assertEqual(int(cov["files_remaining_dirty"]), 0)
+
+    def test_zero_dirty_skips_full_payload_load_cache_dict(self):
+        """Shipped warm path must not deserialize full file payloads on 0-dirty.
+
+        Criterion: after SQLite is warm, zero-dirty update_maps must not call
+        cache_store.load_cache_dict (full pairs) or ic.load_cache (legacy full).
+        Light index + meta only.
+        """
+        self.write("warm.py", "print(0)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        self.assertTrue(cs.has_sqlite(self.root))
+        # Second run seeds zero-dirty + sqlite
+        r_seed = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r_seed.get("zero_dirty_fast_path"), r_seed)
+
+        full_loads = {"load_cache_dict": 0, "load_cache": 0}
+        real_lcd = cs.load_cache_dict
+        real_lc = ic.load_cache
+
+        def counting_lcd(root):
+            full_loads["load_cache_dict"] += 1
+            return real_lcd(root)
+
+        def counting_lc(root):
+            full_loads["load_cache"] += 1
+            return real_lc(root)
+
+        # Patch at the modules the shipped path imports from
+        import wikifier.cache_store as cs_mod
+        import wikifier.import_cache as ic_mod
+        orig_cs = cs_mod.load_cache_dict
+        orig_ic = ic_mod.load_cache
+        cs_mod.load_cache_dict = counting_lcd  # type: ignore
+        ic_mod.load_cache = counting_lc  # type: ignore
+        try:
+            r2 = cli.update_maps(project_root=self.root, full=False)
+        finally:
+            cs_mod.load_cache_dict = orig_cs  # type: ignore
+            ic_mod.load_cache = orig_ic  # type: ignore
+
+        self.assertTrue(r2.get("success"), r2)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        self.assertEqual(
+            full_loads["load_cache_dict"],
+            0,
+            f"warm 0-dirty must not call load_cache_dict; counts={full_loads}",
+        )
+        self.assertEqual(
+            full_loads["load_cache"],
+            0,
+            f"warm 0-dirty must not call load_cache; counts={full_loads}",
+        )
+
+    def test_max_files_coverage_incomplete(self):
+        for i in range(6):
+            self.write(f"f{i}.py", f"v={i}\n")
+        r = cli.update_maps(project_root=self.root, full=True, max_files=2)
+        self.assertTrue(r.get("success"), r)
+        cov = r.get("map_coverage") or {}
+        self.assertFalse(cov.get("complete"), cov)
+        self.assertEqual(int(cov.get("files_skipped") or 0), 4)
+        self.assertGreaterEqual(int(cov.get("files_remaining_dirty") or 0), 4)
+        self.assertIn("agent_note", cov)
+
+    def test_mtime_index_skips_content_stable(self):
+        p = self.write("s.py", "x=1\n")
+        cli.update_maps(project_root=self.root, full=True)
+        cache = ic.load_cache(self.root)
+        ent = cache["s.py"]
+        ent["mtime"] = 1
+        ic.save_cache(self.root, cache)
+        time.sleep(0.05)
+        os.utime(p, None)
+        updates = []
+        need = ic.compute_files_needing_reparse(
+            self.root, [p], content_stable_mtime_updates=updates
+        )
+        # content_hash should make this stable once hash stored
+        if ent.get("content_hash"):
+            self.assertEqual(need, [])
+            self.assertGreaterEqual(len(updates), 1)
+
+
+class TestBootstrapCoverageAndAcsGuidance(TempProjectTestCase):
+    def test_bootstrap_surfaces_acs_guidance(self):
+        self.write("h.py", "import os\n")
+        cli.update_maps(project_root=self.root, full=True)
+        boot = cli.session_bootstrap(project_root=self.root)
+        self.assertTrue(boot.get("success"), boot)
+        self.assertIn("acs_guidance", boot)
+        self.assertIn("actionable_low_conf_edges", boot["acs_guidance"])
+        acs = boot.get("acs") or {}
+        self.assertIn("acs_version", acs)
+
+
+class TestGoModResolve(TempProjectTestCase):
+    def test_same_module_import_resolves(self):
+        from wikifier.parsers import go_lang as go
+
+        self.write(
+            "go.mod",
+            "module example.com/demo\n\ngo 1.21\n",
+        )
+        self.write("pkg/util/util.go", "package util\nfunc X() {}\n")
+        main = self.write(
+            "cmd/main.go",
+            'package main\nimport "example.com/demo/pkg/util"\n',
+        )
+        edges = go.parse_go_imports(str(main))
+        self.assertTrue(edges)
+        resolved = [e for e in edges if e.get("resolved_path")]
+        self.assertTrue(resolved, msg=f"edges={edges}")
+        self.assertIn("util", resolved[0]["resolved_path"])
+
+
+if __name__ == "__main__":
+    unittest.main()

{wikifier-4.6.3 → wikifier-4.6.4}/wikifier/__init__.py

@@ -78,4 +78,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.6.3"
+__version__ = "4.6.4"

{wikifier-4.6.3 → wikifier-4.6.4}/wikifier/agent_loop.py

@@ -548,8 +548,33 @@ def session_bootstrap(
     acs_actionable = 0
     try:
         from . import import_cache as ic
-        cache = ic.load_cache(root) or {}
-        acs = ic.ensure_acs_summary_persisted(cache, root) or {}
+        try:
+            from . import cache_store as cs
+        except Exception:
+            cs = None  # type: ignore
+        # Prefer light meta read (SQLite) over full multi-MB pair deserialize
+        acs: Dict[str, Any] = {}
+        cyc: Dict[str, Any] = {}
+        if cs is not None:
+            meta = cs.load_meta(root, keys=("_acs_summary", "_cycles", "_map_coverage"))
+            acs = meta.get("_acs_summary") if isinstance(meta.get("_acs_summary"), dict) else {}
+            cyc = meta.get("_cycles") if isinstance(meta.get("_cycles"), dict) else {}
+            cov = meta.get("_map_coverage") if isinstance(meta.get("_map_coverage"), dict) else {}
+            if cov:
+                out["map_coverage"] = cov
+            out["cache_backend"] = cs.backend_name(root)
+        needs_full = (
+            not acs
+            or str(acs.get("acs_version") or "") < "1.3"
+            or "reason_code_counts" not in acs
+            or "actionable_low_conf_edges" not in acs
+        )
+        if needs_full:
+            cache = ic.load_cache(root) or {}
+            acs = ic.ensure_acs_summary_persisted(cache, root) or {}
+            cyc = cache.get("_cycles") or {}
+            if cs is not None and not out.get("cache_backend"):
+                out["cache_backend"] = cs.backend_name(root)
         acs_actionable = int(acs.get("actionable_low_conf_edges") or 0)
         out["acs"] = {
             "acs_version": acs.get("acs_version"),
@@ -557,12 +582,22 @@ def session_bootstrap(
             "low_conf_edges": acs.get("low_conf_edges"),
             "dynamic_literal_noise_edges": acs.get("dynamic_literal_noise_edges"),
             "avg_confidence": acs.get("avg_confidence"),
+            "reason_code_counts": acs.get("reason_code_counts"),
+            "agent_signal_counts": acs.get("agent_signal_counts"),
         }
-        cyc = cache.get("_cycles") or {}
+        # Agents must not thrash on raw low_conf_edges (ACS v1.3 scores more edges)
+        out["acs_guidance"] = (
+            "Prefer actionable_low_conf_edges + reason_code_counts "
+            "(skip external_or_bare/dynamic_literal); do not use low_conf_edges alone as a work queue."
+        )
         out["cycles"] = {
             "cyclic_scc_count": (cyc.get("stats") or {}).get("cyclic_scc_count"),
             "all_cycle_files_sample": (cyc.get("all_cycle_files") or [])[:10],
         }
+        if "map_coverage" not in out and cs is not None:
+            snap = cs.get_map_coverage_from_meta(root)
+            if snap.get("map_coverage"):
+                out["map_coverage"] = snap["map_coverage"]
     except Exception as e:
         out["acs_error"] = str(e)
 

wikifier-4.6.4/wikifier/cache_store.py

@@ -0,0 +1,348 @@
+"""Stdlib SQLite import-cache store (agent warm-path; zero new deps).
+
+AGENT MAP:
+  load_cache_dict / save_cache_dict  — full cache dict (file entries + _meta keys)
+  load_mtime_index                   — light {rel: mtime, content_hash} for dirty
+  load_meta / save_meta_key          — reserved _keys without loading pairs
+  update_file_index_rows             — mtime/hash refresh without full rewrite
+  backend_name / has_sqlite
+
+Dual-read: if ``import_cache.sqlite`` missing but legacy ``import_cache.json``
+exists, load JSON and migrate on next save. Warm dirty detection should use
+``load_mtime_index`` so agents avoid deserializing multi‑MB pair payloads.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Tuple
+
+STAGING = ".wikifier_staging"
+SQLITE_NAME = "import_cache.sqlite"
+JSON_NAME = "import_cache.json"
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS files (
+  rel_path TEXT PRIMARY KEY NOT NULL,
+  mtime INTEGER NOT NULL DEFAULT 0,
+  content_hash TEXT,
+  payload TEXT NOT NULL DEFAULT '{}'
+);
+CREATE TABLE IF NOT EXISTS meta (
+  key TEXT PRIMARY KEY NOT NULL,
+  value TEXT NOT NULL
+);
+"""
+
+
+def sqlite_path(root: Path) -> Path:
+    return Path(root) / STAGING / SQLITE_NAME
+
+
+def json_path(root: Path) -> Path:
+    return Path(root) / STAGING / JSON_NAME
+
+
+def has_sqlite(root: Path) -> bool:
+    try:
+        return sqlite_path(root).is_file() and sqlite_path(root).stat().st_size > 0
+    except Exception:
+        return False
+
+
+def backend_name(root: Path) -> str:
+    if has_sqlite(root):
+        return "sqlite"
+    if json_path(root).is_file():
+        return "json"
+    return "none"
+
+
+def _connect(root: Path) -> sqlite3.Connection:
+    path = sqlite_path(root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    conn = sqlite3.connect(str(path), timeout=60.0)
+    try:
+        conn.execute("PRAGMA journal_mode=WAL")
+        conn.execute("PRAGMA synchronous=NORMAL")
+        conn.executescript(_SCHEMA)
+    except Exception:
+        conn.close()
+        raise
+    return conn
+
+
+@contextmanager
+def _db(root: Path) -> Iterator[sqlite3.Connection]:
+    conn = _connect(root)
+    try:
+        yield conn
+        conn.commit()
+    finally:
+        conn.close()
+
+
+def load_mtime_index(root: Path) -> Dict[str, Dict[str, Any]]:
+    """Light index for dirty detection: rel → {mtime, content_hash}.
+
+    Prefers SQLite. Falls back to scanning legacy JSON (expensive once).
+    """
+    root = Path(root)
+    if has_sqlite(root):
+        out: Dict[str, Dict[str, Any]] = {}
+        try:
+            with _db(root) as conn:
+                for rel, mtime, chash in conn.execute(
+                    "SELECT rel_path, mtime, content_hash FROM files"
+                ):
+                    out[str(rel)] = {
+                        "mtime": int(mtime or 0),
+                        "content_hash": chash,
+                    }
+            return out
+        except Exception:
+            pass
+    # Legacy JSON fallback
+    jp = json_path(root)
+    if not jp.is_file():
+        return {}
+    try:
+        with open(jp, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception:
+        return {}
+    out = {}
+    if not isinstance(data, dict):
+        return out
+    for k, v in data.items():
+        if not isinstance(k, str) or k.startswith("_") or not isinstance(v, dict):
+            continue
+        out[k] = {
+            "mtime": int(v.get("mtime", 0) or 0),
+            "content_hash": v.get("content_hash"),
+        }
+    return out
+
+
+def load_meta(root: Path, keys: Optional[Iterable[str]] = None) -> Dict[str, Any]:
+    """Load reserved meta keys (``_acs_summary``, ``_cycles``, …) without file payloads."""
+    root = Path(root)
+    want = set(keys) if keys is not None else None
+    if has_sqlite(root):
+        try:
+            with _db(root) as conn:
+                rows = conn.execute("SELECT key, value FROM meta").fetchall()
+            out: Dict[str, Any] = {}
+            for k, raw in rows:
+                if want is not None and k not in want:
+                    continue
+                try:
+                    out[str(k)] = json.loads(raw)
+                except Exception:
+                    out[str(k)] = raw
+            return out
+        except Exception:
+            pass
+    # JSON fallback — still full parse (legacy only)
+    jp = json_path(root)
+    if not jp.is_file():
+        return {}
+    try:
+        with open(jp, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except Exception:
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    out = {}
+    for k, v in data.items():
+        if not isinstance(k, str) or not k.startswith("_"):
+            continue
+        if want is not None and k not in want:
+            continue
+        out[k] = v
+    return out
+
+
+def load_cache_dict(root: Path) -> Dict[str, Any]:
+    """Full cache dict: file entries + reserved keys (same shape as historical JSON)."""
+    root = Path(root)
+    if has_sqlite(root):
+        try:
+            cache: Dict[str, Any] = {}
+            with _db(root) as conn:
+                for rel, mtime, chash, payload in conn.execute(
+                    "SELECT rel_path, mtime, content_hash, payload FROM files"
+                ):
+                    try:
+                        ent = json.loads(payload) if payload else {}
+                    except Exception:
+                        ent = {}
+                    if not isinstance(ent, dict):
+                        ent = {}
+                    ent["mtime"] = int(mtime or 0)
+                    if chash:
+                        ent["content_hash"] = chash
+                    cache[str(rel)] = ent
+                for k, raw in conn.execute("SELECT key, value FROM meta"):
+                    try:
+                        cache[str(k)] = json.loads(raw)
+                    except Exception:
+                        cache[str(k)] = raw
+            return cache
+        except Exception:
+            pass
+    jp = json_path(root)
+    if not jp.is_file():
+        return {}
+    try:
+        with open(jp, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def save_cache_dict(root: Path, cache: Dict[str, Any], write_json: Optional[bool] = None) -> str:
+    """Persist cache to SQLite (primary). Optionally dual-write compact JSON.
+
+    ``write_json``: None → dual-write if env WIKIFIER_CACHE_JSON=1 or file count ≤ 400
+    (keeps small projects greppable; avoids rewriting 20MB+ JSON on large monorepos).
+
+    Returns backend name written: ``sqlite`` or ``sqlite+json``.
+    """
+    root = Path(root)
+    if not isinstance(cache, dict):
+        return "none"
+    # Barrel preservation: merge missing barrel keys from existing store
+    _BARREL = ("_barrel_resolutions", "_barrel_file_index")
+    if any(k not in cache for k in _BARREL):
+        try:
+            prev = load_cache_dict(root)
+            for k in _BARREL:
+                if k not in cache and prev.get(k):
+                    cache[k] = prev[k]
+        except Exception:
+            pass
+
+    file_n = sum(
+        1
+        for k, v in cache.items()
+        if isinstance(k, str) and not k.startswith("_") and isinstance(v, dict)
+    )
+    if write_json is None:
+        env = os.environ.get("WIKIFIER_CACHE_JSON", "").strip().lower()
+        if env in ("1", "true", "yes", "always"):
+            write_json = True
+        elif env in ("0", "false", "no", "never"):
+            write_json = False
+        else:
+            write_json = file_n <= 400
+
+    with _db(root) as conn:
+        conn.execute("DELETE FROM files")
+        conn.execute("DELETE FROM meta")
+        for k, v in cache.items():
+            if not isinstance(k, str):
+                continue
+            if k.startswith("_"):
+                try:
+                    raw = json.dumps(v, ensure_ascii=False, separators=(",", ":"))
+                except Exception:
+                    raw = json.dumps(str(v))
+                conn.execute(
+                    "INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)",
+                    (k, raw),
+                )
+            elif isinstance(v, dict):
+                mtime = int(v.get("mtime", 0) or 0)
+                chash = v.get("content_hash")
+                try:
+                    payload = json.dumps(v, ensure_ascii=False, separators=(",", ":"))
+                except Exception:
+                    payload = "{}"
+                conn.execute(
+                    "INSERT OR REPLACE INTO files(rel_path, mtime, content_hash, payload) "
+                    "VALUES (?, ?, ?, ?)",
+                    (k, mtime, chash, payload),
+                )
+
+    if write_json:
+        jp = json_path(root)
+        jp.parent.mkdir(parents=True, exist_ok=True)
+        with open(jp, "w", encoding="utf-8") as f:
+            json.dump(cache, f, ensure_ascii=False, separators=(",", ":"))
+        return "sqlite+json"
+    # If dual-write disabled, leave legacy json in place for dual-read until removed;
+    # do not delete automatically (safe migration).
+    return "sqlite"
+
+
+def update_file_index_rows(
+    root: Path,
+    rows: List[Tuple[str, int, Optional[str]]],
+) -> int:
+    """Update mtime/content_hash for existing file rows without rewriting payloads.
+
+    rows: (rel_path, mtime, content_hash|None)
+    Returns number of rows updated (SQLite only; 0 if no db).
+    """
+    root = Path(root)
+    if not has_sqlite(root) or not rows:
+        return 0
+    n = 0
+    with _db(root) as conn:
+        for rel, mtime, chash in rows:
+            if chash:
+                cur = conn.execute(
+                    "UPDATE files SET mtime = ?, content_hash = ? WHERE rel_path = ?",
+                    (int(mtime), chash, rel),
+                )
+            else:
+                cur = conn.execute(
+                    "UPDATE files SET mtime = ? WHERE rel_path = ?",
+                    (int(mtime), rel),
+                )
+            n += int(cur.rowcount or 0)
+    return n
+
+
+def save_meta_key(root: Path, key: str, value: Any) -> bool:
+    """Write a single meta key to SQLite (warm ACS upgrade without full rewrite)."""
+    root = Path(root)
+    if not key.startswith("_"):
+        return False
+    try:
+        raw = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    except Exception:
+        return False
+    if not has_sqlite(root):
+        # Fall back: load full, set, save
+        cache = load_cache_dict(root)
+        cache[key] = value
+        save_cache_dict(root, cache)
+        return True
+    with _db(root) as conn:
+        conn.execute(
+            "INSERT OR REPLACE INTO meta(key, value) VALUES (?, ?)",
+            (key, raw),
+        )
+    return True
+
+
+def get_map_coverage_from_meta(root: Path) -> Dict[str, Any]:
+    """Read last map_coverage snapshot from meta if present."""
+    meta = load_meta(root, keys=("_map_coverage", "_acs_summary"))
+    cov = meta.get("_map_coverage") if isinstance(meta.get("_map_coverage"), dict) else {}
+    acs = meta.get("_acs_summary") if isinstance(meta.get("_acs_summary"), dict) else {}
+    return {
+        "map_coverage": cov,
+        "acs_version": acs.get("acs_version"),
+        "cache_backend": backend_name(root),
+        "actionable_low_conf_edges": acs.get("actionable_low_conf_edges"),
+        "reason_code_counts": acs.get("reason_code_counts"),
+    }