codegraph-brain 0.17.0__tar.gz → 0.18.0__tar.gz

codegraph_brain-0.18.0/.github/test-count-baseline

@@ -0,0 +1 @@
+2264

codegraph_brain-0.18.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.18.0"
+}

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [0.18.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.17.0...codegraph-brain-v0.18.0) (2026-09-06)
+
+
+### Features
+
+* **extractors:** a class named as a value is a reference (D10, [#415](https://github.com/zaebee/codegraph-brain/issues/415)) ([#430](https://github.com/zaebee/codegraph-brain/issues/430)) ([aea4076](https://github.com/zaebee/codegraph-brain/commit/aea4076b45d0761f50bb989936e89c8054402372))
+* **extractors:** a decorator's arguments are edges, and a decorated class keeps its own ([#429](https://github.com/zaebee/codegraph-brain/issues/429)) ([#434](https://github.com/zaebee/codegraph-brain/issues/434)) ([fd0c63f](https://github.com/zaebee/codegraph-brain/commit/fd0c63f1f887a0b65a433d01571654ae79419ef3))
+* **query:** orphan classes — what production no longer builds ([#415](https://github.com/zaebee/codegraph-brain/issues/415)) ([#431](https://github.com/zaebee/codegraph-brain/issues/431)) ([3b4db3c](https://github.com/zaebee/codegraph-brain/commit/3b4db3cb231d43ae388b080d64d19b3244739017))
+* **resolver:** resolve self.<attr>.<method> through the declared receiver ([#414](https://github.com/zaebee/codegraph-brain/issues/414)) ([#423](https://github.com/zaebee/codegraph-brain/issues/423)) ([a1c94a2](https://github.com/zaebee/codegraph-brain/commit/a1c94a2e4629da955deef761467730a7d711c3fe))
+
+
+### Bug Fixes
+
+* **extractors:** attribute a module-level or class-body call to its owner ([#416](https://github.com/zaebee/codegraph-brain/issues/416)) ([#428](https://github.com/zaebee/codegraph-brain/issues/428)) ([c9f39b8](https://github.com/zaebee/codegraph-brain/commit/c9f39b81bf3a644441b7b5a3215df2d6b39b9489))
+* **resolver:** an import prefix that reaches a node is first-party, not external ([#424](https://github.com/zaebee/codegraph-brain/issues/424)) ([#426](https://github.com/zaebee/codegraph-brain/issues/426)) ([50f8b7c](https://github.com/zaebee/codegraph-brain/commit/50f8b7c03d716c25f9341a879c76a8707f3853fb))
+* **resolver:** resolve a name through the package that re-exports it ([#417](https://github.com/zaebee/codegraph-brain/issues/417)) ([#427](https://github.com/zaebee/codegraph-brain/issues/427)) ([ef76f95](https://github.com/zaebee/codegraph-brain/commit/ef76f9546b4477d4736406eabe417e6e49e68e23))
+
+
+### Documentation
+
+* auto-sync architecture graph and MCP reference ([#433](https://github.com/zaebee/codegraph-brain/issues/433)) ([40af3ee](https://github.com/zaebee/codegraph-brain/commit/40af3ee6839b53a953124e25f1f39b5379bff890))
+
 ## [0.17.0](https://github.com/zaebee/codegraph-brain/compare/codegraph-brain-v0.16.0...codegraph-brain-v0.17.0) (2026-09-05)
 
 

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/CLAUDE.md

@@ -35,8 +35,9 @@ make format && make lint && make type-check && make pytest && make doc-coverage
 # Single test
 uv run pytest tests/unit/test_python_extractor.py::test_extract_simple_function -v
 
-# Tests with coverage
-uv run pytest --cov=cgis --cov-report=html
+# Line coverage (same scope as CI — see the Makefile comment on why scripts/ counts)
+make coverage        # runs: uv run pytest --cov=cgis --cov=scripts --cov-report=term-missing
+make coverage-html   # same, writes htmlcov/
 ```
 
 ## Architecture

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/Makefile

@@ -1,4 +1,4 @@
-.PHONY: format lint type-check pytest doc-coverage check \
+.PHONY: format lint type-check pytest doc-coverage coverage coverage-html check \
         ui-dev ui-build ui-test ui-lint ui-format ui-preview ui-analyze ui-check \
         all-checks
 
@@ -19,6 +19,20 @@ pytest:
 doc-coverage:
 	uv run interrogate src
 
+# Line coverage. `--cov=scripts` is not optional and not cosmetic: sonar.sources
+# is `src,scripts`, so SonarCloud counts every executable line under scripts/ as
+# a line to cover whether or not the report mentions it. Omitting the directory
+# does not exclude it — it reports all of it as uncovered, which once put
+# new-code coverage at 37.8% on a PR whose script was covered at 99% locally.
+# Keep this scope identical to the Pytest step in .github/workflows/ci.yml, or
+# the number you read here is not the number the gate reads.
+coverage:
+	uv run pytest --cov=cgis --cov=scripts --cov-report=term-missing
+
+# Same scope, browsable. Writes htmlcov/ (git-ignored); open htmlcov/index.html.
+coverage-html:
+	uv run pytest --cov=cgis --cov=scripts --cov-report=html
+
 # Full Python verification (run before every commit/PR)
 check: format lint type-check pytest doc-coverage
 

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codegraph-brain
-Version: 0.17.0
+Version: 0.18.0
 Summary: Semantic code graph for AI agents — deterministic FQN resolution, impact analysis and architectural drift gates, exposed over MCP.
 Project-URL: Homepage, https://github.com/zaebee/codegraph-brain
 Project-URL: Repository, https://github.com/zaebee/codegraph-brain
@@ -198,8 +198,8 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:117)"]:::classNode
-        models_Node["Node (models.py:83)"]:::classNode
+        models_Edge["Edge (models.py:138)"]:::classNode
+        models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
         pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
@@ -217,7 +217,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:28)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:30)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -234,8 +234,8 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 
 | Symbol | Type | File |
 |--------|------|------|
-| `Node` | CLASS | [`models.py:83`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L83) |
-| `Edge` | CLASS | [`models.py:117`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L117) |
+| `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
+| `Edge` | CLASS | [`models.py:138`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L138) |
 | `run` | METHOD | [`pipeline.py:51`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L51) |
 | `_process_file` | METHOD | [`pipeline.py:155`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L155) |
 | `_is_noop_incremental` | METHOD | [`pipeline.py:185`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L185) |
@@ -245,7 +245,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 | `resolve` | METHOD | [`engine.py:36`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L36) |
 | `SemanticUpliftEngine` | CLASS | [`uplift.py:66`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L66) |
 | `execute_uplift` | METHOD | [`uplift.py:91`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L91) |
-| `SQLiteStore` | CLASS | [`sqlite_store.py:28`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L28) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:30`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L30) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/README.md

@@ -148,8 +148,8 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:117)"]:::classNode
-        models_Node["Node (models.py:83)"]:::classNode
+        models_Edge["Edge (models.py:138)"]:::classNode
+        models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
         pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
@@ -167,7 +167,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:28)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:30)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge
@@ -184,8 +184,8 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 
 | Symbol | Type | File |
 |--------|------|------|
-| `Node` | CLASS | [`models.py:83`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L83) |
-| `Edge` | CLASS | [`models.py:117`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L117) |
+| `Node` | CLASS | [`models.py:85`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L85) |
+| `Edge` | CLASS | [`models.py:138`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/core/models.py#L138) |
 | `run` | METHOD | [`pipeline.py:51`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L51) |
 | `_process_file` | METHOD | [`pipeline.py:155`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L155) |
 | `_is_noop_incremental` | METHOD | [`pipeline.py:185`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/pipeline.py#L185) |
@@ -195,7 +195,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
 | `resolve` | METHOD | [`engine.py:36`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/engine.py#L36) |
 | `SemanticUpliftEngine` | CLASS | [`uplift.py:66`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L66) |
 | `execute_uplift` | METHOD | [`uplift.py:91`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/resolver/uplift.py#L91) |
-| `SQLiteStore` | CLASS | [`sqlite_store.py:28`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L28) |
+| `SQLiteStore` | CLASS | [`sqlite_store.py:30`](https://github.com/zaebee/codegraph-brain/blob/main/src/cgis/storage/sqlite_store.py#L30) |
 <!-- END_CGIS_GRAPH -->
 
 ---

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/docs/architecture/HOW_IT_WORKS.md

@@ -85,7 +85,8 @@ CREATE TABLE IF NOT EXISTS nodes (
             domains TEXT,
             confidence_score REAL NOT NULL,
             metadata TEXT,
-            namespace TEXT NOT NULL DEFAULT 'INTERNAL'
+            namespace TEXT NOT NULL DEFAULT 'INTERNAL',
+            is_test INTEGER NOT NULL DEFAULT 0
         );
 
         CREATE TABLE IF NOT EXISTS edges (

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/docs/architecture/diagrams/pipeline_flow.mermaid

@@ -8,8 +8,8 @@ classDef stdlibNode fill:#eceff1,stroke:#607d8b,stroke-width:1px,color:#455a64;
 classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dasharray: 3 3,color:#bf360c;
 
     subgraph sg_models["models.py"]
-        models_Edge["Edge (models.py:117)"]:::classNode
-        models_Node["Node (models.py:83)"]:::classNode
+        models_Edge["Edge (models.py:138)"]:::classNode
+        models_Node["Node (models.py:85)"]:::classNode
     end
     subgraph sg_pipeline["pipeline.py"]
         pipeline_IngestionPipeline_get_extractor["_get_extractor (pipeline.py:245)"]:::methodNode
@@ -27,7 +27,7 @@ classDef externalNode fill:#fff3e0,stroke:#e65100,stroke-width:1px,stroke-dashar
         uplift_SemanticUpliftEngine_execute_uplift["execute_uplift (uplift.py:91)"]:::methodNode
     end
     subgraph sg_sqlite_store["sqlite_store.py"]
-        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:28)"]:::classNode
+        sqlite_store_SQLiteStore["SQLiteStore (sqlite_store.py:30)"]:::classNode
     end
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Node
     pipeline_IngestionPipeline_run -->|REFERENCES| models_Edge

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/docs/how-to/MCP_REFERENCE.md

@@ -106,6 +106,41 @@ Report per-domain architectural drift against declared ideal patterns.
 
 ---
 
+## `cgis_find_orphans`
+
+Classes nothing in production builds, extends or names — dead-code candidates (#415).
+
+    Finds classes that no test, type checker or linter flags, because each is
+    still imported somewhere: a package re-export keeps a class importable long
+    after its last real caller is gone. On one mid-sized backend this reported
+    43 of 1 789 classes, and the hand-written equivalent's findings were all
+    real and all deleted.
+
+    Two filters decide the answer. **Tests are not users** — a class built only
+    by its own test is exactly the shape being hunted. **A re-export is not a
+    use** — ``IMPORTS_SYMBOL`` does not count, or nothing is ever reported. What
+    counts is construction (``CALLS``), inheritance (``EXTENDS``) and being named
+    (``REFERENCES`` — an annotation, or a class handed to a framework); the last
+    keeps abstract ports and Protocols off the list.
+
+    ``prefix`` narrows to one package on a dot boundary. ``include_tests`` counts
+    test code as a user, turning the report into "unreachable from anywhere".
+
+    Returns JSON ``{orphans, considered, test_sources}``; each orphan carries
+    ``fqn``/``file``/``line``. **A listing is a candidate for deletion, not a
+    proof** — a class named only inside a decorator (#429) or arriving through a
+    star import is invisible here, so the sweep errs towards reporting a live
+    class rather than hiding a dead one. ``test_sources: 0`` in a repository that
+    has tests means the graph predates the ``is_test`` column: re-ingest.
+
+| Argument | Type | Required | Description |
+| :--- | :--- | :---: | :--- |
+| `db_path` | `string` |  |  |
+| `prefix` | `any` |  |  |
+| `include_tests` | `boolean` |  |  |
+
+---
+
 ## `cgis_find_symbol`
 
 Resolve a partial symbol name to candidate FQNs (substring match, ranked).

{codegraph_brain-0.17.0 → codegraph_brain-0.18.0}/docs/specs/2026-09-05-annotation-graph-design.md

@@ -18,6 +18,12 @@ type against but nobody constructs looks identical to dead code.
 
 ## Measurement basis
 
+All figures below are from `src/cgis/` at HEAD and a graph ingested from it —
+**except D10's**, which are from five repositories ingested at `c9f39b8`, because
+the effect D10 measures is invisible on cgis. That is not incidental: three of
+this spec's findings (#417, #424, D10) do not reproduce on cgis's own source, so
+a cgis-only measurement is evidence of nothing for resolver and reference work.
+
 All figures below are from `src/cgis/` at HEAD and a graph ingested from it:
 
 ```
@@ -59,9 +65,28 @@ The implemented feature was run against `Ownima/owner-api` (`ownima-backend/app`
 | `REFERENCES` edges | 2 004 (0 pointing at a non-CLASS node) |
 | classes carrying `self_types` | 677 (2 847 attributes) |
 | `self.<attr>.<method>` sites, **production only** | 554 |
-| …receiver resolvable | **476 (86%)** |
+| …receiver resolvable *(forecast, before PR2 existed)* | 476 (86%) |
+| …**actually resolved once PR2 landed** | **347 (63%)** |
 | …same, tests only | 445 / 1 732 (26%) |
 
+That 63% is itself a correction. The first measurement said 85%, and an
+adversarial review showed it counted 136 **fabricated** edges as successes:
+`classify_fqn` judges by root string, and `external_roots` is built from
+import-map values, so a first-party FQN whose import root differs from its
+ingest-relative node root classifies EXTERNAL — and D7's library branch then
+minted a boundary node for a class of ours that does not exist,
+`app.api.dependencies.session.AsyncSessionDep.execute` among them, at confidence
+1.0. Receiver resolution now refuses a receiver whose path reaches a project
+root; fabrications from this path are 0.
+
+The forecast counted a receiver as resolvable when its name appeared in
+`self_types`, without asking whether the declared type is a class that has that
+method. On `owner-api` the two nearly coincide, because its receivers are real
+injected classes. On this repository they do not: the same method forecast 89%
+and the truth is 80%, the gap being attributes declared as builtin containers
+(`self._profiles: dict[...]` records `dict`), which name no class. Quote the
+measured number, not the forecast.
+
 86% against the 66% #414 predicted from its two-source rule: the two sources this
 design adds (`self.x: T = ...` and `self.x = SomeClass()`) are worth ~20 points on
 the very repository the issue was filed from. The 26% in tests is 876 unannotated
@@ -282,6 +307,170 @@ a dot-boundary test so `Foo` is not treated as inside `FooBar`). A class
 naming itself is not evidence anyone uses it, and counting it would
 manufacture a false negative in the orphan query.
 
+### D10 — a class named in a load position is a reference, whatever the position
+
+PR3's mandate was to "measure the `response_model=` precision gap (D4) and decide
+it here". The measurement was taken on five codebases and found a *different*
+gap, several times larger. This decision is the answer to it.
+
+**The measurement.** A prototype of the orphan query — internal production CLASS
+nodes with no incoming `CALLS`/`EXTENDS`/`REFERENCES` from a non-test source —
+was run on five graphs ingested at `c9f39b8`. Each reported orphan was then
+checked against the ground truth #415's own reference implementation uses: a bare
+name load of that class, in a production file that imports it, outside its own
+module.
+
+| repo | internal classes | orphans reported | of those, alive | rate |
+|---|---|---|---|---|
+| cgis | 93 | 2 | 0 | 0% |
+| owner-api | 1 789 | 109 | 44 | **40%** |
+| memory-facets | 383 | 18 | 6 | **33%** |
+| aura-core | 124 | 18 | 6 | **33%** |
+| rich (library) | 181 | 31 | 1 | 3% |
+
+Three unrelated applications agree at a third to two-fifths wrong. A mature
+library and cgis itself sit near zero, and the reason is not that they are
+better written: **application code hands classes to a framework, library code
+constructs them.** `app.add_middleware(SecurityMiddleware)` names a class and
+never calls it. This is the third feature in this spec that cgis's own source
+cannot exercise, after star imports (#417) and root-prefix mismatch (#424); a
+measurement taken only on cgis would have reported the query ready.
+
+The `response_model=` gap D4 predicted turns out to be two occurrences. The
+positions that actually matter, pooled across all five repos (57 false positives):
+
+| shape | n | example |
+|---|---|---|
+| attribute head — enum member, classmethod | 25 | `TransactionType.TOP_UP`, `Rule.stats()` |
+| handed to a call as a value | 18 | `add_middleware(X)`, `route_class=X` |
+| `except` clause | 5 | `except ConversationNotFoundError:` |
+| collection literal | 3 | `("fuel_types", FuelType)` |
+| other — `BinOp`, return annotation, `arg` | 6 | |
+
+**The decision: one rule, not five.** Every row above is the same thing — a name
+that resolves to an internal class, appearing in a load position. Enumerating
+positions would take more code, draw arbitrary boundaries, and still miss the
+six-item tail. So the extractor emits a `raw_dep:<name>` candidate for an
+`identifier` in a load position when the name is either in the module's
+`import_map` or the name of a class defined in that file.
+
+Three kinds of position are excluded. Those that already carry an edge: the
+`function` field of a call (that is `CALLS`) and an annotation (that is the
+annotation path's own `rawdep_` edge — emitting both made ~80% of the
+name-reference edges duplicates, and the band meant to guard the rule was mostly
+measuring annotations). Those that name something other than a class: the member
+half of an attribute — `TOP_UP` in `TransactionType.TOP_UP` is a field lookup on
+whatever the object turns out to be. And every position that *binds* the name
+rather than using it.
+
+That last group is where both reviews of the first implementation converged, and
+they were right: the predicate was a denylist over a grammar, and it accepted 29
+binding positions of the 82 probed — loop and comprehension targets, walrus
+targets, `with`/`except`/`case` aliases, unpacking targets, `nonlocal`, `del`,
+`*args`/`**kwargs` names, type parameters. A binding that emits a reference says
+"this class is used" about a loop variable, which is the exact failure the rule
+exists to prevent.
+
+The fix is structural rather than a longer list. `is_name_load` first climbs out
+of grouping nodes — tuples, lists, unpacking targets — so the enclosing
+construct decides, and `for a, (b, Widget) in xs` is a binding while
+`f((a, Widget))` is a use without either shape being enumerated. Two node types
+hold a use and a binding side by side, told apart only by order (`except Widget
+as e` versus `case [1] as Widget`), and one bare identifier under a
+`case_pattern` is a capture while `case Widget():` and `case Widget.A:` are not.
+`tests/unit/test_name_load_positions.py` pins all 60 positions this paragraph
+claims, so a position the list has not met fails there instead of silently
+emitting.
+
+**A class reached through its module is also named.** `from app.api import
+validators` then `validators.Rule.confirm_by(...)` gives a head that resolves to
+a module, which D3 drops, so the class stayed invisible — two live owner-api
+classes were reported dead for this. An attribute head therefore records the
+two-segment path alongside the bare name; when the head is itself the class
+(`Widget.SIZE`) the extra candidate resolves to nothing and costs nothing.
+
+Everything else in the pipeline is reused unchanged. The source is the nearest
+owner — enclosing function, else class, else module — which is the rule #416
+settled. `_resolved_dep_edge` already drops any candidate that does not resolve
+to an internal CLASS node (D3), so a name that is a function, a variable or a
+third-party symbol never reaches the graph. The edge type is `REFERENCES` (D2)
+at confidence 0.9 (D6), and the self-reference drop in D9 applies unchanged.
+
+**Cost — stated here so it is not discovered in review.** Counting distinct
+`(owner, class)` pairs, which is what dedupes into edges:
+
+| repo | `REFERENCES` | total edges | growth |
+|---|---|---|---|
+| cgis | 592 → 767 | 5 911 → 6 125 | 4% |
+| owner-api | 2 793 → 7 235 | 70 334 → 74 777 | 6% |
+| memory-facets | 1 182 → 1 660 | 12 773 → 13 251 | 4% |
+| aura-core | 88 → 168 | 4 312 → 4 392 | 2% |
+| rich | 652 → 980 | 7 519 → 7 847 | 4% |
+
+The whole graph grows 2–6%. An earlier draft of this table predicted 5–13%; the
+difference is the annotation exclusion above, which removed the duplicate half.
+On cgis the 175 new edges split 172 name references and a handful of annotation
+positions the module-path rule newly reaches.
+`audit_reachability` is unaffected: it traverses enforcement edges only.
+`impact` and `trace_flow` apply no edge-type filter and will widen
+correspondingly, several times more than the PR1 risk already noted.
+
+**Measured outcome.** Implemented, reviewed, corrected, and re-run over the same
+five graphs:
+
+| repo | orphans before | false | orphans after | false |
+|---|---|---|---|---|
+| cgis | 2 | 0 (0%) | 2 | 0 (0%) |
+| owner-api | 109 | 44 (40%) | 43 | 5 (12%) |
+| memory-facets | 18 | 6 (33%) | 11 | 0 (0%) |
+| aura-core | 18 | 6 (33%) | 9 | 0 (0%) |
+| rich | 31 | 1 (3%) | 14 | 0 (0%) |
+
+**Owner-api's five residuals are the ground truth being wrong, not the rule** —
+checked one at a time, and independently confirmed by the review.  Each is a
+short-name collision the name-based sweep cannot resolve and an FQN graph can:
+`domains.rating.calculator.UserMetrics` is reported dead while
+`domains/admin/users.py` names `UserMetrics`, but that file imports
+`app.domains.admin.schemas.UserMetrics` and nothing imports the calculator's.
+Likewise `CancelReservationResponse` and `CreateReservationRequest` (both
+shadowed by `grpc.services`), a `Config`, and a `Message`. #415's reference
+implementation names this limitation in its own docstring — "a method sharing a
+name with a live one elsewhere hides in that one's shadow" — and resolving
+through the import map is precisely what a graph buys over a name sweep.
+
+An earlier draft of this section claimed the same for all seven residuals of the
+first implementation. **Two of those seven were real misses**, not collisions:
+`api.validators.confirmation.Rule` and `domains.pricing.season_validators.Rule`
+are both live, reached as `confirmation.Rule.confirm_by(...)` through a module
+alias. The module-path rule above closes them. The claim was made from
+hand-checking five of the seven and generalising, which is exactly the habit the
+measurement discipline in this spec exists to prevent.
+
+The orphan counts fall further than the false-positive count alone explains
+(owner-api 109 → 43). The extra rescues are same-module uses the ground truth
+excludes by construction: `register_message("entities", "Garage", Garage)`,
+`Dep = Annotated[TransactionWalletMonthlyFilter, Query()]`,
+`{"model": BaseValidationError}`. Spot-checked; all real. memory-facets moved the
+other way, 9 → 11, when the binding-position fix stopped two classes being
+rescued by a loop variable that happened to share their name.
+
+**What it cannot do.** Three limits, all measured rather than assumed:
+
+* A class mentioned only inside code that is itself dead reads as live. #415's
+  reference implementation carries the same limitation and states it plainly:
+  it under-reports and never over-reports.
+* A class named only inside a **decorator** is invisible, because `_walk` never
+  descends into decorators ([#429](https://github.com/zaebee/codegraph-brain/issues/429)).
+  117 known names appear in owner-api decorators, mostly `response_model=Foo`;
+  those classes survive only when a return annotation names them too. This
+  raises #429 from an audit-precision issue to an orphan-query one.
+* A class arriving through `from x import *` is not gated in, because the gate is
+  the module's `import_map` keys and a star import contributes none. One
+  production file in owner-api is affected, none in the other four repositories. #415's reference implementation carries
+the same limitation and states it plainly: it under-reports and never
+over-reports. For a check whose whole value is that people trust it, a false
+"live" is the cheap direction.
+
 ## Work breakdown
 
 Three sequential PRs. Each merges before the next starts.
@@ -307,14 +496,50 @@ Serves both issues; neither can be precise without it.
 * Fixes the placeholder collision as a consequence: two unrelated classes with a
   same-named attribute no longer share one vertex.
 
-### PR3 — #415 orphan query
-
-* `is_test_path()` + `Node.is_test` + column migration (D5).
-* Orphans query: internal CLASS nodes with no incoming `CALLS` or `EXTENDS` from
-  a non-test source. `IMPORTS_SYMBOL` excluded.
-* Surfaced as a CLI command and an MCP tool, following the existing
-  `audit_reachability` shape.
-* Measure the `response_model=` precision gap (D4) and decide it here.
+### PR3a — the name-as-value reference edge (D10)
+
+* `raw_dep:` emission for an `identifier` in a load position, gated on the
+  module's `import_map` or a class defined in the same file.
+* Exclusions: a call's own `function` field, the member half of an attribute.
+* Re-measure the orphan query's false-positive rate on all five repos of D10;
+  the acceptance number is that rate, not an edge count.
+* State the `impact` / `trace_flow` density change in the PR.
+
+The measurement that motivated this split is D10. The original PR3 owed a
+decision on the `response_model=` gap; taking that measurement found a larger
+one, and shipping the query on top of it would have meant a check that is wrong
+a third of the time on every application codebase tested.
+
+### PR3b — #415 orphan query
+
+* `is_test_path()` (`core/paths.py`) + `Node.is_test` + column migration (D5).
+  The flag is *derived* from `file_path` in a model validator rather than passed
+  in: the query's correctness rests on every node agreeing what a test is, and
+  an extractor that forgot to set it would make its own classes look
+  production-reachable. An explicit value is still honoured, because the
+  resolver mints virtual boundary nodes with no real file to classify.
+* `find_orphan_classes` (`query/context/orphans.py`): internal `CLASS` nodes,
+  not in test files, with no incoming `CALLS` / `EXTENDS` / `REFERENCES` from a
+  non-test source. `IMPORTS_SYMBOL` excluded; `CONTAINS` excluded (a module
+  holding a class is not a user of it). Measured on owner-api, no `DEPENDS_ON`
+  edge targets an internal class, so the three types above are exhaustive.
+* `cgis orphans` and the `cgis_find_orphans` MCP tool, in the
+  `audit_reachability` shape — including its non-zero exit on findings, so the
+  query gates CI like a linter.
+* The report carries `considered` and `test_sources` alongside the findings.
+  The denominator because "3 orphans" means something different out of 40
+  classes than out of 1 800; `test_sources` because a graph ingested before this
+  column has none, which silently counts every test as production — the CLI says
+  so rather than under-reporting quietly.
+
+**Measured end to end on owner-api** (`ownima-backend/app`, re-ingested):
+748 internal production classes, 8 418 test-source nodes, **43 orphans** — the
+same 43 the throwaway measurement script reported in PR3a, which is the
+agreement worth having between a product query and the script that justified it.
+`--prefix domains` narrows to 16 of 284, mostly request/response schemas, which
+is the shape #415 predicted for that subtree. `--include-tests` drops the count
+to 39: four classes are alive only because their own tests build them, which is
+the filter doing its work on real code.
 
 ## Testing
 
@@ -334,6 +559,11 @@ must be re-derived from a fresh ingest, never from the stale root `graph.db`.
 | Fixture: a class referenced only as `list[OnlyInGeneric]` is **not** an orphan | D9 regresses to `clean_python_type_string` |
 | Fixture: a class constructed only from `tests/` is reported as an orphan | the `is_test` filter stops being applied |
 | Fixture: a class referenced only by a parameter annotation is **not** an orphan | the annotation edge stops being emitted |
+| Fixture: a class only ever `except`-ed is **not** an orphan | D10's load-position rule stops covering `except` |
+| Fixture: a class only handed to a call (`add_middleware(X)`) is **not** an orphan | D10 regresses to counting constructions |
+| Fixture: an enum named only as `E.MEMBER` is **not** an orphan | the attribute head stops being collected |
+| Fixture: a *function* handed to a call emits no `REFERENCES` | D3's internal-CLASS filter stops applying to D10 candidates |
+| Five-repo sweep: orphan false-positive rate is 0 on the D10 set | any load position stops being covered |
 
 The last two are the pair #415 identifies as load-bearing: without the first all
 six of its rows read as live, and without the second every abstract port reads as
@@ -347,12 +577,18 @@ against the design as originally written.
   that D8 does not otherwise address. The `.`-prefixed relative-import case
   shares the condition and must keep its current behavior. Verify each
   `NodeNamespace.INTERNAL` consumer before the split.
-* **Traversal density (PR1).** `impact` and `trace_flow` apply no edge-type
-  filter by default, so +583 `REFERENCES` edges will widen their results.
-  Arguably correct — an annotation is a real dependency — but it changes existing
-  output and should be stated in the PR, not discovered.
-* **Response-schema precision (PR3).** Known and deliberate (D4). PR3 must report
-  the measured false-positive rate rather than ship silently.
+* **Traversal density (PR1, and several times more in PR3a).** `impact` and
+  `trace_flow` apply no edge-type filter by default, so PR1's +583 `REFERENCES`
+  edges widened their results, and D10 roughly doubles `REFERENCES` again on top
+  (5–13% of the whole graph, per repo — see D10's cost table). Arguably correct:
+  naming a class is a real dependency. But it changes existing output, and each
+  PR must state the movement rather than let a consumer discover it.
+* **Response-schema precision (PR3).** Predicted by D4 as the query's main
+  precision limit. Measured in D10: **two occurrences across five repositories.**
+  The real limit was a different one — a class named as a value — which D10
+  addresses. Recorded here because the prediction being wrong is the reason PR3
+  was split, and a reader of D4 should not still expect `response_model=` to be
+  the problem.
 * **`self_types` is wrong in two rare shapes — PR2 reads this map, so its author
   must know.** Both were found by an adversarial pass over the extractor's
   heuristics and both measure **zero occurrences** across this repository and
@@ -371,12 +607,16 @@ against the design as originally written.
     and `self_types` disagree on the third.
 * **Measurement basis.** Every number here has a five-week-stale twin in the root
   `graph.db`. Re-ingest before re-measuring.
-* **Module-level construction is invisible — [#416](https://github.com/zaebee/codegraph-brain/issues/416).**
-  A constructor called at module level emits no `CALLS` edge at all: `_walk`
-  dispatches a call node only when there is an enclosing function. A class built
-  only in a registry dict, a singleton, or DI wiring therefore has no incoming
-  `CALLS`, and PR3's orphan query would report it as dead. On this repository
-  `PythonExtractor` and `TypeScriptExtractor` are already in that state. This is
-  a **second** precision limit alongside the `response_model=` gap in D4, and
-  probably the larger one — it was found while validating PR1, not predicted
-  here. PR3 must measure it before the query is trusted.
+* **Module-level construction — [#416](https://github.com/zaebee/codegraph-brain/issues/416), CLOSED (`c9f39b8`).**
+  A constructor called at module level emitted no `CALLS` edge at all, so a class
+  built only in a registry dict, a singleton, or DI wiring read as dead. Fixed by
+  attributing such a call to its nearest owner. On owner-api it rescued 32 classes
+  the query would have reported dead.
+
+* **Calls inside a decorator expression are still dropped — [#429](https://github.com/zaebee/codegraph-brain/issues/429), OPEN.**
+  `_walk` hands a `decorated_definition` off and never descends into the
+  decorators, so `@router.post(..., dependencies=[Depends(guard)])` leaves the
+  endpoint with no `DEPENDS_ON` and `cgis audit` reads a superuser-only route as
+  unguarded. It does not affect the orphan query — D10's rule covers a class
+  *named* in a decorator through the same `import_map` gate — but it is the
+  remaining hole in "a call outside a function is still a call".