# 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](../../expert/index.md) 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

```bash
python UX_and_AIX_experiences/04_expert/33_what_a_synthetic_module_actually_is.py
```

```powershell
py -3.14t UX_and_AIX_experiences/04_expert/33_what_a_synthetic_module_actually_is.py
```

{download}`Download this collection <../../downloads/expert-examples.zip>` · [Source on GitHub](https://github.com/Synaptic724/melder/blob/90d52e0a12cb0743d62568d5a19ce954a54443bc/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

```{literalinclude} ../../downloads/04_expert/33_what_a_synthetic_module_actually_is.py
:language: python
:linenos:
```

## 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](index.md) · [Level guide](../../expert/index.md)

## Related guides

- [Build a working system from generated code](../../expert/codegen.md)
- [Persistence, profiles, and source custody](../../expert/persistence.md)