Create, seal, and read a checkpoint

Prerequisite: configuration ownership. These entry lessons introduce recording without requiring the complete Expert persistence guide.

Configure and activate Crystallizer before creating checkpoints. The creation lesson gets a checkpoint ID, lists it, describes it, and confirms that another checkpoint receives a different ID.

Know which operation completed

Operation	What you can conclude
`create_checkpoint(...)`	A checkpoint exists in the running record
`flush_checkpoint(...)`	The checkpoint is sealed locally; inspect remote delivery separately
`list_cached_checkpoint_ids()`	Which checkpoint IDs remain in the bounded local cache
`reload_cached_checkpoint(...)`	A cached record is read back into the record system
`verify_checkpoint_chain(...)`	A report about the recorded lineage

A bounded cache can evict older entries. A successful local seal does not establish remote durability. Reloading a record is also different from rebuilding its runtime objects: use restore and cold boot for that next step.

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()
    print("crystallizer activated at start:", crystallizer.activated)
    assert crystallizer.activated is False

    # THE CONFIG. Bare constructor - unlike the frame posture in lesson 06,
    # this one you build empty and fill in.
    config = md.CrystallizerConfiguration()
    config.with_defaults()

    # AETHER'S LADDER, NOT NEXUS'S. Rung 1: seal it.
    config.finalize()
    assert config.activated is False
    print("config finalized - activated:", config.activated)

    # Rung 2: the caller activates. Nexus would have done this for us;
    # Aether and Crystallizer both make it explicit.
    config.activate()
    assert config.activated is True
    print("config activated - activated:", config.activated)

    # Rung 3: the subsystem comes up.
    crystallizer.activate(config)
    assert crystallizer.activated is True
    # NOTE: `is_activated` is a PROPERTY, not a method - calling it gives
    # "TypeError: 'bool' object is not callable". Two read names for one
    # bit, both properties.
    assert crystallizer.is_activated is True
    print("crystallizer activated:", crystallizer.activated)

    # THE THREE-EXIT BUILDER. Same destination, you pick the rung. This is
    # a SECOND configuration object - the one above is already installed.
    builder = md.CrystallizerConfigurationBuilder()
    for terminator in ("build", "finalize", "activate"):
        assert hasattr(builder, terminator), terminator
    print()
    print("CrystallizerConfigurationBuilder terminators: build/finalize/activate")
    print("AetherConfigurationBuilder offers only build() - rung 2 is yours")

    ready = md.CrystallizerConfigurationBuilder().with_defaults().activate()
    assert isinstance(ready, md.CrystallizerConfiguration)
    assert ready.activated is True
    print("builder.activate() -> a config already in force")

    # ------------------------------------------------------------------
    # THE CHECKPOINT
    # ------------------------------------------------------------------
    before = crystallizer.list_checkpoint_ids()
    assert isinstance(before, list)
    print()
    print("checkpoints before:", len(before))

    checkpoint_id = crystallizer.create_checkpoint(
        description="advanced lesson 17 - first checkpoint",
    )
    assert isinstance(checkpoint_id, str) and checkpoint_id
    print("created checkpoint:", checkpoint_id)

    after = crystallizer.list_checkpoint_ids()
    assert checkpoint_id in after
    assert len(after) == len(before) + 1
    print("checkpoints after: ", len(after))

    # THE ID IS THE HANDLE. Everything else keys off it.
    described = crystallizer.describe_checkpoint(checkpoint_id)
    assert isinstance(described, dict)
    print("describe_checkpoint ->", len(described), "keys")
    print("  keys:", sorted(described)[:6])

    # A second checkpoint gets its own id - they are not overwritten.
    second_id = crystallizer.create_checkpoint(description="second")
    assert second_id != checkpoint_id
    assert len(crystallizer.list_checkpoint_ids()) == len(before) + 2
    print("second checkpoint is a distinct id, not an overwrite")

    print()
    print("caller-driven activation is the house rule - nexus is the exception")
    print("create_checkpoint hands back an ID; the ID is the whole handle")

Runnable examples

Taking a checkpoint — Advanced 17
Loading it back — Advanced 18

All advanced examples · Level contents · Full contents

Canonical page source