On this page
Research is graduated by room๏
๐ต Expert ยท Lesson 08
HOW AN AGENT REACHES MUTATION RESEARCH - and the discovery that access to it is GRADUATED BY ROOM KIND, exactly the way the conduit surface was in advanced 11.
MEASURE THE THREE ROOMS AND THE PATTERN IS UNMISSABLE:
static room 0 research verbs capability room 21 research verbs codegen room 34 research verbs
And the split is not arbitrary. Compare the two that have any:
capability-only verbs: NONE codegen-only verbs: 13
Codegen is a STRICT SUPERSET. So the question is only: which 13 does it add? Every one of them is a WRITE.
SHAPING LANES research_create_lane, research_attach, research_detach, research_join, research_archive CAMPAIGN STATE research_set_campaign, research_clear_campaign ANCESTRY STAGING research_stage_ancestry, research_clear_staged_ancestry COMPOSITION research_group_register, research_group_recompose CANDIDATES research_preview, research_synthesize
THE LAW, STATED PLAINLY: A CAPABILITY ROOM CAN READ THE ENTIRE RESEARCH RECORD AND CANNOT CHANGE ONE THING IN IT. ONLY A CODEGEN ROOM CAN SHAPE HISTORY.
That is the same shape as advanced 11 one level up. There, static could reuse an existing spell but not create one; capability could create. Here, capability can read the whole record but not write it; codegen can. The library applies one authority idea to two different planes, and in both cases it does it BY ABSENCE - the verb is not on the class, it is not a guard that refuses.
WHY THAT PARTICULAR LINE Reading history is safe: it cannot mislead anyone else. WRITING history is not - a lane you archived, an ancestry you staged, a group you recomposed all change what the NEXT reader concludes. So the room that may fabricate code is also the only room that may restate the past, and both powers arrive together rather than separately.
AND THE PAIR THAT MAKES IT WORTH HAVING research_preview what would this DO? validate_codegen am I PERMITTED to do this? (lesson 07) Two independent "would this work" questions, both answerable WITHOUT acting. Most systems make an agent choose between acting blindly and not acting at all. AND A VERB HAS THREE STATES, NOT TWO. It can be ABSENT (static has no research surface at all), PRESENT BUT REFUSING (the room carries it, the research root is not up, and the call raises a teach-grade RuntimeError), or WORKING. The command path takes a NON-CONSTRUCTING peek at the root precisely so that asking for research never boots one behind your back - and someone who ASKED deserves an error rather than an empty answer that reads like "nothing was recorded". Collapsing those two into one reply is how a reader concludes a world has no history when what it has is no ROOT.
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/08_research_is_graduated_by_room.py
py -3.14t UX_and_AIX_experiences/04_expert/08_research_is_graduated_by_room.py
Public surface๏
the research_* gradient across static / capability / codegen rooms computed off the live surfaces; read-vs-write as the dividing line; and research_heads driven from a capability room both before and after MutationResearch is activated
Code๏
1"""
2TIER: expert (08)
3GOAL: HOW AN AGENT REACHES MUTATION RESEARCH - and the discovery that
4 access to it is GRADUATED BY ROOM KIND, exactly the way the conduit
5 surface was in advanced 11.
6
7 MEASURE THE THREE ROOMS AND THE PATTERN IS UNMISSABLE:
8
9 static room 0 research verbs
10 capability room 21 research verbs
11 codegen room 34 research verbs
12
13 And the split is not arbitrary. Compare the two that have any:
14
15 capability-only verbs: NONE
16 codegen-only verbs: 13
17
18 Codegen is a STRICT SUPERSET. So the question is only: which 13
19 does it add? Every one of them is a WRITE.
20
21 SHAPING LANES research_create_lane, research_attach,
22 research_detach, research_join, research_archive
23 CAMPAIGN STATE research_set_campaign, research_clear_campaign
24 ANCESTRY STAGING research_stage_ancestry,
25 research_clear_staged_ancestry
26 COMPOSITION research_group_register, research_group_recompose
27 CANDIDATES research_preview, research_synthesize
28
29 THE LAW, STATED PLAINLY:
30 A CAPABILITY ROOM CAN READ THE ENTIRE RESEARCH RECORD AND CANNOT
31 CHANGE ONE THING IN IT. ONLY A CODEGEN ROOM CAN SHAPE HISTORY.
32
33 That is the same shape as advanced 11 one level up. There, static
34 could reuse an existing spell but not create one; capability could
35 create. Here, capability can read the whole record but not write
36 it; codegen can. The library applies one authority idea to two
37 different planes, and in both cases it does it BY ABSENCE - the
38 verb is not on the class, it is not a guard that refuses.
39
40 WHY THAT PARTICULAR LINE
41 Reading history is safe: it cannot mislead anyone else. WRITING
42 history is not - a lane you archived, an ancestry you staged, a
43 group you recomposed all change what the NEXT reader concludes. So
44 the room that may fabricate code is also the only room that may
45 restate the past, and both powers arrive together rather than
46 separately.
47
48 AND THE PAIR THAT MAKES IT WORTH HAVING
49 research_preview what would this DO?
50 validate_codegen am I PERMITTED to do this? (lesson 07)
51 Two independent "would this work" questions, both answerable
52 WITHOUT acting. Most systems make an agent choose between acting
53 blindly and not acting at all.
54 AND A VERB HAS THREE STATES, NOT TWO. It can be ABSENT (static has
55 no research surface at all), PRESENT BUT REFUSING (the room carries
56 it, the research root is not up, and the call raises a teach-grade
57 RuntimeError), or WORKING. The command path takes a NON-CONSTRUCTING
58 peek at the root precisely so that asking for research never boots
59 one behind your back - and someone who ASKED deserves an error
60 rather than an empty answer that reads like "nothing was recorded".
61 Collapsing those two into one reply is how a reader concludes a
62 world has no history when what it has is no ROOT.
63SURFACE EXERCISED: the research_* gradient across static / capability /
64 codegen rooms computed off the live surfaces;
65 read-vs-write as the dividing line; and research_heads
66 driven from a capability room both before and after
67 MutationResearch is activated
68VERIFY: RUN GREEN 2026-08-03; the three-state section added 2026-08-05
69 and not yet re-run.
70"""
71import melder as md
72
73# The 13 verbs a codegen room adds - every one writes to the record.
74CODEGEN_ONLY = (
75 "research_create_lane", "research_attach", "research_detach",
76 "research_join", "research_archive",
77 "research_set_campaign", "research_clear_campaign",
78 "research_stage_ancestry", "research_clear_staged_ancestry",
79 "research_group_register", "research_group_recompose",
80 "research_preview", "research_synthesize",
81)
82
83# A sample of the reads capability already has - proof the line is
84# read/write and not "codegen gets research".
85SHARED_READS = (
86 "research_walk", "research_history", "research_heads",
87 "research_residency", "research_diff", "research_impact",
88 "research_group_view", "research_group_diff", "research_source_drift",
89)
90
91
92def _room(nexus, kind, name):
93 config = nexus.create_rift_configuration()
94 config.with_space_type(kind)
95 rift = nexus.create_rift(configuration=config, rift_name=name)
96 rift.mark_active()
97 return rift.space
98
99
100def _research_verbs(commands) -> set:
101 return {name for name in dir(commands) if name.startswith("research_")}
102
103
104def main() -> None:
105 nexus = md.Nexus()
106 system_config = nexus.create_configuration()
107 system_config.with_rift_creation_enabled(True)
108 nexus.activate(system_config)
109
110 static = _room(nexus, "static", "grad-static").command_system
111 capability = _room(nexus, "capability", "grad-capability").command_system
112 codegen = _room(nexus, "codegen", "grad-codegen").command_system
113
114 static_verbs = _research_verbs(static)
115 capability_verbs = _research_verbs(capability)
116 codegen_verbs = _research_verbs(codegen)
117
118 print("research verbs by room kind:")
119 print(" static ", len(static_verbs))
120 print(" capability ", len(capability_verbs))
121 print(" codegen ", len(codegen_verbs))
122
123 # THE GRADIENT. Not a binary - three tiers.
124 assert len(static_verbs) == 0, "a static room cannot ask what changed"
125 assert 0 < len(capability_verbs) < len(codegen_verbs)
126 print()
127 print("a STATIC room cannot ask what changed at all")
128
129 # STRICT SUPERSET. Capability has nothing codegen lacks.
130 assert capability_verbs < codegen_verbs, "codegen must be a superset"
131 only_capability = capability_verbs - codegen_verbs
132 assert not only_capability, f"capability-only verbs: {only_capability}"
133 print("codegen is a STRICT SUPERSET - capability has nothing it lacks")
134
135 # AND THE 13 IT ADDS ARE ALL WRITES.
136 added = codegen_verbs - capability_verbs
137 print()
138 print("codegen adds", len(added), "verbs, and every one WRITES:")
139 for verb in sorted(added):
140 print(" ", verb)
141 for verb in CODEGEN_ONLY:
142 assert verb in added, f"{verb} was expected to be codegen-only"
143 assert not hasattr(capability, verb), (
144 f"capability gained {verb} - the read/write line moved"
145 )
146
147 # THE READS ARE SHARED. This is what proves the line is read-vs-write
148 # rather than "codegen gets research".
149 print()
150 print("capability already has every read, including:")
151 for verb in SHARED_READS:
152 assert hasattr(capability, verb), verb
153 assert hasattr(codegen, verb), verb
154 print(" ", verb)
155
156 # AND THERE IS A THIRD STATE, which presence alone cannot show.
157 # A verb can be ABSENT, or PRESENT BUT REFUSING, or WORKING - and
158 # melder spells all three differently.
159 #
160 # Right now MutationResearch is not up. The verb is on the surface and
161 # it REFUSES LOUDLY rather than returning None, because the command
162 # path takes a NON-CONSTRUCTING peek at the research root: asking for
163 # research must never quietly boot one behind your back, and a user
164 # who ASKED deserves an error rather than an empty answer that reads
165 # like "there is nothing recorded".
166 try:
167 capability.research_heads()
168 raise AssertionError("expected a refusal: research is not active")
169 except RuntimeError as inactive:
170 print()
171 print("capability.research_heads() with research DOWN refused:")
172 print(" ", str(inactive)[:104])
173
174 # NOW BRING IT UP and the same call answers. Same verb, same room.
175 research = md.MutationResearch()
176 configuration = research.create_configuration()
177 configuration.with_defaults().activate()
178 research.activate(configuration)
179
180 heads = capability.research_heads()
181 assert isinstance(heads, dict), heads
182 print()
183 print("...and with research UP the SAME call answers:", sorted(heads))
184 print(" three states, spelled three ways: ABSENT on static,")
185 print(" PRESENT-BUT-REFUSING while the root is down, WORKING once it")
186 print(" is up. Collapsing any two of those into one answer is how a")
187 print(" reader concludes a world has no history when it has no ROOT.")
188
189 # The write half is still refused by ABSENCE, even now that research
190 # is live - the gradient is about AUTHORITY, not about availability.
191 assert not hasattr(capability, "research_create_lane"), (
192 "activating research must not hand capability the write verbs"
193 )
194 print(" and a live research root does NOT hand capability the writes")
195
196 # AUTHORITY BY ABSENCE, one plane up from advanced 11.
197 assert not hasattr(static, "research_walk")
198 assert not hasattr(capability, "research_create_lane")
199 print()
200 print("absence again - not a guard that refuses, a verb that is not there")
201
202 # THE PAIR. Permission and consequence, both without acting.
203 assert hasattr(codegen, "research_preview")
204 assert hasattr(codegen, "validate_codegen")
205 print()
206 print("validate_codegen -> am I PERMITTED?")
207 print("research_preview -> what would it DO?")
208 print("both answerable without acting. that is the whole AIX story.")
209
210 print()
211 print("capability READS the record; only codegen may WRITE it")
212 print("the room that may fabricate code is the room that may restate")
213 print("the past - both powers arrive together, never separately")
214
215
216if __name__ == "__main__":
217 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.