On this page
What a synthetic module actually is๏
๐ต Expert ยท Lesson 33
WHAT A SYNTHETIC MODULE ACTUALLY IS, and why one crystal shape holds both it and a file on your disk. Lessons 26, 27, 29, 30 and 32 all MAKE synthetic modules. None of them says what one IS. This does.
A SYNTHETIC MODULE IS A REAL MODULE WITH NO FILE. It is a live ModuleType subclass the crystallizer owns: it carries its own source text and hash, registers with a class-level import registry behind a meta-path finder, and answers plain import name like anything else. Its source IS the record - there is no file to go read, so there is nothing to go stale.
FOUR STATES, NONE INFERRED FROM ANOTHER: registration, import-hook install, publication into sys.modules, and source execution. materialize_codegen is the convenience path that composes all four. And it PUBLISHES BEFORE IT EXECUTES, deliberately - that is how importlib treats real modules, so a circular import sees a partially-initialised module instead of a missing one.
CUSTODY IS HOW THE CRYSTALLIZER DECIDES WHAT A MODULE IS. Bind walks your object's dependencies and classifies every module it meets through FOUR authority classes, taking the FIRST that matches:
synthetic_module claims by OBJECT IDENTITY (isinstance), never path - because a path rule would misclassify it. Reads no disk. Makes NO fingerprint claim; its rebuild payload already carries source_sha256. user_source claims by path under the configured user roots. THE ONLY FINGERPRINT CUSTODIAN - a bind-time SHA256 over your source. This is the trust boundary, and it is the whole reason drift is detectable at all. site_package installed distributions. Descends and reads, but claims NOTHING - you did not write it, so its changing is not your bug. unknown the fallback: pathless, unresolvable, binary. THE ONLY CLASS THAT DOES NOT DESCEND. Recorded as an honest leaf so the manifest never implies a more complete picture than the source supports.
SO THE ANSWER TO "CAN THIS DRIFT" IS DECIDED BY CUSTODY, NOT BY CHANCE. Only user source is fingerprinted, so only user source can be caught changing under you. A synthetic module cannot drift - not because drift is unchecked but because its text is the record.
AND BIND FORMATS BOTH INTO ONE CRYSTAL. There is no synthetic crystal and no file crystal. One flat module inventory, plus four kind-partitions that are subsets of it, plus root_module_kind naming which lane the root took. The KIND is DATA IN the crystal, not a different crystal - which is exactly why a world can mix generated and hand-written code and still checkpoint as one thing.
A NOTE ON WHAT THIS LESSON POINTS AT. SyntheticModule, the custody strategies and SpellCrystal are all AGENT_ACCESS: internal - "read it to understand the runtime, do not drive it directly". They are NAMED here because you cannot reason about your own world without knowing they exist. Every line below drives the PUBLIC surface only.
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/33_what_a_synthetic_module_actually_is.py
py -3.14t UX_and_AIX_experiences/04_expert/33_what_a_synthetic_module_actually_is.py
Public surface๏
validate_codegen / materialize_codegen / research_source / research_module / research_source_drift
Code๏
1"""
2TIER: expert (33)
3GOAL: WHAT A SYNTHETIC MODULE ACTUALLY IS, and why one crystal shape holds
4 both it and a file on your disk. Lessons 26, 27, 29, 30 and 32 all
5 MAKE synthetic modules. None of them says what one IS. This does.
6
7 A SYNTHETIC MODULE IS A REAL MODULE WITH NO FILE. It is a live
8 `ModuleType` subclass the crystallizer owns: it carries its own
9 source text and hash, registers with a class-level import registry
10 behind a meta-path finder, and answers plain `import name` like
11 anything else. Its source IS the record - there is no file to go
12 read, so there is nothing to go stale.
13
14 FOUR STATES, NONE INFERRED FROM ANOTHER: registration, import-hook
15 install, publication into `sys.modules`, and source execution.
16 `materialize_codegen` is the convenience path that composes all
17 four. And it PUBLISHES BEFORE IT EXECUTES, deliberately - that is
18 how importlib treats real modules, so a circular import sees a
19 partially-initialised module instead of a missing one.
20
21 CUSTODY IS HOW THE CRYSTALLIZER DECIDES WHAT A MODULE *IS*.
22 Bind walks your object's dependencies and classifies every module it
23 meets through FOUR authority classes, taking the FIRST that matches:
24
25 synthetic_module claims by OBJECT IDENTITY (isinstance), never
26 path - because a path rule would misclassify it.
27 Reads no disk. Makes NO fingerprint claim; its
28 rebuild payload already carries source_sha256.
29 user_source claims by path under the configured user roots.
30 THE ONLY FINGERPRINT CUSTODIAN - a bind-time
31 SHA256 over your source. This is the trust
32 boundary, and it is the whole reason drift is
33 detectable at all.
34 site_package installed distributions. Descends and reads, but
35 claims NOTHING - you did not write it, so its
36 changing is not your bug.
37 unknown the fallback: pathless, unresolvable, binary.
38 THE ONLY CLASS THAT DOES NOT DESCEND. Recorded as
39 an honest leaf so the manifest never implies a
40 more complete picture than the source supports.
41
42 SO THE ANSWER TO "CAN THIS DRIFT" IS DECIDED BY CUSTODY, NOT BY
43 CHANCE. Only user source is fingerprinted, so only user source can
44 be caught changing under you. A synthetic module cannot drift - not
45 because drift is unchecked but because its text is the record.
46
47 AND BIND FORMATS BOTH INTO ONE CRYSTAL. There is no synthetic
48 crystal and no file crystal. One flat module inventory, plus four
49 kind-partitions that are subsets of it, plus `root_module_kind`
50 naming which lane the root took. The KIND is DATA IN the crystal,
51 not a different crystal - which is exactly why a world can mix
52 generated and hand-written code and still checkpoint as one thing.
53
54 A NOTE ON WHAT THIS LESSON POINTS AT. `SyntheticModule`, the custody
55 strategies and `SpellCrystal` are all AGENT_ACCESS: internal - "read
56 it to understand the runtime, do not drive it directly". They are
57 NAMED here because you cannot reason about your own world without
58 knowing they exist. Every line below drives the PUBLIC surface only.
59SURFACE EXERCISED: validate_codegen / materialize_codegen /
60 research_source / research_module /
61 research_source_drift
62VERIFY: rides the owner's 3.14t harness; asserts are the contract.
63"""
64import importlib
65
66import melder as md
67
68
69FRAME = "custody-world"
70SYNTHETIC_MODULE = "custody_generated_unit"
71
72GENERATED_SOURCE = '''"""A module with no file. Its source IS the record."""
73
74
75class Unit:
76 def __init__(self) -> None:
77 self.origin = "synthetic"
78
79 def describe(self) -> str:
80 return "unit:" + self.origin
81'''
82
83
84class DiskUnit:
85 """Declared in THIS file, so its root module is file-backed."""
86
87 def __init__(self) -> None:
88 self.origin = "disk"
89
90
91def _row(label: str, row: object) -> None:
92 if isinstance(row, dict):
93 print(" %-18s kind=%-11s origin=%-10s drifted=%-5s unavailable=%s"
94 % (label, row.get("kind"), row.get("origin"),
95 row.get("drifted"), row.get("text_unavailable")))
96 else:
97 print(" %-18s -> %s" % (label, type(row).__name__))
98
99
100def main() -> None:
101 crystallizer = md.Crystallizer()
102 crystallizer.activate(
103 md.CrystallizerConfigurationBuilder().with_defaults().activate(),
104 )
105 research = md.MutationResearch()
106 configuration = research.create_configuration()
107 configuration.with_defaults().activate()
108 research.activate(configuration)
109
110 spellbook_configuration = (
111 md.SpellbookConfiguration(FRAME).with_defaults().finalize()
112 )
113 book = md.Spellbook(aetheric_frame=FRAME,
114 configuration=spellbook_configuration)
115 book.configure_aether_frame(
116 system_state="dynamic",
117 disposal=None,
118 disposal_method_names=None,
119 rift_enabled=True,
120 ai_native=True,
121 )
122
123 # AN EMPTY FRAME IS A REAL FRAME. `configure_aether_frame` declares the
124 # frame's LAW; `conjure` REALIZES it by giving it a root conduit, and
125 # that realization is what publishes it to the Nexus. Publication is
126 # gated on `rift_enabled` ALONE - the spell loop it runs iterates
127 # whatever the book holds, including nothing. So the frame below is
128 # conjured EMPTY and is immediately linkable; spells are cargo, not a
129 # precondition, and everything bound after this arrives incrementally.
130 book.conjure(name="custody-root")
131
132 nexus = md.Nexus()
133 system_configuration = nexus.create_configuration()
134 system_configuration.with_rift_creation_enabled(True)
135 system_configuration.with_allowed_target_frame_names([FRAME])
136 nexus.activate(system_configuration)
137 rift_configuration = nexus.create_rift_configuration()
138 rift_configuration.with_space_type("codegen")
139 rift = nexus.create_rift(configuration=rift_configuration,
140 rift_name="custody")
141 rift.mark_active()
142 rift.create_frame_link(FRAME)
143 commands = rift.space.command_system
144
145 # ONE MODULE WITH NO FILE. materialize composes all four states:
146 # register -> hook -> publish -> execute.
147 commands.validate_codegen(GENERATED_SOURCE, frame_name=FRAME)
148 kept = commands.materialize_codegen(
149 GENERATED_SOURCE, module_name=SYNTHETIC_MODULE, frame_name=FRAME,
150 )
151 assert kept["materialized"] is True, kept
152 print("materialized:", SYNTHETIC_MODULE)
153 print(" it has no file, and `import` still resolves it - the import")
154 print(" hook is installed and the module is registered")
155
156 generated = importlib.import_module(SYNTHETIC_MODULE)
157 assert generated.Unit().describe() == "unit:synthetic"
158 print(" imported and executed: Unit().describe() ->",
159 generated.Unit().describe())
160
161 # TWO BINDS, TWO AUTHORITY CLASSES, ONE VERB - both landing in a frame
162 # that was already live and empty before either existed.
163 synthetic_spell = book.bind(spell=generated.Unit, existence="unique",
164 permissions="create",
165 binding_name="custody-synthetic")
166 disk_spell = book.bind(spell=DiskUnit, existence="unique",
167 permissions="create", binding_name="custody-disk")
168 print()
169 print("bound BOTH with the same verb:")
170 print(" synthetic root:", synthetic_spell[:12])
171 print(" file-backed :", disk_spell[:12])
172
173 # THE SAME PUBLIC READ ANSWERS FOR BOTH - and labels the difference.
174 print()
175 print("research_source - same read, same shape, different KIND:")
176 synthetic_view = commands.research_source(synthetic_spell)
177 disk_view = commands.research_source(disk_spell)
178 for label, view in (("synthetic", synthetic_view), ("file", disk_view)):
179 assert isinstance(view, dict), view
180 root = str(view["root_module"])
181 row = view["modules"][root]
182 assert set(row) >= {"source", "origin", "kind", "drifted",
183 "text_unavailable"}, sorted(row)
184 _row(label + " root", row)
185
186 synthetic_root = str(synthetic_view["root_module"])
187 synthetic_row = synthetic_view["modules"][synthetic_root]
188 disk_root = str(disk_view["root_module"])
189 disk_row = disk_view["modules"][disk_root]
190
191 # THE SYNTHETIC LANE IS THE RELIABLE ONE, not the exotic one:
192 # synthetic sources are ALWAYS harvested; user text is opt-in.
193 assert synthetic_row["kind"] == "synthetic", synthetic_row
194 assert synthetic_row["origin"] == "recorded"
195 assert synthetic_row["text_unavailable"] is False
196 print(" the synthetic row is ALWAYS harvested - no opt-in, no file,")
197 print(" no way for it to be missing")
198
199 # A RECORDED ROW REPORTS drifted=None, AND THAT IS NOT IGNORANCE.
200 # There is no second copy to disagree with: the text IS the record.
201 assert synthetic_row["drifted"] is None
202 print(" drifted=None on a recorded row means there is NOTHING TO")
203 print(" DISAGREE WITH - the text is the record, not a copy of it")
204
205 # THE FILE-BACKED ROW TOOK ONE OF TWO LANES, and both are honest.
206 assert disk_row["kind"] in ("user", "live_disk"), disk_row
207 if disk_row["kind"] == "user":
208 print(" the file row was RETAINED (opt-in retention lane is on)")
209 else:
210 print(" the file row was read LIVE from disk through the recorded")
211 print(" path - and only THIS lane can compute drift, because only")
212 print(" user source carries a bind-time SHA256 to compare against")
213
214 # THE DOSSIER READ. One call instead of hand-joining five.
215 print()
216 print("research_module - the one-call dossier for a single module:")
217 dossier = commands.research_module(synthetic_spell, synthetic_root)
218 assert isinstance(dossier, dict)
219 print(" keys:", sorted(dossier)[:8])
220 print(" source labeled synthetic/user/live_disk, plus fingerprint,")
221 print(" path, dependencies both ways, importers, exports and drift")
222
223 # THE WORLD-LEVEL DRIFT REPORT ONLY SEES WHAT WAS SEALED.
224 print()
225 drift = commands.research_source_drift()
226 assert isinstance(drift, dict)
227 print("research_source_drift ->", sorted(drift)[:5])
228 print(" it reports per SEALED module - and sealing is a FINGERPRINT")
229 print(" claim, which only user source makes. A synthetic module is")
230 print(" absent from drift not because it was skipped but because the")
231 print(" question does not apply to it")
232
233 print()
234 print("ONE CRYSTAL HOLDS BOTH. There is no synthetic crystal and no")
235 print("file crystal - one flat module inventory, four kind-partitions")
236 print("over it, and root_module_kind naming the lane the root took.")
237 print("The kind is DATA IN the crystal, which is why a world can mix")
238 print("generated and hand-written code and checkpoint as one thing.")
239
240
241if __name__ == "__main__":
242 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.