codmap 0.0.11__tar.gz → 0.0.12__tar.gz

{codmap-0.0.11/codmap.egg-info → codmap-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.11
+Version: 0.0.12
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -161,7 +161,7 @@ Optional extras: `mcp` (Model Context Protocol server), `scip` (protobuf, for SC
 ## Quickstart
 
 ```bash
-# build the canonical graph of a package
+# build the canonical graph of a package (its directory name is the package name every id starts with)
 codemap build ./yourpkg -o graph.json
 
 # repo-scoped: add consumers (tests/examples) + docs for blast-radius/impact
@@ -271,8 +271,10 @@ unstable among 13 675). So one build misses such an edge about 1 time in 4, two
 1 in 64. `codemap build --deep --repeat N` builds N samples — each in a fresh interpreter, the
 regime the share was measured in; in-process repeats come in correlated streaks — and unions them: an edge seen in fewer
 than N runs carries `extras.seen`, `provenance.samples` records N and how many edges varied, and the
-note on the graph says both. Refused out loud on the fast tier (byte-stable already) and together with
-`--incremental` (a spliced graph cannot be resampled).
+note on the graph says both. Refused out loud on the fast tier (byte-stable already). With `--incremental`
+and `watch`, N becomes a property of the chain and every place the chain samples — base, fallback, each
+tick's recompute — samples N times; measured on twenty real commits, that is what removes the chain's misses,
+and a periodic full rebuild does not.
 
 **Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md),
 [gaps/deep_tier_union_by_repeat_2026-09-04.md](gaps/deep_tier_union_by_repeat_2026-09-04.md).

{codmap-0.0.11 → codmap-0.0.12}/README.md

@@ -125,7 +125,7 @@ Optional extras: `mcp` (Model Context Protocol server), `scip` (protobuf, for SC
 ## Quickstart
 
 ```bash
-# build the canonical graph of a package
+# build the canonical graph of a package (its directory name is the package name every id starts with)
 codemap build ./yourpkg -o graph.json
 
 # repo-scoped: add consumers (tests/examples) + docs for blast-radius/impact
@@ -235,8 +235,10 @@ unstable among 13 675). So one build misses such an edge about 1 time in 4, two
 1 in 64. `codemap build --deep --repeat N` builds N samples — each in a fresh interpreter, the
 regime the share was measured in; in-process repeats come in correlated streaks — and unions them: an edge seen in fewer
 than N runs carries `extras.seen`, `provenance.samples` records N and how many edges varied, and the
-note on the graph says both. Refused out loud on the fast tier (byte-stable already) and together with
-`--incremental` (a spliced graph cannot be resampled).
+note on the graph says both. Refused out loud on the fast tier (byte-stable already). With `--incremental`
+and `watch`, N becomes a property of the chain and every place the chain samples — base, fallback, each
+tick's recompute — samples N times; measured on twenty real commits, that is what removes the chain's misses,
+and a periodic full rebuild does not.
 
 **Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md),
 [gaps/deep_tier_union_by_repeat_2026-09-04.md](gaps/deep_tier_union_by_repeat_2026-09-04.md).

{codmap-0.0.11 → codmap-0.0.12}/codemap/cli.py

@@ -85,10 +85,9 @@ def _cmd_build(args) -> int:
     incr_info = None
     repeat = getattr(args, "repeat", None)
     repeat = 1 if repeat is None else repeat
-    # R1-C45 / D7–D8: refused out loud, never swallowed. The fast tier is byte-stable and
-    # CI pins it, so N runs there buy nothing and cost N minutes; and an incremental graph's
-    # spliced part is an earlier build's sample by definition (R1-C43), so resampling only
-    # the affected modules would leave `seen` relative to different N on neighbouring edges.
+    # R1-C45 / D7: refused out loud, never swallowed. The fast tier is byte-stable and CI
+    # pins it, so N runs there buy nothing and cost N minutes. With --incremental the flag
+    # is allowed since R1-C47: N is a property of the chain, and a different N restarts it.
     if repeat < 1:
         print("error: --repeat must be >= 1", file=sys.stderr)
         return 2
