On this page

Loading it back๏ƒ

๐ŸŸ  Advanced ยท Lesson 18

THE LOADING HALF - and the one place in melder where a successful return deliberately does NOT mean what you would assume.

TWO PLACES A CHECKPOINT CAN LIVE created an id exists in the running crystallizer cached it has been SEALED to the local cache create_checkpoint() gives you the first. flush_checkpoint() moves it to the second - and, if a persistence manager is attached, tries to ship it onward too.

flush_checkpoint(id=None) -> list[str] seal, then ship list_cached_checkpoint_ids() what is sealed locally reload_cached_checkpoint(id) -> dict read one back verify_checkpoint_chain(...) -> dict is the lineage intact delete_cached_checkpoint(id) -> str drop one

NOW THE TWO WARNINGS, BOTH FROM MELDER'S OWN CONTRACT.

  1. A SUCCESSFUL FLUSH DOES NOT PROVE THE REMOTE RECEIVED ANYTHING.

"THE REMOTE LEG IS LENIENT BY DEFAULT. Under the default posture an [error is tolerated and] a successful return does NOT prove the remote received anything - the local seal is [what you actually get]."

Everywhere else in this tier melder refuses rather than substituting (lessons 06/13/14/17/18). HERE IT IS DELIBERATELY LENIENT, and the reason is sound: a network you do not control should not be able to fail your local checkpoint. But it means flush() returning cleanly guarantees the LOCAL SEAL and nothing about the remote.

If you need remote confirmation, the return value of flush() is not it. Knowing which half of a two-part verb a return value covers is the difference between a backup and the belief in one.

  1. FLUSHING CAN EVICT SOMETHING ELSE.

"The FIFO cap means an old cached checkpoint can be EVICTED AS A SIDE EFFECT."

So flush is not purely additive. The cache is bounded, and sealing a new checkpoint may silently retire your oldest. If a specific checkpoint matters, do not assume it is still cached - list_cached_checkpoint_ids() is the check, and it is cheap.

THE TIER'S CLOSING IDEA Every lesson from 09 onward has been about the same discipline: know exactly what a call promises. Two bits instead of one. Names instead of contents. A refusal instead of a partial application. And here, at the end, a verb that is honest about covering two legs with different guarantees.

Before you run๏ƒ

Use the Advanced 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/03_advanced/18_loading_it_back.py

py -3.14t UX_and_AIX_experiences/03_advanced/18_loading_it_back.py

Download this collection ยท Source on GitHub

Public surface๏ƒ

flush_checkpoint, list_cached_checkpoint_ids, reload_cached_checkpoint, verify_checkpoint_chain, delete_cached_checkpoint

