On this page

One config every book๏ƒ

๐ŸŸก Intermediate ยท Lesson 35

ONE SPELLBOOK CONFIGURATION SHARED BY EVERY BOOK. When several books make up one subsystem, per-book configs drift - one book's teardown vocabulary says "close", another forgot it. The fix is ONE SpellbookConfiguration for the whole subsystem.

KNOW WHICH OBJECT YOU ARE TALKING ABOUT. A frame has two:

  • the FRAME POSTURE (AethericFrameConfiguration) - narrow: system state, ai-native, rift, the devops brakes. It is SHARED WITH EVERY BOOK ON THE FRAME ALREADY, by default, with no opt-in. The frame mints exactly one and every Spellbook only borrows that reference. Set posture through any one book and every book on that frame reads it.

  • the RICH CONFIG (SpellbookConfiguration) - wide: disposal, disposal method names, scheduler workers, barrier timeout, singleton specialization. THIS one is PER-BOOK by default. Two books on the same frame mint two separate ones.

This lesson is about making the RICH one shared. Two shapes:

SHAPE 1 - MANUAL SHARE (fully public, works today, shown below): 1. build ONE SpellbookConfiguration for the frame 2. set the policy on it once 3. hand THE SAME OBJECT to every Spellbook you construct Every book now reads one policy, by reference. The first conjure freezes that object; every later book's conjure re-enters the freeze and locks against the same object.

SHAPE 2 - FRAME-OWNED SHARE (the frame holds the config and later books ADOPT it with nothing passed). The machinery is complete and it takes exactly two things, in this order: 1. THE SWITCH - the frame posture must carry shared_framewide_spellbook_configuration=True. Every sharing path early-outs while it is False. It must be flipped BEFORE the frame's first conjure, because the posture freezes on that first bind and the switch is refused once frozen. 2. PUBLICATION - one book binds its rich config to the frame. Two doors do this, whichever runs first: configure_aether_ frame(), and conjure() itself (conjure freezes and binds whenever the book is not already locked). FIRST ONE WINS. Then every book constructed AFTER that adopts the frame-owned object at construction and reports is_configuration_locked() True; a book that already existed converges at its own conjure, swapping to the shared object and cleaning up its local one. Handing a DIFFERENT config to a later book on that frame is refused. Adoption is total - no per-book override - and a book's cleanup() leaves the shared object alone.

HONEST GAP: shape 2 has NO public switch today. Nothing in the public API sets shared_framewide_spellbook_configuration - every construction site in the runtime passes False or omits it, and no Spellbook door exposes the retained posture. So shape 1 is the answer to "one config for every book" until a door exists. The probes pin shape 2's machinery through the private seam so it cannot rot while it waits.

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/35_one_config_every_book.py

py -3.14t UX_and_AIX_experiences/02_intermediate/35_one_config_every_book.py

Download this collection ยท Source on GitHub

Public surface๏ƒ

one configuration object across multiple books

