codmap 0.0.6__tar.gz → 0.0.8__tar.gz

{codmap-0.0.6 → codmap-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.6
+Version: 0.0.8
 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, **732 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **743 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.6 → codmap-0.0.8}/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, **732 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **743 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.6 → codmap-0.0.8}/codemap/cli.py

@@ -104,7 +104,7 @@ def _cmd_build(args) -> int:
         # roots come from extract_repo in this same call; never inherited from a graph
         # loaded off disk, which is how a stale scope would sneak into a fresh build.
         roots=graph.provenance.get("roots") if (args.consumer or args.docs) else None,
-        inputs=graph.provenance.get("inputs"))
+        inputs=_inputs_with_membership(graph, scope, args))
     # R1-C21: a well-formed but vacuous graph must announce itself — silence is what
     # lets an unparsed layout read as a clean bill of health downstream.
     for d in diagnostics(graph):
@@ -132,6 +132,27 @@ def _cmd_build(args) -> int:
     return 0
 
 
+def _inputs_with_membership(graph, scope, args):
+    """The extractor's ``inputs`` block plus the manifest membership result (R1-C41).
+
+    Computed here because it is the one place that holds both sides: the graph and the
+    scope manifest that claims to describe its input. The *result* travels in the graph
+    (beside ``skipped``, which carries the same kind of fact) because build-time stderr
+    never reaches whoever reads the artifact an hour later, possibly without the sidecar.
+
+    Omitted entirely when no manifest resolved — that is "could not compare", and writing
+    a zero there would turn an unknown into a clean bill of health.
+    """
+    inputs = dict(graph.provenance.get("inputs") or {})
+    if not scope:
+        return inputs or None
+    from codemap.scope import unlisted_files
+    base = roots_base(args.path, tuple(args.consumer or ()), tuple(args.docs or ()))
+    inputs["unlisted"] = unlisted_files(
+        (n.file for n in graph.nodes.values() if n.file), scope, base=base)
+    return inputs
+
+
 def _resolve_scope_quietly(args):
     """The input scope manifest, or None. Never fatal — a build must not fail on it."""
     from codemap.scope import resolve_scope

{codmap-0.0.6 → codmap-0.0.8}/codemap/diagnostics.py

@@ -21,6 +21,7 @@ NO_CROSS_ROOT_EDGES = "no_cross_root_edges"
 SCHEMA_MISMATCH = "schema_mismatch"
 UNREAD_INPUTS = "unread_inputs"
 MODULE_COUNT_MISMATCH = "module_count_mismatch"
+SCOPE_MEMBERSHIP = "scope_membership"
 
 #: A ``warning`` invalidates the conclusions a surface draws from the graph — read them as
 #: unknown. A ``note`` states a fact about how the graph was built and invalidates nothing.
@@ -189,6 +190,42 @@ def unread_inputs_diagnostic(graph) -> dict | None:
     }
 
 
