Operator Runbook

The Colony & the Method · docs/runbooks/operator.md @ 44baf03d5041 (gen2-runtime) — opens the published snapshot ac338733bbba

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-four pages about the colony. Each agent is an Elixir process holding a generative model and doing inference, attached to a body that logs into a Minecraft world as an ordinary player. Around that sit the broadcast suite that films them and the runbooks that keep the whole thing running. There are typed specifications for each organ of the model, plus the world and genome specs. There are also the adversarial review personas used to attack a proposed change before it ships.

It is for the reader curious how a running system is put together and how it is held to account. The accountability half is the more distinctive. There is a lab protocol governing evidence and attribution, and a claim fence that restricts the vocabulary a claim is allowed to use. There is a public gate log. And there is a standing invitation to reproduce any verdict from the commit and the seed named in its receipt.

Start with the public read, then the lab protocol, then the falsification invitation. If you want the mathematics rather than the operations, go straight to the typed organ specs.

What it is not: a description of a mind, and not all one kind of document. A large part of this corpus is design and planning — specs marked as proposed rather than applied, organs designed but not built, plans that were later superseded — and each page states which it is. A specification is not a running system, and these pages are careful about the difference; the reader should be too. Eight documents were withheld from publication because they describe private infrastructure.

PlainClearPrecise

Your browser cannot switch reading levels, so the document itself is shown.

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.

Prerequisites

Elixir ~> 1.17, Erlang/OTP >= 27 (for the built-in :json module).
No hex dependencies to fetch (pure core).

Everyday commands

task	command
Compile	`mix compile`
Full QA suite	`mix test`
Baseline benchmark table	`mix run scripts/benchmark.exs [max_ticks]`
Validation evidence dump	`mix run scripts/evidence.exs`
Regenerate golden artifact	`mix run scripts/gen_golden.exs`
Run a scenario (IEx)	see scenario authoring
Record a blanket evidence log	`mix run scripts/record_run.exs [seed] [agent] [ticks]`
Independently verify a log	`mix sp.verify runs/<run>.jsonl` (exit non-zero on violation)
Overlooker UI (god view + blanket monitor)	`cd ui && mix deps.get && mix phx.server` → http://localhost:4000

Overlooker UI & falsifiable evidence

The third-party observer view is the Phoenix LiveView app under ui/ — the full world every tick plus a per-tick Markov-blanket verdict. See docs/ui/overlooker.md. The headless, falsifiable counterpart is the evidence log + mix sp.verify; see docs/observability/evidence_log.md. Recording is opt-in (record_blanket?: true) and never affects determinism.

Inspecting an episode

sim = SP.Sim.new(seed: 404, agent: SP.Baselines.Infrastructure, max_ticks: 800) |> SP.Sim.run()

SP.Sim.summary(sim)                 # compact outcome
SP.Observability.episode_report(sim)# provenance + summary + metrics
SP.Sim.points(sim)                  # per-tick viability trajectory (chronological)
sim.trace.signal_type_counts        # sensor modality usage
sim.trace.action_counts             # action usage
sim.trace.build_counts              # infrastructure built (by kind)
sim.trace.expansions                # seam expansion events

Observability surfaces

Viability trajectory — SP.Sim.points/1 (envelope, risk, prior divergence, energy, integrity, stage, region_count per tick).
Signal / action audit — aggregated counts in sim.trace.
Resource/region state — SP.World.region/2, SP.World.Region fields.
Provenance — SP.Observability.provenance/1 (seed, cadence, catalogue version, world dims) for reproducibility capture.
JSON export — SP.Observability.json/1 / json_pretty/1.

Debug vs production mode

Production (learner) mode — agents receive only %{int => float} observations. This is the default path through SP.Interface.
Debug mode — pass debug?: true to SP.Sim.new/1 to enable the in-loop leak trap (raises if any learner-facing observation is ever non-clean). Use in CI / development, not for learner serving.
The semantic inverse (SP.Interface.reveal_*) and SP.Baselines.Lens are engineering-only; never wire them into a learner.

