Compose a subsystem and inspect its impact

Prerequisite: research records. A composition pins a set of recorded spell versions as one named unit. Its identity follows its membership. Recompose adds or removes selected members and produces a successor; it does not erase the previous roster.

Read the unit at the right grain

Roster, history, and member differences come from the research record. Footprint, drift, and impact join the member versions to custody information. Missing custody is reported explicitly; it must not silently count as an empty dependency graph.

The subsystem lesson creates three real module worlds before forming its group. Impact considers the union of member effects and distinguishes effects inside the composition from effects outside it. The membership comparison remains at subsystem grain; select changed members for deeper code comparisons afterward.

Compose source separately

research_synthesize selects top-level functions or classes from a donor module into a base module and returns composed source with a preview. A method is not a top-level function. The workshop lesson exercises both replacement and addition using two generated modules so the comparison has two genuinely different inputs.

Staged ancestry belongs to the next fresh world entry. If the candidate is abandoned, clear that staging explicitly so an unrelated later bind cannot inherit it.

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:
    crystallizer = md.Crystallizer()
    crystallizer.activate(
        md.CrystallizerConfigurationBuilder().with_defaults().activate(),
    )
    research = md.MutationResearch()
    configuration = research.create_configuration()
    configuration.with_defaults().activate()
    research.activate(configuration)

    spellbook_configuration = (
        md.SpellbookConfiguration(FRAME).with_defaults().finalize()
    )
    book = md.Spellbook(aetheric_frame=FRAME,
                        configuration=spellbook_configuration)
    book.configure_aether_frame(
        system_state="dynamic",
        disposal=None,
        disposal_method_names=None,
        rift_enabled=True,
        ai_native=True,
    )

    # AN EMPTY FRAME IS A REAL FRAME. `configure_aether_frame` declares the
    # frame's LAW; `conjure` REALIZES it by giving it a root conduit, and
    # that realization is what publishes it to the Nexus. Publication is
    # gated on `rift_enabled` ALONE - the spell loop it runs iterates
    # whatever the book holds, including nothing. So the frame below is
    # conjured EMPTY and is immediately linkable; spells are cargo, not a
    # precondition, and everything bound after this arrives incrementally.
    book.conjure(name="workshop-root")

    nexus = md.Nexus()
    system_configuration = nexus.create_configuration()
    system_configuration.with_rift_creation_enabled(True)
    system_configuration.with_allowed_target_frame_names([FRAME])
    nexus.activate(system_configuration)
    rift_configuration = nexus.create_rift_configuration()
    rift_configuration.with_space_type("codegen")
    rift = nexus.create_rift(configuration=rift_configuration,
                             rift_name="workshop")
    rift.mark_active()
    rift.create_frame_link(FRAME)
    commands = rift.space.command_system

    # THE ROOM WRITES BOTH MODULE WORLDS. Validation gates materialization;
    # a rejected verdict registers and publishes NOTHING.
    print("THE ROOM WRITES ITS OWN MATERIAL:")
    for module_name, source in ((BASE_MODULE, BASE_SOURCE),
                                (DONOR_MODULE, DONOR_SOURCE)):
        verdict = commands.validate_codegen(source, frame_name=FRAME)
        kept = commands.materialize_codegen(
            source, module_name=module_name, frame_name=FRAME,
        )
        assert kept["materialized"] is True, kept
        print("  %-26s validate(%s) -> materialize(ok)"
              % (module_name, type(verdict).__name__))

    # The import hook is installed, so plain import resolves onto the
    # world object. THIS is what gives two spells two module worlds.
    base_module = importlib.import_module(BASE_MODULE)
    donor_module = importlib.import_module(DONOR_MODULE)

    # DISTINCT CLASS NAMES, and that is not cosmetic. These are two
    # INDEPENDENT binds, so both spells are visible at once - and two
    # visible spells sharing a name make `meld("SpellName")` ambiguous,
    # which the structural validator refuses outright. A distinct
    # binding_name alone does NOT settle it; the name itself has to
    # resolve, or the pair needs a spellframe. (Two versions on ONE
    # lineage are exempt - they are one spell, not two.)
    base = book.bind(spell=base_module.ReportBase, existence="unique",
                     permissions="create", binding_name="workshop-base")
    donor = book.bind(spell=donor_module.ReportDonor, existence="unique",
                      permissions="create", binding_name="workshop-donor")
    print("  bound from the generated modules -> custody minted")
    print("  base:", base[:12], " donor:", donor[:12])

    # THE DEFAULT IS KIND-AWARE, not a single fallback. Asked for a diff
    # with no strategy, the room checks whether BOTH sides are
    # compositions. If they are not, it pins "structural" - its reasoning
    # layer - and calls down. If they ARE, it passes NO strategy at all and
    # lets the engine's own "members" default answer. One verb, two
    # vocabularies, chosen by what you handed it.
    print()
    print("DIFF IS DERIVED, and its default is KIND-AWARE:")
    print("  spell pair       -> the room pins `structural`")
    print("  composition pair -> the room stands back; engine says `members`")
    try:
        _show("diff(default)", commands.research_diff(base, donor))
        _show("diff(source)",
              commands.research_diff(base, donor, strategy="source"))
        _show("diff(parts)",
              commands.research_diff(base, donor, strategy="parts"))
    except RuntimeError as custody:
        print("  custody read REFUSED:", str(custody)[:100])
        return
    print("  these two are spells, so `structural` was chosen FOR them")

    # AN EXPLICIT ASK IS NEVER REROUTED. The room pins a default only when
    # you supplied none; the moment you name a strategy it goes down
    # untouched, and an unknown name surfaces the engine's own KeyError
    # rather than being quietly answered by a different question.
    try:
        commands.research_diff(base, donor, strategy="no-such-strategy")
        raise AssertionError("expected the engine's KeyError")
    except KeyError as unknown:
        print("  unknown strategy -> KeyError:", str(unknown)[:70])
        print("  a default is a KINDNESS FOR SILENCE, never an override")

    # THE GRAIN, learned the way the engine teaches it. `summarise` is a
    # METHOD on the donor's Report, not a top-level function.
    print()
    print("THE WORKSHOP - compose, do not merge:")
    try:
        commands.research_synthesize(base, donor,
                                     take_functions=["summarise"])
        raise AssertionError("a method is not a top-level function")
    except ValueError as grain:
        print("  take_functions=['summarise'] REFUSED:")
        print("   ", str(grain)[:112])
        print("  the refusal NAMES the donor's real top-level parts")

    # TWO MODULE WORLDS MEAN BOTH ACTIONS ARE REACHABLE.
    replaced = commands.research_synthesize(
        base, donor, take_functions=["render_header"],
    )
    assert replaced["base_module"] != replaced["donor_module"], (
        "the whole point of generating two modules"
    )
    assert [row["action"] for row in replaced["selections"]] == ["replaced"]
    print("  take_functions=['render_header'] -> REPLACED (base had one)")

    added = commands.research_synthesize(
        base, donor, take_functions=["render_footer"],
    )
    assert [row["action"] for row in added["selections"]] == ["added"]
    assert "render_footer" in str(added["composed_source"])
    _show("synthesize", added)
    print("  take_functions=['render_footer'] -> ADDED (base had none)")
    print("  'added' is only reachable across TWO module worlds, which is")
    print("  why this lesson generates them instead of typing them here")
    print("  composed source + preview returned. NOTHING executed, bound")
    print("  or recorded - a candidate is not a version")

    # THE ANCESTRY STAMP - ambient, one-shot, survives until used.
    print()
    print("THE ANCESTRY STAMP:")
    commands.research_stage_ancestry([base, donor])
    print("  staged [base, donor] for the NEXT fresh world entry")
    commands.research_clear_staged_ancestry()
    print("  cleared without consuming - abandoning a composition without")
    print("  this is how a later, innocent bind acquires false parents")

    staged = commands.research_synthesize(
        base, donor, take_functions=["render_footer"], stage_ancestry=True,
    )
    assert staged["ancestry_staged"] is True
    print("  stage_ancestry=True stages [base, donor] in the same call")
    commands.research_clear_staged_ancestry()

    print()
    print("compose in the workshop; the record books the outcome")
    print("a version-control system that merged your source would be")
    print("guessing, and this one refuses to guess")

Runnable examples

Composing a version in the workshop — Expert 30
Compositions a subsystem as one unit — Expert 14
A subsystems blast radius — Expert 32

All expert examples · Level contents · Full contents

Canonical page source