# The codebase as a walkable graph

**🔵 Expert · Lesson 19**

THE GRAPH DOCUMENTS. Expert 18 addressed prose by section. The two graph documents carry the same prose surface AND a real graph: nodes, edges, traversal, and blast radius - answered at import, with nothing conjured.

md.__graph_network__ the graph md.__graph_details__ the prose about what the graph names

THE ONE THAT CHANGES HOW YOU WORK graph.node_at(source_path, line) You have a traceback. You have `file.py:412`. That call turns a line number into the NODE that encloses it, and from there `impact()` tells you what else moves if you change it. Stack trace to blast radius without leaving the process.

EVERY EDGE EXPLAINS ITSELF Edge(source, relation, target, cardinality, phase, origin, why) Two fields there are unusual and both are the point: `why` - the justification for the edge, carried WITH it `origin` - `authored` or `derived`: did a human assert this, or did a tool infer it? `origin` is a TRUST FILTER you can pass to `walk()` and `impact()`. Walk only `authored` when you need what someone meant; walk only `derived` when you need what the machine can prove. A graph that cannot tell you which is which forces you to trust all of it equally, which in practice means trusting none of it.

AND GUESSES DO NOT SHIP. `edge_count` excludes extractor candidates - the leads over-generate roughly eightfold and never reach the adjacency table. What you walk is evidence.

`walk()` YIELDS, AND THAT IS A CONTEXT BUDGET DECISION It is a generator "so an agent can stop at the first useful hop instead of materialising a subgraph it will discard" - expert 18's law again, one grain up. Breadth-first, so shallow relationships arrive first and stopping early stops at the RIGHT things.

TWO GUARANTEES THAT MAKE A WALK SAFE - CYCLES ARE HANDLED. `borrows` and `used_by` run both ways, so the graph has cycles and every node is expanded at most once. An unguarded walk would not terminate. - AN EDGE TO AN UNKNOWN NODE IS STILL YIELDED, then not expanded. "The relationship is real even where the target is not described here." A graph that hid those edges would quietly understate what touches what.

IMPACT IS MEASURED IN FILES impact(node_id) -> Impact(source, hops, nodes, edges) Ranked by PROXIMITY, nearest first. Not "here are 400 symbols" - here are the files, in the order you should look at them, in the unit you actually open and edit.

AND THE TWO DOCUMENTS JOIN details_key(node_id) -> the section key in the details document describe(node_id) -> that section's text A node in the network document addresses prose in the other one. That is why they ship as a pair.

## Before you run

Use the [Expert guide](../../expert/index.md) for prerequisite concepts. Run from a checkout with Melder installed and Python 3.14 free-threading selected. The collection download includes the level's local helper modules.

## Run the saved script

```bash
python UX_and_AIX_experiences/04_expert/19_the_codebase_as_a_walkable_graph.py
```

```powershell
py -3.14t UX_and_AIX_experiences/04_expert/19_the_codebase_as_a_walkable_graph.py
```

{download}`Download this collection <../../downloads/expert-examples.zip>` · [Source on GitHub](https://github.com/Synaptic724/melder/blob/a30a754d0bb61db0b142936010cdb82cffecec6f/UX_and_AIX_experiences/04_expert/19_the_codebase_as_a_walkable_graph.py)

## Public surface

md.__graph_network__ / __graph_details__ -
                   node_count, edge_count, relations, node_ids, node,
                   find_nodes, nodes_in, node_at, edges_from, edges_to,
                   neighbors, walk, impact, details_key, describe

## Code

```{literalinclude} ../../downloads/04_expert/19_the_codebase_as_a_walkable_graph.py
:language: python
:linenos:
```

## Check the outcome

The script contains its own assertions or demonstrated refusal paths. Run it to evaluate those checks against your installed version. The code above is taken directly from the saved file; no run output is invented here.

[More expert examples](index.md) · [Level guide](../../expert/index.md)

## Related guides

- [The runtime documents itself](../../expert/self-documents.md)