Notch swapping a live object

🔵 Expert · Lesson 17

LINEAGES, AND A HOT SWAP TAKEN END TO END. An index is a version LINEAGE with exactly one SELECTED member. This lesson builds one, stages a second version onto it, shows that staging changes nothing about what resolves - which is why the swap is a two-step act - then takes the swap by the new version's spell_id, melds it at the index's address, and notches back. Everything runs on public calls.

THE THREE VERBS

book.bind(...) v1 active on a fresh index conduit.bind_inactive(...) v2 PARKED on the same index; returns v2's spell_id conduit.notch_spell( v2 becomes the active member spell_index=index, spell_id=v2_id)

EVERY VERSION IS BOUND THE WAY THE FIRST ONE WAS. An index keeps its first version's binding for life: the kind of spellframe (none, a string category or a Protocol) and the address that gives - the spellframe's name, or a bare class's own name, and the binding name. bind_inactive refuses a version bound any other way before anything is registered, so a retry with the right arguments is admitted. That is why a notch never moves the address, and whoever melds by the address follows the notch. Two classes cannot share a bare address, so v1 and v2 are both bound under one string category, "pricing" (2026-10-25; until then a version could be staged at any address and a notch moved the address with it).

NAME THE VERSION BY ITS SPELL_ID. A spell_id names one version, and the public spell_id->object lookups (get_spell_by_spell_id, find_spell_by_spell_id) answer exactly that version, active or parked (owner ruling 2026-10-17; until 0.2.8253 they answered a parked spell_id with the ACTIVE member). notch_spell takes the spell_id too and resolves the exact version inside the call. The Spellbook is still not the surface you notch from - the conduit's verb does the resolving (owner ruling 2026-10-16; until then the verb took only the parked OBJECT, no public door handed one out, and this lesson stopped at staging).

WHAT STAGING ACTUALLY BUYS YOU bind_inactive puts a real, bound, owned spell into the lineage and leaves the selection alone. The candidate is inert and unmeldable until something promotes it. That separation is what lets a swap be PREPARED long before it is TAKEN - the expensive, failure-prone half (compiling and registering a new version) happens while the old version is still serving.

AND WHAT A NOTCH DOES WHEN IT HAPPENS 0. Checks the version: it must belong to the conduit's Spellbook and to the index you passed, or the call raises ValueError before anything moves. 1. Moves the address's frame claim from the outgoing version to the incoming one in one compare-and-set. When another spell holds the address it raises RuntimeError naming the holder, and nothing moves. 2. Parks the outgoing active spell off the four active owned maps, then TEARS DOWN ITS CREATION CONTEXT so the door epoch bumps and the warm fast-door cannot serve the stale spell. 3. Promotes the parked candidate into the active maps and repoints the index pointer, old spell_id -> new spell_id. 4. Re-registers the index gated + dirty, so revalidation recompiles LAZILY on the next resolve rather than inside the window. All of it happens under one seal, and the sealed conduits' creation gates are quiesced for the duration, so no in-flight meld can straddle the repoint. You do not arrange any of that; the verb does, the same way link does in expert 16.

THE OUTGOING VERSION IS NOT DESTROYED. It stays a member of the lineage, parked, with the object it built, which is why a rollback is structurally the same act as the swap - a notch back by its spell_id - rather than a restore.

MIND THE LAYER WHEN YOU READ THE SOURCE. _apply_notch says contracted borrowers are "NOT yet fanned out HERE (owner-side only)". That HERE is load-bearing: the seam is the local switch, and Conduit.notch_spell one layer up does walk the links. A statement read out of its scope becomes a false one.

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/17_notch_swapping_a_live_object.py

py -3.14t UX_and_AIX_experiences/04_expert/17_notch_swapping_a_live_object.py

Download this collection · Source on GitHub

Public surface

Conduit.bind_inactive, Conduit.notch_spell(spell_id=...), Conduit.meld(spellframe=...), SpellIndex.selected_spell_id / spells_in_index, Conduit.get_spell_by_spell_id

Code

