Record structure before you need to restore it

Prerequisites: checkpoint entry points and configuration ownership. Crystallizer records structural information and source custody. A checkpoint is not a serialization of your live application objects or their arbitrary mutable state.

Setup order is part of the example

For the recorded dynamic-world examples, activate custody and research first, finalize the SpellbookConfiguration, configure dynamic frame posture, and then bind and conjure. This makes recording available when the structural events occur. Activating a recorder afterward does not imply it observed earlier bindings.

Profiles, checkpoints, and research sets

Name	Partitions or identifies
Persistence profile	The content window receiving recorded emissions
Checkpoint ID	A particular checkpoint in ledger creation order
Research set	An independent body of declared version history and residency
Aetheric frame	A live runtime world

Switching the active profile moves a pointer. It does not copy the previous profile's content, and list_checkpoint_ids() remains a process-wide ledger read. The profile lesson compares explicit and active-profile descriptions and exercises clear versus delete.

Know where the source came from

Synthetic modules carry recorded source and can be imported without a file. File-backed source can be retained or read from the recorded path, depending on policy. The source-view lesson reports kind, origin, availability, and drift rather than treating all source text as the same evidence.

Continue to restore, external storage, or recorded source and diffs according to the next operation you need.

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

    # RECORDING IS OPT-IN, and asking a configured-but-inactive
    # crystallizer about profiles REFUSES rather than answering emptily.
    try:
        crystallizer.list_profile_names()
        raise AssertionError("expected a refusal before activation")
    except RuntimeError as inactive:
        print("profiles before activation ->", str(inactive)[:88])
        print("  a world that quietly recorded nothing would be worse")
        print("  than one that refused")

    crystallizer.activate(
        md.CrystallizerConfigurationBuilder().with_defaults().activate(),
    )

    # THE ONE YOU HAVE ALREADY BEEN USING HAS A NAME.
    assert crystallizer.active_profile_name == "default"
    assert "default" in crystallizer.list_profile_names()
    print()
    print("active profile:", crystallizer.active_profile_name)
    print("  every earlier lesson recorded here without naming it")

    # A WORLD WORTH RECORDING.
    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,
    )
    book.bind(spell=Ledger, existence="unique", permissions="create",
              binding_name="profile-ledger")
    book.conjure(name="profile-root")

    on_default = crystallizer.create_checkpoint()
    print()
    print("sealed a checkpoint on 'default':", on_default[:14], "...")

    # A SECOND WORLD OF RECORD, BY NAME. No object is handed back.
    crystallizer.create_profile("staging")
    assert crystallizer.active_profile_name == "staging", (
        "create_profile activates by default"
    )
    assert set(crystallizer.list_profile_names()) >= {"default", "staging"}
    print()
    print("create_profile('staging') -> active is now:",
          crystallizer.active_profile_name)
    print("  it returned None. The NAME is the handle; the profile object")
    print("  never escapes the depths, so there is nothing to alias or")
    print("  accidentally keep alive")

    # AND HERE IS THE LINE PEOPLE GET WRONG, INCLUDING THE AUTHOR OF THIS
    # LESSON ON THE FIRST TRY. A profile decides what a checkpoint
    # CONTAINS. It does not give you a private ledger.
    on_staging = crystallizer.create_checkpoint()
    everything = crystallizer.list_checkpoint_ids()
    assert on_staging in everything
    assert on_default in everything, (
        "list_checkpoint_ids returns ALL ids - the ledger is process-wide"
    )
    print("sealed a checkpoint on 'staging':", on_staging[:14], "...")
    print()
    print("list_checkpoint_ids() ->", len(everything), "ids, and BOTH are")
    print("  here. Its contract says `all checkpoint ids in exact ledger")
    print("  creation order` - one ledger for the process. Switching")
    print("  profiles does not hand you a private one.")
    print("  What the profile partitions is the CONTENT: create_checkpoint")
    print("  snapshots ONE profile's twin window and advances THAT")
    print("  profile's journal mark. Same shelf, different boxes.")

    # SWITCHING MOVES A POINTER AND NOTHING ELSE - including not moving
    # the ledger, which is why both ids are still listed below.
    crystallizer.set_active_profile("default")
    assert crystallizer.active_profile_name == "default"
    after_switch = crystallizer.list_checkpoint_ids()
    assert set(after_switch) == set(everything), (
        "the switch moves a pointer; it does not copy, migrate or hide"
    )
    print()
    print("set_active_profile('default') -> the ledger is unchanged:",
          set(after_switch) == set(everything))
    print("  `moves the pointer only - no data is copied or migrated`")
    print("  cuts both ways: nothing follows you, and nothing is taken")

    # YOU CAN ALSO NAME THE PROFILE EXPLICITLY rather than switching to
    # it - the argument is there so a caller never has to move the
    # pointer just to seal somewhere.
    targeted = crystallizer.create_checkpoint(profile_name="staging")
    assert crystallizer.active_profile_name == "default", (
        "checkpointing another profile must not move the active pointer"
    )
    print()
    print("create_checkpoint(profile_name='staging') ->", targeted[:14],
          "... and the active profile is still",
          crystallizer.active_profile_name)

    # DESCRIBE READS THE ACTIVE ONE WHEN YOU NAME NOTHING - and this is
    # where the CONTENT partition is visible, since the ledger read is
    # not. `describe_profile` reports per-level twin counts and the
    # emission sequence for ONE profile.
    active_view = crystallizer.describe_profile()
    default_view = crystallizer.describe_profile("default")
    staging_view = crystallizer.describe_profile("staging")
    assert isinstance(active_view, dict)
    assert active_view == default_view, (
        "None must resolve to the ACTIVE profile, which is 'default' here"
    )
    print()
    print("describe_profile()          -> the ACTIVE one (keys:",
          "%s)" % sorted(active_view)[:4])
    print("describe_profile('staging') -> that one    (keys:",
          "%s)" % sorted(staging_view)[:4])
    print("  None means ACTIVE, not `all profiles` - proven by the two")
    print("  reads above being equal while 'default' is active")
    print("  and THIS is where the partition shows: per-profile twin")
    print("  counts and emission sequence, not the shared ledger")

    # CLEAR EMPTIES AND KEEPS. DELETE REMOVES.
    crystallizer.clear_profile("staging")
    assert "staging" in crystallizer.list_profile_names(), (
        "clear is the NON-destructive reset - the profile survives"
    )
    print()
    print("clear_profile('staging')  -> still listed:",
          "staging" in crystallizer.list_profile_names())

    crystallizer.delete_profile("staging")
    assert "staging" not in crystallizer.list_profile_names()
    print("delete_profile('staging') -> still listed:",
          "staging" in crystallizer.list_profile_names())
    print("  two verbs because emptying a world and removing it are")
    print("  different intentions, and one of them is recoverable")

    # AND THE DEFAULT IS NEVER DELETABLE.
    try:
        crystallizer.delete_profile("default")
        raise AssertionError("expected a refusal: default is guaranteed")
    except ValueError as refusal:
        print()
        print("delete_profile('default') refused -", str(refusal)[:80])
        print("  the same shape of law as the default research lane that")
        print("  never archives: every system needs one thing that cannot")
        print("  be removed, or its own fallbacks have nowhere to fall")

    print()
    print("one process, several records, and you addressed them by name")

Runnable examples

Several worlds of record in one process — Expert 34
Two knobs and a terminator per rung — Expert 06
What a synthetic module actually is — Expert 33

All expert examples · Level contents · Full contents

Canonical page source