Code๏ƒ

  1"""
  2TIER: advanced (18)
  3GOAL: THE LOADING HALF - and the one place in melder where a successful
  4      return deliberately does NOT mean what you would assume.
  5
  6      TWO PLACES A CHECKPOINT CAN LIVE
  7        created   an id exists in the running crystallizer
  8        cached    it has been SEALED to the local cache
  9      create_checkpoint() gives you the first. flush_checkpoint() moves
 10      it to the second - and, if a persistence manager is attached, tries
 11      to ship it onward too.
 12
 13        flush_checkpoint(id=None) -> list[str]   seal, then ship
 14        list_cached_checkpoint_ids()             what is sealed locally
 15        reload_cached_checkpoint(id)  -> dict    read one back
 16        verify_checkpoint_chain(...)  -> dict    is the lineage intact
 17        delete_cached_checkpoint(id)  -> str     drop one
 18
 19      NOW THE TWO WARNINGS, BOTH FROM MELDER'S OWN CONTRACT.
 20
 21      1. A SUCCESSFUL FLUSH DOES NOT PROVE THE REMOTE RECEIVED ANYTHING.
 22
 23         "THE REMOTE LEG IS LENIENT BY DEFAULT. Under the default posture
 24          an [error is tolerated and] a successful return does NOT prove
 25          the remote received anything - the local seal is [what you
 26          actually get]."
 27
 28         Everywhere else in this tier melder refuses rather than
 29         substituting (lessons 06/13/14/17/18). HERE IT IS DELIBERATELY
 30         LENIENT, and the reason is sound: a network you do not control
 31         should not be able to fail your local checkpoint. But it means
 32         flush() returning cleanly guarantees the LOCAL SEAL and nothing
 33         about the remote.
 34
 35         If you need remote confirmation, the return value of flush() is
 36         not it. Knowing which half of a two-part verb a return value
 37         covers is the difference between a backup and the belief in one.
 38
 39      2. FLUSHING CAN EVICT SOMETHING ELSE.
 40
 41         "The FIFO cap means an old cached checkpoint can be EVICTED AS A
 42          SIDE EFFECT."
 43
 44         So flush is not purely additive. The cache is bounded, and
 45         sealing a new checkpoint may silently retire your oldest. If a
 46         specific checkpoint matters, do not assume it is still cached -
 47         list_cached_checkpoint_ids() is the check, and it is cheap.
 48
 49      THE TIER'S CLOSING IDEA
 50      Every lesson from 09 onward has been about the same discipline:
 51      know exactly what a call promises. Two bits instead of one. Names
 52      instead of contents. A refusal instead of a partial application.
 53      And here, at the end, a verb that is honest about covering two legs
 54      with different guarantees.
 55SURFACE EXERCISED: flush_checkpoint, list_cached_checkpoint_ids,
 56                   reload_cached_checkpoint, verify_checkpoint_chain,
 57                   delete_cached_checkpoint
 58VERIFY: rides the owner's 3.14t run; asserts are the contract.
 59"""
 60import melder as md
 61
 62
 63def main() -> None:
 64    crystallizer = md.Crystallizer()
 65    config = md.CrystallizerConfigurationBuilder().with_defaults().activate()
 66    crystallizer.activate(config)
 67    assert crystallizer.activated is True
 68    print("crystallizer up (builder.activate() - one terminator per rung)")
 69
 70    # CREATED, not yet sealed.
 71    checkpoint_id = crystallizer.create_checkpoint(
 72        description="advanced lesson 18 - to be flushed",
 73    )
 74    print()
 75    print("created:", checkpoint_id)
 76    print("in create list:", checkpoint_id in crystallizer.list_checkpoint_ids())
 77
 78    cached_before = crystallizer.list_cached_checkpoint_ids()
 79    assert isinstance(cached_before, list)
 80    print("cached before flush:", len(cached_before))
 81
 82    # SEAL, THEN SHIP. One verb, two legs, different guarantees.
 83    flushed = crystallizer.flush_checkpoint(checkpoint_id)
 84    assert isinstance(flushed, list)
 85    print()
 86    print("flush_checkpoint ->", flushed)
 87    print("  ^ this return covers the LOCAL SEAL.")
 88    print("    it does NOT prove a remote received anything.")
 89
 90    cached_after = crystallizer.list_cached_checkpoint_ids()
 91    assert isinstance(cached_after, list)
 92    print("cached after flush:", len(cached_after))
 93
 94    # THE CACHE IS BOUNDED. Do not assume; ask. This is cheap and it is
 95    # the only honest way to know a specific checkpoint survived.
 96    still_there = checkpoint_id in cached_after
 97    print("our checkpoint still cached:", still_there)
 98    if not still_there:
 99        print("  (FIFO cap evicted it - which the contract warns about)")
100
101    # READ ONE BACK. The id remains the whole handle.
102    if still_there:
103        reloaded = crystallizer.reload_cached_checkpoint(checkpoint_id)
104        assert isinstance(reloaded, dict)
105        print()
106        print("reload_cached_checkpoint ->", len(reloaded), "keys")
107        print("  keys:", sorted(reloaded)[:6])
108
109    # IS THE LINEAGE INTACT? Checkpoints form a chain, not a pile.
110    chain = crystallizer.verify_checkpoint_chain()
111    assert isinstance(chain, dict)
112    print()
113    print("verify_checkpoint_chain ->", len(chain), "keys")
114    print("  keys:", sorted(chain)[:6])
115
116    # DROPPING ONE IS EXPLICIT. Eviction is a side effect; deletion is a
117    # decision - and the two should never be confused.
118    if still_there:
119        deleted = crystallizer.delete_cached_checkpoint(checkpoint_id)
120        assert isinstance(deleted, str)
121        assert checkpoint_id not in crystallizer.list_cached_checkpoint_ids()
122        print()
123        print("delete_cached_checkpoint ->", deleted)
124        print("deletion is a DECISION; eviction is a SIDE EFFECT")
125
126    print()
127    print("know which leg of a two-part verb the return value covers")
128    print("a bounded cache means 'I flushed it' is not 'it is still there'")
129
130
131if __name__ == "__main__":
132    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 advanced examples ยท Level guide