codmap 0.0.5__tar.gz → 0.0.7__tar.gz

{codmap-0.0.5 → codmap-0.0.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.5
+Version: 0.0.7
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **734 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.5 → codmap-0.0.7}/README.md

@@ -8,7 +8,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **734 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.5 → codmap-0.0.7}/codemap/extract/griffe_extractor.py

@@ -54,6 +54,30 @@ class _Walk:
     aliased: list = field(default_factory=list)   # (skipped_id, owner_id)
 
 
+def _assert_is_the_target(loaded, pkg_dir: Path, module_name: str) -> None:
+    """Raise unless what griffe loaded is the directory we were handed (R1-C36).
+
+    Separate from its caller so the decision can be tested on shapes that a single
+    ``search_paths`` entry cannot produce end to end. A **namespace package reports a
+    list** of directories rather than one path — the shape that once crashed the
+    extractor (issue #4) — and a package assembled from several parts is a legitimate
+    hit as long as the requested directory is one of them.
+
+    An empty ``loaded`` is not treated as a mismatch: "griffe told us nothing about the
+    file" is not "griffe told us the wrong file", and inventing a failure from silence
+    is the same error in the other direction.
+    """
+    candidates = loaded if isinstance(loaded, (list, tuple)) else ([loaded] if loaded else [])
+    dirs = {(q if q.is_dir() else q.parent).resolve() for q in map(Path, candidates)}
+    if dirs and pkg_dir not in dirs:
+        raise ValueError(
+            f"resolved `{module_name}` to {', '.join(sorted(str(d) for d in dirs))} but was "
+            f"asked for {pkg_dir}. A same-named package is shadowing the target (an "
+            "installed copy, or one in the current directory). Build from a different "
+            "working directory, or rename the target."
+        )
+
+
 def build_structural(package_path: str | Path):
     """The cheap, deterministic base: griffe load + definition nodes + structural
     edges (contains / imports / inherits / decorated_by / export). No behavioral
@@ -78,18 +102,7 @@ def build_structural(package_path: str | Path):
     # a future default), a graph must describe the directory that was asked for. A wrong
     # answer here is invisible downstream — it is well-formed, complete and about the
     # wrong tree — so it fails loudly instead.
-    loaded = getattr(root, "filepath", None)
-    # A namespace package reports a *list* of directories, not one path — the very shape
-    # that once crashed the extractor (issue #4). Handle it here rather than assume.
-    candidates = loaded if isinstance(loaded, (list, tuple)) else ([loaded] if loaded else [])
-    dirs = {(q if q.is_dir() else q.parent).resolve() for q in map(Path, candidates)}
-    if dirs and pkg_dir not in dirs:
-        raise ValueError(
-            f"resolved `{module_name}` to {', '.join(sorted(str(d) for d in dirs))} but was "
-            f"asked for {pkg_dir}. A same-named package is shadowing the target (an "
-            "installed copy, or one in the current directory). Build from a different "
-            "working directory, or rename the target."
-        )
+    _assert_is_the_target(getattr(root, "filepath", None), pkg_dir, module_name)
 
     graph = Graph(target=module_name)
     walk = _Walk()

{codmap-0.0.5 → codmap-0.0.7}/codemap/provenance.py

@@ -43,12 +43,17 @@ MATCH, OLDER, NEWER, UNKNOWN = "match", "older", "newer", "unknown"
 
 # -- tool identity (D2) -------------------------------------------------------
 
-@lru_cache(maxsize=1)
-def tool_version() -> str | None:
-    """The installed distribution's version, or None when it is not installed.
+def installed_version() -> str | None:
+    """What the distribution *currently on disk* says, read on every call.
 
-    The single source: `codemap.__version__` reads it too, having drifted a release
-    behind while it was a literal.
+    R1-C38-f1. `tool_version()` below is cached for a whole process, which is right for
+    provenance — every graph a build writes must carry one version — and wrong for the
+    only question that needs the value twice: has the installation changed underneath a
+    long-running server? The cached reader answers with what was true at import, so a
+    comparison between the two is a comparison of one value with itself.
+
+    Measured before trusting it: an upgrade performed while a process runs *is* visible
+    to a fresh `importlib.metadata.version()`, with no `invalidate_caches()` needed.
     """
     from importlib.metadata import PackageNotFoundError, version
     try:
