On this page

Persistence mesh your code their lanes๏ƒ

๐Ÿ”ต Expert ยท Lesson 02

THE ASYMMETRY AT THE EDGE OF YOUR WORLD, demonstrated rather than described. Melder never speaks to your database - it calls YOUR callables. So the interesting question is what happens when one of them is missing or broken, and the answer is deliberately different for writes and reads.

WRITES DEGRADE AND COUNT. A missing write lane is a silent no-op. A write lane that RAISES is swallowed and TALLIED. Your local seal never fails because a network you do not own did. READS REFUSE. A missing read lane raises. "A missing lane means UNAVAILABLE, NOT EMPTY" - because an empty answer would be indistinguishable from "your remote has nothing", and that is the one reply that must never be guessed.

LENIENCY WITHOUT ACCOUNTING IS JUST QUIET DATA LOSS. That is why the manager carries upload_failure_count and store_failure_count and puts them in describe_external_persistence_manager(). Your handler is allowed to fail; you are not allowed to be unaware of it.

AND CALLABLES NEVER ENTER THE RECORD. Handlers live in a separate configuration and the description "expose[s] handler PRESENCE flags, never callable objects", because executable code cannot be serialized into a world record. A recorded world stays code-free and portable, which is what lets it be restored somewhere your storage code has never run.

LOCAL CUSTODY IS NEVER HOSTAGE TO A NETWORK YOU DO NOT OWN. Expert 09 shows the same rule from the wiring side; this lesson is the failure side of it.

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/02_persistence_mesh_your_code_their_lanes.py

py -3.14t UX_and_AIX_experiences/04_expert/02_persistence_mesh_your_code_their_lanes.py

Download this collection ยท Source on GitHub

Public surface๏ƒ

ExternalPersistenceManagerConfiguration store/fetch/ list handlers, configure_external_persistence_manager, flush_checkpoint through a working and then a FAILING handler, reload_profile_from_external with no read lane, and the failure counters in the describe payload

Code๏ƒ

  1"""
  2TIER: expert (02)
  3GOAL: THE ASYMMETRY AT THE EDGE OF YOUR WORLD, demonstrated rather than
  4      described. Melder never speaks to your database - it calls YOUR
  5      callables. So the interesting question is what happens when one of
  6      them is missing or broken, and the answer is deliberately different
  7      for writes and reads.
  8
  9        WRITES DEGRADE AND COUNT.  A missing write lane is a silent
 10          no-op. A write lane that RAISES is swallowed and TALLIED. Your
 11          local seal never fails because a network you do not own did.
 12        READS REFUSE.  A missing read lane raises. "A missing lane means
 13          UNAVAILABLE, NOT EMPTY" - because an empty answer would be
 14          indistinguishable from "your remote has nothing", and that is
 15          the one reply that must never be guessed.
 16
 17      LENIENCY WITHOUT ACCOUNTING IS JUST QUIET DATA LOSS. That is why
 18      the manager carries `upload_failure_count` and `store_failure_count`
 19      and puts them in `describe_external_persistence_manager()`. Your
 20      handler is allowed to fail; you are not allowed to be unaware of it.
 21
 22      AND CALLABLES NEVER ENTER THE RECORD. Handlers live in a separate
 23      configuration and the description "expose[s] handler PRESENCE flags,
 24      never callable objects", because executable code cannot be
 25      serialized into a world record. A recorded world stays code-free and
 26      portable, which is what lets it be restored somewhere your storage
 27      code has never run.
 28
 29      LOCAL CUSTODY IS NEVER HOSTAGE TO A NETWORK YOU DO NOT OWN. Expert
 30      09 shows the same rule from the wiring side; this lesson is the
 31      failure side of it.
 32SURFACE EXERCISED: ExternalPersistenceManagerConfiguration store/fetch/
 33                   list handlers, configure_external_persistence_manager,
 34                   flush_checkpoint through a working and then a FAILING
 35                   handler, reload_profile_from_external with no read
 36                   lane, and the failure counters in the describe payload
 37VERIFY: rewritten 2026-08-05 to DEMONSTRATE the asymmetry it previously
 38        only asserted in prose; not yet run.
 39"""
 40import melder as md
 41
 42
 43FRAME = "mesh-edge-world"
 44
 45WRITTEN: list = []
 46
 47
 48def store_ok(kind: str, profile_name: str, unit_id: str,
 49             payload: dict) -> None:
 50    WRITTEN.append((kind, unit_id))
 51
 52
 53def store_broken(kind: str, profile_name: str, unit_id: str,
 54                 payload: dict) -> None:
 55    raise IOError("the database is on fire")
 56
 57
 58class Ledger:
 59    def __init__(self) -> None:
 60        self.entries: list = []
 61
 62
 63def _mesh(store_handler):
 64    configuration = md.ExternalPersistenceManagerConfiguration()
 65    configuration.with_store_handler(store_handler)
 66    return configuration
 67
 68
 69def main() -> None:
 70    crystallizer = md.Crystallizer()
 71    crystallizer.activate(
 72        md.CrystallizerConfigurationBuilder().with_defaults().activate(),
 73    )
 74
 75    spellbook_configuration = (
 76        md.SpellbookConfiguration(FRAME).with_defaults().finalize()
 77    )
 78    book = md.Spellbook(aetheric_frame=FRAME,
 79                        configuration=spellbook_configuration)
 80    book.configure_aether_frame(
 81        system_state="dynamic",
 82        disposal=None,
 83        disposal_method_names=None,
 84        rift_enabled=True,
 85        ai_native=True,
 86    )
 87    book.bind(spell=Ledger, existence="unique", permissions="create",
 88              binding_name="mesh-edge-ledger")
 89    book.conjure(name="mesh-edge-root")
 90
 91    # A WRITE LANE ONLY. No fetch handler, no list handler - deliberately
 92    # a half-wired mesh, which is the whole subject of this lesson.
 93    crystallizer.configure_external_persistence_manager(_mesh(store_ok))
 94    wiring = crystallizer.describe_external_persistence_manager()
 95    assert wiring["attached"] is True
 96    print("mesh attached with a WRITE lane and no read lane")
 97    print("  and the record holds no callables - only presence flags:")
 98    assert not [k for k, v in wiring.items() if callable(v)]
 99    print("   ", sorted(k for k in wiring if "handler" in k or "enabled" in k))
