# Asking what code would do before running it

**🔵 Expert · Lesson 22**

FORESIGHT. An agent about to replace a version can ask what the replacement WOULD do - what it defines, what it imports, how it differs from what is there, what it would break, and whether the room would even permit it - and get all of that WITHOUT running, binding, or recording anything.

commands.research_preview( candidate_source, against_spell_id=existing_spell_id, frame_name=FRAME, )

ONE CALL, FIVE ANSWERS defines / import_roots what the candidate declares and pulls diff would-be source + structural diff against the version it would REPLACE impact the blast radius of that replacement, joined with research residency candidate_sha256 the identity it would have validation the room's normal codegen verdict, but ONLY when frame_name is supplied That last one matters: `validate_codegen` answers "am I permitted", `research_preview` answers "what would happen", and passing a frame folds the first into the second so an agent asks once.

ORDER OF SETUP IS LOAD-BEARING, IN TWO SEPARATE WAYS

1. A BIND ONLY AUTO-RECORDS INTO A LIVE RESEARCH ROOT. The seam returns quietly when research is absent, cleaned or inactive, because "research bookkeeping never gates a bind". So a world built before you activate research is a world research never saw. Activate first, then build.

2. AND A RECORDED WORLD MUST BE BORN CONFIGURED. With custody active, a DYNAMIC conjure REFUSES outright if any bind ran before the SpellbookConfiguration was finalized:

md.SpellbookConfiguration(FRAME).with_defaults().finalize() md.Spellbook(aetheric_frame=FRAME, configuration=...) book.bind(...) # now the binds are config-coherent book.conjure(dynamic=True)

The reason is stated in the refusal itself: the profile record, the checkpoints and the default bootstrap would DURABLY PERSIST binds that ran against unsettled configuration. A runtime can tolerate that; a RECORD cannot, because the record is what a future boot rebuilds from. Automatic-mode worlds and worlds with no active Crystallizer are exempt, so nothing that is not being recorded pays for this.

Note which lessons this caught: every lesson in this tier that activates custody AND conjures dynamic, and none of the others. The rule is narrow and it is exactly as narrow as the risk.

AND FORESIGHT NEEDS CUSTODY. The impact half reaches through the Crystallizer for the physical picture (expert 14's record-vs- foresight split), so it refuses loudly when custody is not recording rather than handing back an empty radius.

THE PROOF THAT PREVIEW IS READ-ONLY IS IN THIS FILE The lesson reads the research heads before and after the preview and asserts they are IDENTICAL. "Nothing executes, binds, or records" is a claim melder makes about itself; here it is checked.

A BROKEN CANDIDATE ANSWERS, IT DOES NOT EXPLODE Hand it source that does not parse and `parse_error` comes back populated with the rest of the payload still shaped the same way. An agent generating code gets malformed output sometimes; a foresight tool that raised on it would be useless exactly when it is needed.

## 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/22_asking_what_code_would_do_before_running_it.py
```

```powershell
py -3.14t UX_and_AIX_experiences/04_expert/22_asking_what_code_would_do_before_running_it.py
```

{download}`Download this collection <../../downloads/expert-examples.zip>` · [Source on GitHub](https://github.com/Synaptic724/melder/blob/4b364a338debcb1c010d0f6e9dcbbabb62945ba0/UX_and_AIX_experiences/04_expert/22_asking_what_code_would_do_before_running_it.py)

## Public surface

research_preview (defines / import_roots / diff /
                   impact / candidate_sha256 / parse_error),
                   research_impact, research_heads, and the
                   Crystallizer + MutationResearch activation order

## Code

```{literalinclude} ../../downloads/04_expert/22_asking_what_code_would_do_before_running_it.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

- [Preview, stage, and governed change](../../expert/governed-change.md)
- [Complete operational walkthroughs](../../expert/walkthroughs.md)

## API contracts

- [Crystallizer](../../reference/api/persistence/crystallizer.md)
- [MutationResearch](../../reference/api/research/mutationresearch.md)