@@ -57,6 +62,19 @@ def tool_version() -> str | None:
         return None
 
 
+@lru_cache(maxsize=1)
+def tool_version() -> str | None:
+    """The installed distribution's version, or None when it is not installed.
+
+    The single source: `codemap.__version__` reads it too, having drifted a release
+    behind while it was a literal.
+
+    Cached on purpose — a build stamps one version into everything it writes. Anything
+    asking *"is this still true?"* rather than *"what was it?"* wants `installed_version()`.
+    """
+    return installed_version()
+
+
 
 @lru_cache(maxsize=8)
 def _commit_of(root: Path) -> str | None:

{codmap-0.0.5 → codmap-0.0.7}/codemap/serve/session.py

@@ -97,6 +97,38 @@ def _match(q: Query, n) -> dict:
     return e
 
 
+def tool_drift(running: str | None, installed: str | None) -> dict | None:
+    """Say when this process is running code the installed distribution has moved past.
+
+    R1-C38. A warm server holds two things that go stale independently: the graph and the
+    **code**. `reload` refreshes the graph, and nothing refreshes the code — a process
+    started before an upgrade keeps answering in the shape it was born with, over a graph
+    that carries everything the new shape needs. Measured, not imagined: a server started
+    before R1-C33 served a freshly rebuilt 0.13 graph and returned dossiers without the
+    `signature` the artifact contained, with nothing in the answer to say why.
+
+    `stats` already separates the graph's schema from the running tool's. This is the same
+    separation one level up, and it is only visible because the version is read from the
+    installed metadata at call time while the code was loaded at import — which is a
+    property of *how the caller reads it*, not of this function. Shipped once without it
+    (0.0.6): `Session._tool_drift` passed the cached `tool_version()` on both sides, so the
+    two arguments were the same value by construction and this returned `None` forever.
+    See `installed_version()` and R1-C38-f1.
+    """
+    if not running or not installed or running == installed:
+        return None
+    return {
+        "code": "tool_restart_needed",
+        "severity": "warning",
+        "running": running,
+        "installed": installed,
+        "consequence": "Answers keep the shape of the running code; `reload` refreshes the "
+                       "graph, never the code.",
+        "message": f"this server is running codemap {running} while {installed} is installed — "
+                   "restart it to serve the installed version.",
+    }
+
+
 def build_query_result(q: Query, name: str) -> dict:
     """The full symbol dossier — shared by ``codemap query`` and warm serve."""
     matches = q.find(name)
@@ -267,11 +299,25 @@ class Session:
         # edges from a layout the extractor didn't understand), rather than letting every
         # downstream conclusion silently inherit the emptiness.
         from codemap.diagnostics import diagnostics
-        diags = diagnostics(self.graph)
+        diags = list(diagnostics(self.graph))
+        # R1-C38: the graph is not the only thing that goes stale in a warm server.
+        drift = self._tool_drift()
+        if drift:
+            diags.append(drift)
         if diags:
             out["diagnostics"] = diags
         return out
 