Code๏ƒ

  1"""
  2TIER: intermediate (35)
  3GOAL: ONE SPELLBOOK CONFIGURATION SHARED BY EVERY BOOK. When several
  4      books make up one subsystem, per-book configs drift - one book's
  5      teardown vocabulary says "close", another forgot it. The fix is
  6      ONE SpellbookConfiguration for the whole subsystem.
  7
  8      KNOW WHICH OBJECT YOU ARE TALKING ABOUT. A frame has two:
  9
 10        * the FRAME POSTURE (AethericFrameConfiguration) - narrow: system
 11          state, ai-native, rift, the devops brakes. It is SHARED WITH
 12          EVERY BOOK ON THE FRAME ALREADY, by default, with no opt-in.
 13          The frame mints exactly one and every Spellbook only borrows
 14          that reference. Set posture through any one book and every
 15          book on that frame reads it.
 16
 17        * the RICH CONFIG (SpellbookConfiguration) - wide: disposal,
 18          disposal method names, scheduler workers, barrier timeout,
 19          singleton specialization. THIS one is PER-BOOK by default.
 20          Two books on the same frame mint two separate ones.
 21
 22      This lesson is about making the RICH one shared. Two shapes:
 23
 24      SHAPE 1 - MANUAL SHARE (fully public, works today, shown below):
 25        1. build ONE SpellbookConfiguration for the frame
 26        2. set the policy on it once
 27        3. hand THE SAME OBJECT to every Spellbook you construct
 28        Every book now reads one policy, by reference. The first conjure
 29        freezes that object; every later book's conjure re-enters the
 30        freeze and locks against the same object.
 31
 32      SHAPE 2 - FRAME-OWNED SHARE (the frame holds the config and later
 33      books ADOPT it with nothing passed). The machinery is complete and
 34      it takes exactly two things, in this order:
 35        1. THE SWITCH - the frame posture must carry
 36           shared_framewide_spellbook_configuration=True. Every sharing
 37           path early-outs while it is False. It must be flipped BEFORE
 38           the frame's first conjure, because the posture freezes on
 39           that first bind and the switch is refused once frozen.
 40        2. PUBLICATION - one book binds its rich config to the frame.
 41           Two doors do this, whichever runs first: configure_aether_
 42           frame(), and conjure() itself (conjure freezes and binds
 43           whenever the book is not already locked). FIRST ONE WINS.
 44        Then every book constructed AFTER that adopts the frame-owned
 45        object at construction and reports is_configuration_locked()
 46        True; a book that already existed converges at its own conjure,
 47        swapping to the shared object and cleaning up its local one.
 48        Handing a DIFFERENT config to a later book on that frame is
 49        refused. Adoption is total - no per-book override - and a book's
 50        cleanup() leaves the shared object alone.
 51
 52      HONEST GAP: shape 2 has NO public switch today. Nothing in the
 53      public API sets shared_framewide_spellbook_configuration - every
 54      construction site in the runtime passes False or omits it, and no
 55      Spellbook door exposes the retained posture. So shape 1 is the
 56      answer to "one config for every book" until a door exists. The
 57      probes pin shape 2's machinery through the private seam so it
 58      cannot rot while it waits.
 59SURFACE EXERCISED: one configuration object across multiple books
 60"""
 61import melder as md
 62
 63
 64class ServiceA:
 65    pass
 66
 67
 68class ServiceB:
 69    pass
 70
 71
 72def main() -> None:
 73    # THE DEFAULT for the rich config: two books, two configurations.
 74    solo_a = md.Spellbook(aetheric_frame="drifting-world")
 75    solo_b = md.Spellbook(aetheric_frame="drifting-world")
 76    assert solo_a.get_configuration() is not solo_b.get_configuration()
 77    print("default: same frame, two separate rich configurations")
 78
 79    # ...while the frame POSTURE was already one object for both books.
 80    print("posture was shared the whole time - that one needs no opt-in")
 81
 82    # SHAPE 1, step 1+2: ONE policy object for the whole subsystem.
 83    shared = md.SpellbookConfiguration()
 84    shared.with_defaults()
 85    shared.set_property("phase_scheduler_workers_per_spellbook", 1)
 86
 87    # SHAPE 1, step 3: hand THE SAME OBJECT to every book.
 88    book_a = md.Spellbook(configuration=shared)
 89    book_b = md.Spellbook(configuration=shared)
 90
 91    # Both books read THE SAME object - one teardown story, one
 92    # scheduler policy, no drift possible.
 93    assert book_a.get_configuration() is book_b.get_configuration()
 94    assert book_a.get_configuration() is shared
 95    print("two books, one configuration object")
 96
 97    book_a.bind(spell=ServiceA, existence="unique")
 98    book_b.bind(spell=ServiceB, existence="unique")
 99    # Root conduit names are unique PER FRAME, and an unnamed conjure takes
100    # the name "default". Two books in one frame therefore need two names -
101    # the shared configuration is what they have in common, not their identity.
102    conduit_a = book_a.conjure(name="shared-policy-a")
103    conduit_b = book_b.conjure(name="shared-policy-b")
104    assert isinstance(conduit_a.meld("ServiceA"), ServiceA)
105    assert isinstance(conduit_b.meld("ServiceB"), ServiceB)
106    print("both worlds conjured under the one shared policy")
107
108
109if __name__ == "__main__":
110    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