# Graph

Edge list and relationship data for the knowledge graph, keyed by entity page.

`edges.json` holds typed relationships between pages. Created on the first
ingest that extracts entities.

## Edge vocabulary

Each verb exists because it answers a question retrieval actually gets asked.
If a proposed edge doesn't answer one of these, it doesn't belong in the graph
— put it in prose on the page instead.

| Verb | Question it answers | Written by |
|---|---|---|
| `part_of` | Where does this live? What is it a piece of? | `ckb-ingest`, `ckb-code-map` |
| `uses` | What does this reach for at runtime? | `ckb-ingest`, `ckb-index-external` |
| `depends_on` | What breaks if I change this? | `ckb-ingest`, `ckb-code-map` |
| `produces` | Where does this output come from? | `ckb-ingest` |
| `configures` | What changes this thing's behaviour? | `ckb-ingest` |
| `validates` | What checks, tests, or judges this? | `ckb-ingest` |
| `implements` | What contract must this honour? | `ckb-ingest`, `ckb-spec` |
| `caused` | Why did this happen? | `ckb-ingest` |
| `contradicts` | What disagrees with this, unresolved? | `ckb-ingest`, `ckb-lint` |
| `supersedes` | What replaced this, and what did it replace? | `ckb-ingest`, `ckb-decide`, `ckb-lint` |
| `decided_by` | Who made this call? | `ckb-decide` |
| `affects` | What does this decision constrain? | `ckb-decide` |
| `has_expertise_in` | Who can answer questions on this? | `ckb-ingest` |
| `owns` | Who is responsible for this? | `ckb-ingest`, `ckb-code-map` |
| `mentioned_in` | Which source document discusses this? | `ckb-index-external` (lib indexes only) |

Conventions:

* **One direction per relationship.** `part_of`, `supersedes`, `depends_on`,
  and `uses` are canonical; don't also record the inverse (`contains`,
  `superseded_by`, …) as a second edge. Frontmatter carries the inverse where
  a page needs to state it (`superseded_by:`), and traversal reads edges both
  ways regardless.
* **Evidence, not inference.** `has_expertise_in` and `owns` are recorded only
  from demonstrated evidence — someone attending a meeting is not expertise,
  and a job title is not ownership. The same applies to every other verb: an
  absent edge beats a fabricated one.
* **In-degree is a retrieval signal.** How many edges point *at* a page is a
  rough measure of how central it is, and `ckb-retrieve` fuses it as one
  ranked list among several. That only works if edges are recorded honestly;
  padding the graph degrades search rather than improving it.

*(No edges recorded yet — populated on the next ingest.)*