@@ -96,12 +95,13 @@ def _cmd_build(args) -> int:
         print(f"error: --repeat {repeat} needs --deep — the fast tier is byte-stable, so "
               "repeating it unions identical samples", file=sys.stderr)
         return 2
-    if repeat > 1 and getattr(args, "incremental", False):
-        print(f"error: --repeat {repeat} cannot be combined with --incremental — the spliced "
-              "part of an incremental graph is an earlier build's sample and cannot be "
-              "resampled; run a full build", file=sys.stderr)
-        return 2
     if args.consumer or args.docs:
+        if getattr(args, "incremental", False):
+            # R1-C44 / D6: the flag used to be swallowed here without a word. Not an
+            # error — a stated boundary: the incremental path is single-package.
+            print("[note] --incremental was not applied: --consumer/--docs make this a "
+                  "repo-scoped build, which is always full (the incremental path is "
+                  "single-package only)", file=sys.stderr)
         graph = extract_repo(
             args.path,
             consumers=tuple(args.consumer or ()),
@@ -201,12 +201,15 @@ def _incremental_build(args):
     old_meta = read_meta(args.out)
     old_scope = (old_meta or {}).get("scope")
     if not (Path(args.out).exists() and old_scope):
-        return extract(args.path, deep=args.deep), {"mode": "full", "affected": []}
+        return extract(args.path, deep=args.deep, repeat=getattr(args, "repeat", None) or 1), \
+            {"mode": "full", "affected": []}
     old_graph = store.load(args.out)
     new_scope = resolve_scope(args.path)
+    repeat = getattr(args, "repeat", None) or 1
     if old_graph.target != Path(args.path).resolve().name:
-        return extract(args.path, deep=args.deep), {"mode": "full", "affected": []}
-    return update_graph(old_graph, args.path, old_scope, new_scope, deep=args.deep)
+        return extract(args.path, deep=args.deep, repeat=repeat), {"mode": "full", "affected": []}
+    return update_graph(old_graph, args.path, old_scope, new_scope, deep=args.deep,
+                        repeat=repeat)
 
 
 def _watch_build_argv(args) -> list[str]:
@@ -219,6 +222,8 @@ def _watch_build_argv(args) -> list[str]:
     argv = ["build", args.path, "-o", args.out, "--incremental"]
     if args.deep:
         argv.append("--deep")
+    if (getattr(args, "repeat", None) or 1) > 1:
+        argv += ["--repeat", str(args.repeat)]  # R1-C47: N is a property of the chain
     for c in args.consumer or ():
         argv += ["--consumer", c]
     for d in args.docs or ():
@@ -261,6 +266,7 @@ def _cmd_watch(args) -> int:
     build_args = _argparse.Namespace(
         path=args.path, out=args.out, deep=args.deep, consumer=args.consumer,
         docs=args.docs, mode=args.mode, incremental=True,
+        repeat=getattr(args, "repeat", None) or 1,
         _argv=_watch_build_argv(args))
 
     reported: set[str] = set()
@@ -891,7 +897,9 @@ def build_parser() -> argparse.ArgumentParser:
     sub = p.add_subparsers(dest="command", required=True)
 
     b = sub.add_parser("build", help="Build the canonical graph from a package path.")
-    b.add_argument("path", help="Path to the package directory (holds __init__.py).")
+    b.add_argument("path", help="Path to the package directory (holds __init__.py). Its "
+                                "directory name is the package name every node id starts "
+                                "with — a copy under another name answers to that name.")
     b.add_argument("-o", "--out", help="Write graph.json here (default: stdout JSON).")
     b.add_argument("--deep", action="store_true",
                    help="Deep call resolution via jedi (richer, ~1 min; default fast).")
@@ -904,14 +912,17 @@ def build_parser() -> argparse.ArgumentParser:
                    help="Consumer granularity: thin=per-file (default), full=per-function.")
     b.add_argument("--incremental", action="store_true",
                    help="Reuse an existing --out graph + its scope sidecar: recompute "
-                        "only changed modules (R1-C9). Identical to a full build; much "
-                        "faster on --deep. Single-package only (no --consumer/--docs).")
+                        "only changed modules (R1-C9). Byte-identical to a full build on "
+                        "the fast tier; on --deep it carries the earlier build's jedi "
+                        "sample forward (docs/incremental.md). Much faster on --deep. "
+                        "Single-package only (no --consumer/--docs).")
     b.add_argument("--repeat", type=int, default=1, metavar="N",
                    help="--deep only: run the jedi layer N times and union the samples. "
                         "One deep build is one sample (a real edge was present in 75%% "
                         "of single builds, measured); an edge seen in fewer than N runs "
                         "carries extras.seen, provenance.samples records N. Costs N× the "
-                        "jedi time. Not combinable with --incremental.")
+                        "jedi time, in parallel. With --incremental N becomes a property "
+                        "of the chain: a different N restarts it from a full build.")
     b.set_defaults(func=_cmd_build)
 
     sc = sub.add_parser("scope", help="Resolve the input scope manifest (scope_id + profile), or --diff two.")
