On this page

The frame conduit cloud๏ƒ

๐ŸŸก Intermediate ยท Lesson 37

THE CONDUIT CLOUD - the frame's shared registry of conduits, and the first object in this tier that is owned by the WORLD rather than by you.

You reach it from any conduit:

cloud = conduit.get_conduit_cloud()

And here is the sentence that matters, from melder's own contract:

"Reaches THROUGH the aetheric frame to the frame-owned cloud, so the returned object is SHARED BY EVERY CONDUIT ON THE FRAME."

So get_conduit_cloud() is not a factory and not a per-conduit view. Two conduits on the same frame hand you THE SAME OBJECT. Ask any of them, get the same registry - which is what makes it a trustworthy place to answer "what conduits exist here?"

Frames are worlds (advanced 03), and the cloud is a world-level object. Different frame, different cloud - the wall holds here too.

WHAT IT ANSWERS - all cheap reads over the frame's conduits: frame_name which world am I the registry for count_conduits() how many list_conduit_ids() by id list_conduit_names() by name has_conduit_id/name() membership without fetching find_conduit_id_by_name(name) -> id or None get_conduit_by_id/name() the actual object

AND THE CLUSTER HALF, which is dynamic-mode territory: list_cloud_names() / has_cluster_name() / get_cluster() create_cluster() / delete_cluster() add_conduit_to_cluster() / remove_conduit_from_cluster() get_clusters_for_conduit() / refresh_cluster_shares_for_conduit() Clusters are how conduits share lineage as a group. This lesson names that surface and stays on the registry half; the cluster lifecycle is its own subject.

WHY THE READS MATTER MORE THAN THEY LOOK find_conduit_id_by_name returning Optional rather than raising is the honest shape for a lookup that may legitimately miss - and it pairs with has_conduit_name() so you can ask the membership question without paying for the object. Cheap questions before expensive ones, the same discipline as the describe ladder at advanced 16.

YOU REACH THIS OBJECT; YOU NEVER NAME IT. ConduitCloud is NOT on the package root (owner ruling 2026-08-04) and that is deliberate, not an oversight. Its constructor needs an AethericFrame and a DevopsInformationRegistry - neither exported, neither defaulted - so md.ConduitCloud(...) could never have been called. Its own docstring says it: "users do not construct one." An exported name you cannot construct advertises a door that is painted on. It is the same ruling Scan got: Spellbook.scan(module) is the API because it applies the posture gate and the bind transaction, so exporting the class only advertised a way around them. Here there is not even a way around - just a name. THE REACH IS UNCHANGED. conduit.get_conduit_cloud() still hands you the live object and every verb below still works. What you lose is isinstance(cloud, md.ConduitCloud), and the honest replacement is to test what the object DOES - which is what this lesson now does, and arguably what it should have done from the start.

Before you run๏ƒ

Use the Intermediate 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/02_intermediate/37_the_frame_conduit_cloud.py

py -3.14t UX_and_AIX_experiences/02_intermediate/37_the_frame_conduit_cloud.py

Download this collection ยท Source on GitHub

Public surface๏ƒ

conduit.get_conduit_cloud(), the frame-shared registry law, the read surface. NOTE: no md.ConduitCloud - the type is reached, never named.

Code๏ƒ

  1"""
  2TIER: intermediate (37)
  3GOAL: THE CONDUIT CLOUD - the frame's shared registry of conduits, and
  4      the first object in this tier that is owned by the WORLD rather
  5      than by you.
  6
  7      You reach it from any conduit:
  8
  9        cloud = conduit.get_conduit_cloud()
 10
 11      And here is the sentence that matters, from melder's own contract:
 12
 13        "Reaches THROUGH the aetheric frame to the frame-owned cloud, so
 14         the returned object is SHARED BY EVERY CONDUIT ON THE FRAME."
 15
 16      So `get_conduit_cloud()` is not a factory and not a per-conduit
 17      view. Two conduits on the same frame hand you THE SAME OBJECT. Ask
 18      any of them, get the same registry - which is what makes it a
 19      trustworthy place to answer "what conduits exist here?"
 20
 21      Frames are worlds (advanced 03), and the cloud is a world-level
 22      object. Different frame, different cloud - the wall holds here too.
 23
 24      WHAT IT ANSWERS - all cheap reads over the frame's conduits:
 25        frame_name              which world am I the registry for
 26        count_conduits()        how many
 27        list_conduit_ids()      by id
 28        list_conduit_names()    by name
 29        has_conduit_id/name()   membership without fetching
 30        find_conduit_id_by_name(name) -> id or None
 31        get_conduit_by_id/name() the actual object
 32
 33      AND THE CLUSTER HALF, which is dynamic-mode territory:
 34        list_cloud_names() / has_cluster_name() / get_cluster()
 35        create_cluster() / delete_cluster()
 36        add_conduit_to_cluster() / remove_conduit_from_cluster()
 37        get_clusters_for_conduit() / refresh_cluster_shares_for_conduit()
 38      Clusters are how conduits share lineage as a group. This lesson
 39      names that surface and stays on the registry half; the cluster
 40      lifecycle is its own subject.
 41
 42      WHY THE READS MATTER MORE THAN THEY LOOK
 43      `find_conduit_id_by_name` returning Optional rather than raising is
 44      the honest shape for a lookup that may legitimately miss - and it
 45      pairs with has_conduit_name() so you can ask the membership question
 46      without paying for the object. Cheap questions before expensive
 47      ones, the same discipline as the describe ladder at advanced 16.
 48
 49      YOU REACH THIS OBJECT; YOU NEVER NAME IT. `ConduitCloud` is NOT on
 50      the package root (owner ruling 2026-08-04) and that is deliberate,
 51      not an oversight. Its constructor needs an `AethericFrame` and a
 52      `DevopsInformationRegistry` - neither exported, neither defaulted -
 53      so `md.ConduitCloud(...)` could never have been called. Its own
 54      docstring says it: "users do not construct one." An exported name
 55      you cannot construct advertises a door that is painted on.
 56      It is the same ruling `Scan` got: `Spellbook.scan(module)` is the
 57      API because it applies the posture gate and the bind transaction,
 58      so exporting the class only advertised a way around them. Here
 59      there is not even a way around - just a name.
 60      THE REACH IS UNCHANGED. `conduit.get_conduit_cloud()` still hands
 61      you the live object and every verb below still works. What you lose
 62      is `isinstance(cloud, md.ConduitCloud)`, and the honest replacement
 63      is to test what the object DOES - which is what this lesson now
 64      does, and arguably what it should have done from the start.
 65SURFACE EXERCISED: conduit.get_conduit_cloud(), the frame-shared registry
 66                   law, the read surface. NOTE: no `md.ConduitCloud` -
 67                   the type is reached, never named.
 68VERIFY: rides the owner's 3.14t run; asserts are the contract.
 69"""
 70import melder as md
 71
 72
 73class Ledger:
 74    """Something to bind so the frame has real work in it."""
 75
 76
 77class OtherLedger(Ledger):
 78    """The other frame's own Ledger - a new class, so its own spell_id."""
 79
 80
 81def main() -> None:
 82    book = md.Spellbook(aetheric_frame="cloud-demo")
 83    book.bind(spell=Ledger, existence="unique", binding_name="demo")
 84
 85    root = book.conjure(name="cloud-root")
 86    cloud = root.get_conduit_cloud()
 87
 88    # NOT `isinstance(cloud, md.ConduitCloud)` - that name is deliberately
 89    # off the root. Test what the object DOES instead: it knows which
 90    # world it is the registry for, and it answers the registry surface.
 91    assert cloud is not None
 92    assert hasattr(cloud, "frame_name")
 93    print("cloud for frame:", cloud.frame_name)
 94    assert cloud.frame_name == "cloud-demo"
 95
 96    # THE SHARING LAW. A second conduit on the SAME frame reaches the
 97    # SAME registry object - not a copy, not a view.
 98    peer = md.Spellbook(aetheric_frame="cloud-demo").conjure(name="cloud-peer")
 99    peer_cloud = peer.get_conduit_cloud()
