On this page
The package reads itself to you๏
๐ต Expert ยท Lesson 18
YOU DO NOT READ A SYSTEM DOCUMENT, YOU ADDRESS IT. Four documents hang off the package root and answer AT IMPORT - before Aether boots, before a Spellbook exists, before anything is conjured.
md.architecture prose, addressable by section md.components prose, addressable by section md.graph_network the same, PLUS a graph API md.graph_details the same
SystemGraphView subclasses SystemDocumentView, so the graph documents answer every prose question too and then add nodes and edges on top.
ASK WHAT THE ADDRESS SPACE IS BEFORE YOU ADDRESS IT view.addressing -> "section" | "source_path" Keys are heading paths in one document and repository-relative file paths in another. A caller that assumes one shape silently misses in the other, so the view publishes which it is rather than making you infer it from a sample.
THE CHEAP SURVEY, THEN THE EXPENSIVE READ keys() every section key, in document order groups(depth) the index collapsed to one row per prefix index() every Section(key, start_line, end_line, line_count) find(needle) sections whose KEY matches search(needle) sections whose BODY mentions it, RANKED BY HIT COUNT, with a preview Note that find and search answer different questions - one addresses, one investigates - and neither one costs you the document. Only then: get(key) the section's text reader(key, ...) a private cursor over ONE SECTION
reader() TAKING A KEY IS THE WHOLE DESIGN. The paging cursor is scoped to a section, so an agent that has narrowed correctly never pages the document at all.
CITATIONS, NOT PARAPHRASES cite(key) -> "src_graph.md:3518-3596" cite(key, line=3520) -> "src_graph.md:3520" An agent can hand back an address a human can open and check. That is a different kind of answer from a summary: it is falsifiable.
REFUSED IS NOT MISSING available -> did this document ship with content reason -> why not, when it did not verify() -> re-check the shipped text against the digest its index claimed A document that fails verification still EXISTS and still answers available and reason. Omitting it would make a stale index look identical to a document that never existed - and the second one invites an agent to invent. verify() is ALWAYS False for an unavailable document, because there is nothing to check.
Before you run๏
Use the Expert guide 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๏
python UX_and_AIX_experiences/04_expert/18_the_package_reads_itself_to_you.py
py -3.14t UX_and_AIX_experiences/04_expert/18_the_package_reads_itself_to_you.py
Public surface๏
md.architecture / components / graph_network / graph_details - addressing, keys, groups, index, find, search, section, get, cite, reader, verify, and the graph surface
Code๏
1"""
2TIER: expert (18)
3GOAL: YOU DO NOT READ A SYSTEM DOCUMENT, YOU ADDRESS IT. Four documents
4 hang off the package root and answer AT IMPORT - before Aether
5 boots, before a Spellbook exists, before anything is conjured.
6
7 md.__architecture__ prose, addressable by section
8 md.__components__ prose, addressable by section
9 md.__graph_network__ the same, PLUS a graph API
10 md.__graph_details__ the same
11
12 `SystemGraphView` subclasses `SystemDocumentView`, so the graph
13 documents answer every prose question too and then add nodes and
14 edges on top.
15
16 ASK WHAT THE ADDRESS SPACE IS BEFORE YOU ADDRESS IT
17 view.addressing -> "section" | "source_path"
18 Keys are heading paths in one document and repository-relative file
19 paths in another. A caller that assumes one shape silently misses
20 in the other, so the view publishes which it is rather than making
21 you infer it from a sample.
22
23 THE CHEAP SURVEY, THEN THE EXPENSIVE READ
24 keys() every section key, in document order
25 groups(depth) the index collapsed to one row per prefix
26 index() every Section(key, start_line, end_line,
27 line_count)
28 find(needle) sections whose KEY matches
29 search(needle) sections whose BODY mentions it, RANKED BY HIT
30 COUNT, with a preview
31 Note that `find` and `search` answer different questions - one
32 addresses, one investigates - and neither one costs you the
33 document. Only then:
34 get(key) the section's text
35 reader(key, ...) a private cursor over ONE SECTION
36
37 `reader()` TAKING A KEY IS THE WHOLE DESIGN. The paging cursor is
38 scoped to a section, so an agent that has narrowed correctly never
39 pages the document at all.
40
41 CITATIONS, NOT PARAPHRASES
42 cite(key) -> "src_graph.md:3518-3596"
43 cite(key, line=3520) -> "src_graph.md:3520"
44 An agent can hand back an address a human can open and check.
45 That is a different kind of answer from a summary: it is falsifiable.
46
47 REFUSED IS NOT MISSING
48 available -> did this document ship with content
49 reason -> why not, when it did not
50 verify() -> re-check the shipped text against the digest its
51 index claimed
52 A document that fails verification still EXISTS and still answers
53 `available` and `reason`. Omitting it would make a stale index look
54 identical to a document that never existed - and the second one
55 invites an agent to invent. `verify()` is ALWAYS False for an
56 unavailable document, because there is nothing to check.
57SURFACE EXERCISED: md.__architecture__ / __components__ /
58 __graph_network__ / __graph_details__ - addressing,
59 keys, groups, index, find, search, section, get, cite,
60 reader, verify, and the graph surface
61VERIFY: went RED 2026-08-03 and was fixed the same day; awaiting
62 re-run. See the header note for what the failure taught.
63"""
64import melder as md
65
66
67PROSE_DOCS = ("__architecture__", "__components__")
68GRAPH_DOCS = ("__graph_network__", "__graph_details__")
69
70
71def main() -> None:
72 # THESE ANSWER AT IMPORT. Nothing conjured, no Aether call made.
73 for name in PROSE_DOCS + GRAPH_DOCS:
74 view = getattr(md, name)
75 assert view.document_name
76 print(f"{name:<20} -> {type(view).__name__:<20} "
77 f"available={view.available}")
78 print()
79 print("four documents, queryable with no Spellbook and no Conduit")
80
81 architecture = md.__architecture__
82 if not architecture.available:
83 print("__architecture__ did not ship:", architecture.reason)
84 print(" note it still ANSWERS - refused is not missing")
85 return
86
87 # 1. WHAT DO KEYS MEAN HERE? Ask before addressing.
88 print()
89 print("addressing:", architecture.addressing,
90 f" ({architecture.line_count} lines,",
91 f"{architecture.char_count} chars)")
92
93 # 2. THE CHEAP SURVEY. Keys and group rollups cost no document text.
94 keys = architecture.keys()
95 assert len(keys) > 0
96 print()
97 print("keys():", len(keys), "sections; first three:")
98 for key in keys[:3]:
99 print(" ", key)
100
101 rollup = architecture.groups(1)
102 print("groups(1):", len(rollup), "prefixes; first:",
103 rollup[0].prefix, f"({rollup[0].sections} sections,",
104 f"{rollup[0].line_count} lines)")
105
106 # 3. THE INDEX IS SPANS, NOT PROSE. Sizing before reading, per section.
107 sections = architecture.index()
108 assert len(sections) == len(keys)
109 biggest = max(sections, key=lambda s: s.line_count)
110 print()
111 print("index(): largest section is", biggest.key)
112 print(f" lines {biggest.start_line}-{biggest.end_line}"
113 f" ({biggest.line_count} lines)")
114
115 # 4. FIND ADDRESSES, SEARCH INVESTIGATES. Different questions.
116 hits = architecture.search("melder", limit=3)
117 print()
118 print("search('melder'): top", len(hits), "by hit count")
119 for hit in hits:
120 print(f" {hit.hits:>4} hits line {hit.first_line:<6} {hit.key}")
121
122 # 5. NOW PAY FOR ONE SECTION - and only one.
123 target = keys[0]
124 section = architecture.section(target)
125 body = architecture.get(target)
126 assert section.key == target
127 assert isinstance(body, str)
128 print()
129 print(f"get({target!r}) -> {len(body)} chars,"
130 f" {section.line_count} lines")
131
132 # 6. A CITATION AN AGENT CAN HAND BACK. Falsifiable, unlike a summary.
133 print("cite:", architecture.cite(target))
134 print("cite(line=...):",
135 architecture.cite(target, line=section.start_line))
136
137 # 7. THE CURSOR IS SCOPED TO A SECTION, which is why narrowing first
138 # means never paging the document.
139 reader = architecture.reader(target, line_target=20)
140 chunk = reader.read()
141 print()
142 print("reader(key).read() ->", chunk.end_line - chunk.start_line,
143 "lines, has_more =", chunk.has_more)
144 print(" a cursor over ONE SECTION, not over the document")
145
146 # 8. THE INTEGRITY GATE. The shipped text is checked against the
147 # digest its own index claimed.
148 verified = architecture.verify()
149 assert isinstance(verified, bool)
150 print()
151 print("verify() ->", verified,
152 " sha:", (architecture.content_sha256 or "")[:12], "...")
153 print(" an unavailable document answers False - nothing to check -")
154 print(" and still reports `available` and `reason` rather than")
155 print(" vanishing, because a gap invites an agent to invent")
156
157 # 9. THE GRAPH DOCUMENTS ARE THESE PLUS NODES AND EDGES.
158 graph = md.__graph_network__
159 assert isinstance(graph, type(architecture)) or True
160 print()
161 print("__graph_network__ is a", type(graph).__name__,
162 "- a document view PLUS:")
163 if graph.available:
164 print(" nodes:", graph.node_count, " edges:", graph.edge_count)
165 print(" relations:", list(graph.relations)[:4])
166 node_ids = graph.node_ids()
167 if node_ids:
168 first = node_ids[0]
169 print(" node_ids()[0] ->", first)
170 print(" details_key ->", graph.details_key(first))
171 else:
172 print(" did not ship:", graph.reason)
173
174 print()
175 print("survey with keys/groups, narrow with find/search, then pay")
176 print("for one section - and answer with a citation, not a summary")
177
178
179if __name__ == "__main__":
180 main()
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.