codmap 0.0.8__tar.gz → 0.0.10__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.8
+Version: 0.0.10
 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, **743 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 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 &
@@ -58,8 +58,9 @@ export edges, best-effort call edges, registry-family `implements` links, string
 and per-call argument contracts — then answers questions over it.
 
 Design principles: **source-only** (static `ast`/`griffe`, never imports the target), **deterministic**
-(canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
-codes), **honest** (approximations are labeled, not hidden).
+(canonical sorted JSON, no timestamps — diffable; byte-stable on the fast tier, see the caveat
+[below](#one-caveat-on-deterministic)), **CLI-AI-first** (JSON by default, stable exit codes),
+**honest** (approximations are labeled, not hidden).
 
 ## Point questions and whole-graph questions
 
@@ -247,6 +248,22 @@ against *all* true edges (the price of Python's dynamism), and a grep-vs-graph p
 cheaper than grep for impact on unique names, tens of × on polymorphic ones, and no cheaper for locating a
 symbol.
 
+## One caveat on "deterministic"
+
+The **fast tier is byte-stable**: two builds of an unchanged tree produce identical files, and CI
+compares the bytes on every push. The **deep tier (`--deep`, jedi) is not**. Ten deep builds of an
+unchanged tree here produced two distinct artifacts — differing in two per-symbol call counters out
+of 2133 nodes, no edges — and on a larger external tree one build in seven lost one real call edge of
+9524. The cause is jedi's per-script execution budget: an inference that runs out of it returns
+nothing, and nothing is recorded as `unresolved`.
+
+So a deep graph is one sample of a slightly fuzzy function, not a function of its input. Every deep
+build says so in its own diagnostics, and `codemap diff` says so when both sides are deep — read a
+delta of a few call edges as possible tool noise before reading it as a change in the code. Anything
+that must be reproducible byte-for-byte — a gate, a two-release comparison — belongs on the fast tier.
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md).
+
 ## Dogfooding
 
 codemap is validated end-to-end against a real external package. Place a target repo as a sibling and

{codmap-0.0.8 → codmap-0.0.10}/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, **743 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 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 &
@@ -22,8 +22,9 @@ export edges, best-effort call edges, registry-family `implements` links, string
 and per-call argument contracts — then answers questions over it.
 
 Design principles: **source-only** (static `ast`/`griffe`, never imports the target), **deterministic**
-(canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
-codes), **honest** (approximations are labeled, not hidden).
+(canonical sorted JSON, no timestamps — diffable; byte-stable on the fast tier, see the caveat
+[below](#one-caveat-on-deterministic)), **CLI-AI-first** (JSON by default, stable exit codes),
+**honest** (approximations are labeled, not hidden).
 
 ## Point questions and whole-graph questions
 
@@ -211,6 +212,22 @@ against *all* true edges (the price of Python's dynamism), and a grep-vs-graph p
 cheaper than grep for impact on unique names, tens of × on polymorphic ones, and no cheaper for locating a
 symbol.
 
+## One caveat on "deterministic"
+
+The **fast tier is byte-stable**: two builds of an unchanged tree produce identical files, and CI
+compares the bytes on every push. The **deep tier (`--deep`, jedi) is not**. Ten deep builds of an
+unchanged tree here produced two distinct artifacts — differing in two per-symbol call counters out
+of 2133 nodes, no edges — and on a larger external tree one build in seven lost one real call edge of
+9524. The cause is jedi's per-script execution budget: an inference that runs out of it returns
+nothing, and nothing is recorded as `unresolved`.
+
+So a deep graph is one sample of a slightly fuzzy function, not a function of its input. Every deep
+build says so in its own diagnostics, and `codemap diff` says so when both sides are deep — read a
+delta of a few call edges as possible tool noise before reading it as a change in the code. Anything
+that must be reproducible byte-for-byte — a gate, a two-release comparison — belongs on the fast tier.
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md).
+
 ## Dogfooding
 
 codemap is validated end-to-end against a real external package. Place a target repo as a sibling and

{codmap-0.0.8 → codmap-0.0.10}/codemap/cli.py

@@ -104,7 +104,11 @@ 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=_inputs_with_membership(graph, scope, args))
+        inputs=_inputs_with_membership(graph, scope, args),
+        # R1-C43: this call *overwrites* whatever update_graph stamped, so the flag has
+        # to be re-derived here or it is lost. `unchanged` counts as carried over too —
+        # nothing in that graph was recomputed by this build at all.
+        incremental=(incr_info or {}).get("mode") in ("incremental", "unchanged"))
     # 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):
@@ -747,6 +751,8 @@ def _cmd_diff(args) -> int:
             print(f"[warning] {line}", file=sys.stderr)
         print(f"[warning] differences below may be tool changes, not code changes "
               f"(old: {cmp['old']} | new: {cmp['new']})", file=sys.stderr)
+    for caveat in cmp.get("caveats") or ():
+        print(f"[note] {caveat}", file=sys.stderr)
     print(render_apidiff(old, new), end="")
     if args.exit_code and not build_apidiff(old, new)["ok"]:
         return 1

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

@@ -22,6 +22,8 @@ SCHEMA_MISMATCH = "schema_mismatch"
 UNREAD_INPUTS = "unread_inputs"
 MODULE_COUNT_MISMATCH = "module_count_mismatch"
 SCOPE_MEMBERSHIP = "scope_membership"
+DEEP_TIER_UNSTABLE = "deep_tier_unstable"
+INCREMENTAL_DEEP_SPLICE = "incremental_deep_splice"
 
 #: 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.
@@ -190,6 +192,75 @@ def unread_inputs_diagnostic(graph) -> dict | None:
     }
 
 
+def deep_tier_diagnostic(graph) -> dict | None:
+    """State the deep tier's noise floor on the artifact itself (R1-C42).
+
+    A **note**, not a warning: nothing here is wrong, and no finding below is invalid.
+    What was missing is that the tier's instability was known — measured at R1-C9, and
+    the reason the CI determinism job runs the fast tier only — while living exclusively
+    in a comment in a workflow file. A consumer read "deterministic" and built a
+    two-release comparison on it; the difference they saw was the tool, not the code.
+
+    Measured on two trees: ten deep builds of an unchanged tree produced **two** distinct
+    artifacts (7/3), differing in two per-symbol call counters and no edges; on a larger
+    tree one build in seven lost one real call edge of 9524. The cause is jedi's
+    per-script execution budget — an inference that runs out of it returns nothing, and
+    that reads as `unresolved` rather than as an error.
+    """
+    if (graph.provenance or {}).get("tier") != "deep":
+        return None
+    return {
+        "code": DEEP_TIER_UNSTABLE,
+        "severity": NOTE,
+        "tier": "deep",
+        "consequence": ("Everything here is a lower bound as usual; treat a difference "
+                        "of a few jedi-resolved edges between two deep graphs as tool "
+                        "noise rather than a change in the code."),
+        "message": (
+            "built on the deep (jedi) tier, which is not byte-stable: two builds of an "
+            "unchanged tree can differ by a few jedi-resolved edges — measured at roughly "
+            "one run in three on two trees: two per-symbol call counters on one, one "
+            "`accesses` edge of 12190 on the other."
+        ),
+    }
+
+
+def incremental_splice_diagnostic(graph) -> dict | None:
+    """Say when a deep graph carries regions this build did not recompute (R1-C43).
+
+    Sibling of :func:`deep_tier_diagnostic`, and the reason it is a separate code: that
+    one says *this graph is one sample*, which a reader can act on by building again.
+    This one says the sample is **frozen** — building again incrementally returns it
+    unchanged, so the standard remedy silently does nothing.
+
+    Measured on an 88-module package: from a graph missing one real `accesses` edge,
+    five consecutive incremental builds recovered it **0 times** while full builds of
+    the very same tree recovered it **5 of 5**. And the miss defends itself — the
+    invalidation rule that would have recomputed the writer reads the old graph, where
+    the edge is exactly what is absent (gaps/incremental_noise_persistence_2026-09-02.md).
+
+    Fast tier is excluded on purpose: there the splice is exact and byte-identity to a
+    full build is pinned by the suite, so there is no sample to freeze.
+    """
+    prov = graph.provenance or {}
+    if prov.get("tier") != "deep" or not prov.get("incremental"):
+        return None
+    return {
+        "code": INCREMENTAL_DEEP_SPLICE,
+        "severity": NOTE,
+        "tier": "deep",
+        "consequence": ("Do not read a missing call or attribute edge here as evidence "
+                        "that nothing depends on a symbol, and do not test that by "
+                        "rebuilding incrementally — only a full rebuild resamples."),
+        "message": (
+            "parts of this deep graph were spliced from an earlier build rather than "
+            "recomputed: on this tier that carries the earlier build's jedi sample "
+            "forward, including anything it missed — measured at 0 recoveries in 5 "
+            "incremental builds against 5 of 5 full builds of the same tree."
+        ),
+    }
+
+
 def scope_membership_diagnostic(graph) -> dict | None:
     """Flag files the graph was built from that the input manifest never listed (R1-C41).
 
@@ -274,7 +345,8 @@ def diagnostics(graph) -> list[dict]:
     checks = (import_graph_diagnostic(graph), namespace_target_diagnostic(graph),
               cross_root_diagnostic(graph), schema_diagnostic(graph),
               unread_inputs_diagnostic(graph), module_count_diagnostic(graph),
-              scope_membership_diagnostic(graph))
+              scope_membership_diagnostic(graph), deep_tier_diagnostic(graph),
+              incremental_splice_diagnostic(graph))
     return [d for d in checks if d is not None]
 
 

{codmap-0.0.8 → codmap-0.0.10}/codemap/incremental.py

@@ -25,6 +25,27 @@ so we fall back to it.
 
 The acceptance bar (BACKLOG R1-C9) is **byte-identical to a full rebuild**; the test
 suite pins exactly that across edit / add / remove scenarios on both tiers.
+
+**That bar is reachable on the fast tier only** — and saying it without a tier was
+wrong twice over (R1-C43). Two full *deep* builds of an unchanged tree are not
+byte-identical to each other (R1-C42), so there is no fixed artifact to be identical
+*to*. Worse, measurement found a divergence this path introduces on its own:
+
+- The splice **freezes a sample.** An edge jedi missed in the old build is copied
+  forward verbatim; measured 0 recoveries in 5 incremental builds against 5 in 5 full
+  builds of the same tree. "Build it again and see" — the standard answer to tier
+  noise — does not work here.
+- The splice **blinds the invalidation that would undo it.** ``_affected_modules``
+  rule (b) below reads the *old* graph, so a missing edge is a missing reason to
+  recompute: editing the module that owns the target left the writer unaffected when
+  the edge was absent, and affected when it was present. Same edit, same tree.
+
+The `unresolved` set cannot be indexed by the changed module — not knowing where an
+edge went is what `unresolved` *means* — so this is structural for a cache keyed on
+its own incomplete answer, not an oversight. What we do about it today is declare it:
+``provenance.incremental`` marks such a graph and the diagnostic says what follows.
+
+Measurement: ``gaps/incremental_noise_persistence_2026-09-02.md``.
 """
 
 from __future__ import annotations
@@ -99,6 +120,10 @@ def _affected_modules(old_graph, new_graph, base_mods, changed_removed, module_o
         if e.type == "imports" and e.target in base_mods:
             affected.add(e.source)
     # rule (b): a module whose old behavioral edge targeted a changed/removed module.
+    # R1-C43, the limit stated where it lives: this reads the OLD graph, so on the deep
+    # tier it is only as complete as that build's jedi sample. An edge the old build
+    # missed is a dependency this rule cannot see — measured: with the edge present the
+    # writer was invalidated, with the same edge missing it was not, on the same edit.
     for e in old_graph.edges:
         if e.type in _DEP_EDGE_TYPES:
             tgt_mod = module_of(e.target)
@@ -147,10 +172,15 @@ def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dic
     """Incrementally rebuild ``old_graph`` for the current source tree.
 
     Returns ``(graph, info)`` where ``info`` records the decision (``mode``:
-    ``unchanged`` | ``incremental`` | ``full`` and the affected module list). The
-    result is byte-identical to ``extract(package_path, deep=deep)`` — the cheap
-    layers are rebuilt whole and the expensive jedi passes are recomputed for the
-    affected modules and spliced from the old graph for the rest.
+    ``unchanged`` | ``incremental`` | ``full`` and the affected module list). The cheap
+    layers are rebuilt whole; the expensive jedi passes are recomputed for the affected
+    modules and spliced from the old graph for the rest.
+
+    On the **fast** tier the result is byte-identical to ``extract(package_path,
+    deep=deep)``. On the **deep** tier it is not, and not only because the target moves
+    (R1-C42): the spliced regions carry the *previous* build's sample, and the splice
+    is self-perpetuating — see the module docstring (R1-C43). Such a graph is stamped
+    ``provenance.incremental: true``.
     """
     target_pkg = old_graph.target
     tier = "deep" if deep else "fast"
@@ -191,5 +221,6 @@ def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dic
                          behavior_only=affected, attr_only=affected)
     unaffected = module_ids - affected
     _splice_unaffected(graph, old_graph, unaffected, module_of)
-    graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"))
+    graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"),
+                                        incremental=True)
     return graph, {"mode": "incremental", "affected": sorted(affected)}

