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.

For application checks at registration itself, use the bind-hook review pipeline. Its pre callbacks inspect the supplied reference, activation annotates the new Spell, and post observes the registered result.

Staging is not promotion

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

The candidate is bound the way the index's first version was: the same kind of spellframe (none, a string category or a Protocol) and the same address (the spellframe's name, or a bare class's own name, and the binding name). bind_inactive refuses any other binding before it registers anything, and add_to_spell_index refuses to move a version into an index bound another way. So a notch never moves the address, and a meld by the address builds whichever version is selected. Versions that carry different class names are bound under one spellframe category from the first version on; expert 17 does that and shows a bare staging refused.

Promotion is notch_spell(spell_index=..., spell_id=...) given that spell_id: the candidate becomes the selected member and the next meld builds it, and a notch back by the previous spell_id restores the old version, which stayed parked. Expert 17 runs the whole loop on public calls, as does the README's sketch. A lookup by spell_id is exact: get_spell_by_spell_id returns the version that spell_id names, parked or active, and the version an index has active is a lookup by the index, get_spell_by_index_id. The calls that build nothing follow the same rule: has_live_creation(spell=...), describe_live_creation_status(spell=...) and purge(spell_id=...) given a spell_id answer for that version, parked or active, so a parked version's objects can be checked or retired without a notch back; meld builds only the selected member. notch_spell refuses a version of another index, or one another Spellbook owns, before it changes anything, and it refuses an address another spell holds: a version split off into an index of its own keeps its binding, so it can be notched active there only once its old index no longer serves that address. add_to_spell_index and remove_from_spell_index take spell_id= the same way, to move a parked candidate onto another index bound the same way or out into one of its own.

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("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("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