@@ -1015,6 +1026,11 @@ def build_parser() -> argparse.ArgumentParser:
     w.add_argument("--docs", action="append", metavar="PATH", help="Docs root. Repeatable.")
     w.add_argument("--mode", choices=["thin", "full"], default="thin",
                    help="Consumer granularity (as for `build`).")
+    w.add_argument("--repeat", type=int, default=1, metavar="N",
+                   help="--deep only: sample the jedi layer N times on every build this "
+                        "loop makes — base, fallback and each tick's recompute (R1-C47). "
+                        "Measured: an incremental chain's misses come from single samples, "
+                        "not from age.")
     w.add_argument("--cycles", type=int, default=None,
                    help="Stop after N polls instead of running forever (CI / testing).")
     _add_poll_options(

{codmap-0.0.11 → codmap-0.0.12}/codemap/extract/griffe_extractor.py

@@ -140,15 +140,22 @@ def add_behavioral_layer(graph, root, module_name, search_path, *, deep: bool,
                  only=attr_only)
 
 
-def _sample_worker(package_path: str, deep: bool) -> dict:
-    """One full extraction in a child interpreter; returns the graph as a dict (R1-C45)."""
+def _sample_worker(package_path: str, deep: bool, only=None) -> dict:
+    """One extraction in a child interpreter; returns the graph as a dict (R1-C45).
+
+    ``only`` (a set of module paths) restricts the two jedi passes to those modules —
+    the incremental hook (R1-C9), so a chain can resample just what a tick touched
+    (R1-C47). The structural base is rebuilt in every worker regardless: cheap,
+    deterministic, and cheaper than shipping it across processes.
+    """
     graph, root, module_name, search_path = build_structural(package_path)
-    add_behavioral_layer(graph, root, module_name, search_path, deep=deep)
+    add_behavioral_layer(graph, root, module_name, search_path, deep=deep,
+                         behavior_only=only, attr_only=only)
     return graph.to_dict()
 
 
 def collect_samples(package_path, *, deep: bool, runs: int,
-                    workers: int | None = None) -> list[Graph]:
+                    workers: int | None = None, only=None) -> list[Graph]:
     """``runs`` independent samples of ``package_path``, each in a fresh interpreter.
 
     Lives here, beside the two functions the worker calls, so ``extract/union.py`` stays
@@ -161,7 +168,8 @@ def collect_samples(package_path, *, deep: bool, runs: int,
     ctx = multiprocessing.get_context("spawn")
     procs = max(1, min(runs, workers or os.cpu_count() or 1))
     with ctx.Pool(processes=procs) as pool:
-        dicts = pool.starmap(_sample_worker, [(str(package_path), deep)] * runs)
+        dicts = pool.starmap(_sample_worker,
+                             [(str(package_path), deep, set(only) if only else None)] * runs)
     samples = []
     for d in dicts:
         g = Graph.from_dict(d)

{codmap-0.0.11 → codmap-0.0.12}/codemap/incremental.py

@@ -54,10 +54,10 @@ import copy
 from pathlib import Path
 
 from codemap.extract.griffe_extractor import (
-    add_behavioral_layer, build_structural, extract,
+    add_behavioral_layer, build_structural, collect_samples, extract,
 )
-from codemap.extract.union import BEHAVIOR_CALL_RES
-from codemap.model import Graph
+from codemap.extract.union import BEHAVIOR_CALL_RES, merge_samples
+from codemap.model import SPLICED_EDGE_TYPES, Graph
 from codemap.provenance import build_provenance, tool_identity
 from codemap.scope import diff_scopes
 
@@ -75,8 +75,9 @@ _BEHAVIOR_REF_RES = frozenset({"name", "annotation"})
 # it — or the fast tier's byte-identity to a full build (R1-C9) breaks on it.
 _BEHAVIORAL_EXTRAS = ("calls", "control", "complexity", "attr_access", "shadows")
 # Old edge types whose target landing in a changed/removed module makes the source
-# module stale (it must re-resolve). Only the spliced passes matter here.
-_DEP_EDGE_TYPES = frozenset({"calls", "accesses", "references"})
+# module stale (it must re-resolve). Only the spliced passes matter here — and the serve
+# layer reads the same set to know which ops answer from a spliced class (R1-C44).
+_DEP_EDGE_TYPES = SPLICED_EDGE_TYPES
 
 # Above this fraction of modules affected, a full rebuild is cheaper (and trivially
 # correct) — no point splicing most of the graph.
@@ -159,21 +160,38 @@ def _splice_unaffected(new_graph, old_graph, unaffected, module_of) -> None:
                     node.extras[k] = copy.deepcopy(old_extras[k])
 
 
-def _same_builder(provenance: dict, tier: str) -> bool:
-    """Was the old graph produced by *this* codemap, on this tier? (R1-C25)
+def _same_builder(provenance: dict, tier: str, repeat: int = 1) -> str | None:
+    """Why the old graph is *not* from this builder — ``None`` when it is (R1-C25).
 
     A graph with no provenance (pre-0.12) cannot answer, so it is treated as a
     different builder — the conservative direction: a needless full rebuild costs a
     minute, a silently stale graph costs a wrong answer.
+
+    R1-C47: the sample count is part of the builder. ``extras.seen`` on a spliced edge
+    means "k of N", and it can only mean that if N is the same N the chain has used all
+    along — a request with a different N starts a new chain from a full build.
     """
     if not provenance:
