Read versions, residency, and recorded code

Prerequisites: recording setup and room authority. 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.

def main() -> None:
    # THE TWO ENUMS. Different questions, so different types.
    states = [state.name for state in md.LaneState]
    types = [kind.name for kind in md.LaneType]
    print("LaneState (lifecycle):", states)
    print("LaneType  (intent):   ", types)
    assert set(states) == {"open", "joined", "archived"}
    assert set(types) == {"development", "experiment", "production", "test"}

    # THE LADDER, third subsystem to use it (aether 07, crystallizer 17).
    # AETHER-HOSTED, and reached the same way as md.Crystallizer() and
    # md.Nexus(): Aether builds all three roots when it boots, so this call
    # is a LOOKUP, not a construction. One process, one Aether, one research
    # root under it - there is no free-standing research world to make.
    research = md.MutationResearch()
    assert research.activated is False
    print()
    print("start - configured:", research.is_configured,
          "activated:", research.activated)

    config = research.create_configuration()
    config.with_defaults().finalize()
    assert config.activated is False, "finalize seals; it does not enable"
    config.activate()
    research.activate(config)
    assert research.activated is True
    print("activated via the caller-driven ladder (not nexus's shortcut)")

    # A RESEARCH SET is one named body of history.
    research_set = research.create_research_set("promotion-history")
    assert isinstance(research_set, md.ResearchSet)
    assert research_set.name == "promotion-history"
    assert "promotion-history" in research.list_research_set_names()
    print()
    print("research set:", research_set.name, "| id:", research_set.set_id)

    # Every set opens with a default lane, so history has somewhere to go
    # before you have made any decisions about structure.
    default_lane = research_set.default_lane
    assert default_lane is not None
    assert research_set.lane_names(), "a set always has at least one lane"
    print("lanes:", research_set.lane_names())

    # LANE TYPE ENFORCEMENT IS A CHOICE, and it is readable.
    enforcement = research_set.lane_type_enforcement
    assert isinstance(enforcement, bool)
    research_set.set_lane_type_enforcement(True)
    assert research_set.lane_type_enforcement is True
    research_set.set_lane_type_enforcement(enforcement)
    print("lane_type_enforcement is a knob, currently:", enforcement)

    # RESIDENCY. One spell, one lane, one answer - and a miss is None
    # rather than an exception, the same honest-absence shape as
    # ConduitCloud.find_conduit_id_by_name (intermediate 37).
    assert research_set.residence_of("no-such-spell") is None
    print()
    print("residence_of() on an unknown spell -> None, not an exception")

    # THE READ SURFACE, ON A SET NOTHING HAS BEEN REGISTERED INTO. An
    # empty record is PRESENT AND EMPTY, not absent - which is the shape
    # you have to be able to tell apart from "no record at all".
    heads = research_set.heads()
    assert isinstance(heads, dict)
    assert "default" in heads, heads
    assert heads["default"] is None, heads
    print()
    print("heads() on a fresh set ->", heads)
    print("  the default lane is THERE with a tip of None. Open-but-empty")
    print("  and absent are different facts, and melder spells them")
    print("  differently: a missing key means `not open`, a None value")
    print("  means `open, nothing in it yet`")

    walked = research_set.walk("default")
    assert isinstance(walked, list) and walked == [], walked
    print("walk('default') ->", len(walked),
          "rows - somewhere for history to go before any has happened")
    print("  (history / campaign_view are driven in expert 29 and 15,")
    print("   where there is something recorded to read)")

    # CAMPAIGNS - group work across lanes without threading an id around.
    assert research.active_campaign is None
    research.set_active_campaign("q3-promotion")
    assert research.active_campaign == "q3-promotion"
    print()
    print("active campaign:", research.active_campaign)
    research.clear_active_campaign()
    assert research.active_campaign is None
    print("cleared - campaigns are explicit at both ends")

    # ANCESTRY IS STAGED FIRST. Declaring parents is a separate, visible
    # step from recording the entry that uses them.
    assert research.staged_ancestry is None
    research.stage_ancestry(["parent-a", "parent-b"])
    assert research.staged_ancestry == ["parent-a", "parent-b"]
    print()
    print("staged ancestry:", research.staged_ancestry)
    research.clear_staged_ancestry()
    assert research.staged_ancestry is None
    print("cleared - a half-built lineage is visible, never auto-attached")

    print()
    print("state is lifecycle, type is intent - a lane carries both")
    print("residency means one spell, one lane, one answer to 'where is it'")

Runnable examples

Research sets lanes and residency — Expert 03
Diffs are derived never stored — Expert 04
Campaigns the why that rides along — Expert 15
Branching the record and joining back — Expert 23
Many research sets one world — Expert 25
Reading your own recorded code — Expert 29
Organising lanes after the fact — Expert 31

All expert examples · Level contents · Full contents

Canonical page source