# The Knowledge-Graph / Retrieval-Topology Specification _Adopted specification. Recorded 2026-07-21 (Protocol 50). Author of the data model: **GPT-5.6 Sol**, second pass, repo-aware (read access to `dev`). Referenced from `QUEUE.md` item **R11**. This is the **recorded** specification as captured in the Protocol 50 landing pass — the data model, the three load-bearing ideas, the node-state model, and Dispatch's owner-endorsed amendments — not a verbatim external transcript (the raw response was not in the recording session's possession; if the verbatim reply is later recovered it should be filed alongside this doc, not in place of it)._ > **Build nothing from this yet.** This is the design of record for R11. The honest cost is at the > bottom: even GPT's "minimum" version needs a real parser (a session or two, not an afternoon). --- ## The core ruling — build a RETRIEVAL TOPOLOGY first, not a universal graph of every project fact Protocols, suites, guards, queue items, museum history and Atlas assurance **can** join the same schema later, but their derivation is less uniform, and including them prematurely risks **"a polished graph that lies."** So the first deliverable is only the retrieval chain: the skill, `CLAUDE.md`, the `rules/*.md` notes, `ARCHITECTURE.md`, the library, the queue and its log, memory — and how they route to and claim scope over each other. **Stopping rule (carries into R11's own entry):** build the retrieval topology first; extend to protocols / guards / museum / Atlas **only if the first map is actually used** to find or prevent drift. If it becomes wallpaper, stop. --- ## The three ideas that matter most — these must survive verbatim in substance **(a) `routes_to` and `claims_scope_over` are two INDEPENDENTLY DERIVED edges.** One is derived from `CLAUDE.md`'s retrieval-map rows (the map says "touching X → read note Y"). The other is derived from each note's own "load this when touching …" header (the note declares what it covers). The gap between what the map routes and what the notes claim is **not found by a checker looking for problems — it EMERGES when the two derivations disagree.** That is much harder to fool than a single rule that must anticipate the specific failure. (This is exactly the class of gap R10 finding D found by hand; deriving both edges makes it fall out mechanically.) **(b) `claims_checked_by` and `invokes` are SEPARATE edges.** A protocol *naming* Suite 30 and something *actually running* Suite 30 are different facts. The cache-guard defect is the proof: protocol, script, hook and suite all existed and named each other, and the classifier still missed every real icon path. **Naming is not running.** The graph must model the two independently so "declared coverage" can be diffed against "coverage that actually executes." **(c) Every extractor must report `records_seen`, `records_emitted`, `records_unparsed`, and `parser_status`.** If the retrieval-map heading is ever renamed and the parser returns zero routes, the graph must say **"route extraction failed"** — NOT render ten orphaned notes as though the project collapsed. This is the silent-empty-parse failure that has defined this week (the inert cache guard, the stale architecture sizes), designed out **at the data layer**. --- ## Also adopted - **Node states: `observed / declared / manifested / unavailable`.** A node a session can actually read on the current checkout is `observed`; one named but not present (e.g. a gitignored `library/` target on a clean clone) is `declared`/`unavailable` — so a consumer knows not to infer its contents. Same provenance discipline P3 gives the museum, applied to the whole knowledge layer. - **Baseline-local keys for most nodes; cross-release identity ONLY for protocol and queue IDs** — those two already have no-reuse contracts (Protocol 49 discipline), so they can carry stable identity across releases; everything else is keyed to the current baseline. - **A file rename appears as remove + add, NOT inferred by git similarity.** This project measured git's content-similarity rename detection undercounting by ~22% and failing silently (recorded under P1) — so the extractor does not trust that heuristic. - **The public projection is built FROM PUBLIC SOURCES PLUS GENERIC PLACEHOLDERS**, never by ingesting private data and redacting it. **Fail-closed by construction rather than by discipline** — the same shape as the museum's name-substitution guard (P2). --- ## ⭐ Dispatch's amendment, owner-endorsed — ONE derivation, THREE renderings GPT designed a **diagnostic instrument**; the owner asked for a **picture**. Both are wanted — and the owner then corrected Dispatch that there is a **third** consumer, which may be the most valuable of all. One derivation feeds three views: 1. **TOPOLOGY view** (human, visual) — skill → contract → notes → architecture → library → museum → atlas as an actual readable shape. **This is a Fable design job.** 2. **DIAGNOSTICS view** (human, plain) — selectors, dangling edges, parser status. **Stays plain**; no design pass. 3. **⭐⭐ MACHINE-READABLE answer for SESSIONS** (the third consumer, owner's correction — *"we don't just need visuals, whatever helps the AI too ya know?"*). A session touching `.github/workflows/` can ask *what governs this path* and get back **both** the note the map routes it to **and** the note that claims it, **plus the fact that they disagree** — the map together with its known defects. A session asking *"is this guarded?"* gets **"named, invoked, and here is what its classifier actually reaches"** rather than protocol prose. And the `observed/declared/manifested/unavailable` states let a session reading `library/CODE_MAP.md` on a clean checkout know the file is **declared-but-unreadable**, so it must not infer the contents — the same provenance problem P3 solves for the museum, solved for the whole knowledge layer. **This is the "one source, two views" ruling already made for `QUEUE.md`/L and the museum/P3 — extended to three.** Dispatch had initially framed the diagnostic surface as a consolation prize; the owner's correction is that the session-facing answer is arguably the highest-value output, which is why R11 is placed as **infrastructure** (the R2-restructure category), not post-2.8.5 visualisation decoration. --- ## Honest cost (recorded so it isn't under-scoped) GPT's "minimum" version still needs a **real parser**: AST detection for suite definitions, glob expansion against the tracked tree, and boundary-accurate block parsing (of the retrieval-map table, the note headers, the protocol headings). **A session or two, not an afternoon.** --- ## Cross-references - **R11** (`QUEUE.md`) — the queue home for this spec. - **Item I, the Atlas** — shares the schema; the Atlas's assurance view is one derivation over the same graph. Link, don't fuse (owner ruling). The stable-identifier scheme in item I's design note (b) is the identity contract this graph's cross-release keys obey. - **P3** (museum-as-AI-resource) — the same provenance / fail-closed-on-unknown discipline; the museum extract and this graph are two consumers of the "provenance, not permission" rule. - **R10 findings A–D** — the audit that motivated this; findings A (blanket retrieval), C (Suite 220 under-checks), and D (retrieval-map routing gaps) are exactly what the two-independently-derived-edges model is designed to surface mechanically.