"""
TIER: expert (17)
GOAL: LINEAGES, AND A HOT SWAP TAKEN END TO END. An index is a
      version LINEAGE with exactly one SELECTED member. This lesson
      builds one, stages a second version onto it, shows that staging
      changes nothing about what resolves - which is why the swap is a
      two-step act - then takes the swap by the new version's spell_id,
      melds it at the index's address, and notches back. Everything
      runs on public calls.

      THE THREE VERBS

        book.bind(...)                v1 active on a fresh index
        conduit.bind_inactive(...)    v2 PARKED on the same index;
                                      returns v2's spell_id
        conduit.notch_spell(          v2 becomes the active member
            spell_index=index, spell_id=v2_id)

      EVERY VERSION IS BOUND THE WAY THE FIRST ONE WAS. An index keeps
      its first version's binding for life: the kind of spellframe
      (none, a string category or a Protocol) and the address that
      gives - the spellframe's name, or a bare class's own name, and
      the binding name. `bind_inactive` refuses a version bound any
      other way before anything is registered, so a retry with the
      right arguments is admitted. That is why a notch never moves the
      address, and whoever melds by the address follows the notch. Two
      classes cannot share a bare address, so v1 and v2 are both bound
      under one string category, "pricing" (2026-10-25; until then a
      version could be staged at any address and a notch moved the
      address with it).

      NAME THE VERSION BY ITS SPELL_ID. A spell_id names one version,
      and the public spell_id->object lookups (`get_spell_by_spell_id`,
      `find_spell_by_spell_id`) answer exactly that version, active or
      parked (owner ruling 2026-10-17; until 0.2.8253 they answered a
      parked spell_id with the ACTIVE member). `notch_spell` takes the
      spell_id too and resolves the exact version inside the call. The
      Spellbook is still not the surface
      you notch from - the conduit's verb does the resolving (owner
      ruling 2026-10-16; until then the verb took only the parked
      OBJECT, no public door handed one out, and this lesson stopped
      at staging).

      WHAT STAGING ACTUALLY BUYS YOU
      `bind_inactive` puts a real, bound, owned spell into the lineage
      and leaves the selection alone. The candidate is inert and
      unmeldable until something promotes it. That separation is what
      lets a swap be PREPARED long before it is TAKEN - the expensive,
      failure-prone half (compiling and registering a new version)
      happens while the old version is still serving.

      AND WHAT A NOTCH DOES WHEN IT HAPPENS
        0. Checks the version: it must belong to the conduit's
           Spellbook and to the index you passed, or the call raises
           ValueError before anything moves.
        1. Moves the address's frame claim from the outgoing version to
           the incoming one in one compare-and-set. When another spell
           holds the address it raises RuntimeError naming the holder,
           and nothing moves.
        2. Parks the outgoing active spell off the four active owned
           maps, then TEARS DOWN ITS CREATION CONTEXT so the door epoch
           bumps and the warm fast-door cannot serve the stale spell.
        3. Promotes the parked candidate into the active maps and
           repoints the index pointer, old spell_id -> new spell_id.
        4. Re-registers the index gated + dirty, so revalidation
           recompiles LAZILY on the next resolve rather than inside the
           window.
      All of it happens under one seal, and the sealed conduits' creation
      gates are quiesced for the duration, so no in-flight meld can
      straddle the repoint. You do not arrange any of that; the verb
      does, the same way `link` does in expert 16.

      THE OUTGOING VERSION IS NOT DESTROYED. It stays a member of the
      lineage, parked, with the object it built, which is why a
      rollback is structurally the same act as the swap - a notch back
      by its spell_id - rather than a restore.

      MIND THE LAYER WHEN YOU READ THE SOURCE. `_apply_notch` says
      contracted borrowers are "NOT yet fanned out HERE (owner-side
      only)". That HERE is load-bearing: the seam is the local switch,
      and `Conduit.notch_spell` one layer up does walk the links. A
      statement read out of its scope becomes a false one.
SURFACE EXERCISED: Conduit.bind_inactive, Conduit.notch_spell(spell_id=...),
                   Conduit.meld(spellframe=...),
                   SpellIndex.selected_spell_id / spells_in_index,
                   Conduit.get_spell_by_spell_id
VERIFY: RUN GREEN 2026-10-25 on 3.14t, GIL off and on.
"""
import melder as md


class HotSwapPricingV1:
    def __init__(self) -> None:
        self.rate = 100


class HotSwapPricingV2:
    def __init__(self) -> None:
        self.rate = 250


