On this page

Many research sets one world๏ƒ

๐Ÿ”ต Expert ยท Lesson 25

RESEARCH SETS, PLURAL. Everything so far used the default set and never said there was a choice. A ResearchSet is a whole INDEPENDENT BODY OF HISTORY over the same runtime - its own lanes, its own residency, its own journal, its own campaigns.

research.create_research_set("refactor-2026") research.list_research_set_names() research.research_set("refactor-2026")

WHY MORE THAN ONE Lanes branch a line of versions. A SET is the thing lanes live in - so two sets are two entirely separate investigations that happen to be looking at the same world. Expert 23's join can never cross them, residency is per set, and a lane name in one set says nothing about a lane name in the other. Two agents auditing the same runtime for different reasons do not have to agree on a lane vocabulary, or even know about each other.

EVERY RESEARCH VERB TAKES set_name, AND IT DEFAULTS Root-level reads and writes carry set_name="default". That is why the first twenty-odd lessons never mentioned sets: the default was doing the work silently. The moment you have two, the argument stops being decoration.

AN UNKNOWN SET NAME RAISES, AND THE ERROR LISTS THE KNOWN ONES This is a small thing that matters enormously to an agent. A typo does not return an empty set that looks like "no history here" - it refuses AND tells you what does exist, so the next call is correct instead of being another guess. Compare with a silent empty: an agent would conclude the world had no record and act on it.

AND OMITTING THE NAME RESOLVES THE DEFAULT, NOT ALL SETS. research_set() is "the default one", never "every one" - so the cheap call is scoped rather than sweeping, and nothing accidentally reports across investigations that were meant to stay apart.

THE WORLD IS SHARED; THE RECORD IS NOT The spells, the frames, the conduits - one runtime, seen by both. What differs is what each set has DECLARED about it. A version can be resident in one set and unknown to another, and neither is wrong: a research set records what an investigation chose to look at, not everything that exists.

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/25_many_research_sets_one_world.py

py -3.14t UX_and_AIX_experiences/04_expert/25_many_research_sets_one_world.py

Download this collection ยท Source on GitHub

Public surface๏ƒ

MutationResearch.create_research_set / list_research_set_names / research_set, per-set lanes and residency, and the set_name argument on the root research verbs

Code๏ƒ

  1"""
  2TIER: expert (25)
  3GOAL: RESEARCH SETS, PLURAL. Everything so far used the default set and
  4      never said there was a choice. A ResearchSet is a whole INDEPENDENT
  5      BODY OF HISTORY over the same runtime - its own lanes, its own
  6      residency, its own journal, its own campaigns.
  7
  8        research.create_research_set("refactor-2026")
  9        research.list_research_set_names()
 10        research.research_set("refactor-2026")
 11
 12      WHY MORE THAN ONE
 13      Lanes branch a line of versions. A SET is the thing lanes live in -
 14      so two sets are two entirely separate investigations that happen to
 15      be looking at the same world. Expert 23's join can never cross
 16      them, residency is per set, and a lane name in one set says nothing
 17      about a lane name in the other. Two agents auditing the same
 18      runtime for different reasons do not have to agree on a lane
 19      vocabulary, or even know about each other.
 20
 21      EVERY RESEARCH VERB TAKES `set_name`, AND IT DEFAULTS
 22      Root-level reads and writes carry `set_name="default"`. That is why
 23      the first twenty-odd lessons never mentioned sets: the default was
 24      doing the work silently. The moment you have two, the argument
 25      stops being decoration.
 26
 27      AN UNKNOWN SET NAME RAISES, AND THE ERROR LISTS THE KNOWN ONES
 28      This is a small thing that matters enormously to an agent. A typo
 29      does not return an empty set that looks like "no history here" -
 30      it refuses AND tells you what does exist, so the next call is
 31      correct instead of being another guess. Compare with a silent
 32      empty: an agent would conclude the world had no record and act on
 33      it.
 34
 35      AND OMITTING THE NAME RESOLVES THE DEFAULT, NOT ALL SETS.
 36      `research_set()` is "the default one", never "every one" - so the
 37      cheap call is scoped rather than sweeping, and nothing accidentally
 38      reports across investigations that were meant to stay apart.
 39
 40      THE WORLD IS SHARED; THE RECORD IS NOT
 41      The spells, the frames, the conduits - one runtime, seen by both.
 42      What differs is what each set has DECLARED about it. A version can
 43      be resident in one set and unknown to another, and neither is
 44      wrong: a research set records what an investigation chose to look
 45      at, not everything that exists.
 46SURFACE EXERCISED: MutationResearch.create_research_set /
 47                   list_research_set_names / research_set, per-set lanes
 48                   and residency, and the set_name argument on the root
 49                   research verbs
 50VERIFY: rides the owner's 3.14t harness; asserts are the contract.
 51"""
 52import melder as md
 53
 54
 55FRAME = "many-sets-world"
 56
 57
 58class Invoice:
 59    def __init__(self) -> None:
 60        self.total = 0
 61
 62
 63def main() -> None:
 64    crystallizer = md.Crystallizer()
 65    crystallizer.activate(
 66        md.CrystallizerConfigurationBuilder().with_defaults().activate(),
 67    )
 68    research = md.MutationResearch()
 69    configuration = research.create_configuration()
 70    configuration.with_defaults().activate()
 71    research.activate(configuration)
 72
 73    # ONE WORLD. Both investigations will look at exactly this.
 74    # A RECORDED WORLD MUST BE BORN CONFIGURED. With custody active, a
 75    # dynamic conjure REFUSES if any bind ran before the configuration
 76    # was finalized - the profile record and default bootstrap would
 77    # otherwise durably persist binds made against unsettled config.
 78    spellbook_configuration = (
 79        md.SpellbookConfiguration(FRAME).with_defaults().finalize()
 80    )
 81    book = md.Spellbook(aetheric_frame=FRAME,
 82                        configuration=spellbook_configuration)
 83    invoice_id = book.bind(
 84        spell=Invoice, existence="unique", permissions="create",
 85        binding_name="sets-invoice",
 86    )
 87    book.configure_aether_frame(
 88        system_state="dynamic",
 89        disposal=None,
 90        disposal_method_names=None,
 91    )
 92    book.conjure(name="sets-root")
 93    print("one world, one spell:", invoice_id[:12], "...")
 94
 95    # THE DEFAULT SET WAS ALWAYS THERE - every earlier lesson used it
 96    # without naming it.
 97    names = research.list_research_set_names()
 98    print()
 99    print("research sets at start:", names)
