# Read versions, residency, and recorded code

Prerequisites: [recording setup](persistence.md) and [room authority](agent-rooms.md).
MutationResearch organizes version history. A `ResearchSet` has its own lanes,
residency, journal, and snapshots; another set can investigate the same live world
without sharing that organization.

## Separate place, lifecycle, and purpose

Lane state answers whether the lane is open, joined, or archived. Lane type names
the kind of work. Residency identifies the lane holding a declared version inside
one set. A campaign attributes work across lanes.

The campaign lesson demonstrates an important default: an omitted campaign on an
eligible write inherits the ambient campaign. Clear it to stop that attribution.
An omitted campaign on a history query instead leaves the read unfiltered.

## Read at the grain of the question

| Question | Starting read |
| --- | --- |
| What happened recently? | `research_recent` |
| Where is this version recorded? | `research_residency` |
| What code was recorded? | `research_source` |
| What is in one module? | `research_module` |
| Which top-level pieces exist? | `research_parts`, then `research_part` |
| What changed between versions? | `research_diff` or `research_part_diff` |

Comparisons use recorded material so two versions can remain distinct. Current
disk text cannot stand in for both versions of a historical diff. Select the
strategy explicitly when text, structural shape, and individual parts would answer
different questions. Foresight reads require custody to be available.

Room commands operate over their supported set surface. The plural-set lesson
uses the public MutationResearch/ResearchSet APIs to select independent sets
explicitly; do not assume every room command accepts `set_name`.


## The workflow in code

These are the core steps from the saved example. Use its complete linked script for all class definitions and setup.

```{literalinclude} ../downloads/04_expert/03_research_sets_lanes_and_residency.py
:language: python
:pyobject: main
:linenos:
```


## Runnable examples

- [Research sets lanes and residency](../examples/expert/03-research-sets-lanes-and-residency.md) — Expert 03
- [Diffs are derived never stored](../examples/expert/04-diffs-are-derived-never-stored.md) — Expert 04
- [Campaigns the why that rides along](../examples/expert/15-campaigns-the-why-that-rides-along.md) — Expert 15
- [Branching the record and joining back](../examples/expert/23-branching-the-record-and-joining-back.md) — Expert 23
- [Many research sets one world](../examples/expert/25-many-research-sets-one-world.md) — Expert 25
- [Reading your own recorded code](../examples/expert/29-reading-your-own-recorded-code.md) — Expert 29
- [Organising lanes after the fact](../examples/expert/31-organising-lanes-after-the-fact.md) — Expert 31

[All expert examples](../examples/expert/index.md) · [Level contents](index.md) · [Full contents](../contents.md)

[Canonical page source](https://github.com/Synaptic724/melder/blob/90d52e0a12cb0743d62568d5a19ce954a54443bc/docs/expert/research.md)