{codmap-0.0.8 → codmap-0.0.10}/codemap/provenance.py

@@ -155,9 +155,16 @@ def relative_root(root: str | Path | None, path: str | Path) -> str:
 
 
 def build_provenance(*, tier: str, scope: dict | None = None,
-                     roots: dict | None = None, inputs: dict | None = None) -> dict:
-    """Assemble the ``provenance`` block. Deterministic; no clock, no absolute path."""
-    prov: dict = {"tool": tool_identity(), "tier": tier}
+                     roots: dict | None = None, inputs: dict | None = None,
+                     incremental: bool = False) -> dict:
+    """Assemble the ``provenance`` block. Deterministic; no clock, no absolute path.
+
+    ``incremental`` records whether parts of this graph were **carried over rather than
+    recomputed in this build** (R1-C43). Always written, including ``false`` — absence
+    means the graph predates the field, which is *unknown*, not *full* (R1-C28).
+    """
+    prov: dict = {"tool": tool_identity(), "tier": tier,
+                  "incremental": bool(incremental)}
     if inputs:
         # R1-C23/D2: what the extractor read, and what it could not. Belongs with the
         # identity rather than in the sidecar — a consumer holding only the graph is
@@ -253,6 +260,7 @@ def comparability(old: dict | None, new: dict | None) -> dict:
     were dead.
     """
     differences: list[str] = []
+    caveats: list[str] = []
     if not old or not new:
         differences.append("one of the graphs records no provenance "
                            "(built before schema 0.12) — the pair cannot be verified")
@@ -264,9 +272,20 @@ def comparability(old: dict | None, new: dict | None) -> dict:
         old_roots, new_roots = old.get("roots"), new.get("roots")
         if old_roots != new_roots:
             differences.append(f"different scope roots: {old_roots} → {new_roots}")
+        if old.get("tier") == new.get("tier") == "deep":
+            # R1-C42: matching tiers make the pair comparable, and on the deep tier that
+            # is not the same as "every difference here is a code change". Measured on
+            # two trees: builds of an *unchanged* tree differ in roughly one run of
+            # three, by a couple of call classifications — and on the larger tree by one
+            # real call edge in ~9500. A caveat, not a difference: it is the right pair,
+            # the reader just must not read a two-edge delta as a fact about the code.
+            caveats.append("both sides are deep-tier, which is not byte-stable: two "
+                           "builds of an unchanged tree can differ by a few jedi-resolved "
+                           "edges, so read a small delta as possible tool noise")
     return {
         "comparable": not differences,
         "differences": differences,
+        "caveats": caveats,
         "old": describe(old),
         "new": describe(new),
     }

{codmap-0.0.8 → codmap-0.0.10}/codemap/serve/apidiff.py

@@ -53,6 +53,10 @@ def render_apidiff(old: Graph, new: Graph) -> str:
                    + f". Old: {prov['old']} | new: {prov['new']}. "
                      "Differences below may be tool changes, not code changes.")
         out.append("")
+    # R1-C42: comparable, and still carrying a noise floor the reader has to know about.
+    for caveat in prov.get("caveats") or ():
+        out.append(f"> ℹ️ {caveat}.")
+        out.append("")
 
     removed = d["removed"]
     if removed:

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.8
+Version: 0.0.10
 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, **743 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **765 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 &
@@ -58,8 +58,9 @@ export edges, best-effort call edges, registry-family `implements` links, string
 and per-call argument contracts — then answers questions over it.
 
 Design principles: **source-only** (static `ast`/`griffe`, never imports the target), **deterministic**
-(canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
-codes), **honest** (approximations are labeled, not hidden).
+(canonical sorted JSON, no timestamps — diffable; byte-stable on the fast tier, see the caveat
+[below](#one-caveat-on-deterministic)), **CLI-AI-first** (JSON by default, stable exit codes),
+**honest** (approximations are labeled, not hidden).
 
 ## Point questions and whole-graph questions
 
@@ -247,6 +248,22 @@ against *all* true edges (the price of Python's dynamism), and a grep-vs-graph p
 cheaper than grep for impact on unique names, tens of × on polymorphic ones, and no cheaper for locating a
 symbol.
 
+## One caveat on "deterministic"
+
+The **fast tier is byte-stable**: two builds of an unchanged tree produce identical files, and CI
+compares the bytes on every push. The **deep tier (`--deep`, jedi) is not**. Ten deep builds of an
+unchanged tree here produced two distinct artifacts — differing in two per-symbol call counters out
+of 2133 nodes, no edges — and on a larger external tree one build in seven lost one real call edge of
+9524. The cause is jedi's per-script execution budget: an inference that runs out of it returns
+nothing, and nothing is recorded as `unresolved`.
+
+So a deep graph is one sample of a slightly fuzzy function, not a function of its input. Every deep
+build says so in its own diagnostics, and `codemap diff` says so when both sides are deep — read a
+delta of a few call edges as possible tool noise before reading it as a change in the code. Anything
+that must be reproducible byte-for-byte — a gate, a two-release comparison — belongs on the fast tier.
+
+**Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md).
+
 ## Dogfooding
 
 codemap is validated end-to-end against a real external package. Place a target repo as a sibling and

{codmap-0.0.8 → codmap-0.0.10}/codmap.egg-info/SOURCES.txt

@@ -109,6 +109,8 @@ 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_r1c42_deep_tier_stability.py
+tests/test_r1c43_incremental_splice.py
 tests/test_r1c4_complexity.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py

{codmap-0.0.8 → codmap-0.0.10}/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.8"
+version = "0.0.10"
 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.10/tests/test_r1c42_deep_tier_stability.py

@@ -0,0 +1,92 @@
+"""R1-C42 — the deep tier is not byte-stable, and the artifact must say so.
+
+Raised by the second real target: seven builds of an unchanged clean tree, and in one
+of them a real `calls` edge (resolved through `getattr`) was gone — 9524 edges against
+9523. They had briefly concluded a regression between two releases from it, which is
+the failure this suite exists to prevent: a consumer reading "deterministic" and
+comparing two deep graphs as if every difference were a change in the code.
+
+The instability itself was **known** — measured at R1-C9, and the reason the CI
+determinism job runs the fast tier only. It lived in a comment in a workflow file,
+while README said "deterministic" unqualified and `provenance.md` said two builds of an
+unchanged tree are byte-identical. So the fix is disclosure in the places a consumer
+actually reads: the graph's own diagnostics, and any comparison of two deep graphs.
+
+Reproduced here on our own tree before the fix: ten deep builds → two distinct
+artifacts (7/3), differing in two per-symbol call counters and no edges. The cause is
+jedi's per-script execution budget: an inference that runs out of it returns nothing,
+and nothing reads as `unresolved`. That is not testable in a unit suite — a build takes
+~40 s and flips about one run in three — so what is pinned here is the disclosure.
+"""
+
+from __future__ import annotations
+
+from codemap.diagnostics import DEEP_TIER_UNSTABLE, NOTE, WARNING, deep_tier_diagnostic, diagnostics
+from codemap.model import Graph
+from codemap.provenance import comparability
+from codemap.serve.apidiff import render_apidiff
+
+
+def _graph(tier: str) -> Graph:
+    g = Graph(target="pkg")
+    g.provenance = {"tier": tier, "tool": {"name": "codemap", "version": "0.0.9"}}
+    return g
+
+
+# -- the note on the artifact --------------------------------------------------
+
+def test_a_fast_graph_says_nothing():
+    assert deep_tier_diagnostic(_graph("fast")) is None
+
+
+def test_a_deep_graph_declares_its_noise_floor():
+    d = deep_tier_diagnostic(_graph("deep"))
+    assert d is not None and d["code"] == DEEP_TIER_UNSTABLE
+    assert "not byte-stable" in d["message"]
+    assert d["consequence"]
+
+
+def test_it_is_a_note_and_not_a_warning():
+    """A warning says the findings below are invalid. Nothing here is invalid — the
+    graph is sound, it is one sample of a slightly fuzzy function (issue #8's rule)."""
+    d = deep_tier_diagnostic(_graph("deep"))
+    assert d["severity"] == NOTE != WARNING
+
+
+def test_it_reaches_the_surface_a_consumer_reads():
+    codes = [d["code"] for d in diagnostics(_graph("deep"))]
+    assert DEEP_TIER_UNSTABLE in codes
+    assert DEEP_TIER_UNSTABLE not in [d["code"] for d in diagnostics(_graph("fast"))]
+
+
+def test_a_pre_provenance_graph_is_not_guessed_about():
+    g = Graph(target="pkg")
+    g.provenance = {}
+    assert deep_tier_diagnostic(g) is None
+
+
+# -- the caveat on a comparison ------------------------------------------------
+
+def test_two_deep_graphs_stay_comparable_and_carry_the_caveat():
+    c = comparability(_graph("deep").provenance, _graph("deep").provenance)
+    assert c["comparable"] is True, "matching tiers are the right pair — never a refusal"
+    assert c["caveats"] and "not byte-stable" in c["caveats"][0]
+
+
+def test_two_fast_graphs_carry_no_caveat():
+    c = comparability(_graph("fast").provenance, _graph("fast").provenance)
+    assert c["caveats"] == []
+
+
+def test_mixed_tiers_are_still_an_incomparability_not_a_caveat():
+    c = comparability(_graph("fast").provenance, _graph("deep").provenance)
+    assert c["comparable"] is False
+    assert any("different tier" in d for d in c["differences"])
+    assert c["caveats"] == [], "a caveat must not soften a genuine incomparability"
+
+
+def test_the_rendered_diff_shows_it_above_the_verdict():
+    out = render_apidiff(_graph("deep"), _graph("deep"))
+    assert "not byte-stable" in out
+    head = out.split("## ")[0]
+    assert "not byte-stable" in head, "a footnote is not a disclosure"