100    assert "default" in names
101
102    # A SECOND INVESTIGATION. Its own lanes, journal, residency.
103    research.create_research_set("refactor-2026")
104    research.create_research_set("security-audit")
105    names = research.list_research_set_names()
106    print("after creating two more:", names)
107    assert {"default", "refactor-2026", "security-audit"} <= set(names)
108
109    refactor = research.research_set("refactor-2026")
110    audit = research.research_set("security-audit")
111    assert refactor is not audit
112
113    # LANE VOCABULARIES DO NOT COLLIDE ACROSS SETS. Both investigations
114    # can call a lane "candidate" and mean different things.
115    refactor.create_lane("candidate", lane_type="experiment")
116    audit.create_lane("candidate", lane_type="test")
117    print()
118    print("both sets have a lane called 'candidate' - and they are")
119    print("different lanes in different histories")
120
121    # DECLARE THE SPELL IN ONE SET ONLY. This is the crux: a version can
122    # be resident in one investigation and unknown to another.
123    refactor.register_spell(invoice_id, lane="candidate",
124                            reason="under refactor review")
125    assert refactor.residence_of(invoice_id) is not None
126    assert audit.residence_of(invoice_id) is None
127    print()
128    print("declared in 'refactor-2026'   -> resident")
129    print("not declared in 'security-audit' -> residence_of is None")
130    print("  neither is wrong. A set records what an investigation chose")
131    print("  to look at, not everything that exists")
132
133    # THE SAME QUESTION, ASKED OF EACH SET, GIVES DIFFERENT ANSWERS.
134    # `walk(lane)` returns that lane's line of versions plus its ancestry
135    # hop - so the same lane NAME in two sets walks two different lines.
136    refactor_walk = refactor.walk("candidate")
137    audit_walk = audit.walk("candidate")
138    assert isinstance(refactor_walk, list)
139    print()
140    print("walk('candidate') in each set:")
141    print("   refactor-2026  ->", len(refactor_walk), "version(s)")
142    print("   security-audit ->", len(audit_walk), "version(s)")
143    assert len(refactor_walk) == 1 and len(audit_walk) == 0, (
144        "the spell was declared in one investigation only"
145    )
146    # Each node payload carries its lane identity alongside the node
147    # fields, so a walked row is self-describing.
148    row = refactor_walk[0]
149    print("   a walked row carries:", sorted(row)[:5], "...")
150    print("  same lane name, two histories, and neither can see the other")
151
152    # A TYPO REFUSES AND NAMES WHAT EXISTS. This is the difference
153    # between an agent self-correcting and an agent inventing.
154    try:
155        research.research_set("refactor-2025")
156        raise AssertionError("expected a refusal on an unknown set name")
157    except Exception as error:
158        message = str(error)
159        print()
160        print("research_set('refactor-2025') refused -")
161        print("  ", message[:130])
162        assert "refactor-2026" in message or "default" in message, (
163            "the refusal must LIST the known names, or a typo is just a "
164            "dead end"
165        )
166        print("  it listed the real names, so the next call is correct")
167        print("  rather than another guess. An empty return here would")
168        print("  have read as 'this world has no history'")
169
170    # AND THE BARE CALL IS THE DEFAULT, NEVER ALL OF THEM.
171    default_set = research.research_set()
172    assert default_set is research.research_set("default")
173    print()
174    print("research_set() with no name IS the default set - scoped, not")
175    print("sweeping, so nothing reports across investigations by accident")
176
177    print()
178    print("lanes branch a line; a SET is the world those lanes live in")
179    print("one runtime, several independent records of it")
180
181
182if __name__ == "__main__":
183    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.

More expert examples ยท Level guide

API contracts๏ƒ