-        return False
-    return (provenance.get("tool") == tool_identity()
-            and provenance.get("tier") == tier)
+        return "builder-changed"
+    if (provenance.get("tool") != tool_identity()
+            or provenance.get("tier") != tier):
+        return "builder-changed"
+    if ((provenance.get("samples") or {}).get("runs", 1)) != repeat:
+        return "samples-changed"
+    return None
+
+
+def _full(package_path, *, deep: bool, repeat: int) -> Graph:
+    """A full build with the chain's sample count (R1-C47 / D2)."""
+    return extract(package_path, deep=deep, repeat=repeat)
+
+
+def _count_seen(graph: Graph) -> int:
+    return sum(1 for e in graph.edges if "seen" in e.extras)
 
 
 def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dict,
-                 *, deep: bool = False) -> tuple[Graph, dict]:
+                 *, deep: bool = False, repeat: int = 1) -> tuple[Graph, dict]:
     """Incrementally rebuild ``old_graph`` for the current source tree.
 
     Returns ``(graph, info)`` where ``info`` records the decision (``mode``:
@@ -186,16 +204,25 @@ def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dic
     (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``.
+
+    ``repeat=N`` (R1-C47) makes every place this path samples — the fallback full build
+    and the recompute of the affected modules — take N samples in fresh interpreters,
+    merged as a full ``--repeat`` build would be. Measured on twenty real commits: the
+    chain's misses come from single samples, not from age, so this is the remedy and a
+    periodic full rebuild is not. N must equal the old graph's ``samples.runs`` or the
+    chain restarts from a full build (``reason: samples-changed``).
     """
     target_pkg = old_graph.target
     tier = "deep" if deep else "fast"
     # R1-C25: the input is not the only thing that can change. `unchanged` below decides
     # from the source tree alone, so an upgraded codemap over an untouched tree used to
     # return yesterday's graph built by yesterday's extractor — the exact confusion the
