On this page

Getting data into your database๏ƒ

๐Ÿ”ต Expert ยท Lesson 09

PUT YOUR WORLD IN YOUR OWN DATABASE - and notice what melder does NOT do to get it there. This wires a real mesh, seals a real checkpoint, and watches the bytes arrive.

MELDER NEVER IMPORTS YOUR DATABASE. The whole external lane is four callables you write:

store(kind, profile_name, unit_id, payload) -> None fetch(kind, unit_id) -> payload | None list_units(kind, profile_name) -> iterable of ids delete(kind, unit_id)

The contract says it plainly: "one callable, one table with a kind column, any DB stack - melder never imports it." There is no driver, no dialect, no connection string anywhere in the library. kind is "checkpoint" / "formation" / "emission", so ONE table with a kind column carries the entire mesh if you want it to.

CALLABLES LIVE OUTSIDE THE RECORD, AND THAT IS A LAW WITH A REASON. Handlers go in a SEPARATE configuration object, and the record "expose[s] handler PRESENCE flags, never callable objects". Why: executable code cannot be serialized into a world record, so a recorded world stays CODE-FREE AND PORTABLE. A record that embedded your storage code would only be restorable somewhere that code already ran.

AN EMPTY CONFIGURATION WILL NOT FREEZE, ON PURPOSE. Upload-on-flush defaults True, so a configuration with no write handler is incoherent - it promises to upload with nothing to upload through. A READ-ONLY deployment must therefore say so out loud by disabling upload-on-flush. The default refuses to let you be vague.

SEAL-THEN-SHIP IS ONE VERB WITH TWO GUARANTEES, AND ONLY ONE OF THEM IS YOURS. flush_checkpoint does the local seal AND the remote push, and the remote leg is LENIENT BY DEFAULT: a successful return proves THE LOCAL SEAL and nothing about your database. So this lesson ASSERTS the local seal and only REPORTS what the mesh saw - because asserting the remote would be teaching you to trust the one half the return value does not cover. That is the same rule from the other side: LOCAL CUSTODY IS NEVER HOSTAGE TO A NETWORK YOU DO NOT OWN.

AND TWO DESCRIBE DOORS, WHICH IS NOT REDUNDANCY describe_external_persistence_manager() what is WIRED describe_external_interface() what the CONTRACT is An operator debugging a mesh needs the first; someone implementing handlers needs the second. Neither performs a network call.

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/09_getting_data_into_your_database.py

py -3.14t UX_and_AIX_experiences/04_expert/09_getting_data_into_your_database.py

Download this collection ยท Source on GitHub

Public surface๏ƒ

ExternalPersistenceManagerConfiguration with real store/fetch/list_units handlers, configure_external_persistence_manager, create_checkpoint / flush_checkpoint through the mesh, both describe doors, and the absence of any sync verb

