codmap 0.0.9__tar.gz → 0.0.10__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.9
+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, **752 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 &

{codmap-0.0.9 → 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, **752 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 &

{codmap-0.0.9 → 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):

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

@@ -23,6 +23,7 @@ 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.
@@ -213,12 +214,49 @@ def deep_tier_diagnostic(graph) -> dict | None:
         "severity": NOTE,
         "tier": "deep",
         "consequence": ("Everything here is a lower bound as usual; treat a difference "
-                        "of a few call edges between two deep graphs as possible tool "
+                        "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 call edges — measured at roughly one run "
-            "in three on a 2133-node tree, by two per-symbol counters and no edges."
+            "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."
         ),
     }
 
@@ -307,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), deep_tier_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.9 → 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.9 → 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
@@ -273,8 +280,8 @@ def comparability(old: dict | None, new: dict | None) -> dict:
             # 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 call edges, "
-                           "so read a small call-graph delta as possible tool noise")
+                           "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,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.9
+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, **752 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 &

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

@@ -110,6 +110,7 @@ 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.9 → 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.9"
+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_r1c43_incremental_splice.py

@@ -0,0 +1,220 @@
+"""R1-C43 — an incremental deep graph says that parts of it were not recomputed.
+
+Two separate things are pinned here, and only the second one is a *fix*:
+
+1. ``provenance.incremental`` is written by every build path, ``false`` included — a
+   consumer must be able to tell "recomputed in full" from "predates the field", and an
+   absent key is the second of those (R1-C28).
+2. The diagnostic that reads it, which fires on the deep tier only.
+
+The third block pins a **known limit, not a guarantee**: ``_affected_modules`` rule (b)
+reads the *old* graph, so an edge that build missed is a dependency it cannot see. On
+the deep tier the old graph is one jedi sample, so a noise-dropped edge switches off the
+recompute that would have restored it. Measured on an 88-module package — same edit,
+same tree, the writer module was invalidated when the edge was present and not when it
+was absent (gaps/incremental_noise_persistence_2026-09-02.md §6). These tests state that
+behaviour deliberately: when it is fixed, they must be rewritten, not deleted quietly.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from codemap import cli, store
+from codemap.diagnostics import (
+    DEEP_TIER_UNSTABLE, INCREMENTAL_DEEP_SPLICE, NOTE, WARNING,
+    diagnostics, incremental_splice_diagnostic, render_lines,
+)
+from codemap.extract import extract
+from codemap.incremental import _affected_modules, _module_indexer, update_graph
+from codemap.model import Edge, Graph, Node
+from codemap.provenance import build_provenance
+from codemap.scope import resolve_scope
+
+PKG_INIT = '"""Tiny package."""\n'
+BASE = '''\
+"""Base."""
+
+
+class Config:
+    """A config."""
+
+    width = 10
+'''
+LEAF = '''\
+"""Leaf."""
+
+from .base import Config
+
+
+def widen(c: Config) -> int:
+    """Read a field off a typed parameter."""
+    return c.width + 1
+'''
+OTHER = '''\
+"""Unrelated to the pair above."""
+
+
+def helper() -> int:
+    return 1
+'''
+
+
+def _pkg(tmp_path: Path) -> Path:
+    pkg = tmp_path / "tiny"
+    pkg.mkdir()
+    (pkg / "__init__.py").write_text(PKG_INIT, encoding="utf-8")
+    (pkg / "base.py").write_text(BASE, encoding="utf-8")
+    (pkg / "leaf.py").write_text(LEAF, encoding="utf-8")
+    (pkg / "other.py").write_text(OTHER, encoding="utf-8")
+    return pkg
+
+
+def _scope(pkg: Path) -> dict:
+    return resolve_scope(pkg, use_git=False)
+
+
+# -- 1. the field ------------------------------------------------------------
+
+def test_a_full_build_declares_that_it_recomputed_everything(tmp_path):
+    """`false` is a statement; the reader must not have to infer it from absence."""
+    g = extract(_pkg(tmp_path), deep=False)
+    assert g.provenance["incremental"] is False
+
+
+def test_an_incremental_rebuild_declares_that_it_did_not(tmp_path):
+    pkg = _pkg(tmp_path)
+    g0 = extract(pkg, deep=False)
+    s0 = _scope(pkg)
+    (pkg / "other.py").write_text(OTHER + "\n# edited\n", encoding="utf-8")
+    g1, info = update_graph(g0, pkg, s0, _scope(pkg), deep=False)
+    if info["mode"] == "incremental":
+        assert g1.provenance["incremental"] is True
+    else:
+        # a four-module fixture trips the >=50% full-rebuild fallback easily; a full
+        # rebuild recomputes everything and must say so.
+        assert g1.provenance["incremental"] is False
+
+
+def test_the_cli_does_not_drop_the_flag_when_it_restamps_provenance(tmp_path):
+    """The subtle one: `_cmd_build` **overwrites** the block `update_graph` produced.
+
+    Nothing in the library-level tests can catch that — they read the graph object
+    before the CLI touches it — so the field would have been written, overwritten with
+    the default, and shipped as `false` on every incremental build.
+    """
+    pkg = _pkg(tmp_path)
+    out = tmp_path / "g.json"
+    assert cli.main(["build", str(pkg), "-o", str(out)]) == 0
+    assert json.loads(out.read_text(encoding="utf-8"))["provenance"]["incremental"] is False
+
+    (pkg / "other.py").write_text(OTHER + "\n# edited\n", encoding="utf-8")
+    assert cli.main(["build", str(pkg), "-o", str(out), "--incremental"]) == 0
+    written = json.loads(out.read_text(encoding="utf-8"))["provenance"]
+    assert written["incremental"] is True
+
+
+def test_an_untouched_tree_is_carried_over_too(tmp_path):
+    """`mode: unchanged` returns the previous graph whole — nothing was recomputed."""
+    pkg = _pkg(tmp_path)
+    out = tmp_path / "g.json"
+    assert cli.main(["build", str(pkg), "-o", str(out)]) == 0
+    assert cli.main(["build", str(pkg), "-o", str(out), "--incremental"]) == 0
+    assert json.loads(out.read_text(encoding="utf-8"))["provenance"]["incremental"] is True
+
+
+def test_the_flag_survives_a_round_trip_through_the_artifact(tmp_path):
+    g = extract(_pkg(tmp_path), deep=False)
+    g.provenance = build_provenance(tier="deep", incremental=True)
+    out = tmp_path / "g.json"
+    store.save(g, out)
+    assert store.load(out).provenance["incremental"] is True
+
+
+# -- 2. the diagnostic -------------------------------------------------------
+
+def _graph(tier: str, **kw) -> Graph:
+    g = Graph(target="tiny")
+    g.provenance = build_provenance(tier=tier, **kw)
+    return g
+
+
+def test_a_spliced_deep_graph_says_so():
+    d = incremental_splice_diagnostic(_graph("deep", incremental=True))
+    assert d is not None
+    assert d["code"] == INCREMENTAL_DEEP_SPLICE
+    assert d["severity"] == NOTE and d["severity"] != WARNING
+
+
+def test_a_full_deep_graph_is_not_accused_of_splicing():
+    assert incremental_splice_diagnostic(_graph("deep", incremental=False)) is None
+
+
+def test_the_fast_tier_is_excluded_because_its_splice_is_exact():
+    """Byte-identity to a full build is pinned there; there is no sample to freeze."""
+    assert incremental_splice_diagnostic(_graph("fast", incremental=True)) is None
+
+
+def test_a_graph_predating_the_field_is_not_guessed_about():
+    g = Graph(target="tiny")
+    g.provenance = {"tier": "deep", "tool": {"name": "codemap"}}  # no `incremental` key
+    assert incremental_splice_diagnostic(g) is None
+
+
+def test_it_reaches_the_aggregator_alongside_the_tier_note():
+    """Two different facts about one graph: it is a sample, and the sample is frozen."""
+    codes = {d["code"] for d in diagnostics(_graph("deep", incremental=True))}
+    assert {INCREMENTAL_DEEP_SPLICE, DEEP_TIER_UNSTABLE} <= codes
+
+
+def test_the_rendered_note_tells_the_reader_not_to_retry_incrementally():
+    text = " ".join(render_lines(_graph("deep", incremental=True)))
+    assert "full rebuild" in text or "full rebuild resamples" in text
+    assert "ℹ️" in text
+
+
+# -- 3. the limit this does NOT fix ------------------------------------------
+
+def _old_graph(with_edge: bool) -> Graph:
+    """Two old graphs differing by exactly one behavioral edge.
+
+    `leaf.widen` writes/reads `base.Config.width`. The pair is *not* import-linked in
+    the way rule (a) needs (that rule keys on module-level `imports` edges, added
+    below only for the unrelated module), so rule (b) — which reads this graph — is the
+    only route by which editing `base` can invalidate `leaf`.
+    """
+    g = Graph(target="tiny")
+    for mid in ("tiny", "tiny.base", "tiny.leaf", "tiny.other"):
+        g.add_node(Node(id=mid, kind="module"))
+    g.add_node(Node(id="tiny.base.Config.width", kind="attribute"))
+    g.add_node(Node(id="tiny.leaf.widen", kind="function"))
+    if with_edge:
+        g.add_edge(Edge(type="accesses", source="tiny.leaf.widen",
+                        target="tiny.base.Config.width",
+                        extras={"access": "read", "resolution": "deep"}))
+    return g
+
+
+def _affected_for(with_edge: bool) -> set[str]:
+    old = _old_graph(with_edge)
+    new = Graph(target="tiny")          # no fresh `imports` edge into base → rule (a) idle
+    for mid in ("tiny", "tiny.base", "tiny.leaf", "tiny.other"):
+        new.add_node(Node(id=mid, kind="module"))
+    module_of = _module_indexer({n.id for n in old.nodes.values() if n.kind == "module"})
+    changed = {"tiny.base"}
+    return _affected_modules(old, new, changed, changed, module_of)
+
+
+def test_the_edge_is_what_makes_the_writer_get_recomputed():
+    assert "tiny.leaf" in _affected_for(with_edge=True)
+
+
+def test_and_without_it_the_writer_is_silently_left_alone():
+    """The measured failure, stated: a dropped edge is a dropped reason to recompute.
+
+    Not an assertion that this is right — it is the limit R1-C43 names and does not
+    close. Door (2) (a periodic full rebuild) or door (3) (restricting what an
+    incremental deep graph may be used to conclude) would change this expectation.
+    """
+    assert "tiny.leaf" not in _affected_for(with_edge=False)

{codmap-0.0.9 → codmap-0.0.10}/tests/test_r1c9_incremental.py

@@ -7,14 +7,24 @@ fast and deep tiers, over a small multi-module package with cross-module calls,
 inheritance, and attribute access (the relationships the splice must get right).
 
 Deep byte-identity holds here because this fixture's jedi inference is single-hop and
-stable. On large packages jedi's *bounded* deep inference is cache-warmth-dependent —
-two full ``--deep`` builds already differ by a few deep-only edges — so there the
-guarantee is "identical up to jedi's own run-to-run variance" (see docs/incremental.md).
+stable. On large packages it does not, and the two reasons are worth keeping apart:
+
+- Two full ``--deep`` builds of an unchanged tree already differ from each other
+  (R1-C42), so on that tier there is no fixed artifact to be identical *to*. This was
+  attributed to jedi's **cache warmth** until 2026-09-02, when a cold ``XDG_CACHE_HOME``
+  per build flipped just as often (5 of 10) and refuted it; the cause is jedi's
+  per-script execution budget. That correction reached ``docs/incremental.md`` the same
+  day and not this docstring — the copy nobody grepped for.
+- The splice adds a divergence of its own (R1-C43): it carries the previous build's
+  sample forward, and the rule that would invalidate it reads that same incomplete
+  graph. Pinned in ``tests/test_r1c43_incremental_splice.py``.
+
 The splice logic itself is exact, which is what this fixture proves.
 """
 
 from __future__ import annotations
 