-    # provenance block exists to name. A different tool or tier is a full rebuild.
-    if not _same_builder(old_graph.provenance, tier):
-        graph = extract(package_path, deep=deep)
-        return graph, {"mode": "full", "affected": [], "reason": "builder-changed"}
+    # provenance block exists to name. A different tool, tier or sample count is a full
+    # rebuild.
+    reason = _same_builder(old_graph.provenance, tier, repeat)
+    if reason is not None:
+        return _full(package_path, deep=deep, repeat=repeat), \
+            {"mode": "full", "affected": [], "reason": reason}
 
     d = diff_scopes(old_scope, new_scope)
     changed = {m for p in d["changed"] if (m := _path_to_module(p, target_pkg))}
@@ -218,14 +245,32 @@ def update_graph(old_graph: Graph, package_path, old_scope: dict, new_scope: dic
                                  module_of) & module_ids
 
     if not module_ids or len(affected) >= _FULL_FALLBACK_FRACTION * len(module_ids):
+        if repeat > 1:
+            # R1-C47: the fallback used to be the chain's weakest point — a 63-module
+            # commit reset a --repeat 3 chain to one sample on the replay's third tick.
+            return _full(package_path, deep=deep, repeat=repeat), \
+                {"mode": "full", "affected": sorted(affected)}
         add_behavioral_layer(graph, root, module_name, search_path, deep=deep)
         graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"))
         return graph, {"mode": "full", "affected": sorted(affected)}
 
-    add_behavioral_layer(graph, root, module_name, search_path, deep=deep,
-                         behavior_only=affected, attr_only=affected)
+    if repeat > 1:
+        # R1-C47 / D2: N fresh interpreters, each restricted to the affected modules;
+        # the structural base is rebuilt in each (deterministic, ~4 s) so the merge
+        # sees identical nodes. The spliced part keeps its own `seen` — same N (D1).
+        graph, stats = merge_samples(collect_samples(package_path, deep=deep,
+                                                     runs=repeat, only=affected))
+        graph.loaded_schema = None
+    else:
+        add_behavioral_layer(graph, root, module_name, search_path, deep=deep,
+                             behavior_only=affected, attr_only=affected)
+        stats = {"runs": 1}
     unaffected = module_ids - affected
     _splice_unaffected(graph, old_graph, unaffected, module_of)
+    if repeat > 1:
+        # `unstable` describes the artifact a reader holds, not the part this tick
+        # touched: recount over recomputed and spliced edges alike.
+        stats = {"runs": repeat, "unstable": _count_seen(graph)}
     graph.provenance = build_provenance(tier=tier, inputs=graph.provenance.get("inputs"),
-                                        incremental=True)
+                                        incremental=True, samples=stats)
     return graph, {"mode": "incremental", "affected": sorted(affected)}

{codmap-0.0.11 → codmap-0.0.12}/codemap/model.py

@@ -97,6 +97,13 @@ EDGE_TYPES = frozenset({
     "accesses",       # function → attribute node it reads/writes (extras.access, R1-C20)
 })
 
+# The subset of EDGE_TYPES an incremental build splices from the old graph for modules
+# it did not recompute (``incremental.py``) — and therefore the classes a deep+incremental
+# graph answers from an *earlier* build's jedi sample (R1-C43). Lives with the vocabulary
+# because two layers that may not import each other need it: the extractor's union
+# (R1-C45) and the serve layer, which derives from it which ops must say so (R1-C44 / D4).
+SPLICED_EDGE_TYPES = frozenset({"calls", "accesses", "references"})
+
 
 @dataclass
 class Node:

{codmap-0.0.11 → codmap-0.0.12}/codemap/query.py

@@ -696,6 +696,14 @@ class Query:
                "by_distance": by_distance, "max_distance": max_distance,
                "risk": self._impact_risk(len(refs), max_distance, len(by_root),
                                          kind=kind)}
+        # R1-C44 / D1: a symbol the graph does not hold has no blast radius to report —
+        # `none` here used to be an affirmative "nothing depends on it" about a name the
+        # tool had never seen (a typo, another tree, a copy under another directory name).
+        if node is None:
+            out["risk"] = "unknown"
+            out["risk_reason"] = ("symbol not in graph — nothing is known about it; "
+                                  "this is not an empty blast radius")
+            return out
         # Honesty (R1-C20 P0, issue #1): a field with no modelled accessor is a
         # *lower bound*, not proof of safety — attribute access resolution is
         # best-effort. Say so instead of the affirmative "none".

{codmap-0.0.11 → codmap-0.0.12}/codemap/serve/impact.py

@@ -22,7 +22,9 @@ def render_impact(query: Query, symbol: str, *, depth: int = 2) -> str:
     )
     lines.append("")
     if not ids:
-        lines.append(f"_No definition found for `{symbol}`._")
+        lines.append(f"_No definition found for `{symbol}` — nothing is known about it; "
+                     "this is not an empty blast radius. Check the name (ids start with "
+                     "the package directory's name)._")
         return "\n".join(lines) + "\n"
 
     for sid in ids:

{codmap-0.0.11 → codmap-0.0.12}/codemap/serve/session.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 
 from collections import Counter
 
-from codemap.model import SCHEMA_VERSION, Graph
+from codemap.model import SCHEMA_VERSION, SPLICED_EDGE_TYPES as _SPLICED_EDGE_TYPES, Graph
 from codemap.query import Query
 from codemap.serve.api_surface import render_api_surface
 from codemap.serve.architecture import build_architecture, render_architecture
@@ -40,13 +40,61 @@ _REPORTS = {
 # disclaimers). Absence of the label = structural/complete (imports, contains,
 # inherits, exports — exact). One label per answer (no per-edge confidence: edges
 # already carry `resolution`). From the GitNexus разбор, built natively.
-_PARTIAL_OPS = frozenset({"callers", "callees", "impact", "flows", "call_contract",
-                          "tests", "covers"})
+# R1-C44 / D4: which edge classes each relational op reads. Two sets are *derived* from
+# this table instead of being listed by hand, so that adding an op — or adding an edge
+# class to the incremental splice — forces a decision here rather than a silent gap:
+#   `_PARTIAL_OPS`  — ops that lean on best-effort static resolution (calls, accesses),
+#                     and so answer a lower bound (R1-C13);
+#   `_SPLICE_OPS`   — ops that read a class the incremental build splices from the old
+#                     graph, and so on a deep+incremental graph read the *earlier* build's
+#                     jedi sample (R1-C43).
+# `accessors` used to be in neither — it reads `accesses`, modelled best-effort, and
+# carried no `epistemic` at all (found by the R1-C44 measurement).
+_OP_EDGE_CLASSES = {
+    "callers": frozenset({"calls"}),
+    "callees": frozenset({"calls"}),
+    "call_contract": frozenset({"calls"}),
+    "flows": frozenset({"calls"}),
+    "impact": frozenset({"calls", "references", "accesses"}),
+    "accessors": frozenset({"accesses"}),
+    "tests": frozenset({"calls", "references"}),
+    "covers": frozenset({"calls", "references"}),
+}
+_BEST_EFFORT_CLASSES = frozenset({"calls", "accesses"})
+_PARTIAL_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
+                         if cls & _BEST_EFFORT_CLASSES)
+_SPLICE_OPS = frozenset(op for op, cls in _OP_EDGE_CLASSES.items()
+                        if cls & _SPLICED_EDGE_TYPES)
 _EPISTEMIC_PARTIAL = {
     "epistemic": "partial",
-    "reason": "leans on static call resolution (partial for Python) — a lower "
-              "bound; pair with grep/tests before acting.",
+    "reason": "leans on static resolution of calls and attribute accesses (partial "
+              "for Python) — a lower bound; pair with grep/tests before acting.",
 }