100
101    # THE WRITE LANE WORKS.
102    checkpoint_id = crystallizer.create_checkpoint()
103    flushed = crystallizer.flush_checkpoint(checkpoint_id)
104    assert checkpoint_id in flushed
105    print()
106    print("flush_checkpoint ->", checkpoint_id[:14], "...")
107    print("  your store handler received", len(WRITTEN), "unit(s)")
108
109    # THE READ LANE IS MISSING, AND IT REFUSES. This is the half that
110    # does NOT degrade quietly.
111    try:
112        crystallizer.reload_profile_from_external("default")
113        raise AssertionError("a missing read lane must refuse, not answer")
114    except RuntimeError as unavailable:
115        print()
116        print("reload_profile_from_external with no fetch/list lane:")
117        print("  ", str(unavailable)[:96])
118        print("  UNAVAILABLE is not EMPTY. An empty answer here would be")
119        print("  indistinguishable from `your remote has nothing`, and")
120        print("  that is the one reply that must never be guessed")
121
122    # NOW A WRITE LANE THAT FAILS. Re-configuring replaces the manager,
123    # so the counters below start clean.
124    crystallizer.configure_external_persistence_manager(_mesh(store_broken))
125    before = crystallizer.describe_external_persistence_manager()
126    assert before["store_failure_count"] == 0, before
127    print()
128    print("re-wired with a handler that raises. store_failure_count:",
129          before["store_failure_count"])
130
131    # THE LOCAL SEAL STILL SUCCEEDS. That is the guarantee.
132    second_id = crystallizer.create_checkpoint()
133    flushed_again = crystallizer.flush_checkpoint(second_id)
134    assert second_id in flushed_again, (
135        "the LOCAL seal must not fail because a remote handler raised"
136    )
137    assert second_id in crystallizer.list_cached_checkpoint_ids()
138    print("flush_checkpoint ->", second_id[:14], "... returned CLEANLY")
139    print("  and it is in the local cache. Your handler raised IOError and")
140    print("  the local custody did not care - that is the guarantee")
141
142    # AND THE FAILURE WAS COUNTED. Leniency with a receipt.
143    after = crystallizer.describe_external_persistence_manager()
144    assert after["store_failure_count"] > 0, after
145    print()
146    print("store_failure_count:", before["store_failure_count"], "->",
147          after["store_failure_count"])
148    print("  leniency without accounting is just quiet data loss. The")
149    print("  write was allowed to fail; you were not allowed to be")
150    print("  unaware of it. If you need the failure to be LOUD instead,")
151    print("  that is what strict uploads are for.")
152
153    print()
154    print("writes degrade and COUNT; reads REFUSE")
155    print("melder called your callables and never touched your database")
156
157
158if __name__ == "__main__":
159    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

API contracts๏ƒ