# 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](../../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/08_research_is_graduated_by_room.py
```

```powershell
py -3.14t UX_and_AIX_experiences/04_expert/08_research_is_graduated_by_room.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/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

```{literalinclude} ../../downloads/04_expert/08_research_is_graduated_by_room.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

- [Agent rooms and explicit authority](../../expert/agent-rooms.md)

## API contracts

- [MutationResearch](../../reference/api/research/mutationresearch.md)