+# D4 — the second reason, named separately: "a lower bound by static resolution" and
+# "part of this graph was carried over, not recomputed" are different facts.
+_EPISTEMIC_SPLICE = (
+    "parts of this deep graph were carried over from an earlier build rather than "
+    "recomputed (provenance.incremental: true), and this op reads edge classes the "
+    "splice copies — a missing edge here may be the earlier build's jedi miss, and "
+    "rebuilding incrementally will not resample it; only a full build (or --repeat) does."
+)
+# D5 — a graph older than the field: say what is not known, not more.
+_EPISTEMIC_SPLICE_UNKNOWN = (
+    "this deep graph predates provenance.incremental, so whether parts of it were "
+    "carried over from an earlier build is unknown; this op reads edge classes an "
+    "incremental build would splice."
+)
+
+
+def _not_found(name_or_id: str) -> dict:
+    """The resolution block for a symbol the graph does not hold (R1-C44 / D1).
+
+    ``ok`` stays true — the question was well-formed and this *is* the answer. What
+    must not happen is the answer being indistinguishable from "found, and nothing
+    references it": that envelope used to be byte-identical for both.
+    """
+    return {"input": name_or_id, "id": None, "found": False,
+            "ambiguous": False, "alternatives": []}
 
 # R1-C28: ops that cut a computed answer down to a limit. Orthogonal to _PARTIAL_OPS
 # — that one is about how well calls *resolve*; this one is about how much of the
@@ -132,6 +180,13 @@ def tool_drift(running: str | None, installed: str | None) -> dict | None:
 def build_query_result(q: Query, name: str) -> dict:
     """The full symbol dossier — shared by ``codemap query`` and warm serve."""
     matches = q.find(name)
