Restore and cold boot

Prerequisite: persistence and custody. Keep the record operations separate from rebuilding a runtime:

create_checkpoint records the checkpoint in the in-process ledger.
flush_checkpoint seals it to the local cache.
reload_cached_checkpoint brings cached record data back into the ledger.
load_checkpoint attempts to rebuild the selected world through its public operations.

Inspect the report

A restore report carries status, built counts, shortfalls, and identity translation. Runtime identities are rebuilt; the translation information connects recorded and new identities. The separate research-record JSON lesson preserves the identity of the record it hydrates. Those are different contracts.

Preflight can refuse an incomplete chain before construction. Preserve the full required profile chain when preparing a cold start; reloading a single checkpoint does not imply every predecessor has been reloaded.

Follow both demonstrations

Expert 24 walks the checkpoint verbs while holding the existing world. Expert 27 flushes, tears down the root, creates a new runtime, and reads the cache again. The latter deliberately reports an admission refusal if the bundle is incomplete. A script finishing successfully therefore does not, on its own, prove a complete world was restored. Read the reported status, built resources, and shortfalls.

CrystallizerBootstrap packages the restart sequence into a one-shot operation: activate, attach configured storage, reload, verify, load, report. Its empty-history case differs from a broken chain. Use the pod-boot lesson for its complete setup.

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, conduit, commands = build_world()
    vault = conduit.meld(spell=Vault, binding_name="outlive-vault")
    vault.contents.append("written before any codegen")
    print("world up; custody recording:", crystallizer.activated)

    # Two codegen edits, each materialized - running is not keeping, so
    # each gets an address of its own.
    for label, code in (("edit-1", FIRST_EDIT), ("edit-2", SECOND_EDIT)):
        commands.validate_codegen(code, frame_name=FRAME)
        commands.execute_codegen(code, frame_name=FRAME)
        commands.materialize_codegen(
            code,
            module_name="outlive_policy_%s" % label.replace("-", "_"),
            frame_name=FRAME,
        )
        vault.contents.append(label)
    print("two edits materialized; vault holds", len(vault.contents),
          "entries")

    # SEAL. Minting puts it in the LEDGER - memory, which the next step
    # destroys.
    checkpoint_id = crystallizer.create_checkpoint()
    assert checkpoint_id in crystallizer.list_checkpoint_ids()

    # FLUSH. THIS is what survives. Skip it and the rest of this script
    # has nothing to load, with no error to say why.
    flushed = crystallizer.flush_checkpoint(checkpoint_id)
    assert checkpoint_id in flushed
    assert checkpoint_id in crystallizer.list_cached_checkpoint_ids()
    print("checkpoint", checkpoint_id[:14], "minted and flushed to cache")

    # ---------------- THE TEARDOWN ----------------
    aether = md.Aether()
    del vault, conduit, commands, crystallizer

    aether.cleanup()
    collected = gc.collect()
    print()
    print("aether.cleanup() + gc.collect() ->", collected, "objects collected")

    fresh_aether = md.Aether()
    assert fresh_aether is not aether, (
        "cleanup() must clear the singleton - a fresh Aether() may never "
        "return the cleaned instance"
    )
    print("md.Aether() now returns a NEW root")
    del aether

    # ------- AFTER: a runtime that has never seen this world -------
    reborn = md.Crystallizer()
    reborn.activate(
        md.CrystallizerConfigurationBuilder().with_defaults().activate(),
    )
    research = md.MutationResearch()
    configuration = research.create_configuration()
    configuration.with_defaults().activate()
    research.activate(configuration)

    assert checkpoint_id in reborn.list_cached_checkpoint_ids(), (
        "the flushed checkpoint must survive the singleton teardown - if "
        "this fails, the cache is not bytes at rest"
    )
    print("the cache crossed the teardown; our checkpoint is still there")

    # Cache back into the ledger: bookkeeping, not a boot.
    summary = reborn.reload_cached_checkpoint(checkpoint_id)
    assert isinstance(summary, dict)
    print("reload_cached_checkpoint -> summary keys:", sorted(summary)[:5])

    # THE BOOT VERB. Refuses if the folded chain is incomplete.
    try:
        report = reborn.load_checkpoint(checkpoint_id)
    except RuntimeError as refusal:
        print()
        print("load_checkpoint REFUSED at admission:")
        print("  ", str(refusal)[:130])
        print("  preflight ran BEFORE any replay and the message ends")
        print("  `nothing was built` - the chain folded incomplete")
    else:
        assert isinstance(report, dict)
        print()
        print("load_checkpoint -> RestoreReport keys:", sorted(report))
        for key in ("identity_translation", "identity_translation_map",
                    "translation_map", "identity_map"):
            if key in report:
                print("   %s: %d remapped" % (key, len(report[key])))
                print("  rebuilt objects get NEW ids - the world that comes")
                print("  back is EQUIVALENT, not identical")
                break

    print()
    print("the CACHE outlived the runtime that minted it; ledger is memory")
    print("cleanup() IS the reset, and it is public")
    print("the last rung wants a COMPLETE bundle, checked before it builds")

Runnable examples

A world that outlives its own runtime — Expert 27
Loading a whole world back — Expert 24
Pod boot the order is the product — Expert 01

All expert examples · Level contents · Full contents

Canonical page source