Wiki · Evidence & Verdicts
Scenario Authoring Guide
How to read this page
Three ways to read this page. Precise is the document itself, exactly as it is written in the repository. Plain and Clear were written for this website to help you meet that document — they are about it. They are not it, and they are not evidence.
Eighty-seven dated pages: receipts, pre-registrations, handoffs, validation records and review verdicts. A receipt is written at the moment a piece of work was checked. It names what was claimed, the commit and the seed, what was actually run, and the outcome in one of a small set of controlled words. Then it names what the work did not achieve. That last part is what makes it a receipt rather than an announcement. A pre-registration is the same discipline run in advance: the conditions that would count as a pass and the conditions that would falsify the claim are written down before the run, so neither can be adjusted once the numbers arrive.
That is why so many small dated stubs are an audit trail rather than noise. No one of them is meant to be a good read. The value is in the sequence and in the dates, because you can watch a prediction be registered, then the run happen, then the verdict land — sometimes against the prediction. Pages here record a falsified result, a rejected fix, a retracted overclaim, and a green receipt that turned out not to be reproducible from the commit that carried it. A record that carried only successes would be worth a good deal less than this one.
A gentle way in is to read a pre-registration first, so the shape becomes familiar, then a result page, then one of the corrections. This section sits off the main navigation on purpose: it is the record you check the rest of the site against, not the place to begin.
What it is not: documentation, and not a summary. Nothing here has been tidied in hindsight. Every entry reads as of its date, a later entry may overturn an earlier one, and the presence of a page is not a claim that its result stood.
Your browser cannot switch reading levels, so the document itself is shown.
Precise — the source document
This is the document. Rendered from the repository at the commit above, with nothing rewritten for the web. A gate re-renders it on every deploy and fails the build if a single byte differs.
A scenario is a JSON file in config/scenarios/ validated by SP.Scenario
against SP.Scenario.schema/0 (via SP.Core.Schema). Malformed configs are
rejected with structured errors, never run.
Fields
| field | type | default | meaning |
|---|---|---|---|
name |
string | — (required) | scenario id |
seed |
integer | 1 | world + channel-map seed (full reproducibility) |
regions |
integer | 2 | initial ordinary-adjacency region count |
w, h |
integer | 6 | region grid dimensions |
max_ticks |
integer | 400 | decision-tick horizon |
micro_per_decision |
integer | 3 | world microsteps per decision tick |
dev_interval |
integer | 5 | decision ticks per development tick |
agent |
enum | homeostatic |
one of SP.Scenario.agents/0 keys |
scramble |
boolean | true | per-channel value affine on the opaque interface |
Built-in reference scenarios
| file | purpose | agent |
|---|---|---|
starter.json |
reference difficulty calibration | homeostatic |
epistemic.json |
mimic/ambiguity avoidance via meta sense | probe_first |
morphogenesis.json |
morphology utilisation / development | morphology_seeking |
open_ended.json |
seam engineering & expansion | infrastructure |
leakage_probe.json |
interface fuzz / leakage | leakage_probe |
SP.Scenario.builtin/0 returns the same set in code.
Loading and running
{:ok, scenario} = SP.Scenario.load("config/scenarios/starter.json")
sim = scenario |> SP.Scenario.to_sim_opts() |> SP.Sim.new() |> SP.Sim.run()
report = SP.Observability.episode_report(sim)
Authoring a new scenario
- Copy a built-in JSON and edit fields.
- Validate:
SP.Scenario.load("config/scenarios/mine.json")should return{:ok, _}; a typo'dagentyields{:error, [{:agent, {:not_in, [...]}}]}. - For reproducible difficulty bands, run across a seed batch (see
config/seeds.json) and record the survival/expansion distribution. - To pin a regression, regenerate the golden artifact for your seed
(
scripts/gen_golden.exs) — but prefer the existing reference golden unless intentionally changing dynamics.
Determinism contract
A scenario is reproducible: (seed, regions, w, h, cadence, agent, scramble)
fully determines the trace. Re-running yields byte-identical traces (Invariant
#13). Different seeds yield different worlds and different opaque channel maps.
sha256 647390d7d4824e6d — of the original file, so what was ingested stays checkable.
Plain — written for this website, not the source document
This is a how-to page for people setting up runs of a simulation. A scenario is a small settings file: how big the world is, how long it runs, which agent behaviour to use, which random seed to start from. The page lists every setting with its default and its meaning, shows the built-in examples, and explains how to write a new one and check that it loads. The last section is the one that matters most: a fixed set of settings fully determines the run, so re-running it produces the same trace byte for byte.
Plain · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 647390d7d4824e6d
Clear — written for this website, not the source document
This is a reference guide for a simulation, not a report of any result. It describes how to write the small settings file that defines a run, and it assumes the reader is going to run one.
The first part is a table of settings: what each is called, what type it takes, what it falls back to if you leave it out, and what it means. Between them they cover the size and shape of the world, how long it runs, how often development happens relative to decisions, which agent behaviour to use, and whether the interface between agent and world is scrambled. Anything malformed is rejected with a structured error rather than run.
Then a table of the built-in examples, each written to exercise a different aspect, so a new scenario usually starts life as a copy of one of them. A short block of code shows how to load a scenario, turn it into a run, and get a report out of it.
The authoring recipe is four steps. Copy and edit. Check that it loads cleanly, and that a deliberate typo gives a readable error. Sweep a batch of seeds if you want a stable difficulty band. And regenerate the stored reference artefact only if you meant to change the behaviour.
The closing section states the determinism contract. A fixed set of settings fully determines the trace, and re-running yields byte-identical output, while a different seed changes both the world and the hidden mapping between agent and world.
Clear · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 647390d7d4824e6d