codmap 0.0.3__tar.gz → 0.0.4__tar.gz

{codmap-0.0.3/codmap.egg-info → codmap-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codmap
-Version: 0.0.3
+Version: 0.0.4
 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.12, **530 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 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 &
@@ -61,6 +61,73 @@ Design principles: **source-only** (static `ast`/`griffe`, never imports the tar
 (canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
 codes), **honest** (approximations are labeled, not hidden).
 
+## Point questions and whole-graph questions
+
+Most code-intelligence tools answer **point questions** — you name a symbol and they walk outward a
+few steps. *Where is this defined? Who calls it? What breaks if I change it?* The answer's cost
+scales with the neighbourhood, not the repository, which is why an index or a vector store can serve
+it. The field is good at this, and several tools are faster at it than codemap.
+
+**Whole-graph questions** have no starting symbol, because the property being asked about belongs to
+the graph and to no node in it:
+
+> Is there a dependency cycle anywhere? · Which module is most expensive to change? · Does the code
+> still respect the layering I intended? · Where has behaviour concentrated into one class?
+
+A cycle is invisible from inside every file that participates in it — each one looks perfectly
+reasonable alone. You cannot seed the question, and there is no partial answer.
+`codemap report architecture` computes all of them in one pass; on the dogfood target (88 modules,
+**715 import edges**) that is:
+
+```
+layers         core 9 · data 12 · indicators 16 · analysis 42 · visualization 7 · cli 1
+               analysis → core 38 edges · indicators → core 22 · data → core 13
+violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
+cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
+lazy cycles    40 more, closed only by a function-local import — not import-time failures,
+               still mutual coupling: neither module can be extracted without the other
+coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
+concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5
+```
+
+That single layer violation is worth its line: it is reached only through an import written *inside a
+function*, so until [R1-C29](gaps/import_map_module_level_2026-08-28.md) codemap could not see it and
+reported the architecture as clean. A gate you can walk around by making the import lazy is not a gate.
+
+Then [`codemap check`](docs/architecture-contracts.md) turns the shape you *want* into a CI gate, so
+description and intent cannot drift apart.
+
+Four rival tools have now been measured hands-on on the same benchmark scope — three of them on
+byte-identical input verified by content hash, the fourth (graphlens) on a near-identical staging that
+predates the harness — including the field's most-adopted tool at 68k stars. **All four answer the point
+questions. None answers these on a surface a caller can reach** — nor the related "how does each caller
+actually *pass* its arguments" (`call_contract`) — because a slice of source is the wrong shape for the
+answer.
+
+That sentence used to end at "None answers these", and a second pass over the 68k-star tool made it
+narrower: its *importable library* does carry a cycle finder, reachable from neither its CLI nor its MCP
+tools and called nowhere in its own source. Measured on the same tree it reports **136 cycles**; codemap
+reports **1**. Scoring both against the truth set — every intra-package import, function-local ones
+included — is less flattering than that sounds:
+
+| | reported | of the 41 real ones | precision | recall |
+|---|---:|---:|---:|---:|
+| codemap, that morning | 1 | 1 | 100% | **2.4%** |
+| the peer's library API | 136 | 13 | 10% | 32% |
+| codemap, after R1-C29 | 41 | 41 | 100% | 100% |
+
+Theirs over-reports because it walks name-resolved call edges — a `dict.get` becomes a call into an
+unrelated class. **Ours under-reported because its import map was module-level only**, and it phrased
+that as *"import graph is acyclic"* — a property claim over a partial map, which is the worse of the two
+errors even though it was the smaller one. Both halves of that came from
+[#11](https://github.com/kogriv/codemap/issues/11), filed off a different target and fixed the same day
+([R1-C29](gaps/import_map_module_level_2026-08-28.md)). The lesson is sharper than the win: a
+whole-graph answer inherits every flaw of the graph it is computed from, **including the edges that
+graph never read** — and the tool cannot be the judge of its own recall.
+
+**→ [docs/whole-graph-questions.md](docs/whole-graph-questions.md)** — the full argument, every number
+above reproduced from one run, and the honest limits.
+
 ## Install
 
 **Python 3.11+** — the range is measured on 3.11–3.14 in CI, not assumed ([docs/ci.md](docs/ci.md)).
@@ -79,11 +146,7 @@ pip install 'codmap[mcp]'
 pip install 'codmap[scip]'
 ```
 
-Until the first release lands on PyPI, install straight from the repository instead:
-
-```bash
-pip install git+https://github.com/kogriv/codemap
-```
+Or straight from source: `pip install git+https://github.com/kogriv/codemap`.
 
 Working on codemap itself, from a clone:
 
@@ -111,6 +174,7 @@ codemap report architecture   --graph graph.json   # layers, coupling, god-objec
 codemap report dependencies   --graph graph.json
 codemap report dead-code      --graph graph.json
 codemap report impact --symbol MyClass --graph graph.json
+codemap report api-surface --graph graph.json --format json   # every kind has a json form
 
 # change-set review straight from a diff → risk-sorted dossier
 git diff | codemap review - --graph graph.json
@@ -128,11 +192,15 @@ codemap semantic "detect swing pivots" --build ./pkg --root pkg
 # token-budgeted context pack — most relevant graph slice under N tokens (ranked; --seed to focus)
 codemap pack --graph graph.json --budget 2000 --seed analyze_zones
 
-# warm resident process — JSON requests over stdin/stdout (29 ops)
+# warm resident process — JSON requests over stdin/stdout (31 ops)
 codemap serve --graph graph.json --source-root .
 
 # …or expose the same surface as MCP tools for an AI-agent host (needs [mcp] extra)
 codemap serve --graph graph.json --source-root . --mcp
+
+# keep it current while you work: source → incremental rebuild → the warm server reloads
+codemap watch ./pkg -o graph.json &
+codemap serve --graph graph.json --watch
 ```
 
 ## What it answers
@@ -167,6 +235,12 @@ The [research track](research/) measures this against the field hands-on, on a s
 [positioning doc](research/positioning.md) is the publication layer — the narrative and the numbers behind the
 claims above; [comparison.md](research/comparison.md) is the coverage matrix that backs them.
 
+Where the comparison actually lands, after four hands-on cards: peers are **faster**, cover **more
+languages**, and several are **easier to install**. What none of them answers is the whole-graph
+class — architecture, layers, cycles, coupling — and per-call argument contracts. That is the
+substance behind "complements rather than competes", written out in
+**[docs/whole-graph-questions.md](docs/whole-graph-questions.md)**.
+
 Honesty is part of the bet: the call graph is a **measured lower bound**, not a guess. [docs/accuracy.md](docs/accuracy.md)
 reports it — 100% precision / 100% decidable-recall on a hand-labeled suite, an openly-stated ~60% recall
 against *all* true edges (the price of Python's dynamism), and a grep-vs-graph proof that the graph is ~2×
@@ -184,6 +258,9 @@ the live graph, findings, and the milestone that closed them.
 ## Documentation
 
 - **[DESIGN.md](DESIGN.md)** — product design, the query catalog, v1 boundaries.
+- **[docs/whole-graph-questions.md](docs/whole-graph-questions.md)** — **start here for what codemap is
+  *for*.** Point questions vs whole-graph questions, why the field answers only the first class, the
+  five questions codemap answers with a real run behind each, and the honest limits.
 - **[docs/export.md](docs/export.md)** — export recipes: RAG, mermaid, Obsidian vault, SCIP + ctags interop.
 - **[docs/accuracy.md](docs/accuracy.md)** — measured call-graph accuracy, the honest static ceiling, and
   the grep-vs-graph value proof (both harnesses guarded in CI).
@@ -200,7 +277,9 @@ the live graph, findings, and the milestone that closed them.
 - **[docs/attribute-edges.md](docs/attribute-edges.md)** — `accesses` edges: who reads/writes a class field,
   honest field-level `impact` (`accessors`; `unknown` vs `none`).
 - **[docs/incremental.md](docs/incremental.md)** — `codemap build --incremental`: recompute only changed
-  modules (~12× faster on `--deep`), byte-identical on the fast tier.
+  modules (~12× faster on `--deep`), byte-identical on the fast tier; plus the automatic
+  `codemap watch` + `serve --watch` loop (save → answerable in ~8 s on a real package at the defaults,
+  of which 4.3 s is the rebuild).
 - **[docs/test-mapping.md](docs/test-mapping.md)** — `codemap tests <symbol>`: which tests exercise a
   symbol, as runnable pytest node ids, with the measured distance cutoff and an `unknown` that never
   pretends to be "untested".
@@ -235,8 +314,10 @@ tools. Published here in the repo; every post exists in English and Russian.
 | 2 | **The one that does more — and why that's fine.** — a 1.7 GB hybrid rival that proved the thesis instead of threatening it. | [EN](research/blog/02-the-one-that-does-more.md) · [RU](research/blog/02-the-one-that-does-more.ru.md) |
 | 3 | **The competitor that does *less* — and that's why I take it.** — the emptiest coverage row was the most useful find. For its license, not its features. | [EN](research/blog/03-the-one-that-does-less.md) · [RU](research/blog/03-the-one-that-does-less.ru.md) |
 | 4 | **My determinism test went red. The tool was fine.** — the input was moving under it, and the artifact could not say so. How the graph learned to name what built it. | [EN](research/blog/04-the-determinism-test-that-was-right.md) · [RU](research/blog/04-the-determinism-test-that-was-right.ru.md) |
+| 5 | **A month of dogfooding. Then one more repository found seven bugs in two days.** — eleven pre-registered axes, all asked of one tree. What was missing was not an angle but a shape. | [EN](research/blog/05-the-second-repository.md) · [RU](research/blog/05-the-second-repository.ru.md) |
+| 6 | **I measured the 68,000-star competitor. It was faster than mine. That wasn't the finding.** — four rivals, and the same two columns empty in all of them. | [EN](research/blog/06-two-empty-columns.md) · [RU](research/blog/06-two-empty-columns.ru.md) |
 
-New here? Read **1 → 0 → 2 → 3 → 4**. Every number in every post reproduces from a
+New here? Read **1 → 0 → 2 → 3 → 4 → 5 → 6**. Every number in every post reproduces from a
 [tool card](research/tools/) or the [comparison hub](research/comparison.md) — measurements,
 not verdict.
 

{codmap-0.0.3 → codmap-0.0.4}/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.12, **530 tests with no failures on
+**Status:** 🟢 M0–M20 implemented + research track (R1/R2) — schema 0.13, **655 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 &
@@ -25,6 +25,73 @@ Design principles: **source-only** (static `ast`/`griffe`, never imports the tar
 (canonical sorted JSON, no timestamps — diffable), **CLI-AI-first** (JSON by default, stable exit
 codes), **honest** (approximations are labeled, not hidden).
 
+## Point questions and whole-graph questions
+
+Most code-intelligence tools answer **point questions** — you name a symbol and they walk outward a
+few steps. *Where is this defined? Who calls it? What breaks if I change it?* The answer's cost
+scales with the neighbourhood, not the repository, which is why an index or a vector store can serve
+it. The field is good at this, and several tools are faster at it than codemap.
+
+**Whole-graph questions** have no starting symbol, because the property being asked about belongs to
+the graph and to no node in it:
+
+> Is there a dependency cycle anywhere? · Which module is most expensive to change? · Does the code
+> still respect the layering I intended? · Where has behaviour concentrated into one class?
+
+A cycle is invisible from inside every file that participates in it — each one looks perfectly
+reasonable alone. You cannot seed the question, and there is no partial answer.
+`codemap report architecture` computes all of them in one pass; on the dogfood target (88 modules,
+**715 import edges**) that is:
+
+```
+layers         core 9 · data 12 · indicators 16 · analysis 42 · visualization 7 · cli 1
+               analysis → core 38 edges · indicators → core 22 · data → core 13
+violation    ⚠ analysis ↔ core             — one backward edge, written inside a function
+cycle          pipeline → cache → pipeline  — the classic Python import-order landmine
+lazy cycles    40 more, closed only by a function-local import — not import-time failures,
+               still mutual coupling: neither module can be extracted without the other
+coupling       core.logging_config  Ca 96   — a breaking change here reaches 96 modules
+concentration  ZoneVisualizer 35 methods, worst function CC 66 / MI 12.5
+```
+
+That single layer violation is worth its line: it is reached only through an import written *inside a
+function*, so until [R1-C29](gaps/import_map_module_level_2026-08-28.md) codemap could not see it and
+reported the architecture as clean. A gate you can walk around by making the import lazy is not a gate.
+
+Then [`codemap check`](docs/architecture-contracts.md) turns the shape you *want* into a CI gate, so
+description and intent cannot drift apart.
+
+Four rival tools have now been measured hands-on on the same benchmark scope — three of them on
+byte-identical input verified by content hash, the fourth (graphlens) on a near-identical staging that
+predates the harness — including the field's most-adopted tool at 68k stars. **All four answer the point
+questions. None answers these on a surface a caller can reach** — nor the related "how does each caller
+actually *pass* its arguments" (`call_contract`) — because a slice of source is the wrong shape for the
+answer.
+
+That sentence used to end at "None answers these", and a second pass over the 68k-star tool made it
+narrower: its *importable library* does carry a cycle finder, reachable from neither its CLI nor its MCP
+tools and called nowhere in its own source. Measured on the same tree it reports **136 cycles**; codemap
+reports **1**. Scoring both against the truth set — every intra-package import, function-local ones
+included — is less flattering than that sounds:
+
+| | reported | of the 41 real ones | precision | recall |
+|---|---:|---:|---:|---:|
+| codemap, that morning | 1 | 1 | 100% | **2.4%** |
+| the peer's library API | 136 | 13 | 10% | 32% |
+| codemap, after R1-C29 | 41 | 41 | 100% | 100% |
+
+Theirs over-reports because it walks name-resolved call edges — a `dict.get` becomes a call into an
+unrelated class. **Ours under-reported because its import map was module-level only**, and it phrased
+that as *"import graph is acyclic"* — a property claim over a partial map, which is the worse of the two
+errors even though it was the smaller one. Both halves of that came from
+[#11](https://github.com/kogriv/codemap/issues/11), filed off a different target and fixed the same day
+([R1-C29](gaps/import_map_module_level_2026-08-28.md)). The lesson is sharper than the win: a
+whole-graph answer inherits every flaw of the graph it is computed from, **including the edges that
+graph never read** — and the tool cannot be the judge of its own recall.
+
+**→ [docs/whole-graph-questions.md](docs/whole-graph-questions.md)** — the full argument, every number
+above reproduced from one run, and the honest limits.
+
 ## Install
 
 **Python 3.11+** — the range is measured on 3.11–3.14 in CI, not assumed ([docs/ci.md](docs/ci.md)).
@@ -43,11 +110,7 @@ pip install 'codmap[mcp]'
 pip install 'codmap[scip]'
 ```
 
-Until the first release lands on PyPI, install straight from the repository instead:
-
-```bash
-pip install git+https://github.com/kogriv/codemap
-```
+Or straight from source: `pip install git+https://github.com/kogriv/codemap`.
 
 Working on codemap itself, from a clone:
 
@@ -75,6 +138,7 @@ codemap report architecture   --graph graph.json   # layers, coupling, god-objec
 codemap report dependencies   --graph graph.json
 codemap report dead-code      --graph graph.json
 codemap report impact --symbol MyClass --graph graph.json
+codemap report api-surface --graph graph.json --format json   # every kind has a json form
 
 # change-set review straight from a diff → risk-sorted dossier
 git diff | codemap review - --graph graph.json
@@ -92,11 +156,15 @@ codemap semantic "detect swing pivots" --build ./pkg --root pkg
 # token-budgeted context pack — most relevant graph slice under N tokens (ranked; --seed to focus)
 codemap pack --graph graph.json --budget 2000 --seed analyze_zones
 
-# warm resident process — JSON requests over stdin/stdout (29 ops)
+# warm resident process — JSON requests over stdin/stdout (31 ops)
 codemap serve --graph graph.json --source-root .
 
 # …or expose the same surface as MCP tools for an AI-agent host (needs [mcp] extra)
 codemap serve --graph graph.json --source-root . --mcp
+
+# keep it current while you work: source → incremental rebuild → the warm server reloads
+codemap watch ./pkg -o graph.json &
+codemap serve --graph graph.json --watch
 ```
 
 ## What it answers
@@ -131,6 +199,12 @@ The [research track](research/) measures this against the field hands-on, on a s
 [positioning doc](research/positioning.md) is the publication layer — the narrative and the numbers behind the
 claims above; [comparison.md](research/comparison.md) is the coverage matrix that backs them.
 
+Where the comparison actually lands, after four hands-on cards: peers are **faster**, cover **more
+languages**, and several are **easier to install**. What none of them answers is the whole-graph
+class — architecture, layers, cycles, coupling — and per-call argument contracts. That is the
+substance behind "complements rather than competes", written out in
+**[docs/whole-graph-questions.md](docs/whole-graph-questions.md)**.
+
 Honesty is part of the bet: the call graph is a **measured lower bound**, not a guess. [docs/accuracy.md](docs/accuracy.md)
 reports it — 100% precision / 100% decidable-recall on a hand-labeled suite, an openly-stated ~60% recall
 against *all* true edges (the price of Python's dynamism), and a grep-vs-graph proof that the graph is ~2×
@@ -148,6 +222,9 @@ the live graph, findings, and the milestone that closed them.
 ## Documentation
 
 - **[DESIGN.md](DESIGN.md)** — product design, the query catalog, v1 boundaries.
+- **[docs/whole-graph-questions.md](docs/whole-graph-questions.md)** — **start here for what codemap is
+  *for*.** Point questions vs whole-graph questions, why the field answers only the first class, the
+  five questions codemap answers with a real run behind each, and the honest limits.
 - **[docs/export.md](docs/export.md)** — export recipes: RAG, mermaid, Obsidian vault, SCIP + ctags interop.
 - **[docs/accuracy.md](docs/accuracy.md)** — measured call-graph accuracy, the honest static ceiling, and
   the grep-vs-graph value proof (both harnesses guarded in CI).
@@ -164,7 +241,9 @@ the live graph, findings, and the milestone that closed them.
 - **[docs/attribute-edges.md](docs/attribute-edges.md)** — `accesses` edges: who reads/writes a class field,
   honest field-level `impact` (`accessors`; `unknown` vs `none`).
 - **[docs/incremental.md](docs/incremental.md)** — `codemap build --incremental`: recompute only changed
-  modules (~12× faster on `--deep`), byte-identical on the fast tier.
+  modules (~12× faster on `--deep`), byte-identical on the fast tier; plus the automatic
+  `codemap watch` + `serve --watch` loop (save → answerable in ~8 s on a real package at the defaults,
+  of which 4.3 s is the rebuild).
 - **[docs/test-mapping.md](docs/test-mapping.md)** — `codemap tests <symbol>`: which tests exercise a
   symbol, as runnable pytest node ids, with the measured distance cutoff and an `unknown` that never
   pretends to be "untested".
@@ -199,8 +278,10 @@ tools. Published here in the repo; every post exists in English and Russian.
 | 2 | **The one that does more — and why that's fine.** — a 1.7 GB hybrid rival that proved the thesis instead of threatening it. | [EN](research/blog/02-the-one-that-does-more.md) · [RU](research/blog/02-the-one-that-does-more.ru.md) |
 | 3 | **The competitor that does *less* — and that's why I take it.** — the emptiest coverage row was the most useful find. For its license, not its features. | [EN](research/blog/03-the-one-that-does-less.md) · [RU](research/blog/03-the-one-that-does-less.ru.md) |
 | 4 | **My determinism test went red. The tool was fine.** — the input was moving under it, and the artifact could not say so. How the graph learned to name what built it. | [EN](research/blog/04-the-determinism-test-that-was-right.md) · [RU](research/blog/04-the-determinism-test-that-was-right.ru.md) |
+| 5 | **A month of dogfooding. Then one more repository found seven bugs in two days.** — eleven pre-registered axes, all asked of one tree. What was missing was not an angle but a shape. | [EN](research/blog/05-the-second-repository.md) · [RU](research/blog/05-the-second-repository.ru.md) |
+| 6 | **I measured the 68,000-star competitor. It was faster than mine. That wasn't the finding.** — four rivals, and the same two columns empty in all of them. | [EN](research/blog/06-two-empty-columns.md) · [RU](research/blog/06-two-empty-columns.ru.md) |
 
-New here? Read **1 → 0 → 2 → 3 → 4**. Every number in every post reproduces from a
+New here? Read **1 → 0 → 2 → 3 → 4 → 5 → 6**. Every number in every post reproduces from a
 [tool card](research/tools/) or the [comparison hub](research/comparison.md) — measurements,
 not verdict.
 

codmap-0.0.4/codemap/__init__.py

@@ -0,0 +1,17 @@
+"""codemap — static code-graph builder.
+
+Pipeline: Extract (griffe) -> Build (neutral model) -> Store (JSON) -> Serve (reports).
+See DESIGN.md.
+"""
+
+from codemap.model import Edge, Graph, Node
+from codemap.provenance import tool_version
+
+__all__ = ["Graph", "Node", "Edge"]
+
+#: Read from the installed distribution rather than written down, because it had been
+#: written down and had drifted: this said ``0.0.2`` while `codmap` 0.0.3 was on PyPI, so
+#: every SCIP index and ctags file stamped a version the package had not been for a
+#: release. `provenance` was already asking `importlib.metadata`, which is why graphs were
+#: right and these two exports were not — one source now, and nothing left to drift.
+__version__ = tool_version() or "0+unknown"

{codmap-0.0.3 → codmap-0.0.4}/codemap/arch.py

@@ -16,8 +16,11 @@ integration gate reads). All rules operate on the **core** module import graph
     independent = [["indicators", "data"]]
     # hard bans regardless of layering: `from` must not import `to`.
     forbidden = [{ from = "core", to = "analysis" }]
-    # the import graph must be acyclic.
+    # the import graph must be acyclic *at import time* (the eager graph).
     no_cycles = true
+    # also gate the coupling a lazy import hides: cycles closed only by an import
+    # written inside a function. Off by default — see below.
+    no_lazy_cycles = false
     # every core module's layer must appear in `layers` (catches a new,
     # undeclared top-level package slipping in).
     exhaustive = false
@@ -50,19 +53,21 @@ class ArchitectureContract:
     independent: tuple[tuple[str, ...], ...] = ()
     forbidden: tuple[tuple[str, str], ...] = ()
     no_cycles: bool = False
+    no_lazy_cycles: bool = False
     exhaustive: bool = False
     error: str | None = None
 
     def is_empty(self) -> bool:
         return not (self.layers or self.independent or self.forbidden
-                    or self.no_cycles or self.exhaustive)
+                    or self.no_cycles or self.no_lazy_cycles or self.exhaustive)
 
 
 @dataclass(frozen=True)
 class Violation:
     """One broken rule, with the concrete import edges (or cycle) that break it."""
 
-    rule: str            # layered | independent | forbidden | no_cycles | exhaustive
+    rule: str            # layered | independent | forbidden | no_cycles | no_lazy_cycles
+    #                      | exhaustive
     summary: str         # human one-liner
     edges: tuple[tuple[str, str], ...] = field(default=())   # offending (importer, imported)
     modules: tuple[str, ...] = field(default=())             # for exhaustive / cycles
@@ -97,6 +102,7 @@ def parse_contract(section: dict) -> ArchitectureContract:
         independent=independent,
         forbidden=tuple(forbidden),
         no_cycles=bool(section.get("no_cycles", False)),
+        no_lazy_cycles=bool(section.get("no_lazy_cycles", False)),
         exhaustive=bool(section.get("exhaustive", False)),
     )
 
@@ -160,7 +166,18 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
                 edges=tuple(sorted(bad)),
             ))
 
-    # -- no_cycles: import graph must be acyclic --------------------------------
+    # -- no_cycles: no cycle among imports that run at import time ---------------
+    # R1-C29: deliberately the eager graph. `no_cycles` is a gate against the import-order
+    # failure, and a function-local import is the accepted fix for it — failing a build
+    # because someone applied that fix would punish the remedy.
+    #
+    # R1-C30-f2 settles what §7 of gaps/import_map_module_level_2026-08-28.md left open,
+    # after the second real target ran the gate: what it must NOT do is *stay silent*. A
+    # clean `no_cycles` run on a tree with 48 lazy cycles printed "Contract satisfied.
+    # Rules enforced: no_cycles", from which a reader concludes the graph is acyclic — the
+    # same property claim over a partial judgement that R1-C29 removed from the report,
+    # migrated into the gate. So: the gate stays eager, the *disclosure* is mandatory (see
+    # `build_check`), and a contract that wants the coupling gated says so.
     if contract.no_cycles:
         cycles = query.import_cycles()
         if cycles:
@@ -171,6 +188,20 @@ def check_contract(query, contract: ArchitectureContract) -> list[Violation]:
                 modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
             ))
 
+    # -- no_lazy_cycles: opt in to gating the coupling a lazy import hides -------
+    # Both facts are true at once — a gate you walk around by making the import lazy is
+    # not a gate, and a lazy import is the accepted way to break an import cycle — so this
+    # is the contract owner's call to state, not a default to pick on their behalf.
+    if contract.no_lazy_cycles:
+        lazy = query.lazy_import_cycles()
+        if lazy:
+            worst = sorted(lazy, key=lambda c: (len(c), c))
+            violations.append(Violation(
+                "no_lazy_cycles",
+                f"{len(lazy)} dependency cycle(s) closed only by a function-local import",
+                modules=tuple(" → ".join(c) + " → " + c[0] for c in worst),
+            ))
+
     # -- exhaustive: every core module's layer must be declared -----------------
     if contract.exhaustive and contract.layers:
         declared = set(contract.layers)