+    @staticmethod
+    def _tool_drift() -> dict | None:
+        # The two sides must be read differently or there is nothing to compare (R1-C38-f1):
+        # `codemap.__version__` is fixed at import — that is the *running* code — while the
+        # installed distribution is re-read here, on every call. Using the cached
+        # `tool_version()` on the right made this compare a value with itself.
+        import codemap
+        from codemap.provenance import installed_version
+        return tool_drift(getattr(codemap, "__version__", None), installed_version())
+
     def _op_reload(self, args) -> dict:
         """Reload the on-disk artifact into the served graph, without a restart (#3).
 
@@ -297,10 +343,16 @@ class Session:
         self.query = Query(graph)
         self._served_mtime = self._current_mtime()
         after = {"nodes": len(graph.nodes), "edges": len(graph.edges)}
-        return {"reloaded": True, "before": before, "after": after,
-                "changed": before != after,
-                "freshness": freshness(self.graph_path,
-                                       served_mtime=self._served_mtime)}
+        out = {"reloaded": True, "before": before, "after": after,
+               "changed": before != after,
+               "freshness": freshness(self.graph_path,
+                                      served_mtime=self._served_mtime)}
+        # R1-C38: this is the op whose name promises freshness, so it is the op that owes
+        # the caller the half it cannot deliver — the code, which only a restart replaces.
+        drift = self._tool_drift()
+        if drift:
+            out["diagnostics"] = [drift]
+        return out
 
     def _op_query(self, args) -> dict:
         return build_query_result(self.query, args["name"])

{codmap-0.0.5 → codmap-0.0.7}/codmap.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.5
+Version: 0.0.7
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -44,7 +44,7 @@ and a **SCIP index** for interop with Sourcegraph / Glean and other precise-code
 
 [![CI](https://github.com/kogriv/codemap/actions/workflows/ci.yml/badge.svg)](https://github.com/kogriv/codemap/actions/workflows/ci.yml)
 
-**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **734 tests with no failures on
 Python 3.11–3.14** ([in CI](docs/ci.md): the full suite including the dogfood pass, a determinism check, a
 wheel smoke test, and ctags/SCIP interop against the real CLIs), warm serve surface with 31 ops (28 exposed
 as MCP tools), and SCIP export. See **[DESIGN.md](DESIGN.md)** (product design &

{codmap-0.0.5 → codmap-0.0.7}/codmap.egg-info/SOURCES.txt

@@ -104,6 +104,8 @@ tests/test_r1c33_query_signature.py
 tests/test_r1c34_signature_kinds.py
 tests/test_r1c35_contract_location.py
 tests/test_r1c36_target_resolution.py
+tests/test_r1c37_rule_mutation.py
+tests/test_r1c38_tool_drift.py
 tests/test_r1c3_arch_contract.py
 tests/test_r1c3_dogfood.py
 tests/test_r1c4_complexity.py

{codmap-0.0.5 → codmap-0.0.7}/pyproject.toml

@@ -9,7 +9,7 @@ build-backend = "setuptools.build_meta"
 # version. README says this plainly, since `pip install codmap` / `import codemap` is a
 # seam a reader will otherwise hit by surprise.
 name = "codmap"
-version = "0.0.5"
+version = "0.0.7"
 description = "Static analyzer that turns a package's source into a queryable code graph."
 readme = "README.md"
 # M20/D1: measured, not assumed. Each release of the declared range runs the full suite in

{codmap-0.0.5 → codmap-0.0.7}/tests/test_r1c36_target_resolution.py

@@ -40,6 +40,7 @@ import sys
 import pytest
 
 from codemap.extract import extract
+from codemap.extract.griffe_extractor import _assert_is_the_target
 
 TOY = {
     "__init__.py": '"""A package that merely shares a name with another one."""\n',
@@ -105,3 +106,70 @@ def test_two_copies_of_one_package_give_two_different_graphs(tmp_path):
     gb = {n.id for n in extract(str(b)).nodes.values()}
     assert "pkg.mod.only_in_a" in ga and "pkg.mod.only_in_a" not in gb
     assert "pkg.mod.only_in_b" in gb and "pkg.mod.only_in_b" not in ga
+
+
+# -- the guard on shapes a single search path cannot produce end to end -------
+#
+# A namespace package assembled from several directories is a legitimate resolution: the
+# requested one is *among* the parts. The end-to-end path cannot reach that case, because
+# a build passes exactly one `search_paths` entry, so nothing here would have caught a
+# guard that rejected it — which is why the decision is tested directly rather than
+# assumed from the single-directory case that does run.
+
+def test_the_guard_accepts_a_namespace_package_the_target_is_part_of(tmp_path):
+    a, b = tmp_path / "part_a" / "ns", tmp_path / "part_b" / "ns"
+    a.mkdir(parents=True)
+    b.mkdir(parents=True)
+    _assert_is_the_target([a, b], a.resolve(), "ns")   # must not raise
+    _assert_is_the_target([b, a], a.resolve(), "ns")   # order is not significance
+
+
+def test_the_guard_rejects_a_namespace_package_the_target_is_not_part_of(tmp_path):
+    a, b, asked = tmp_path / "a" / "ns", tmp_path / "b" / "ns", tmp_path / "c" / "ns"
+    for d in (a, b, asked):
+        d.mkdir(parents=True)
+    with pytest.raises(ValueError) as e:
+        _assert_is_the_target([a, b], asked.resolve(), "ns")
+    assert str(asked) in str(e.value) and str(a) in str(e.value), "name both sides"
+
+
+def test_a_single_file_path_is_compared_by_its_directory(tmp_path):
+    pkg = tmp_path / "pkg"
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text("")
+    _assert_is_the_target(pkg / "__init__.py", pkg.resolve(), "pkg")
+
+
+def test_silence_is_not_a_mismatch(tmp_path):
+    """griffe saying nothing about the file is not griffe naming the wrong one. Inventing
+    a failure from an absent answer is the same error pointing the other way."""
+    _assert_is_the_target(None, (tmp_path / "pkg").resolve(), "pkg")
+    _assert_is_the_target([], (tmp_path / "pkg").resolve(), "pkg")
+
+
+def test_a_namespace_layout_does_not_merge_the_two_trees(tmp_path):
+    """The flat-layout case, and it fails worse than the package one.
+
+    Measured against the released 0.0.4 after the fix was already in: with a same-named
+    directory in the working directory, the graph came back as the **union** of both
+    trees — `core.registry` and `core.user` from the target *and* `core.impostor` from the
+    shadow. Namespace packages are additive, so griffe merged the parts it found instead
+    of one winning, and the result described a code base that exists nowhere.
+
+    Harder to notice than the package case, too: node counts go *up*, not sideways, and
+    every symbol in the graph is a real symbol from some real file.
+    """
+    target, shadow = tmp_path / "elsewhere" / "core", tmp_path / "workdir" / "core"
+    target.mkdir(parents=True)
+    shadow.mkdir(parents=True)
+    (target / "registry.py").write_text("def own():\n    return 1\n")
+    (target / "user.py").write_text("import registry\n\n\ndef go():\n    return registry.own()\n")
+    (shadow / "impostor.py").write_text("def impostor():\n    return 0\n")
+
+    out = tmp_path / "g.json"
+    r = subprocess.run([sys.executable, "-m", "codemap.cli", "build", str(target), "-o", str(out)],
+                       cwd=str(shadow.parent), capture_output=True, text=True)
+    assert r.returncode == 0, r.stderr
+    ids = {n["id"] for n in json.loads(out.read_text())["nodes"]}
+    assert {"core.registry.own", "core.user.go"} <= ids
+    assert not any("impostor" in i for i in ids), "the two trees were merged into one graph"

codmap-0.0.7/tests/test_r1c37_rule_mutation.py

@@ -0,0 +1,178 @@
+"""R1-C37 — every contract rule, fed the thing it must react to, on a real tree.
+
+The method is the lab's, not ours. Sent a `no_lazy_cycles` gate that answered green on
+their repository, they did not believe the green: they put **one** lazy import back and
+watched the gate go red. That is the only evidence a gate is doing anything, and after
+running it on our two trees the obvious question was which of the six rules had ever been
+given the same treatment.
+
+Answer: as end-to-end paths, none. Each rule does have a violation test
+(`test_r1c3_arch_contract.py`), and each is built on a hand-assembled three-node `Graph`
+whose layers are spelled into the node ids and whose `root` is set by hand. That proves
+the rule's arithmetic. It cannot show that a rule finds a real violation in a real graph,
+because nothing between source and rule participates: no extraction, no layer inference
+from a package tree, no re-exports, no lazy edges, no thousands of legitimate imports for
+the offending one to hide among. The dogfood test (`test_r1c3_dogfood.py`) runs the real
+tree — and asserts green, which is the shape of evidence the lab correctly refused.
+
+So: one copy of codemap's own package, and for each rule, green → change exactly one line
+→ red naming the edge that was added → restore → the file is byte-identical again. The
+contract in each case holds **only the rule under test**, so nothing else can fire and be
+mistaken for it. Mutation 1 also creates a cycle, for instance; under a layers-only
+contract that cannot be confused with a layering violation.
+
+Cost is about 20 s: seven extractions of a 90-file package. That is the price of testing
+the path that runs in production instead of the arithmetic underneath it.
+"""
+
+from __future__ import annotations
+
+import shutil
+
+import pytest
+
+from codemap.arch import check_contract, parse_contract
+from codemap.extract import extract
+from codemap.query import Query
+
+# Every top-level component of codemap that exists today. `exhaustive` is about a *new*
+# one appearing, so the baseline has to name all of them or it is red before we start.
+# A topological order of codemap's *real* cross-layer imports, not the shipped contract's
+# ten-layer view: `codemap.toml` names the layers a reader should think in, and leaves the
+# six leaf modules undeclared (harmless — an undeclared layer is inert unless `exhaustive`).
+# Here every component must be named, or the baseline is red before a mutation is applied
+# and the mutation proves nothing. The baseline assertion in each test guards this list:
+# if it goes stale, the failure says so rather than passing quietly.
+REAL_LAYERS = ["cli", "incremental", "extract", "serve", "apidiff", "arch", "diagnostics",
+               "freshness", "integrations", "provenance", "query", "store", "model",
+               "tomlio", "watch", "scope"]
+
+SRC = __import__("pathlib").Path(__file__).resolve().parent.parent / "codemap"
+
+
+@pytest.fixture(scope="module")
+def tree(tmp_path_factory):
+    """One copy of the real package. Mutations are applied and reverted in place."""
+    dst = tmp_path_factory.mktemp("mutation") / "codemap"
+    shutil.copytree(SRC, dst)
+    return dst
+
+
+@pytest.fixture(scope="module")
+def baseline(tree):
+    """The unmutated graph — every `green →` half of the six checks below."""
+    return Query(extract(str(tree)))
+
+
+def _check(q, rules: dict):
+    return check_contract(q, parse_contract(rules))
+
+
+def _mutate(tree, rel: str, line: str) -> tuple[str, str]:
+    """Append one import line to a real module. Returns (path, original text)."""
+    path = tree / rel
+    original = path.read_text()
+    path.write_text(original + f"\n\n{line}\n")
+    return str(path), original
+
+
+def _restore(path: str, original: str) -> None:
+    __import__("pathlib").Path(path).write_text(original)
+
+
+def _run(tree, rel, line, rules):
+    """green → mutate → measure → restore → byte-identical. Returns the violations."""
+    path, original = _mutate(tree, rel, line)
+    try:
+        return check_contract(Query(extract(str(tree))), parse_contract(rules))
+    finally:
+        _restore(path, original)
+        assert (tree / rel).read_text() == original
+
+
+# -- one rule per mutation, each with a contract holding only that rule ------
+
+def test_layers_catches_an_import_up_the_stack(tree, baseline):
+    rules = {"layers": REAL_LAYERS}
+    assert _check(baseline, rules) == [], "baseline must be green or the mutation proves nothing"
+    v = _run(tree, "model.py", "from codemap.cli import main  # noqa: F401", rules)
+    assert [x.rule for x in v] == ["layered"]
+    assert ("codemap.model", "codemap.cli") in v[0].edges
+
+
+def test_independent_catches_a_new_edge_between_two_declared_peers(tree, baseline):
+    rules = {"independent": [["extract", "serve"]]}
+    assert _check(baseline, rules) == [], "extract and serve are independent today"
+    v = _run(tree, "extract/roots.py",
+             "from codemap.serve.check import render_check  # noqa: F401", rules)
+    assert [x.rule for x in v] == ["independent"]
+    assert ("codemap.extract.roots", "codemap.serve.check") in v[0].edges
+
+
+def test_forbidden_catches_the_banned_direction_only(tree, baseline):
+    rules = {"forbidden": [{"from": "model", "to": "query"}]}
+    assert _check(baseline, rules) == []
+    v = _run(tree, "model.py", "from codemap.query import Query  # noqa: F401", rules)
+    assert [x.rule for x in v] == ["forbidden"]
+    assert ("codemap.model", "codemap.query") in v[0].edges
+    # The same edge under the opposite ban is not a violation.
+    assert _check(baseline, {"forbidden": [{"from": "query", "to": "model"}]})
+
+
+def test_no_cycles_catches_a_cycle_the_import_actually_closes(tree, baseline):
+    rules = {"no_cycles": True}
+    assert _check(baseline, rules) == [], "codemap's eager import graph is acyclic today"
+    v = _run(tree, "model.py", "from codemap.store import save  # noqa: F401", rules)
+    assert [x.rule for x in v] == ["no_cycles"]
+    # `modules` on a cycle violation holds *rendered paths*, not ids — "a → b → a".
+    assert any("codemap.model" in c and "codemap.store" in c for c in v[0].modules), v[0].modules
+
+
+def test_no_lazy_cycles_catches_a_cycle_only_a_function_local_import_closes(tree, baseline):
+    rules = {"no_lazy_cycles": True}
+    assert _check(baseline, rules) == []
+    line = ("def _mutation_probe():\n"
+            "    from codemap.serve.vault import build_vault\n"
+            "    return build_vault")
+    v = _run(tree, "query.py", line, rules)
+    assert [x.rule for x in v] == ["no_lazy_cycles"]
+    assert any("codemap.query" in c and "codemap.serve.vault" in c for c in v[0].modules), v[0].modules
+
+
+def test_no_cycles_stays_silent_on_the_lazy_one(tree):
+    """The pair that makes the two rules different rules, on the real tree."""
+    line = ("def _mutation_probe():\n"
+            "    from codemap.serve.vault import build_vault\n"
+            "    return build_vault")
+    path, original = _mutate(tree, "query.py", line)
+    try:
+        q = Query(extract(str(tree)))
+        assert check_contract(q, parse_contract({"no_cycles": True})) == []
+        assert check_contract(q, parse_contract({"no_lazy_cycles": True}))
+    finally:
+        _restore(path, original)
+
+
+def test_exhaustive_catches_a_new_undeclared_component(tree, baseline):
+    rules = {"layers": REAL_LAYERS, "exhaustive": True}
+    assert _check(baseline, rules) == [], "REAL_LAYERS is stale — a component was added"
+    newpkg = tree / "newlayer"
+    newpkg.mkdir()
+    (newpkg / "__init__.py").write_text('"""A component nobody declared."""\n')
+    try:
+        v = check_contract(Query(extract(str(tree))), parse_contract(rules))
+        assert [x.rule for x in v] == ["exhaustive"]
+        assert "newlayer" in v[0].modules
+    finally:
+        shutil.rmtree(newpkg)
+
+
+def test_the_tree_is_unchanged_after_every_mutation(tree, baseline):
+    """The other half of a mutation test, once: the red went away with the change that
+    caused it, so the reds above were the mutations and not the harness."""
+    after = Query(extract(str(tree)))
+    assert set(after.graph.nodes) == set(baseline.graph.nodes)
+    rules = {"layers": REAL_LAYERS, "no_cycles": True, "no_lazy_cycles": True,
+             "exhaustive": True, "independent": [["extract", "serve"]],
+             "forbidden": [{"from": "model", "to": "query"}]}
+    assert check_contract(after, parse_contract(rules)) == []

codmap-0.0.7/tests/test_r1c38_tool_drift.py

@@ -0,0 +1,124 @@
+"""R1-C38 — a warm server holds a graph *and* code, and only one of them reloads.
+
+Measured, not imagined. While closing an unrelated debt — "the MCP path for the new
+fields was exercised through `Session.handle`, not through a live agent" — the live check
+was run: the bquant graph was rebuilt with 0.0.5 and `reload` picked it up, 4656 → 4743
+nodes, the schema-mismatch diagnostic gone. The dossier came back **without `signature`**,
+which the rebuilt artifact plainly contained.
+
+Nothing was broken. The server process had been started before R1-C33 landed, so it was
+running the old `build_query_result` over a new graph, and no part of the answer said so.
+`reload` refreshes the artifact; nothing refreshes the code.
+
+`stats` already separates the graph's schema from the running tool's (R1-C25). This is the
+same separation one level up, and it is only observable because the version comes from the
+installed metadata, read at call time, while the code was loaded at import: when those two
+disagree, a restart is pending. `reload` carries the diagnostic too — the op whose name
+promises freshness owes the caller the half it cannot deliver.
+"""
+
+from __future__ import annotations
+
+from codemap.serve.session import tool_drift
+
+
+def test_agreement_is_silent():
+    assert tool_drift("0.0.5", "0.0.5") is None
+
+
+def test_a_process_older_than_what_is_installed_says_restart():
+    d = tool_drift("0.0.4", "0.0.5")
+    assert d["code"] == "tool_restart_needed" and d["severity"] == "warning"
+    assert d["running"] == "0.0.4" and d["installed"] == "0.0.5"
+    assert "restart" in d["message"]
+
+
+def test_it_names_reload_as_the_thing_that_will_not_help():
+    """The whole point: the user's next move would otherwise be `reload`, again."""
+    assert "reload" in tool_drift("0.0.4", "0.0.5")["consequence"]
+
+
+def test_the_other_direction_is_reported_too():
+    """A process newer than the installed distribution is equally a mismatch — saying
+    nothing about it would be guessing which direction is the interesting one."""
+    d = tool_drift("0.0.6", "0.0.5")
+    assert d is not None and d["running"] == "0.0.6" and d["installed"] == "0.0.5"
+
+
+def test_an_unknown_version_is_not_a_drift():
+    """Not installed, or a version we could not read, is silence — not a warning invented
+    out of an absent answer."""
+    assert tool_drift(None, "0.0.5") is None
+    assert tool_drift("0.0.5", None) is None
+    assert tool_drift(None, None) is None
+
+
+def _shadow_installed_version(tmp_path, monkeypatch, version: str) -> None:
+    """Make the *installed* distribution look like `version`, the way an upgrade would.
+
+    A `dist-info` directory earlier on `sys.path` wins, so this changes what
+    `importlib.metadata` answers without touching the imported module — exactly the
+    asymmetry a real upgrade under a running server creates.
+    """
+    d = tmp_path / "site"
+    (d / f"codmap-{version}.dist-info").mkdir(parents=True)
+    (d / f"codmap-{version}.dist-info" / "METADATA").write_text(
+        f"Metadata-Version: 2.1\nName: codmap\nVersion: {version}\n")
+    monkeypatch.syspath_prepend(str(d))
+
+
+def test_the_installed_side_is_read_fresh_or_there_is_nothing_to_compare(tmp_path, monkeypatch):
+    """R1-C38-f1 — the defect 0.0.6 shipped, and the reason no test caught it.
+
+    Every other test here hands `tool_drift` two versions, or forces a difference by
+    patching `codemap.__version__`. Both prove the arithmetic. Neither asks the question
+    the feature exists for: *can the condition arise?* It could not — `_tool_drift` read
+    the installed side through `tool_version()`, which is `lru_cache`d and first called at
+    import by `codemap/__init__.py`, so both sides were the same cached value forever.
+
+    Here nothing about the process is patched. Only the installation changes, as an
+    upgrade changes it, and the running server must notice.
+    """
+    from codemap.serve.session import Session
+
+    assert Session._tool_drift() is None            # agreement before the "upgrade"
+    _shadow_installed_version(tmp_path, monkeypatch, "9.9.9")
+
+    d = Session._tool_drift()
+    assert d is not None, "the installed version is being read from a process-lifetime cache"
+    assert d["code"] == "tool_restart_needed" and d["installed"] == "9.9.9"
+
+
+def test_the_build_side_stays_cached(tmp_path, monkeypatch):
+    """The fix must not turn provenance into a per-call filesystem read: a build stamps
+    one version into everything it writes, so `tool_version()` keeps its cache. The two
+    readers exist because they answer different questions — "what was it?" and "is it
+    still?" — and this is the assertion that keeps them apart."""
+    from codemap.provenance import installed_version, tool_version
+
+    before = tool_version()
+    _shadow_installed_version(tmp_path, monkeypatch, "9.9.9")
+    assert tool_version() == before
+    assert installed_version() == "9.9.9"
+
+
+def test_stats_and_reload_carry_it_when_it_applies(tmp_path, monkeypatch):
+    import codemap
+    from codemap.extract import extract
+    from codemap.serve.session import Session
+    from codemap.store import save
+
+    pkg = tmp_path / "pkg"
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text("")
+    (pkg / "m.py").write_text("def f():\n    return 1\n")
+    out = tmp_path / "g.json"
+    graph = extract(str(pkg))
+    save(graph, str(out))
+
+    s = Session(graph, graph_path=str(out))
+    monkeypatch.setattr(codemap, "__version__", "0.0.0-old", raising=False)
+    codes = {d["code"] for d in s.handle({"op": "stats", "args": {}})["result"].get("diagnostics", [])}
+    assert "tool_restart_needed" in codes
+    reload_out = s.handle({"op": "reload", "args": {}})["result"]
+    assert any(d["code"] == "tool_restart_needed" for d in reload_out.get("diagnostics", []))