+    if not matches:
+        # R1-C44 (the F23 gap, on this surface): `find` matches short names only, so the
+        # full id an agent gets back from `search` used to open an *empty* dossier here.
+        # Resolve it the way every relational op does before concluding "no such symbol".
+        info = q.canonical_info(name)
+        if info:
+            matches = [q.graph.nodes[info["id"]]]
     result: dict = {
         "name": name,
         "defined_at": q.where_defined(name),
@@ -233,7 +288,10 @@ class Session:
         warning when a bare short name resolved to one of many defs arbitrarily.
         """
         info = self.query.canonical_info(name_or_id)
-        self._resolution = info
+        # R1-C44 / D2: `canonical_info` computes "no such symbol" as None, and this
+        # method used to drop it on the floor — the raw input went on to be looked up
+        # in the graph and answered with an honest-looking empty list.
+        self._resolution = {**info, "found": True} if info else _not_found(name_or_id)
         return info["id"] if info else name_or_id
 
     # -- dispatch ------------------------------------------------------------
@@ -263,14 +321,35 @@ class Session:
         except Exception as exc:  # a bad arg must not kill the resident process
             return {"ok": False, "error": f"{type(exc).__name__}: {exc}"}
         r = self._resolution
-        if r and (r["ambiguous"] or r["input"] != r["id"]):
-            env["resolved"] = r
+        # R1-C44 / D2: three-way, not a truthiness test. "not found" is the one case the
+        # block exists for and was the one case `if r and …` threw away.
+        if r is not None:
+            if not r["found"]:
+                env["resolved"] = r
+            elif r["ambiguous"] or r["input"] != r["id"]:
+                env["resolved"] = r
         if op in _PARTIAL_OPS:  # R1-C13: machine-readable "this is a lower bound"
-            env["epistemic"] = _EPISTEMIC_PARTIAL
+            env["epistemic"] = self._epistemic(op)
         if self._limit is not None:  # R1-C28: how much of the answer survived the cut
             env["limit"] = self._limit
         return env
 
+    def _epistemic(self, op: str) -> dict:
+        """The lower-bound block for ``op``, with the splice reason when it applies (D4/D5).
+
+        Conditioned on the graph *and* the op: only a deep graph can carry a frozen
+        sample, and only an op reading a spliced class reads it. On a full deep graph
+        and on the fast tier the block is exactly the R1-C13 one.
+        """
+        block = dict(_EPISTEMIC_PARTIAL)
+        prov = self.graph.provenance or {}
+        if op in _SPLICE_OPS and prov.get("tier") == "deep":
+            if prov.get("incremental") is True:
+                block["splice"] = _EPISTEMIC_SPLICE
+            elif "incremental" not in prov:
+                block["splice"] = _EPISTEMIC_SPLICE_UNKNOWN
+        return block
+
     # -- ops (each takes an args dict) ---------------------------------------
 
     def _op_ping(self, args) -> str:
@@ -355,12 +434,17 @@ class Session:
         return out
 
     def _op_query(self, args) -> dict:
-        return build_query_result(self.query, args["name"])
+        result = build_query_result(self.query, args["name"])
+        if not result["matches"]:  # R1-C44: an empty dossier says why it is empty
+            self._resolution = _not_found(args["name"])
+        return result
 
     def _op_impact(self, args) -> dict:
         sym = args["symbol"]
         depth = int(args.get("depth", 2))
         ids = self.query.impact_targets(sym)  # F23: accept full id / re-export too
+        if not ids:  # R1-C44: this op resolves on its own, so it records on its own
+            self._resolution = _not_found(sym)
         return {
             "symbol": sym,
             "impact": [self.query.impact(sid, depth=depth) for sid in ids],

{codmap-0.0.11 → codmap-0.0.12/codmap.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.11
+Version: 0.0.12
 Summary: Static analyzer that turns a package's source into a queryable code graph.
 Author-email: kogriv <kogriv@gmail.com>
 License-Expression: MIT
@@ -161,7 +161,7 @@ Optional extras: `mcp` (Model Context Protocol server), `scip` (protobuf, for SC
 ## Quickstart
 
 ```bash
-# build the canonical graph of a package
+# build the canonical graph of a package (its directory name is the package name every id starts with)
 codemap build ./yourpkg -o graph.json
 
 # repo-scoped: add consumers (tests/examples) + docs for blast-radius/impact
@@ -271,8 +271,10 @@ unstable among 13 675). So one build misses such an edge about 1 time in 4, two
 1 in 64. `codemap build --deep --repeat N` builds N samples — each in a fresh interpreter, the
 regime the share was measured in; in-process repeats come in correlated streaks — and unions them: an edge seen in fewer
 than N runs carries `extras.seen`, `provenance.samples` records N and how many edges varied, and the
-note on the graph says both. Refused out loud on the fast tier (byte-stable already) and together with
-`--incremental` (a spliced graph cannot be resampled).
+note on the graph says both. Refused out loud on the fast tier (byte-stable already). With `--incremental`
+and `watch`, N becomes a property of the chain and every place the chain samples — base, fallback, each
+tick's recompute — samples N times; measured on twenty real commits, that is what removes the chain's misses,
+and a periodic full rebuild does not.
 
 **Measurement:** [gaps/deep_tier_nondeterminism_2026-09-02.md](gaps/deep_tier_nondeterminism_2026-09-02.md),
 [gaps/deep_tier_union_by_repeat_2026-09-04.md](gaps/deep_tier_union_by_repeat_2026-09-04.md).

{codmap-0.0.11 → codmap-0.0.12}/codmap.egg-info/SOURCES.txt

@@ -112,8 +112,10 @@ 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_r1c44_absent_answers.py
 tests/test_r1c45_repeat_union.py
 tests/test_r1c46_shadowed_definitions.py
+tests/test_r1c47_incremental_resample.py
 tests/test_r1c4_complexity.py
 tests/test_r1c5_apidiff.py
 tests/test_r1c6_pack.py

{codmap-0.0.11 → codmap-0.0.12}/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.11"
+version = "0.0.12"
 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