+import json
 from pathlib import Path
 
 import pytest
@@ -95,13 +105,30 @@ def _scope(pkg: Path) -> dict:
 
 
 def _assert_incremental_matches_full(old_graph, pkg, scope0, *, deep, expect_mode):
+    """The splice reproduces a full build's *content* — and says it was not one.
+
+    R1-C43 split what used to be a single `dumps == dumps`. The graphs must agree on
+    every node and edge, which is the acceptance bar; they must **disagree** on
+    `provenance.incremental`, because an artifact that was partly carried over may not
+    present itself as one that was recomputed. Comparing the whole file conflated the
+    two, and the field that exists to distinguish them would have read as a regression.
+    """
     scope1 = _scope(pkg)
     inc, info = update_graph(old_graph, pkg, scope0, scope1, deep=deep)
     full = extract(pkg, deep=deep)
-    assert store.dumps(inc) == store.dumps(full), f"incremental != full ({info})"
+
+    def content(g):
+        d = json.loads(store.dumps(g))
+        d.pop("provenance", None)
+        return json.dumps(d, sort_keys=True)
+
+    assert content(inc) == content(full), f"incremental != full ({info})"
+    assert full.provenance["incremental"] is False
     # a small toy package trips the full-rebuild fallback easily; the correctness
-    # invariant (dumps-equal) holds either way, so accept a set of allowed modes.
+    # invariant holds either way, so accept a set of allowed modes — but the flag must
+    # follow the mode that actually ran, not the one we hoped for.
     assert info["mode"] in expect_mode
+    assert inc.provenance["incremental"] is (info["mode"] != "full")
     return inc, info