Code๏ƒ

  1"""
  2TIER: expert (09)
  3GOAL: PUT YOUR WORLD IN YOUR OWN DATABASE - and notice what melder does
  4      NOT do to get it there. This wires a real mesh, seals a real
  5      checkpoint, and watches the bytes arrive.
  6
  7      MELDER NEVER IMPORTS YOUR DATABASE. The whole external lane is four
  8      callables you write:
  9
 10        store(kind, profile_name, unit_id, payload) -> None
 11        fetch(kind, unit_id)                        -> payload | None
 12        list_units(kind, profile_name)              -> iterable of ids
 13        delete(kind, unit_id)
 14
 15      The contract says it plainly: "one callable, one table with a kind
 16      column, any DB stack - melder never imports it." There is no driver,
 17      no dialect, no connection string anywhere in the library. `kind` is
 18      "checkpoint" / "formation" / "emission", so ONE table with a kind
 19      column carries the entire mesh if you want it to.
 20
 21      CALLABLES LIVE OUTSIDE THE RECORD, AND THAT IS A LAW WITH A REASON.
 22      Handlers go in a SEPARATE configuration object, and the record
 23      "expose[s] handler PRESENCE flags, never callable objects". Why:
 24      executable code cannot be serialized into a world record, so a
 25      recorded world stays CODE-FREE AND PORTABLE. A record that embedded
 26      your storage code would only be restorable somewhere that code
 27      already ran.
 28
 29      AN EMPTY CONFIGURATION WILL NOT FREEZE, ON PURPOSE. Upload-on-flush
 30      defaults True, so a configuration with no write handler is
 31      incoherent - it promises to upload with nothing to upload through.
 32      A READ-ONLY deployment must therefore say so out loud by disabling
 33      upload-on-flush. The default refuses to let you be vague.
 34
 35      SEAL-THEN-SHIP IS ONE VERB WITH TWO GUARANTEES, AND ONLY ONE OF THEM
 36      IS YOURS. `flush_checkpoint` does the local seal AND the remote push,
 37      and the remote leg is LENIENT BY DEFAULT: a successful return proves
 38      THE LOCAL SEAL and nothing about your database. So this lesson
 39      ASSERTS the local seal and only REPORTS what the mesh saw - because
 40      asserting the remote would be teaching you to trust the one half the
 41      return value does not cover.
 42      That is the same rule from the other side: LOCAL CUSTODY IS NEVER
 43      HOSTAGE TO A NETWORK YOU DO NOT OWN.
 44
 45      AND TWO DESCRIBE DOORS, WHICH IS NOT REDUNDANCY
 46        describe_external_persistence_manager()  what is WIRED
 47        describe_external_interface()            what the CONTRACT is
 48      An operator debugging a mesh needs the first; someone implementing
 49      handlers needs the second. Neither performs a network call.
 50SURFACE EXERCISED: ExternalPersistenceManagerConfiguration with real
 51                   store/fetch/list_units handlers,
 52                   configure_external_persistence_manager,
 53                   create_checkpoint / flush_checkpoint through the mesh,
 54                   both describe doors, and the absence of any sync verb
 55VERIFY: rewritten 2026-08-05 to WIRE a mesh instead of listing verbs;
 56        not yet re-run.
 57"""
 58import melder as md
 59
 60
 61FRAME = "mesh-world"
 62
 63# "Your database". A dict, in memory - because the point is that melder
 64# does not care what this is. Swap it for sqlite, postgres or S3 and not
 65# one line of melder changes.
 66DATABASE: dict[tuple[str, str], dict] = {}
 67WRITES: list[tuple[str, str, str]] = []
 68
 69
 70def store(kind: str, profile_name: str, unit_id: str, payload: dict) -> None:
 71    """One table with a kind column. That is the entire integration."""
 72    DATABASE[(kind, unit_id)] = payload
 73    WRITES.append((kind, profile_name, unit_id))
 74
 75
 76def fetch(kind: str, unit_id: str):
 77    """None means `unknown remotely` - a real answer, not an error."""
 78    return DATABASE.get((kind, unit_id))
 79
 80
 81def list_units(kind: str, profile_name: str):
 82    return [unit for (k, unit) in DATABASE if k == kind]
 83
 84
 85class Ledger:
 86    def __init__(self) -> None:
 87        self.entries: list[str] = []
 88
 89
 90def main() -> None:
 91    crystallizer = md.Crystallizer()
 92    crystallizer.activate(
 93        md.CrystallizerConfigurationBuilder().with_defaults().activate(),
 94    )
 95
 96    # THE HANDLERS GO IN THEIR OWN OBJECT, never into the record.
 97    mesh = md.ExternalPersistenceManagerConfiguration()
 98    mesh.with_store_handler(store)
 99    mesh.with_fetch_handler(fetch)
