Preview, stage, and govern structural change

Prerequisites: research, codegen, and structural admission. Begin with the existing version's residency, source, and impact. research_preview can combine a candidate analysis with the selected frame's codegen verdict before any candidate is bound.

The foresight example checks that preview leaves research heads unchanged and the original pricing object still returns its original result. A malformed candidate returns parse information that the caller can inspect.

Staging is not promotion

bind_inactive places a candidate into the existing SpellIndex while the selected member remains unchanged. Expert 17 asserts the member set, unchanged selection, and unchanged resolved result.

The runtime's promoting verb is notch_spell, which accepts a Spell object. The saved public staging lesson deliberately stops before hand-driving that operation: its demonstrated lookup by the parked ID returns the currently active member. Do not substitute a private-map access or claim that this lesson performs a full swap. The README's notch sketch assumes those version objects are already held.

Keep history and code reconciliation distinct

An anchored research lane starts empty. A clean join checks its relation to the receiver's current tip. A forced join records explicit supersede; it does not merge source code. Compose and evaluate the candidate first, then record the chosen outcome through the applicable public operation.

Archive hides a lane from the active view while retaining its history. It is not runtime object disposal. Keep deliberate version retirement and application cleanup separate from lane organization.

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:
    # 1. RECORD AND CUSTODY FIRST. A world built before these are live is
    #    a world neither of them ever saw.
    crystallizer = md.Crystallizer()
    crystallizer.activate(
        md.CrystallizerConfigurationBuilder().with_defaults().activate(),
    )
    research = md.MutationResearch()
    research_configuration = research.create_configuration()
    research_configuration.with_defaults().activate()
    research.activate(research_configuration)
    assert crystallizer.activated and research.activated
    print("custody recording:", crystallizer.activated,
          " research live:", research.activated)

    # 2. NOW build the world. The bind auto-records because research was
    #    already up - had we activated afterwards, nothing would have
    #    been recorded and no foresight would have been possible.
    # A RECORDED WORLD MUST BE BORN CONFIGURED. With custody active, a
    # dynamic conjure REFUSES if any bind ran before the configuration
    # was finalized - the profile record and default bootstrap would
    # otherwise durably persist binds made against unsettled config.
    spellbook_configuration = (
        md.SpellbookConfiguration(FRAME).with_defaults().finalize()
    )
    book = md.Spellbook(aetheric_frame=FRAME,
                        configuration=spellbook_configuration)
    # AND THE FRAME POSTURE GOES BEFORE THE BIND TOO, for a DIFFERENT
    # reason: a plain bind only auto-records `if self._is_dynamic_posture()`,
    # which reads the FRAME configuration and is answerable before conjure.
    # Bind into a not-yet-dynamic frame and the spell is never declared -
    # no residency, no foresight, and no error either, because research
    # bookkeeping never gates a bind.
    book.configure_aether_frame(
        system_state="dynamic",
        disposal=None,
        disposal_method_names=None,
        rift_enabled=True,
        ai_native=True,
    )
    spell_id = book.bind(
        spell=PriceRule, existence="unique", permissions="create",
        binding_name="foresight-rule",
    )
    conduit = book.conjure(name="foresight-root")
    live = conduit.meld(spell=PriceRule, binding_name="foresight-rule")
    assert live.apply(4) == 40
    print()
    print("world up; PriceRule.apply(4) ->", live.apply(4))
    print("spell_id:", spell_id[:12], "...")

    # 3. A codegen room pointed at it.
    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="foresight")
    rift.mark_active()
    rift.create_frame_link(FRAME)
    commands = rift.space.command_system

    # 4. WHAT DOES THE EXISTING VERSION TOUCH, RIGHT NOW?
    # `spell_id` is KEYWORD-ONLY here, and so is `module_name` - the verb
    # answers about exactly ONE center per call, so it will not let you
    # pass a bare identifier and leave which-kind-of-center to inference.
    radius = commands.research_impact(spell_id=spell_id)
    print()
    print("research_impact(existing) -> keys:", sorted(radius)[:6], "...")
    print("  the CURRENT blast radius, joined with research residency")

    # 5. THE FORESIGHT CALL. Snapshot the record first so we can prove
    #    the preview did not touch it.
    heads_before = commands.research_heads()

    preview = commands.research_preview(
        CANDIDATE,
        against_spell_id=spell_id,
        frame_name=FRAME,
    )
    for key in ("candidate_sha256", "module_name", "parse_error",
                "defines", "import_roots", "diff", "impact",
                "against_spell_id"):
        assert key in preview, key
    print()
    print("research_preview ->", len(preview), "keys")
    print("   parse_error :", preview["parse_error"])
    print("   defines     :", preview["defines"])
    print("   import_roots:", preview["import_roots"] or "(none)")
    print("   candidate   :", str(preview["candidate_sha256"])[:12], "...")
    print("   against     :", str(preview["against_spell_id"])[:12], "...")
    assert preview["parse_error"] is None
    assert preview["against_spell_id"] == spell_id
    print("  it read the candidate's AST - a class defined, no imports -")
    print("  diffed it against the version it would replace, and priced")
    print("  the replacement, all without running a line")

    # 6. AND THE ROOM'S VERDICT CAME ALONG, because frame_name was given.
    print()
    print("frame_name folded the permission question in:")
    print("  'may I' and 'what would happen' answered in ONE call")

    # 7. THE PROOF. Nothing executed, bound, or recorded.
    heads_after = commands.research_heads()
    assert heads_after == heads_before, (
        "research_preview must not move the record - it is foresight, "
        "not a dry-run that half-commits"
    )
    still = conduit.meld(spell=PriceRule, binding_name="foresight-rule")
    assert still.apply(4) == 40
    print("record heads: IDENTICAL before and after the preview")
    print("live object : still the old rule ->", still.apply(4))
    print("  'nothing executes, binds, or records' - checked, not trusted")

    # 8. A CANDIDATE THAT DOES NOT PARSE STILL ANSWERS.
    broken = commands.research_preview(BROKEN, frame_name=FRAME)
    assert broken["parse_error"] is not None
    print()
    print("a candidate that does not parse ->")
    print("   parse_error:", str(broken["parse_error"])[:60])
    print("  same payload shape, populated honestly. An agent's generator")
    print("  emits garbage sometimes, and a foresight tool that raised on")
    print("  garbage would fail exactly when it is most needed")

    print()
    print("ask what it WOULD do, then decide - and the asking is free")
    print("activate record and custody BEFORE you build, or there is")
    print("nothing to have foresight about")

Runnable examples

Asking what code would do before running it — Expert 22
Notch swapping a live object — Expert 17
Branching the record and joining back — Expert 23
Codegen create modify iterate — Expert 26

All expert examples · Level contents · Full contents

Canonical page source