def main() -> None:
    book = md.Spellbook(aetheric_frame="hotswap-world")
    v1_id = book.bind(
        spell=HotSwapPricingV1, spellframe="pricing",
        existence="unique", permissions="create",
    )
    conduit = book.conjure(dynamic=True, name="hotswap-root")
    print("v1 bound and active under the category 'pricing'")

    # THE INDEX IS PUBLICLY REACHABLE from the active spell, and it is a
    # LINEAGE: a set of member ids plus exactly one selection.
    active = conduit.get_spell_by_spell_id(v1_id)
    assert active is not None
    index = active.spell_index
    assert index.selected_spell_id == v1_id
    assert index.spells_in_index() == {v1_id}
    print("index: 1 member, selected =", v1_id[:12], "...")

    # v1 RESOLVES at the index's address. This is the world as it stands.
    before = conduit.meld(spellframe="pricing")
    assert before.rate == 100
    print("meld(spellframe='pricing') -> rate", before.rate)

    # A VERSION BOUND ANOTHER WAY IS REFUSED. Bound bare, v2 would be
    # addressed by its own name - another address than the index's - so
    # bind_inactive refuses it before anything is registered.
    try:
        conduit.bind_inactive(
            spell=HotSwapPricingV2,
            spell_index=index,
            existence="unique",
            permissions="create",
        )
    except ValueError as refusal:
        assert "keeps the binding its first version" in str(refusal)
    else:
        raise AssertionError("a version bound another way must be refused")
    assert index.spells_in_index() == {v1_id}
    print()
    print("bind_inactive bare -> ValueError: the index keeps its first")
    print("  version's binding, and nothing was registered")

    # STAGE A CANDIDATE bound the way the index's first version was. It is
    # bound, owned, and a real member of the lineage - and it changes
    # nothing about what resolves. The refused try left nothing behind, so
    # this is not a spell_id collision.
    v2_id = conduit.bind_inactive(
        spell=HotSwapPricingV2,
        spell_index=index,
        spellframe="pricing",
        existence="unique",
        permissions="create",
    )
    assert index.spells_in_index() == {v1_id, v2_id}
    assert index.selected_spell_id == v1_id, (
        "staging must NOT move the selection - preparing a swap and "
        "taking it are two different acts"
    )
    print("v2 staged under 'pricing': 2 members, selection UNCHANGED")

    # AND THE PARKED CANDIDATE IS INERT. The expensive half of the swap
    # has already happened - v2 is compiled, registered and owned - while
    # the old version is still the one serving traffic.
    still = conduit.meld(spellframe="pricing")
    assert still.rate == 100
    print("meld -> rate", still.rate, " (v2 is parked, not resolvable)")
    print("  the costly half of a swap is done while v1 still serves")

    # A SPELL_ID NAMES ONE VERSION. Looking up the parked spell_id answers
    # the parked version itself - not the member live for this lineage -
    # and the notch below is given that same spell_id.
    resolved_from_parked_id = conduit.get_spell_by_spell_id(v2_id)
    assert resolved_from_parked_id is not None
    assert resolved_from_parked_id.spell_id == v2_id
    print()
    print("looking up the PARKED spell_id returned the PARKED spell")
    print("  and the notch is told the same version by the same spell_id")

    # TAKE THE SWAP. The spell_id bind_inactive returned names the version;
    # the notch resolves it inside the call and checks that it belongs to
    # this index before anything moves. The address does not move: it now
    # serves v2.
    promoted = conduit.notch_spell(spell_index=index, spell_id=v2_id)
    assert promoted.spell_id == v2_id
    assert index.selected_spell_id == v2_id
    assert index.spells_in_index() == {v1_id, v2_id}, (
        "a notch moves the selection; it removes no member"
    )
    after = conduit.meld(spellframe="pricing")
    assert after.rate == 250
    assert conduit.meld(spell_id=v2_id) is after
    print()
    print("notch by spell_id: v2 selected, and the address follows -")
    print("  meld(spellframe='pricing') -> rate", after.rate)

    # ROLL BACK: the same verb pointed the other way, because v1 was
    # parked, not destroyed - and its object with it.
    conduit.notch_spell(spell_index=index, spell_id=v1_id)
    assert index.selected_spell_id == v1_id
    back = conduit.meld(spellframe="pricing")
    assert back.rate == 100
    assert back is before
    print("notch back by spell_id: v1 selected, meld -> rate", back.rate,
          "(v1's own object)")

    print()
    print("an index is a lineage with one selection and one binding")
    print("staging adds a member bound the same way; only a notch moves")
    print("the selection, and the address follows it")
    print("nothing is destroyed by a notch, which is why rolling back")
    print("is the same act and not a restore")


if __name__ == "__main__":
    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