100    mesh.with_list_units_handler(list_units)
101    crystallizer.configure_external_persistence_manager(mesh)
102    print("mesh attached - melder now has four callables and no idea what")
103    print("is behind them")
104
105    # WHAT IS WIRED vs WHAT THE CONTRACT IS. Two questions, two doors,
106    # neither one a network call.
107    wiring = crystallizer.describe_external_persistence_manager()
108    contract = crystallizer.describe_external_interface()
109    assert isinstance(wiring, dict) and isinstance(contract, dict)
110    assert wiring.get("attached") is True, wiring
111    print()
112    print("describe_external_persistence_manager ->", len(wiring),
113          "keys (what is WIRED)")
114    print("describe_external_interface           ->", len(contract),
115          "keys (what the CONTRACT is)")
116
117    # PRESENCE FLAGS, NEVER CALLABLES. Search the whole record payload for
118    # anything callable - a recorded world has to stay code-free.
119    leaked = [key for key, value in wiring.items() if callable(value)]
120    assert not leaked, "the record leaked a callable: %s" % leaked
121    print("  the wiring record holds no callable objects - only presence")
122    print("  flags, because executable code cannot be serialized into a")
123    print("  world record and a record that embedded yours would only")
124    print("  restore where that code already ran")
125
126    # A WORLD WORTH SEALING.
127    spellbook_configuration = (
128        md.SpellbookConfiguration(FRAME).with_defaults().finalize()
129    )
130    book = md.Spellbook(aetheric_frame=FRAME,
131                        configuration=spellbook_configuration)
132    book.configure_aether_frame(
133        system_state="dynamic",
134        disposal=None,
135        disposal_method_names=None,
136        rift_enabled=True,
137        ai_native=True,
138    )
139    book.bind(spell=Ledger, existence="unique", permissions="create",
140              binding_name="mesh-ledger")
141    book.conjure(name="mesh-root")
142
143    # SEAL, THEN SHIP - one verb, two guarantees, one of them yours.
144    checkpoint_id = crystallizer.create_checkpoint()
145    assert checkpoint_id in crystallizer.list_checkpoint_ids()
146    flushed = crystallizer.flush_checkpoint(checkpoint_id)
147
148    # THE LOCAL SEAL IS THE PART THE RETURN VALUE COVERS. Assert it.
149    assert checkpoint_id in flushed, flushed
150    assert checkpoint_id in crystallizer.list_cached_checkpoint_ids()
151    print()
152    print("flush_checkpoint ->", checkpoint_id[:14], "...")
153    print("  LOCAL SEAL asserted: it is in the cache, on this machine")
154
155    # THE REMOTE LEG IS LENIENT, so this is REPORTED and not asserted.
156    # Teaching you to assert it would be teaching you to trust the half
157    # the return value does not cover.
158    print("  your database received", len(WRITES), "unit(s):")
159    for kind, profile_name, unit_id in WRITES[:4]:
160        print("     kind=%-11s profile=%-10s unit=%s"
161              % (kind, profile_name, unit_id[:14]))
162    print("  reported, NOT asserted - the remote leg is lenient by")
163    print("  default, so a clean return proves the local seal and nothing")
164    print("  about your storage. Local custody is never hostage to a")
165    print("  network you do not own. If you need remote confirmation, the")
166    print("  return value of flush is not it - strict uploads are")
167
168    # AND THE ABSENCE THAT MATTERS. No sync(), no mirror_all().
169    for absent in ("sync", "mirror", "mirror_all", "sync_external",
170                   "push_everything"):
171        assert not hasattr(crystallizer, absent), (
172            "%s appeared - an opaque sync verb would make the mesh "
173            "impossible to reason about when it disagrees with itself"
174            % absent
175        )
176    print()
177    print("there is NO sync() - every verb names a KIND and a DIRECTION,")
178    print("so when the two sides disagree you can say which way the last")
179    print("byte was travelling. `sync` cannot answer that question.")
180
181    print()
182    print("four callables, one kind column, zero database imports")
183
184
185if __name__ == "__main__":
186    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๏ƒ