100    assert peer_cloud is cloud, "the cloud is frame-owned, not per-conduit"
101    print("second conduit reached the same object:", peer_cloud is cloud)
102
103    # Asking the same conduit twice is stable too - it is a reach, not a
104    # build, so there is nothing to be inconsistent about.
105    assert root.get_conduit_cloud() is cloud
106
107    # A DIFFERENT FRAME IS A DIFFERENT WORLD, and so a different cloud.
108    # It binds its OWN class: a spell_id is the SHA256 of the class's
109    # code and carries neither the frame nor the binding_name, so Ledger
110    # bound here as well would be refused process-wide. The CLOUD is
111    # still per-frame; identity is not.
112    other_book = md.Spellbook(aetheric_frame="cloud-other")
113    other_book.bind(spell=OtherLedger, existence="unique", binding_name="other")
114    other_root = other_book.conjure(name="other-root")
115    other_cloud = other_root.get_conduit_cloud()
116    assert other_cloud is not cloud
117    assert other_cloud.frame_name == "cloud-other"
118    print("other frame, other cloud:", other_cloud.frame_name)
119
120    # THE READ SURFACE. Counts and lists agree with each other, which is
121    # the minimum you should demand of any registry.
122    names = cloud.list_conduit_names()
123    ids = cloud.list_conduit_ids()
124    print()
125    print("conduits on this frame:", cloud.count_conduits())
126    print("  names:", names)
127    assert isinstance(names, tuple) and isinstance(ids, tuple)
128    assert cloud.count_conduits() == len(ids)
129
130    # Our two conduits are in there by name.
131    for expected in ("cloud-root", "cloud-peer"):
132        assert cloud.has_conduit_name(expected), expected
133    print("both conduits registered by name")
134
135    # MEMBERSHIP WITHOUT FETCHING. has_* answers the cheap question;
136    # find_* returns Optional rather than raising, because a lookup that
137    # can legitimately miss should not need a try block.
138    found_id = cloud.find_conduit_id_by_name("cloud-root")
139    assert found_id is not None
140    assert cloud.has_conduit_id(found_id)
141    print("find_conduit_id_by_name -> id, and has_conduit_id agrees")
142
143    missing = cloud.find_conduit_id_by_name("no-such-conduit")
144    assert missing is None, "a miss is None, not an exception"
145    assert cloud.has_conduit_name("no-such-conduit") is False
146    print("a miss returns None - no exception for an honest absence")
147
148    # And the object itself, once you have decided you want it.
149    fetched = cloud.get_conduit_by_id(found_id)
150    assert fetched is root
151    assert cloud.get_conduit_by_name("cloud-root") is root
152    print("get_conduit_by_id / by_name returned the live conduit")
153
154    # THE CLUSTER SURFACE, named but not exercised here.
155    print()
156    print("cluster surface on the cloud:")
157    for verb in ("list_cloud_names", "has_cluster_name", "get_cluster",
158                 "create_cluster", "delete_cluster", "add_conduit_to_cluster",
159                 "remove_conduit_from_cluster", "get_clusters_for_conduit"):
160        assert hasattr(cloud, verb), verb
161        print("   ", verb)
162
163    print()
164    print("the cloud is FRAME-owned and shared - ask any conduit, same object")
165    print("cheap questions (has_/find_) before expensive ones (get_)")
166
167
168if __name__ == "__main__":
169    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 intermediate examples ยท Level guide