+def scope_membership_diagnostic(graph) -> dict | None:
+    """Flag files the graph was built from that the input manifest never listed (R1-C41).
+
+    Sibling of the conservation law above, and it catches what that one provably cannot:
+    the count compares the *extractor's* walk against the graph, so when both agree and
+    only the **manifest** disagrees — an untracked or gitignored module, a file leaked in
+    from outside the target — it stays silent, correctly. Reported by the second real
+    target (issue #15), who found a sidecar listing 47 files with a hash on each beside a
+    graph built from 48.
+
+    Derived from ``provenance.inputs.unlisted``, which the build records because the
+    comparison needs the scope manifest and a consumer may hold only the graph. Absent
+    field means the build could not compare (no manifest resolved) — that is *unknown*,
+    not zero, so it is not reported as a clean result.
+    """
+    unlisted = ((graph.provenance or {}).get("inputs") or {}).get("unlisted") or {}
+    count = unlisted.get("count") or 0
+    if not count:
+        return None
+    sample = ", ".join(unlisted.get("sample") or [])
+    where = (" (at least one lies outside the scope root entirely)"
+             if unlisted.get("outside_root") else "")
+    return {
+        "code": SCOPE_MEMBERSHIP,
+        "severity": WARNING,
+        "unlisted": count,
+        "consequence": ("The manifest and `scope_id` describe a different input than this "
+                        "graph was built from, so read the input identity as **unknown** — "
+                        "and with it `--incremental` and `watch`, which key off that value."),
+        "message": (
+            f"{count} file(s) in this graph are not listed in the input manifest{where}: "
+            f"{sample}" + (" …" if count > len(unlisted.get("sample") or []) else "")
+        ),
+    }
+
+
 def module_count_diagnostic(graph) -> dict | None:
     """Conservation law over the build: modules cannot outnumber the files that define
     them, nor silently fall short of them (R1-C23 / design D6).
@@ -236,7 +273,8 @@ def diagnostics(graph) -> list[dict]:
     """Every diagnostic that applies to ``graph`` (empty list when it looks sound)."""
     checks = (import_graph_diagnostic(graph), namespace_target_diagnostic(graph),
               cross_root_diagnostic(graph), schema_diagnostic(graph),
-              unread_inputs_diagnostic(graph), module_count_diagnostic(graph))
+              unread_inputs_diagnostic(graph), module_count_diagnostic(graph),
+              scope_membership_diagnostic(graph))
     return [d for d in checks if d is not None]
 
 

{codmap-0.0.6 → codmap-0.0.8}/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.6 → codmap-0.0.8}/codemap/scope.py

@@ -90,8 +90,17 @@ def _pick_root(core: Path, consumers, docs) -> tuple[Path, str]:
     return base, "fs"
 
 
-def _enumerate_git(root: Path, roots: list[tuple[str, str]]) -> tuple[list[str], dict]:
-    """git ls-files over the scope pathspecs → (rel paths, {path: git_blob})."""
+def _enumerate_git(root: Path, roots: list[tuple[str, str]]) -> tuple[list[str], dict, set[str]]:
+    """git ls-files over the scope pathspecs → (rel paths, {path: git_blob}, untracked).
+
+    Two calls, because "the input" is not "the commit" (R1-C41). The tracked set is what
+    ``git ls-files`` knows; ``--others --exclude-standard`` adds exactly what ``git add .``
+    would stage — a module that exists and has not been added yet is read by the extractor
+    like any other, so leaving it out made the manifest describe a different input than the
+    graph was built from, without moving ``scope_id``. Ignored files stay out on purpose:
+    if ``.gitignore`` says a file is not part of the tree, the manifest does not get to
+    decide otherwise — the membership check names them instead (design §1.7 D2).
+    """
     specs = [rp for rp, _ in roots if rp]
     out = _git(root, "ls-files", "-s", "--", *specs) or ""
     paths, blobs = [], {}
@@ -104,7 +113,9 @@ def _enumerate_git(root: Path, roots: list[tuple[str, str]]) -> tuple[list[str],
         if len(cols) >= 2:
             blobs[path] = cols[1]
         paths.append(path)
-    return paths, blobs
+    others = _git(root, "ls-files", "--others", "--exclude-standard", "--", *specs) or ""
+    untracked = {p for p in others.splitlines() if p}
+    return paths + sorted(untracked), blobs, untracked
 
 
 def _enumerate_fs(root: Path, roots, include, exclude_dirs) -> list[str]:
@@ -138,10 +149,10 @@ def resolve_scope(
     roots = _roots_spec(root, core, consumers, docs)
 
     if mode == "git":
-        rels, blobs = _enumerate_git(root, roots)
+        rels, blobs, untracked = _enumerate_git(root, roots)
         rels = [r for r in rels if _match_include(Path(r).name, include)]
     else:
-        rels, blobs = _enumerate_fs(root, roots, include, exclude_dirs), {}
+        rels, blobs, untracked = _enumerate_fs(root, roots, include, exclude_dirs), {}, set()
 
     files = []
     for rel in sorted(set(rels)):
@@ -155,6 +166,11 @@ def resolve_scope(
                "loc": data.count(b"\n") + (1 if data and not data.endswith(b"\n") else 0)}
         if rel in blobs:
             rec["git_blob"] = blobs[rel]
+        if mode == "git":
+            # Always stated, never inferred from a missing key — absence is ambiguous
+            # (R1-C28's rule, applied to the manifest). fs mode omits it: there is no
+            # index to be tracked in, so the question does not arise.
+            rec["tracked"] = rel not in untracked
         files.append(rec)
 
     scope_id = "sha256:" + hashlib.sha256(
@@ -201,6 +217,51 @@ def _git_block(root: Path, roots: list[tuple[str, str]], mode: str) -> dict:
             "dirty": bool(dirty_files), "dirty_files": dirty_files}
 
 
+def unlisted_files(node_files, scope: dict, *, base: str | Path | None = None,
+                   sample: int = 5) -> dict:
+    """Files the graph was built from that the manifest does not list (R1-C41).
+
+    The manifest is the artifact a consumer reads to answer *"what exactly was
+    analyzed"*, and until this check existed it could answer wrong in silence: the
+    graph carried a module whose file the sidecar never mentioned, and ``scope_id`` —
+    the same value ``--incremental`` and ``watch`` key off — did not move.
+
+    **The two sides do not share an origin**, which is the whole difficulty. Node paths
+    are relative to the graph's own base (R1-C31: the parent of the package, or the
+    common ancestor of the roots), manifest paths are relative to the scope root (the
+    git top-level). On a ``src/`` layout those differ by a segment, and a naive string
+    comparison called both files of a healthy build unlisted — measured, 2 of 2. So the
+    node path is joined onto ``base`` and re-expressed against the scope root before it
+    is looked up; lexically, never through ``resolve()``, so a symlinked checkout does
+    not silently rewrite the answer.
+
+    Returns ``{count, sample, outside_root}`` — always, including ``count: 0``, because
+    a missing field is not the same statement as "nothing was unlisted". Paths outside
+    the scope root are reduced to a bare name: they are absolute (the D5 symptom of a
+    file the build should never have read), and the provenance block this ends up in
+    refuses absolute paths by contract.
+    """
+    root = Path(scope.get("root") or ".")
+    listed = {f["path"] for f in scope.get("files") or ()}
+    unlisted: set[str] = set()
+    outside = False
+    for raw in node_files:
+        if not raw:
+            continue
+        p = Path(raw)
+        absolute = p if p.is_absolute() else Path(os.path.normpath(Path(base or root) / p))
+        try:
+            rel = absolute.relative_to(root).as_posix()
+        except ValueError:
+            outside = True
+            unlisted.add(p.name)
+            continue
+        if rel not in listed:
+            unlisted.add(rel)
+    return {"count": len(unlisted), "sample": sorted(unlisted)[:sample],
+            "outside_root": outside}
+
+
 def diff_scopes(a: dict, b: dict) -> dict:
     """Added / removed / changed files between two scope manifests (by path+sha256)."""
     am = {f["path"]: f["sha256"] for f in a.get("files", [])}

{codmap-0.0.6 → codmap-0.0.8}/codemap/serve/session.py

@@ -109,7 +109,11 @@ def tool_drift(running: str | None, installed: str | None) -> dict | None:
 
     `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.
+    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
@@ -306,9 +310,13 @@ class Session:
 
     @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 tool_version
-        return tool_drift(getattr(codemap, "__version__", None), tool_version())
+        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).

{codmap-0.0.6 → codmap-0.0.8}/codmap.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.6
+Version: 0.0.8
 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, **732 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **743 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.6 → codmap-0.0.8}/codmap.egg-info/SOURCES.txt

@@ -108,6 +108,7 @@ 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_r1c41_scope_membership.py
 tests/test_r1c4_complexity.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py

{codmap-0.0.6 → codmap-0.0.8}/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.6"
+version = "0.0.8"
 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.6 → codmap-0.0.8}/tests/test_r1c38_tool_drift.py

@@ -53,6 +53,55 @@ def test_an_unknown_version_is_not_a_drift():
     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

codmap-0.0.8/tests/test_r1c41_scope_membership.py

@@ -0,0 +1,213 @@
+"""R1-C41 — the manifest must describe the input the graph was actually built from.
+
+Raised by the second real target (issue #15): their sidecar listed 47 files with a
+`git_blob` and a `sha256` on each while the graph carried 48, and the artifact a
+consumer reads to answer *"what exactly was analyzed"* answered wrong in silence.
+
+Measuring it made the defect wider than the report — no decoy directory is needed. In
+git mode the manifest enumerated the *tracked* set while the extractor walked the
+*filesystem*, so an untracked module (one that exists and has not been `git add`ed) or a
+gitignored one was in the graph, absent from `scope.files`, and moved `scope_id` not at
+all. Since `scope_id` is the cache key for `--incremental` and the `watch` probe, that is
+a correctness defect and not a reporting one: `--incremental` printed
+`unchanged: 0 module(s) recomputed` over a file that had just grown a new symbol.
+
+Every test here drives the real CLI over a real git repo. The point is not the arithmetic
+of a comparison — it is whether the condition can arise at all, which is the lesson 0.0.6
+paid for.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from codemap import cli
+from codemap.diagnostics import SCOPE_MEMBERSHIP, scope_membership_diagnostic
+from codemap.provenance import build_provenance
+from codemap.scope import resolve_scope, unlisted_files
+
+
+def _git(base: Path, *args: str) -> None:
+    subprocess.run(("git", "-C", str(base), *args), check=True,
+                   capture_output=True, text=True)
+
+
+@pytest.fixture
+def repo(tmp_path) -> Path:
+    """A git repo whose .gitignore excludes a *source* file the extractor still reads."""
+    if not shutil.which("git"):
+        pytest.skip("git not available")
+    (tmp_path / "pkg").mkdir()
+    (tmp_path / "pkg" / "__init__.py").write_text("")
+    (tmp_path / "pkg" / "core.py").write_text("def a():\n    return 1\n")
+    (tmp_path / ".gitignore").write_text("pkg/generated_*.py\n")
+    _git(tmp_path, "init", "-q")
+    _git(tmp_path, "config", "user.email", "t@t")
+    _git(tmp_path, "config", "user.name", "t")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-qm", "init")
+    return tmp_path
+
+
+def _build(repo: Path, out: Path, *extra: str) -> tuple[dict, dict]:
+    assert cli.main(["build", str(repo / "pkg"), "-o", str(out), *extra]) == 0
+    graph = json.loads(out.read_text(encoding="utf-8"))
+    meta = json.loads(Path(str(out) + ".meta.json").read_text(encoding="utf-8"))
+    return graph, meta
+
+
+def _files(meta: dict) -> dict[str, dict]:
+    return {f["path"]: f for f in meta["scope"]["files"]}
+
+
+# -- D1: enumerate what will be read, not what the commit remembers ------------
+
+def test_an_untracked_module_enters_the_manifest_and_moves_the_identity(repo, tmp_path):
+    before, meta_before = _build(repo, tmp_path / "a.json")
+    (repo / "pkg" / "untracked.py").write_text("def brand_new():\n    return 42\n")
+    after, meta_after = _build(repo, tmp_path / "b.json")
+
+    assert "pkg/untracked.py" not in _files(meta_before)
+    assert "pkg/untracked.py" in _files(meta_after), (
+        "a module that exists and has not been `git add`ed is read by the extractor; "
+        "leaving it out of the manifest describes a different input than the graph")
+    # …and the identity has to move, or every cache keyed on it is wrong (below).
+    assert before["provenance"]["scope_id"] != after["provenance"]["scope_id"]
+
+
+def test_incremental_recomputes_an_untracked_edit(repo, tmp_path):
+    out = tmp_path / "inc.json"
+    (repo / "pkg" / "untracked.py").write_text("def brand_new():\n    return 42\n")
+    _build(repo, out)
+    (repo / "pkg" / "untracked.py").write_text(
+        "def brand_new():\n    return 42\n\n\ndef added_later():\n    return 7\n")
+    graph, _ = _build(repo, out, "--incremental")
+    assert any(n["id"].endswith("added_later") for n in graph["nodes"]), (
+        "scope_id is the incremental cache key: if an untracked edit does not move it, "
+        "the rebuild reports `unchanged` and serves a stale graph as current")
+
+
+def test_git_mode_states_tracked_on_every_record_and_fs_mode_omits_it(repo):
+    scope = resolve_scope(repo / "pkg")
+    (repo / "pkg" / "untracked.py").write_text("x = 1\n")
+    scope2 = resolve_scope(repo / "pkg")
+    recs = {f["path"]: f for f in scope2["files"]}
+
+    # stated on every record, never inferred from a missing key (R1-C28's rule)
+    assert all("tracked" in f for f in scope["files"])
+    assert recs["pkg/core.py"]["tracked"] is True
+    assert recs["pkg/untracked.py"]["tracked"] is False
+    assert "git_blob" not in recs["pkg/untracked.py"]  # there is none to record
+    assert "git_blob" in recs["pkg/core.py"]
+
+    # fs mode has no index, so the question does not arise and nothing is claimed
+    fs = resolve_scope(repo / "pkg", use_git=False)
+    assert fs["files"] and all("tracked" not in f for f in fs["files"])
+
+
+# -- D2: membership named, not adopted ----------------------------------------
+
+def test_a_gitignored_module_is_named_and_not_quietly_adopted(repo, tmp_path, capsys):
+    (repo / "pkg" / "generated_version.py").write_text('def v():\n    return "1.2.3"\n')
+    graph, meta = _build(repo, tmp_path / "g.json")
+
+    # the repo says this file is not part of the tree; the manifest does not overrule it
+    assert "pkg/generated_version.py" not in _files(meta)
+    # …and the graph says so out loud instead of leaving a hole
+    unlisted = graph["provenance"]["inputs"]["unlisted"]
+    assert unlisted["count"] == 1
+    assert unlisted["sample"] == ["pkg/generated_version.py"]
+    assert "not listed in the input manifest" in capsys.readouterr().err
+
+
+def test_the_count_check_stays_silent_on_exactly_this_state(repo, tmp_path):
+    """The conservation law cannot catch it, which is why this check exists."""
+    (repo / "pkg" / "generated_version.py").write_text('def v():\n    return "1.2.3"\n')
+    graph, _ = _build(repo, tmp_path / "g.json")
+    from codemap.diagnostics import module_count_diagnostic
+    from codemap.store import load
+
+    g = load(str(tmp_path / "g.json"))
+    modules = sum(1 for n in g.nodes.values() if n.kind == "module")
+    assert modules == graph["provenance"]["inputs"]["python_files"] == 3
+    assert module_count_diagnostic(g) is None       # right to be silent: it agrees
+    assert scope_membership_diagnostic(g)["code"] == SCOPE_MEMBERSHIP
+
+
+# -- the trap: the two sides do not share an origin ----------------------------
+
+def test_a_src_layout_is_not_a_violation(tmp_path):
+    """Node paths are root-relative to the graph's base, manifest paths to the repo.
+
+    On `src/pkg` those differ by a segment, and comparing the strings as they stand
+    called both files of a healthy build unlisted — 2 of 2, measured before the fix.
+    """
+    if not shutil.which("git"):
+        pytest.skip("git not available")
+    (tmp_path / "src" / "pkg").mkdir(parents=True)
+    (tmp_path / "src" / "pkg" / "__init__.py").write_text("")
+    (tmp_path / "src" / "pkg" / "core.py").write_text("def a():\n    return 1\n")
+    (tmp_path / "tests").mkdir()
+    (tmp_path / "tests" / "test_core.py").write_text("from pkg.core import a\n")
+    _git(tmp_path, "init", "-q")
+    _git(tmp_path, "config", "user.email", "t@t")
+    _git(tmp_path, "config", "user.name", "t")
+    _git(tmp_path, "add", "-A")
+    _git(tmp_path, "commit", "-qm", "init")
+
+    out = tmp_path / "s.json"
+    assert cli.main(["build", str(tmp_path / "src" / "pkg"), "-o", str(out)]) == 0
+    core_only = json.loads(out.read_text(encoding="utf-8"))
+    assert cli.main(["build", str(tmp_path / "src" / "pkg"), "--consumer",
+                     str(tmp_path / "tests"), "-o", str(out)]) == 0
+    repo_scoped = json.loads(out.read_text(encoding="utf-8"))
+
+    assert core_only["provenance"]["inputs"]["unlisted"]["count"] == 0
+    assert repo_scoped["provenance"]["inputs"]["unlisted"]["count"] == 0
+
+
+def test_a_file_outside_the_root_is_reduced_to_a_bare_name(tmp_path):
+    """The files this check catches are the ones most likely to be absolute — and the
+    provenance block refuses an absolute path by contract, so a naive record would turn
+    the diagnostic into a build crash."""
+    scope = {"root": str(tmp_path), "files": [{"path": "pkg/core.py"}]}
+    result = unlisted_files(["pkg/core.py", "/elsewhere/decoy/impostor.py"], scope)
+
+    assert result["count"] == 1
+    assert result["sample"] == ["impostor.py"]      # not the absolute path
+    assert result["outside_root"] is True
+    # the contract that would have been violated (build_provenance raises on absolutes)
+    block = build_provenance(tier="fast", inputs={"python_files": 1, "unlisted": result})
+    assert block["inputs"]["unlisted"]["outside_root"] is True
+
+
+# -- zero is a statement; unknown is an omission -------------------------------
+
+def test_zero_is_stated_and_no_manifest_is_left_unstated(repo, tmp_path, monkeypatch):
+    graph, _ = _build(repo, tmp_path / "clean.json")
+    assert graph["provenance"]["inputs"]["unlisted"] == {
+        "count": 0, "sample": [], "outside_root": False}
+
+    from codemap import cli as cli_mod
+    monkeypatch.setattr(cli_mod, "_resolve_scope_quietly", lambda args: None)
+    out = tmp_path / "noscope.json"
+    assert cli.main(["build", str(repo / "pkg"), "-o", str(out)]) == 0
+    unresolved = json.loads(out.read_text(encoding="utf-8"))
+    assert "unlisted" not in unresolved["provenance"]["inputs"], (
+        "no manifest means the build could not compare — writing a zero there would "
+        "turn an unknown into a clean bill of health")
+
+
+def test_the_diagnostic_reports_nothing_when_there_is_nothing_to_report():
+    class _G:
+        provenance = {"inputs": {"unlisted": {"count": 0, "sample": [],
+                                              "outside_root": False}}}
+
+    assert scope_membership_diagnostic(_G()) is None
+    _G.provenance = {"inputs": {}}                  # pre-R1-C41 graph
+    assert scope_membership_diagnostic(_G()) is None