Failure handling

symptom	meaning	action
episode `halted: :dead` early	harsh seed / weak policy	expected on some seeds; check `mean_risk`
`decoded_failures > 0`	agent sent malformed/garbage actions	inspect agent; runtime already ignores them safely
`ungated_attempts > 0`	agent tried actions its morphology can't do	expected during development; informational
golden test fails	dynamics/interface changed	review diff; regenerate intentionally if desired
scenario `load` error	malformed config	fix per the returned `{:error, [{field, reason}]}`

Health checks

mix test green ⇒ invariants hold.
mix run scripts/evidence.exs ⇒ reproducibility/leakage/conservation pass and difficulty bands are in range.

sha256 6bf40df79c514218 — of the original file, so what was ingested stays checkable.

Written for this website — not the document. This is a plain-language retelling, written to help you meet the document. It is not the source, and it is not evidence. It has not yet been checked by a person. Read the document itself → (or choose Precise in the reading-level control above)

This is the day-to-day runbook for whoever is running the benchmark. It is mostly tables of commands.

The first table covers everyday tasks: compile, run the whole suite, produce a benchmark table, dump the validation evidence, regenerate a stored artifact, record a run, independently verify a recorded run, and start a viewing interface.

The rest fills in around that. How to inspect a single episode from an interactive session. Which surfaces exist for looking at what happened. And a clear distinction between the mode a learner is served in, where it receives nothing but numbers keyed by numbers, and a debug mode that raises immediately if anything unclean ever reaches it.

The most useful table is the failure one. It pairs each symptom with what it means and what to do, and several rows say the honest thing: this is expected on some seeds, and the runtime already handles it safely.

Plain · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 6bf40df79c514218

Written for this website — not the document. This is a clearer retelling, written to help you meet the document. It is not the source, and it is not evidence. It has not yet been checked by a person. Read the document itself → (or choose Precise in the reading-level control above)

This is the operator's runbook: the page you keep open while running the benchmark. It is built from tables rather than prose.

It opens with prerequisites, which are short because the core has no dependencies to fetch. Then comes a table of everyday commands: compiling, running the full quality suite, producing a table of reference results, and dumping the validation evidence. The rest regenerate the stored regression artifact, run a scenario, record an evidence log for a run, check such a log independently with a command that exits non-zero on a violation, and start a viewing interface.

A short section describes two ways of observing from outside. One is a live interface showing the whole world each tick together with a per-tick verdict on whether the boundary held. The other is the headless counterpart: a recorded log plus the command that re-derives the verdict from it. Recording is opt-in and does not affect determinism.

An inspection section shows, as a block of interactive commands, how to construct and run an episode and then look at its summary, its provenance, its per-tick trajectory, and aggregate counts of sensor use, actions, structures built and expansions.

A list of observability surfaces follows, covering the viability trajectory, the aggregated signal and action audit, the state of resources and regions, the provenance record, and export to a portable format.

The distinction between two modes is stated plainly. In the mode a learner is served in, agents receive only numbers keyed by numbers, and this is the default path. In debug mode a trap in the loop raises immediately if any observation reaching the learner is ever unclean, and the runbook says to use it in development rather than when serving. The functions that reveal meaning, and the debug lens, are described as engineering-only and must never be wired into a learner.

The most practically useful table pairs each failure symptom with its meaning and the action to take. Several rows do not treat the symptom as a defect at all. An early death is expected on harsh seeds, and garbage actions are already ignored safely by the runtime. Attempts at actions a body cannot yet perform are informational during development. Others point at a real decision, such as reviewing a difference before regenerating a stored artifact.

It closes with two health checks: a green suite means the invariants hold, and the evidence dump should show reproducibility, leakage and conservation passing with difficulty inside its band.

Clear · written 2026-08-01 by claude-opus-5 · not yet checked by a person · about the document whose sha256 is 6bf40df79c514218

Operator Runbook

How to read this page

Precise — the source document