Skip to content

About

Deterministic artificial-life simulator in Rust: agent-based evolution with pluggable brain implementations, GPU-accelerated UI, DuckDB analytics, and LLM-in-the-loop experimentation

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Latest commit

 

History

3,758 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Rust ScriptBots

ScriptBots is a modern Rust reimagining of Andrej Karpathy’s classic agent-based evolution simulator. Our goal is a faithful, deterministic port with a GPU-accelerated UI, pluggable brain implementations, and first-class analytics. This is a multi-crate Cargo workspace separating simulation core, renderer-neutral runtime protocol, brains, storage, rendering, and the application shell.

The authoritative roadmap is PLAN_TO_REARCHITECT_AND_REVIVE_RUST_SCRIPTBOTS.md. The older GPUI port plan is retained as historical design evidence, and a sibling WebAssembly plan lives in PLAN_TO_CREATE_SIBLING_APP_CRATE_TARGETING_WASM.md.

Philosophy & purpose

  • Why this exists: ScriptBots is a minimalist artificial life laboratory. By rebuilding the original simulator with rigorously deterministic Rust systems, we can observe, measure, and reproduce emergent behavior at scale—without undefined behavior or global state muddying results.
  • What we learn: How simple sensory channels and local rules produce complex population dynamics—cooperation vs. predation, resource gradients shaping migration, lineage divergence under different mutation schedules, and the role of perception in survival.
  • LLM-in-the-loop science: The REST API, CLI, and MCP HTTP server expose the full control surface (knobs, patches, snapshots). This lets an external LLM agent act as an autonomous lab assistant: steering experiments, sweeping parameter spaces, logging observations into FrankenSQLite, and drafting human-readable reports.
    • Example workflows:
      • Parameter sweeps: vary mutation.{primary,secondary} and temperature gradients; record birth/death ratios and equilibrium populations.
      • Interventions: toggle closed worlds, inject carnivore cohorts, or freeze food diffusion to test resilience.
      • Reporting: query or export FrankenSQLite tables to generate charts and tables describing discovered phenomena (e.g., altruistic giving thresholds that stabilize mixed diets).
  • A brain testbed: The Brain trait and registry allow swapping decision engines—handwritten controllers, MLP/DWRAON/Assembly, or NeuroFlow—while holding the environment constant. This enables fair comparisons of:
    • Perception encoding (multi-eye vision, smell/sound/blood) and how architectures exploit them.
    • Locomotion control (exact legacy two-rotation parity by default, selectable differential drive) and energy/health trade-offs.
    • Evolutionary operators (mutation/crossover) and speciation pressures.
  • Reproducible research: Deterministic pipelines + a growing replay roadmap mean results can be shared and re-run bit-for-bit, making the project a solid platform for pedagogy, papers, and benchmarking new brain designs.

Why this exists

  • Determinism and safety: Replace legacy C++/GLUT and global state with idiomatic Rust, tightly audited platform-boundary unsafe, and reproducible runs.
  • Performance at scale: Data-parallelism (Rayon) and cache-friendly layouts to simulate thousands of agents efficiently.
  • Modern UX: Declarative, GPU-accelerated GPUI interface with an inspector, overlays, and smooth camera controls.
  • Observability: Persist metrics and snapshots to FrankenSQLite for replay, analytics, and regression testing while the UI consumes lock-free immutable read models.
  • Extensibility: Hot-swap brain implementations (MLP, DWRAON, experimental Assembly, plus optional NeuroFlow) without rewriting the world loop.

Architecture at a glance

The workspace is organized for clear boundaries and fast incremental builds:

rust_scriptbots/
├── Cargo.toml                # Workspace manifest, shared deps/lints/profiles
├── rust-toolchain.toml       # Pinned nightly toolchain and required components
├── crates/
│   ├── scriptbots-core       # Simulation core (WorldState, AgentState, tick pipeline, config)
│   ├── scriptbots-runtime    # Sole-owner HostCore, protocol, fixed-deadline lifecycle, null frontend
│   ├── scriptbots-brain      # Brain trait + base implementations (mlp, dwraon, assembly)
│   ├── scriptbots-brain-ml   # Candle tensors, Tract probe, optional Frankentorch FtBrain
│   ├── scriptbots-brain-neuro# NeuroFlow brain (optional), feature-gated
│   ├── scriptbots-index      # Uniform-grid index; alternate backends are not implemented
│   ├── scriptbots-storage    # FrankenSQLite persistence worker & analytics snapshots
│   ├── scriptbots-render     # GPUI integration and visual layer (World + tabbed Lab)
│   ├── scriptbots-world-gfx  # wgpu rendering pipeline, WGSL shaders, offscreen readback
│   ├── scriptbots-bevy       # Bevy ECS 3D rendering backend and entity simulation
│   ├── scriptbots-app        # Binary crate wiring everything together
│   ├── scriptbots-analytics  # Offline analysis, statistical aggregations, and experiment metrics
│   └── scriptbots-web        # Sibling WebAssembly harness (wasm-bindgen bindings; experimental)
├── docs/
│   └── wasm/                 # ADRs, browser matrix, multithreading notes, rendering spikes
└── original_scriptbots_code_for_reference/  # Upstream C++ snapshot for parity

Architecture diagram (high-level)

Data flows left-to-right; control surfaces are orthogonal and non-invasive:

                           ┌───────────────────────────────────────┐
                           │  scriptbots-brain family              │
                           │  (brain, brain-ml, brain-neuro)       │
                           └──────────────┬────────────────────────┘
                                          │ BrainRegistry (attach by key)
┌──────────────────────────────────────────▼──────────────────────────────────────────┐
│                  scriptbots-core (WorldState, Tick Pipeline)                        │
│  - SoA AgentColumns · Spatial index (scriptbots-index)                              │
│  - Deterministic: sense → brains → actuation → persistence projection               │
└───────────────┬───────────────────────────┬───────────────────────────┬─────────────┘
                │ AgentSnapshots            │ StepOutcome                │ ControlCommand ↑ / disposition ↓
                │                           │ + Arc<PersistenceBatch>     │
        ┌───────▼────────┐          ┌────────▼───────────────┐     ┌─────▼──────────┐
        │ Renderer (GUI) │          │ HostCore owner         │     │ HostCore      │
        │ GPUI window    │          │ PersistenceAdmission   │     │ command driver│
        │ or Terminal TUI│          │ Session / tick boundary│     └─────┬───────────┘
        │ (console text) │          └────────┬───────────────┘           │
        └───────┬────────┘                   │ admitted batch             │
                │ World snapshots   ┌────────▼───────────┐               │
                │ HUD metrics       │ scriptbots-storage │               │
        ┌───────▼────────┐          │ StoragePipeline    │               │
        │ scriptbots-    │          └────────┬───────────┘               │
        │ render         │                   ▼                            │
        └────────────────┘       ┌──────────────────────┐                │
                                 │ FrankenSQLite        │                │
                                 │ run-name.sqlite      │                │
                                 └──────────────────────┘                │
                                                                          │
                                 ┌─────────────────────────────────────────▼────────────────────┐
                                 │ scriptbots-app (orchestrator)                                │
                                 │ - launches ControlRuntime (Tokio thread)                     │
                                 │ - starts HostThread; shares ChannelHostPort with clients     │
                                 │ - selects Renderer (CLI flag/env)                            │
                                 │ - seeds world, installs brains, primes history               │
                                 └───────────────┬───────────────────────────────┬──────────────┘
                                                 │ REST (axum + Swagger UI)      │ MCP HTTP (fastmcp-rust)
                                                 │ /api/knobs /api/config        │ tools: list_knobs,get_config,
                                                 │ /api/knobs/apply PATCH config │ apply_updates,apply_patch
                                                 │                               │
                                                 │                               │
                                          ┌──────▼───────┐                       │
                                          │ control_cli  │ (reqwest; TUI watch)  │
                                          │ list/get/set │  -> REST               │
                                          └──────────────┘                       │
                                                                                 │
┌────────────────────────────────────────────────────────────────────────────────▼─────────────┐
│ scriptbots-web (wasm)                                                                          │
│ - wasm-bindgen: default_init_options/init_sim/tick/snapshot/reset/registerBrain                │
│ - snapshot_format: json | binary (Postcard) · wasm-vs-native parity tests                      │
│ - feeds JS renderer (WebGPU/Canvas)                                                            │
└──────────────────────────────────────────────────────────────────────────────────────────────┘
  • Background workers: HostThread owns the simulation's HostCore and fixed-deadline driver. StoragePipeline is a bounded-admission writer whose separate thread creates and exclusively owns its FrankenSQLite connection; ControlRuntime (Tokio) is separately isolated. A successful enqueue is not a durability receipt: flush or shutdown must acknowledge the earlier transactions. Frontends and control servers submit commands through ChannelHostPort; the host applies them at owner boundaries.
  • Startup is fail-closed and transactional. Renderer selection and control-environment validation happen first, then every enabled REST/MCP socket is prebound and held before configuration output, auto-tuning, process-priority changes, world construction, or storage reservation. Launch consumes those exact listeners, so a bind failure cannot leave config, tuning, or run-database artifacts behind and cannot race a later rebind.
  • REST and MCP run as supervised sibling tasks. An unexpected error or clean task exit stops the sibling, preserves the original failure as the root cause, and publishes failed runtime health; the TUI, GPUI, and Bevy frontends observe that health and terminate with the same root failure. Graceful shutdown joins both tasks and releases both listeners.
  • That supervision guarantee covers ordinary returned errors and task exits. Debug/test builds use unwinding boundaries to exercise panic reporting, while the shipped panic = "abort" release profile intentionally cannot recover from a panic or promise destructor-based cleanup after one.
  • Frontends do not query FrankenSQLite or wait on a storage mutex during paint. The app transfers the scientific world to HostThread; TUI, GPUI, Bevy, and live server transports use ports to that same owner. Both GPUI windows are presentation-only projections, and repaint cadence does not drive scientific ticks. Host lifecycle publications distinguish recoverable blockers, terminal faults, and completed shutdown. The obsolete GPUI science driver has been removed; its boundary-failure tests now exercise HostCore. Scheduled scenario patches use that owner during bootstrap and interactive execution. The bd-pcfj cutover is closed; broader client interaction, lifecycle and native qualification remain with their open frontend/runtime acceptance owners.
  • scriptbots-runtime owns the renderer-neutral command, two-axis status, snapshot, event-cursor, and manual-drive contracts plus the exact sole-owner HostCore. Command lifecycle schema v1 retains the exact envelope, client namespace/sequence, optional admission order, typed control/scientific/config guards, and contiguous application transitions; every terminal runtime outcome has a journal obligation. Its optional native-asupersync feature drives that same !Send host as one current-thread root future at absolute deadlines. Commands and journal-ready signals wake the owner, catch-up is bounded and reported, quiescent paused worlds have no periodic timer, and ordered shutdown retains its exact host and journal obligations without spawning or detaching a simulation task. The lifecycle persistence work is bd-2z0.5.2 (closed).
  • Brain introspection is an explicit read-only projection, never a per-tick side effect. A client issues a revisioned request for up to eight stable AgentUid values; core and each brain family enforce independent bounds for layers, names, values, edges, source scalars, and retained payload. Responses carry the exact source tick and typed unavailable/clipped status, while TUI and GPUI cache by client, stable identity, and source tick. With no request, no brain is inspected and NeuroFlow performs no inspection JSON serialization; digest-neutrality and next-output purity are tested across the supported families.
  • Assembly arithmetic can overflow during valid execution. Its protocol adapter discards that candidate state; the world supplies zero actions for the containment tick and schedules the agent for normal death cleanup. The death records the failing cell and exact float bits; analytics shows a separate Brain fault cause. Healthy agents continue, while malformed inputs, corrupt envelopes, missing evaluators, and other protocol errors still stop the world. This policy is part of Assembly adapter semantic identity v4; the interpreter arithmetic and genome/state codecs are unchanged.
  • Control surfaces are transport-agnostic; both REST and MCP use the same safe ControlHandle and enqueue commands with back-pressure.

Crate roles

  • scriptbots-core: Simulation core with WorldState, AgentState, deterministic staged tick pipeline, config, sensor/actuation scaffolding, and brain registry bindings.
  • scriptbots-runtime: Renderer-neutral command, immutable lifecycle evidence, two-axis status, snapshot, and event-cursor contracts with typed revision domains; the sole-owner HostCore; a pure injected-time fixed-deadline adapter; and an optional Asupersync =0.5.0 native lifecycle (migration validation pending). It depends on core but not storage, servers, or renderers. The default and WASM-facing surface remains runtime-neutral; Asupersync is activated only by native-asupersync on native targets.
  • scriptbots-brain: Brain trait + baseline implementations and adapters; experimental assembly behind a feature.
  • scriptbots-brain-ml: Feature-gated Candle tensor inference and the retained ml.placeholder sensor-copy fallback for Tract and no-backend builds, plus the non-default code-first Frankentorch FtBrain family. Candle is not registered as a production heritable family. FtBrain is wired under brain-ft; its pinned DSR compile, determinism, and benchmark proof remains pending under bd-2z0.3.12.3.
  • scriptbots-brain-neuro: Optional NeuroFlow-based brain; controllable at runtime via config/env (see below).
  • scriptbots-index: Production uniform-grid neighborhood index. Alternate backends are not advertised until they have real implementations and conformance coverage.
  • scriptbots-storage: FrankenSQLite persistence with transactional batched writes, bounded admission, explicit flush/shutdown commit receipts, and immutable latest-value analytics snapshots for frontends.
  • scriptbots-render: GPUI UI layer with a tiled World + Lab shell, canvas renderer for agents/food, selection highlights, tabbed inspection/analytics, and scrollable diagnostics.
  • scriptbots-world-gfx: Low-level wgpu custom world renderer with WGSL shaders and offscreen readback.
  • scriptbots-bevy: Bevy ECS alternative rendering backend, 3D world visualization, camera systems, and adaptive quality governor.
  • scriptbots-app: Binary shell. Wires tracing/logging, config/env and storage, installs brains, seeds agents, starts the sole-owner HostThread, and connects the selected renderer and REST/MCP servers to its ports.
  • scriptbots-web: WebAssembly harness exposing bindings to init/tick/reset and snapshot the simulation; consumes scriptbots-core with default-features = false (sequential fallback; Rayon disabled on wasm).
  • scriptbots-analytics: Offline analysis, statistical rigor (bootstrap, permutation tests, effect sizes, Jarque-Bera normality), and report generators (sb-analyze).

Current status

  • Workspace scaffolding, shared lints, and profiles are in place.
  • scriptbots-core: World state, agent runtime, staged tick, reproduction/combat hooks, history summaries, and brain registry integration are implemented; parity tasks are tracked in the plan doc.
  • scriptbots-runtime: the protocol boundary, typed command/revision/status domains, schema-v1 lifecycle evidence, opaque client ports, cursors, manual-drive contract, sole-owner HostCore, pure fixed-deadline driver, and optional current-thread Asupersync lifecycle are implemented. The app uses HostCore through its owner thread and channel ports. The bd-2z0.5.2 lifecycle work and the bd-pcfj frontend cutover are closed.
  • scriptbots-render: GPUI World + tabbed Lab windows with camera controls, selection highlights, scrollable diagnostics, and optional kira audio.
  • scriptbots-app: explicit renderer selection, pre-storage control-socket reservation, supervised REST/MCP lifecycle, and frontend health propagation are implemented. The original Phase 0.4 startup matrix passed at its July revisions; that historical result does not qualify every current frontend, feature and platform combination.
  • Interactive terminal mode now runs the pinned FrankenTUI Program with the actual simulation owner and shared control services. It preserves the existing map and inspector widgets and adds live lineage, brain-arena, experiment, replay, environment and diagnostic views. Own commands and checkpoints require successful Pending presentation before dispatch and exact final-result presentation before the next request; checkpoint details survive reduced rendering and queued input. Native acceptance remains open under bd-2z0.6.8 and bd-dkd9. Scoped source and real-PTY observations are retained separately from containing DSR collection failures. Complete capability, input-storm and supported-platform qualification remains pending. See the current implementation and TODO for exact revisions, retained evidence and remaining qualification.
  • scriptbots-brain: MLP and DWRAON implementations are enabled by default; Assembly remains experimental; registry wiring is present.
  • scriptbots-brain-neuro: NeuroFlow-backed brain available behind the neuro feature (runtime toggles below).
  • scriptbots-storage: the exact FrankenSQLite source is pinned; its bounded worker now has a file-backed durable outbox, stable per-batch identities, monotonic admitted/applied/durable watermarks, ordered startup recovery, controller wait deadlines, supervised worker ownership, exact recovery identity/schema proof, and a V6 run-scoped base schema with V7 canonical host archives. Code-first V8 domain-event and V9 command-lifecycle projections are committed under bd-2z0.5.2, with centralized DSR proof pending. Same-thread writes use the same outbox protocol, and terminal receipt/join errors preserve one exact typed root cause. Pairwise combat and food-share edges are projected into indexed SQL with stable UIDs, bounded window sampling, and persisted completeness counters. Deadlines do not cancel an in-flight database call or bound the supervised reaper. Hard-bounded SQL reads are refused before opening the database; frontends use immutable analytics snapshots, while offline/reporting SQL uses the synchronous, create-free, read-only StorageReader with explicitly unbounded execution. Strict-run host policy and product checkpoint/replay integration remain open. Run bundles are implemented: RunBundleV1 (scriptbots.run-bundle.v1) with bundle::create_run_bundle, create_run_bundle_from_artifacts, and verify_run_bundle, surfaced as --create-bundle/--bundle-output and --verify-bundle; the two competing implementations were converged under bd-4d9j.

See the active recovery roadmap in PLAN_TO_REARCHITECT_AND_REVIVE_RUST_SCRIPTBOTS.md for staged milestones and acceptance gates. The older GPUI port plan is historical evidence, not current policy.

Getting started

Prerequisites

  • Rust toolchain: nightly-2026-08-31, pinned in rust-toolchain.toml; the workspace and locked dependency graph declare a minimum Rust version of 1.89. Install through rustup.
  • OS: Linux, macOS, or Windows 11 (native or WSL2). GPU drivers should be up to date for best GPUI performance (wgpu backends: Metal/macOS, Vulkan/Linux, D3D12 or Vulkan/Windows).

Build

cargo check

CPU tuning note: Workspace builds now default to a portable baseline so CI runners don’t require AVX2/“native” features. Set RUSTFLAGS="-C target-cpu=native" locally (all launch scripts already do this) if you want host-specific tuning.

Run the app shell

cargo run -p scriptbots-app

Recommended defaults for performance

  • Storage: --storage memory is only suitable for short runs. With the pinned FrankenSQLite, an in-memory commit costs time proportional to the whole database (measured 2026-09-24: 0.5 ms at 100 journal rows, 18.6 ms at 1,600), and the host journal commits once per batch, so a long --mode server --storage memory run slows to under one tick per second and eventually hits the 120 s admission deadline (bd-kgob, bd-w1oi). The default --storage file does not show that growth. File-mode runs used to stall because FrankenSQLite spawned one OS thread per file I/O when driven without an asupersync context; the storage crate now runs that I/O inline on its blocking threads (measured under heavy host load: ~0.6–4 ms per statement/commit instead of ~0.5–0.9 s), so file-backed servers make steady progress. Server throughput is still bounded by one host-journal commit per tick (bd-w1oi).
  • Threads: By default, the core auto-budgets worker threads conservatively. Our profiling shows best throughput at 8 threads on a 32-core CPU for this workload. To match that:
SCRIPTBOTS_MAX_THREADS=8 cargo run -p scriptbots-app -- --storage file --storage-thresholds 128,4096,1024,1024
  • With servers disabled (avoid port conflicts/background overhead):
SCRIPTBOTS_CONTROL_REST_ENABLED=false \
SCRIPTBOTS_CONTROL_MCP=disabled \
SCRIPTBOTS_MAX_THREADS=8 \
cargo run -p scriptbots-app -- --mode terminal --storage file --storage-thresholds 128,4096,1024,1024
  • Profiling helpers (headless):
# No storage (isolates world.step performance)
SCRIPTBOTS_MAX_THREADS=8 cargo run -p scriptbots-app -- --profile-steps 1000

# With storage (memory) and tuned flush thresholds
SCRIPTBOTS_MAX_THREADS=8 cargo run -p scriptbots-app -- --profile-storage-steps 3000 --storage memory --storage-thresholds 128,4096,1024,1024

Set logging verbosity with RUST_LOG, for example:

RUST_LOG=info cargo run -p scriptbots-app

Terminal-only mode

  • Start the interactive terminal laboratory:

    SCRIPTBOTS_MODE=terminal cargo run -p scriptbots-app
  • Use 4–9 for Lineages, Brain Arena, Experiments, Replay, Environment and Diagnostics; the map, inspector, command palette, help and screenshot controls remain available. Command and checkpoint requests wait for their complete pending identity to be presented before dispatch. Ctrl+R retries an ambiguously admitted command using its exact original envelope; application and journal durability are shown separately. Under render pressure, the runtime may select a labeled reduced-detail view. These paths are implemented; their current native and cross-platform qualification is tracked in the linked reality check.

  • In Experiments (6), select a variant row and press Enter to pin it as the baseline, then select a different variant and press C to compare their verified final populations across matched seeds. Without a pinned baseline, C compares the selected variant with the next distinct variant, skipping its other seed rows. The result shows the endpoint tick, paired sample count, challenger-minus-baseline difference, available 95% interval and paired statistical evidence. A single seed is descriptive only; undefined effect sizes remain unavailable. Verification and analysis run in the background; x, Escape or navigation discards a pending result. Live simulation controls continue to address the live owner.

  • In Replay (7), press K to save a checkpoint and use Up/Down to select a catalog row. It shows that saved cut's population and first twelve characters of its WorldDigestV1, separately from the live tick and artifact checksums. The full selected checkpoint ID appears below the comparison section; table IDs are shortened to keep measured columns visible in an 80-column terminal. REST/MCP checkpoint metadata carries agent_count and the full world_digest_v1. These values describe the saved cut even after the world advances or an identical capture request is retried. Viewing the catalog neither executes replay nor verifies determinism; no-comparison status remains explicit. Press Enter to inspect the selected saved cut on the World canvas; the retained artifact's checksums, reconstructed scientific digest, saved tick and population must agree before it is shown. Loading runs in the background; x, navigation or selection changes discard a pending result, and g returns to the live canvas. Live controls and status continue to address the live owner. This exact-cut review supports current application brain registries; custom registries and general recorded-input event replay remain outside it. The canvas labels reconstructed checkpoint state separately from cached frames: original arena handles, per-tick activity counts and presentation history are not restored. Narrative v first uses an exact cached frame. Outside that cache it can reconstruct from a newly saved checkpoint across simulation ticks and configuration edits. Save a checkpoint before the event you want to revisit. Edits require their complete ordered published audit and run at their recorded completed-tick boundaries. For ticks after the saved cut, the target includes config edits at that tick through the captured current revision. Selecting the saved tick itself shows that saved cut. This does not recover the event's original within-tick publication. Pruned audit history and persistence-interval changes refuse review. Persistence stays disabled in the reconstructed world. The complete verification interval is limited to 1,024 ticks. Completed configuration schedules also require an unchanged declaration and the complete ordered successful committed outcome history; future, incomplete, failed or pruned schedules refuse review. Empty installed queues are supported. It checks the reconstructed current digest before showing the requested event as CHECKPOINT REPLAY; g returns live. Agent spawns, manual crossovers, mutation-rate edits and self-contained interventions also have an implemented replay path, including mixed configuration edits at the same tick. The live owner's complete command history and each command's observed configuration revision preserve execution order. Intervention effects use the ordinary core queue and apply at the next science tick; target-boundary inputs are reconstructed after the complete current-digest check. The retained history obeys both the owner entry limit and a 1 MiB entry/payload budget; container spare slots have a separate entry bound. Oversized inputs still execute but leave a revision gap, so review refuses an incomplete interval. This history is volatile; eviction or host restore without the required inputs also refuses review. Archive resurrection requires a source-bound behavioral archive, which the saved science checkpoint does not carry. It, map replacements and migrations remain outside this replay path. Native qualification status is recorded in the reality check. Loading, duplicate bounds, cancellation and stale selection checks use the same worker slot as direct checkpoint review. Live controls continue to address the owner. Native-window/PTY and full DSR acceptance remain open.

  • Auto selection: SCRIPTBOTS_MODE=auto (default) chooses only a renderer compiled into the binary—GPUI first, then Bevy—and only in a real native graphical session; otherwise it uses the terminal. Linux/Unix sessions require a display environment; local macOS sessions use the native window system without X11 variables, while SSH sessions choose the terminal.

  • Auto-mode policy overrides:

    • SCRIPTBOTS_FORCE_TERMINAL=1 → choose terminal in Auto mode even when a display server is present.
    • SCRIPTBOTS_FORCE_GUI=1 → require compiled GPUI in Auto mode even if no display variables are set; unavailable features and launch failures are errors, never terminal fallbacks.
  • CI/headless smoke runs can bypass raw TTY requirements by setting SCRIPTBOTS_TERMINAL_HEADLESS=1, which drives the renderer against an in-memory buffer for a few frames.

  • Emoji mode (terminal renderer):

    • Defaults ON when a modern UTF‑8 terminal is detected; press e to toggle at runtime.
    • Force enable via env: SCRIPTBOTS_TERMINAL_EMOJI=1|true|yes|on; force disable with 0|false|off|no.
    • Heuristic: enabled if TERM is not dumb/linux/vt100, locale contains utf-8|utf8, and CI is unset.
    • Emoji mappings: terrain 🌊/💧/🏜/🌿/🌺/🪨 (lush swaps: 🐟, 🌴, 🌾, barren 🥀); agents single 🐇/🦝/🦊, small groups 🐑/🐻/🐺, large cluster 👥, boosted 🚀, spike peak ⚔ (underline). Heading arrows remain for single agents when available.
    • If emojis render as tofu/misaligned, install an emoji-capable font (e.g., Noto Color Emoji) or toggle off with e.
  • Narrow symbols mode: press n to switch to width-1 friendly symbols while keeping emoji colors off-background; helpful for strict terminals/alignment.

  • Headless report (CI-friendly):

    SCRIPTBOTS_MODE=terminal \
    SCRIPTBOTS_TERMINAL_HEADLESS=1 \
    SCRIPTBOTS_TERMINAL_HEADLESS_FRAMES=24 \
    SCRIPTBOTS_TERMINAL_HEADLESS_REPORT=terminal_report.json \
    cargo run -p scriptbots-app -- --storage memory --threads 2

    This renders offscreen for N frames and writes a JSON summary (frames, ticks, births/deaths, energy stats) to terminal_report.json. The top-level schema is "scriptbots.terminal-headless.v1"; check it before interpreting or comparing reports. scenario.schema_version describes the scenario inputs and does not identify the report format. V1 keeps the existing scenario, initial, frames, summary, narrative_events and narrative_dropped_events fields. Each rendered frame's buffer records its backend, capability profile, viewport, tick, cell counts, full-cell FNV-1a64 digest and layout-derived region evidence; the initial observation has no rendered buffer. Older reports omitted the top-level tag. They are unversioned evidence, and their scenario version must not be interpreted as report V1.

Quick start (platform scripts)

Use the convenience scripts in the repo root to launch ScriptBots with sensible defaults per OS. These scripts set appropriate targets, isolate build artifacts, and pick the right renderer.

Linux — terminal mode

  • Script: run_linux_terminal_mode.sh
  • Usage:
    chmod +x ./run_linux_terminal_mode.sh
    ./run_linux_terminal_mode.sh
  • What it does:
    • Detects CPU count into THREADS (nproc/getconf fallback; override by exporting THREADS beforehand)
    • Builds with native CPU optimizations (RUSTFLAGS="-C target-cpu=native")
    • Forces terminal renderer (SCRIPTBOTS_MODE=terminal)
    • Runs release binary with cargo job parallelism -j $THREADS and passes --threads $THREADS to the app
  • Customize:
    • Reduce CPU usage: THREADS=2 ./run_linux_terminal_mode.sh
    • Headless CI snapshot: export SCRIPTBOTS_TERMINAL_HEADLESS=1 to render against an in-memory buffer
    • Logging: RUST_LOG=info ./run_linux_terminal_mode.sh

Linux — Bevy renderer (Vulkan/GL)

  • Script: run_linux_with_bevy.sh
  • Usage:
    chmod +x ./run_linux_with_bevy.sh
    ./run_linux_with_bevy.sh
  • What it does:
    • Detects CPU count (caps default at 8) and passes the value to cargo (-j) and the app (--threads)
    • Prefers Vulkan via WGPU_BACKEND=vulkan, falling back to GL when Vulkan is unavailable
    • Enables the Bevy renderer (--features bevy_render) and launches with --mode bevy
    • Sets high-performance WGPU hints (SB_WGPU_PRESENT_MODE=full, bloom/tonemap/fog defaults) matching the Windows helper
  • Customize:
    • Limit load: THREADS=4 ./run_linux_with_bevy.sh
    • Force GL: WGPU_BACKEND=gl ./run_linux_with_bevy.sh
    • Append extra flags after the final -- (e.g., ./run_linux_with_bevy.sh -- --debug-watermark)

macOS — terminal console

  • Script: run_macos_version_with_console.sh
  • Usage:
    chmod +x ./run_macos_version_with_console.sh
    ./run_macos_version_with_console.sh
  • What it does:
    • Detects arch (arm64 vs x86_64) and sets --target accordingly
    • Isolates artifacts per-arch via CARGO_TARGET_DIR=target-macos-$ARCH
    • Unsets any stray cross-compile/link flags for a clean native build
    • Uses all cores for build jobs and launches the app in terminal mode (--mode terminal)
  • Customize:
    • Add app flags by appending to the final -- ... section (e.g., --threads 8)
    • Override logging: RUST_LOG=info ./run_macos_version_with_console.sh

macOS — GPU GUI (Metal)

  • Script: run_macos_version_with_gui.sh
  • Usage:
    chmod +x ./run_macos_version_with_gui.sh
    ./run_macos_version_with_gui.sh
  • What it does:
    • Same target/artifact isolation as console script
    • Prefers Metal backend for wgpu (WGPU_BACKEND=metal)
    • Builds with --features gui and launches GUI mode (--mode gui) using --threads 8
  • Customize:
    • Tune threads: edit --threads 8 or set SCRIPTBOTS_MAX_THREADS env
    • Troubleshoot rendering: you can add --renderer-safe to the app args if you see a black canvas

macOS — Bevy renderer (Metal)

  • Script: run_macos_version_with_bevy.sh
  • Usage:
    chmod +x ./run_macos_version_with_bevy.sh
    ./run_macos_version_with_bevy.sh
  • What it does:
    • Selects the correct target triple (aarch64-apple-darwin on Apple Silicon, x86_64-apple-darwin otherwise)
    • Isolates build artifacts per-arch and clears stray cross-compilation flags
    • Forces the Metal backend, high-performance power preference, and Bevy feature flag (--features bevy_render)
    • Launches ScriptBots with --mode bevy and a default 8-thread budget (override with THREADS env)
  • Customize:
    • Retina tweaks: set SB_WGPU_RES_SCALE to 0.5 or 2.0 before running
    • Lower CPU use: THREADS=4 ./run_macos_version_with_bevy.sh
    • Add Bevy-specific CLI flags after --, e.g., ./run_macos_version_with_bevy.sh -- --dump-semantic-png docs/rendering_reference/golden/bevy_default.png (CPU semantic raster; for real offscreen GPU captures use --dump-scene-png SCENE.toml)

Windows — terminal console (MSVC)

  • Script: run_windows_version_with_console.bat
  • Usage:
    • Double-click in Explorer, or run from a Developer PowerShell/Command Prompt:
      run_windows_version_with_console.bat
  • What it does:
    • Uses MSVC target x86_64-pc-windows-msvc
    • Isolates artifacts under target-windows-msvc
    • Uses all cores for build jobs and launches terminal mode (--mode terminal)
  • Prereqs:
    • Rust MSVC toolchain and Visual Studio Build Tools (Windows 11 SDK) installed

Windows — GPU GUI (D3D12/Vulkan)

  • Script: run_windows_version_with_gui.bat
  • Usage:
    • Double-click in Explorer, or run from a Developer PowerShell/Command Prompt:
      run_windows_version_with_gui.bat
  • What it does:
    • Same MSVC target/artifact isolation as console script
    • Builds with --features gui and launches GUI mode (--mode gui) using --threads 8
  • Customize:
    • Adjust threads by editing the --threads value; add app flags after -- as needed (e.g., --debug-watermark)

Windows — Bevy renderer (Vulkan/D3D12)

  • Script: run_windows_version_with_bevy.bat
  • Usage:
    • Double-click in Explorer, or run from a Developer PowerShell/Command Prompt:
      run_windows_version_with_bevy.bat
  • What it does:
    • Reuses the MSVC target (x86_64-pc-windows-msvc) with isolated artifacts under target-windows-msvc
    • Sets high-performance WGPU hints (WGPU_BACKEND=Vulkan, WGPU_POWER_PREFERENCE=high_performance)
    • Builds with --features bevy_render and launches the Bevy renderer (--mode bevy) using --threads 8
  • Customize:
    • To force D3D12 instead of Vulkan: set set WGPU_BACKEND=d3d12 before running
    • Add Bevy-only flags (e.g., --dump-semantic-png, --dump-scene-png) after the final -- in the script

Notes (all platforms):

  • The final -- ... segment in each script passes flags to the application binary. You can add flags like --storage memory, --profile-steps 1000, or --det-check 200 there.
  • To stream control API docs, ensure REST is enabled (default) and open http://127.0.0.1:8088/docs while the app runs.

Build for Web (experimental)

rustup target add wasm32-unknown-unknown
cargo check --target wasm32-unknown-unknown -p scriptbots-web

Windows quickstart (native)

  1. Install Rust (MSVC toolchain):
    • Download rustup-init.exe and select the MSVC target, or run in PowerShell:
    rustup toolchain install nightly-2026-08-31 --profile minimal
    rustup component add --toolchain nightly-2026-08-31 clippy rustfmt
  2. Install Visual Studio Build Tools (2022+):
    • Select the "Desktop development with C++" workload (includes MSVC, Windows 10/11 SDK).
  3. Update GPU drivers (NVIDIA/AMD/Intel) to latest. Ensure D3D12 is available; Vulkan runtime optional.
  4. Build and run:
    cargo run -p scriptbots-app
  5. Troubleshooting: If linking fails with MSVC or SDK errors, re-run the VS installer to include the Windows 11 SDK and C++ toolset (v143+).

Windows via WSL2 (optional)

  • Windows 11 with WSLg supports Linux GUI apps out of the box; GPUI rendering generally works, but performance may vary. If you see blank windows, update your GPU drivers and WSL kernel, then retry.

Feature flags & variants

  • scriptbots-app features:
    • ml → enable scriptbots-brain-ml
    • brain-ft → propagate the non-default pinned Frankentorch dependencies and code-first FtBrain family through scriptbots-brain-ml
    • neuro → enable scriptbots-brain-neuro
    • fast-alloc → enable mimalloc as the global allocator for improved multithreaded performance
    • Example: cargo run -p scriptbots-app --features neuro
    • Frankentorch compile, determinism, and benchmark acceptance is DSR-only through the pinned rust_scriptbots profile; GitHub Actions and direct Cargo invocations are not acceptance evidence.
    • Note: default features enable ml, neuro, and fast-alloc. To disable defaults, use --no-default-features and opt-in explicitly.
  • scriptbots-render:
    • audio → enable Kira-driven audio in the UI layer
  • scriptbots-index: the uniform-grid backend is unconditional; there are no backend-selection feature flags.
  • scriptbots-brain-ml:
    • candle enables real tensor forward/batch inference, without production heritable-family registration.
    • tract and no-backend builds retain the sensor-copy ml.placeholder fallback.
    • brain-ft exposes FtBrainConfig, FtBrainFamily, and FT_BRAIN_KIND.
    • FtBrain also exposes architecture-scoped canonical bias, weight and source-target loci to shared heredity/genome inspection. Activity inspection reconstructs the exact feed-forward computation from recorded owner inputs and verifies recorded output bits; its provenance explicitly says reconstructed. Unrecorded/indistinguishable-zero or mismatched observations are typed unavailable results. Producer work and retained graphs are bounded, and clipped weights remain visible without claiming a complete input explanation. Genome/state codecs and the adapter identity are unchanged. The exact libraries and Ft test source passed a pinned DSR type check; executable regressions remain unqualified because code generation hit the host memory limit.
    • FtBrain cohorts retain distinct weights for every agent and evaluate one packed F32 batched matrix contraction per layer. Core retains successful cohort evaluators across ticks while the exact factory, architecture, ordered stable identities, genomes/provenance and scalar checkpoints still match. This preserves packed weights and scratch between ticks. Membership changes or failures evict cached evaluators; checkpoints and scientific digests omit this execution cache. Scalar preimages and complete successor reconstruction still enforce atomic rejection, so this is not an end-to-end throughput claim. Adapter semantic version 3 identifies the packed executor; canonical genome and evaluator-state codecs are unchanged. Targeted DSR checks cover eight evolving scalar/cohort stages with one cohort construction, mutation/rebind/factory invalidation, warmed failure rollback and checkpoint continuation, plus the scalar-only feature lane.
    • The pinned Frankentorch vector_to_parameters path is not F32-safe, so FtBrain keeps a canonical flat F32 genome and materializes its layer slices without widening through F64. Resolution of that upstream gap and full benchmark qualification remain part of bd-2z0.3.12.3.

Note: NeuroFlow and the native brain implementations are functional. Candle has real library inference; Tract inference and alternate spatial-index backends remain unimplemented. The ML disposition keeps placeholders out of production populations and selects FtBrain as the app-level ML family. FtBrain has real code-first inference, but is not accepted as complete until its pinned DSR evidence is green.

NeuroFlow runtime configuration (optional)

If built with the neuro feature, runtime toggles can be applied via env vars before launch:

SCRIPTBOTS_NEUROFLOW_ENABLED=true \
SCRIPTBOTS_NEUROFLOW_HIDDEN="64,32,16" \
SCRIPTBOTS_NEUROFLOW_ACTIVATION=relu \
cargo run -p scriptbots-app --features neuro

Valid activations: tanh, sigmoid, relu.

Commands cheat sheet

# Build the whole workspace
cargo build --workspace

# Run the UI shell
cargo run -p scriptbots-app

# Lint and format
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all

# Run tests (as they land)
cargo test --workspace

# Build optional crates with features
cargo build -p scriptbots-brain-ml --features candle # library tensor inference; not a production family preset

Command-line options (scriptbots-app)

  • --mode {auto|gui|bevy|terminal|server}: select the frontend, or run the control servers without a renderer. Defaults to auto and can be set via SCRIPTBOTS_MODE.

    • auto: choose GPUI, then Bevy, only when that backend is compiled and a real native graphical session is available; otherwise use the terminal.
    • gui: require GPUI; an uncompiled feature or native window launch failure is returned to the caller.
    • bevy: require the Bevy frontend and fail clearly unless built with the bevy_render application feature.
    • terminal: force emoji TUI.
  • --bootstrap-ticks N: explicitly run N science ticks after seeding and before frontend launch (default 0, so ordinary startup launches at tick zero).

  • --checkpoint-handoff CHECKPOINT_ID: after explicit bootstrap, save a paused owner checkpoint and retire the owner without closing its host session. Requires --storage file. This bounded continuation candidate still has open native qualification under bd-2z0.5.13.

  • --continue-host-db FILE --host-checkpoint-id CHECKPOINT_ID --continue-ticks N: restore that exact handoff, advance a positive number of ticks, and hand off again in the same run and session. Supply the original --brain preset; the prepared executable registry must match the checkpoint. Configuration overrides and frontend options are refused rather than silently replacing saved state. The JSON result names the new checkpoint and observed admitted/applied/durable watermarks.

  • --compare-host-db EXPECTED --compare-host-checkpoint-id ID --host-candidate-db ACTUAL --host-candidate-checkpoint-id ID: compare two settled full-host artifacts at the same tick. Requires complete retained tick-one-to-boundary stage traces and covered brain state. It reports the first observed divergent tick/stage and both artifact identities; divergence exits nonzero.

  • --checkpoint-interval TICKS: record a WorldCheckpointV1 plus a replay digest into the run database every TICKS ticks of an interactive run (default 1000; 0 disables; env SCRIPTBOTS_CHECKPOINT_INTERVAL). --replay-db FILE --checkpoint-start later verifies the run from the latest one.

  • --checkpoint-max-count COUNT and --checkpoint-max-bytes BYTES: retention limits (defaults 256 and 268435456; env SCRIPTBOTS_CHECKPOINT_MAX_COUNT / SCRIPTBOTS_CHECKPOINT_MAX_BYTES). Every producer shares the storage owner's per-run and whole-database limits. SQL bytes include hexadecimal payloads and UTF-8 metadata. API artifact files have a separate budget with the same limits; downloads read through files without retaining a payload cache. Zero refuses new captures. Existing checkpoints remain intact, and exact retries reuse their row and file. Optional interval capture disables itself on quota exhaustion while science and controls continue.

  • --dump-png <FILE> (GUI builds): write an offscreen PNG and exit (no UI). Pair with --png-size WxH.

  • --png-size WxH (GUI builds): snapshot size for --dump-png (e.g., 1280x720).

  • --debug-watermark: overlay a tiny diagnostics watermark in the render canvas.

  • --renderer-safe: force a conservative paint path (useful for troubleshooting black canvas on some Windows setups).

  • --threads N: cap simulation worker threads with a positive budget (overrides inherited Rayon and low-power defaults).

  • --low-power: prefer lower CPU usage (equivalent to --threads 2 unless --threads is provided); also biases auto toward terminal.

  • --profile-steps N: headless world.step() profiling without persistence.

  • --profile-storage-steps N: headless profiling with selected storage mode.

  • --storage-thresholds t,a,e,m: override flush thresholds (tick, agent, event, metric).

  • --profile-sweep N: run a sweep of configurations for profiling and print a summary.

  • --auto-tune N: quick sweep to pick threads/thresholds for the chosen storage, then continue.

  • --det-check N: run determinism self-check (1-thread vs N-threads summaries comparison).

  • --run-archipelago N --archipelago-db FILE --archipelago-ticks TICKS: record bounded populations through sole-owner hosts in one new database. Requires an explicit rng_seed and persistence_interval=1. Islands step in ascending order with separate derived seeds; the inner Rayon pool defaults to one thread and honors --threads. Each complete tick is atomically applied and flushed before the next tick begins. Genomes, narrative records, interaction edges, and lineage edges retain island IDs; genome read APIs require an explicit island, and narrative search results include it in each event identity. Existing single-population interaction graph readers and table exports refuse multi-island runs; use report-archipelago or explicit island-scoped readers for those databases. Migration is disabled by default. --migration-interval N enables it every N ticks for two or more islands. Optional --migration-emigrants N (default 1), --migration-selection random|fittest|youngest|wanderer (default fittest) and --migration-topology ring|fully-connected (default ring) use the existing deterministic runtime policy. Connectivity is bidirectional: each ring connection permits movement in both directions. Actual moves and all island science are persisted in the same complete-barrier transaction; the manifest records the exact policy. Tick summaries describe the tick before migration; final membership and world digests describe the state after migration. Result fields label these phases and report the number of moves persisted, which can be zero if no migration falls within the run. This mode currently has no scheduled interventions, bootstrap, or host-session checkpoint resume. The JSON result reports the observed durability watermarks. The manifest's archipelago extension records all island configs and the common root seed; its ordinary world fields describe island zero. For example:

    cargo run -p scriptbots-app -- --run-archipelago 3 \
      --archipelago-db runs/islands.sqlite --archipelago-ticks 100 \
      --brain mlp --set rng_seed=42 --set persistence_interval=1
    # Add --migration-interval 25 --migration-selection random for gene flow.
    cargo run -p scriptbots-app -- report-archipelago runs/islands.sqlite \
      --verify-conservation --json runs/islands-report.json
  • --set PATH=VALUE: dotted-path configuration override in TOML syntax, repeatable (e.g., --set world_width=800 --set neuroflow.enabled=true; string values use TOML quotes). Configuration layers apply defaults → --config files (in order) → environment → CLI; every applied layer appends a kind-tagged content digest to the run manifest's scenario.ordered_config_layer_digests, and any field where one explicit layer displaced another is recorded in the manifest's config_overrides.

  • --quality TIER: visual quality shortcut for --set render.quality=TIER, validated at parse time (auto|potato|low|medium|high|ultra). The unified render.* settings (quality tier, post stack bloom/vignette/fog/AA, day/night cycle, TUI theme, accessibility palette) are consumed by every frontend; None values defer to per-tier frontend defaults.

  • --dump-png FILE + --png-size WxH (GUI builds): write an offscreen PNG and exit.

  • --dump-semantic-png FILE (Bevy builds): write the CPU semantic projection raster and exit. This is a semantic reference only — it does NOT exercise the GPU pipeline (formerly --dump-bevy-png, renamed so it can never be mistaken for a GPU capture).

  • --dump-scene-png SCENE.toml (Bevy builds): render a scene manifest through the REAL offscreen Bevy GPU pipeline and write capture PNGs + provenance JSON + a JSON scene log under captures/<scene>/. Golden workflow: RUST_REGEN_GOLDEN=1 blesses new goldens under crates/scriptbots-app/tests/scenes/goldens/<scene>/; an existing golden is compared with per-channel/perceptual thresholds (mismatch writes a <name>.diff.png heatmap and fails); a missing golden is an explicit failure with regeneration instructions, never an auto-bless. SCRIPTBOTS_CAPTURE_CORRUPT=1 binds a nonuniform emissive texture to terrain materials for the alarm test. The background, lights and camera stay unchanged, so the alarm must observe rendered terrain rather than a clear-color swap. Pixel qualification still requires an admissible adapter; software captures remain smoke diagnostics.

  • --storage {file|memory}: select the FrankenSQLite target. file exclusively reserves SCRIPTBOTS_STORAGE_PATH or a fresh generated run path and refuses existing databases or stale sidecars; memory opens volatile :memory: through the same engine.

  • --recover-storage FILE: exclusively reopen a validated existing ScriptBots run, replay/finalize its durable outbox, print the admitted/applied/durable watermarks, and exit. This repairs persistence only; it does not reconstruct the in-memory world or resume simulation ticks.

  • Auto-pause (any renderer):

    • --auto-pause-below COUNT (or SCRIPTBOTS_AUTO_PAUSE_BELOW) pauses when population ≤ COUNT
    • --auto-pause-age-above AGE (or SCRIPTBOTS_AUTO_PAUSE_AGE_ABOVE) pauses when any agent’s age ≥ AGE
    • --auto-pause-on-spike (or SCRIPTBOTS_AUTO_PAUSE_ON_SPIKE=true) pauses on first spike hit event
  • --brain {mixed|mlp|dwraon|assembly|ft|neuro}: select which brain family(ies) to install for the run (default mixed). mixed registers MLP, DWRAON, and Assembly unconditionally; it additionally registers Frankentorch FtBrain only when the binary is built with --features brain-ft, and registers the optional NeuroFlow brain only when built with --features neuro (see SCRIPTBOTS_NEUROFLOW_* below for runtime toggles). mlp, dwraon, and assembly install only that single family. neuro explicitly selects the legacy NeuroFlow runner; registration in mixed does not admit it to mixed founding populations. ft installs only the Frankentorch family and fails closed with a typed error when the brain-ft feature is not enabled — it never silently substitutes another family. The flag is an application-layer CLI choice and is NOT a ScriptBotsConfig field, so --config files and SCRIPTBOTS_CONFIG_OVERRIDES cannot override it; precedence is default → SCRIPTBOTS_BRAIN env var → --brain CLI flag.

Bevy terrain uses the verified canonical biome atlas for roughness detail in both the live renderer and offscreen scene capture. Each chunk selects its most common biome and shares that biome's cached texture; quality changes filter the same 64×64 source grain. Vertex colors still supply terrain hue and accessibility palettes. This detail path does not blend biome albedo textures per pixel.

Bevy creature motion interpolates position, heading and spike extension between two producer-observed scientific snapshots, keyed by stable agent identity. Toroidal crossings take the short path; render timing selects a bounded fraction over the measured publication interval without advancing science or extrapolating. This introduces up to one observed interval of pose presentation delay. Pausing, reduced motion, a changed owner/configuration, rewinds, births and ambiguous teleports use the committed pose immediately. Picking and camera follow use the displayed creature position. The offscreen OffscreenCapture::render_interpolated API accepts an explicit fraction and records both endpoint ticks and science digests; an interpolated image has no single world_digest attribution. It does not certify independently supplied worlds as one replay. Terrain, population and other state cues use the later cut. Ordinary endpoint captures keep their existing contract.

Environment variables (quick reference)

  • RUST_LOG — logging filter (e.g., info, trace, scriptbots_core=debug). Use info,scriptbots_core::parallelism=debug to observe the Rayon pool width inside each actual science step.
  • RAYON_NUM_THREADS — simulation pool default when parallel is enabled and the app resolves no explicit thread budget. The resolved --threads, SCRIPTBOTS_MAX_THREADS, auto-tune or low-power budget takes precedence.
  • SCRIPTBOTS_MODE — auto|gui|bevy|terminal|server (frontend or server-only selection).
  • SCRIPTBOTS_FORCE_TERMINAL / SCRIPTBOTS_FORCE_GUI — override Auto-mode renderer detection (1|true|yes); explicit --mode remains authoritative.
  • SCRIPTBOTS_BOOTSTRAP_TICKS — explicit pre-frontend science ticks (default 0, equivalent to --bootstrap-ticks; set a nonzero value only when an intentional warmup is part of the run).
  • SCRIPTBOTS_TERMINAL_HEADLESS — render TUI to an in-memory buffer for CI smoke tests.
  • SCRIPTBOTS_TERMINAL_HEADLESS_FRAMES — number of frames to render in headless mode (default 12; max 360).
  • SCRIPTBOTS_TERMINAL_HEADLESS_REPORT — file path to write a JSON summary from a headless run. It includes the final observed typed narrative_events ring and its narrative_dropped_events count. The same ring is logged at info level; zero dropped events is required before treating it as the complete run timeline.
  • SCRIPTBOTS_MAX_THREADS — explicit application thread budget, below --threads and above auto-tune or low-power defaults. Startup passes the resolved number directly to Rayon. Standalone core callers retain the physical-CPU-capped default when RAYON_NUM_THREADS is absent; world construction never rewrites either variable. Full-host checkpoint continuation restores the launch manifest's resolved budget, when present, before reconstructing the world. The debug observation reports pool capacity at science-step entry, rather than busy-worker utilization.
  • SCRIPTBOTS_TERMINAL_EMOJI — force emoji mode 1|true|yes|on or disable with 0|false|off|no.
  • SCRIPTBOTS_RENDER_SAFE — force conservative rendering path in GUI mode (also enabled by --renderer-safe or --low-power).
  • SCRIPTBOTS_RENDER_WATERMARK — overlay a tiny diagnostics watermark in the GUI canvas (also enabled by --debug-watermark).
  • SCRIPTBOTS_RENDER_QUALITY — auto|potato|low|medium|high|ultra for render.quality (the --quality CLI flag outranks it).
  • Legacy render knobs SB_WGPU_TONEMAP|EXPOSURE|BLOOM|BLOOM_THRESH|BLOOM_INTENSITY|VIGNETTE|FOG|FOG_COLOR|FXAA and SCRIPTBOTS_TERMINAL_PALETTE are mapped onto the typed render.* schema at startup with one INFO log per applied mapping; the canonical typed SCRIPTBOTS_RENDER_* variables and CLI flags outrank them.
  • --set 'render.post.anti_aliasing="fxaa"' enables edge smoothing in the wgpu world/capture pipeline; use "off" to disable it. The resolved setting overrides the renderer's raw environment fallback; normal startup configuration precedence still applies. Shared quality-tier defaults remain Off. The GPUI CPU canvas does not implement FXAA, and TAA remains unsupported.
  • SCRIPTBOTS_CONFIG_OVERRIDES — inline TOML document merged as the most-general environment configuration layer (e.g., world_width = 1000). Beats --config files, loses to the typed SCRIPTBOTS_* variables and to every CLI flag; malformed content fails startup closed. Each applied layer appends a kind-tagged digest to the manifest, and cross-layer displacements land in the manifest's config_overrides.
  • SCRIPTBOTS_RNG_SEED — environment-layer RNG seed; --rng-seed outranks it as a distinct CLI layer with its own provenance.
  • SCRIPTBOTS_BRAIN — environment-layer brain preset (mixed|mlp|dwraon|assembly|ft|neuro, default mixed); --brain outranks it as a distinct CLI layer. Selecting ft without the brain-ft build feature fails closed at startup; selecting an unknown string fails clap parsing before any storage is reserved.
  • SCRIPTBOTS_NEUROFLOW_ENABLED — true|false.
  • SCRIPTBOTS_NEUROFLOW_HIDDEN — comma-separated hidden sizes (e.g., 64,32,16).
  • SCRIPTBOTS_NEUROFLOW_ACTIVATION — tanh|sigmoid|relu.
  • SCRIPTBOTS_CONTROL_REST_ADDR — REST bind address (default 127.0.0.1:8088).
  • SCRIPTBOTS_CONTROL_SWAGGER_PATH — Swagger UI path (default /docs).
  • SCRIPTBOTS_CONTROL_REST_ENABLED — true|false.
  • SCRIPTBOTS_EXPERIMENT_RUN_SLOTS — shared create/resume run-slot capacity for this control service; defaults to the runner's maximum per-batch concurrency. Zero disables new execution while existing jobs and artifacts remain readable. Invalid values fail startup before storage reservation.
  • SCRIPTBOTS_CONTROL_MCP — disabled|http (default http).
  • SCRIPTBOTS_CONTROL_MCP_HTTP_ADDR — MCP HTTP bind address (default 127.0.0.1:8090).
  • SCRIPTBOTS_CONTROL_ALLOWED_AUTHORITIES — comma-separated additional advertised host:port values for REST and MCP HTTP. By default each listener accepts its actual bound IP/port and, for loopback, localhost at that port. Wildcard binds require explicit advertised authorities; a foreign or wrong-port Host is refused.
  • SCRIPTBOTS_CONTROL_ALLOWED_ORIGINS — comma-separated additional browser origins such as https://lab.example, without credentials, paths or queries. Default browser origins are http:// at the accepted authorities. A missing Origin is allowed for CLI/MCP clients; malformed, duplicate, foreign and null Origins are refused before request bodies or control/artifact work. Allowed origins receive CORS responses for GET/HEAD/POST and supported JSON/MCP headers.
  • The same request policy protects REST, Swagger, streams, WebSocket upgrades and MCP HTTP. Absolute request targets must agree with Host. Forwarded and X-Forwarded-* headers are refused: there is no configured trusted-proxy boundary. These checks validate request targeting and do not authenticate callers; stdio MCP is unchanged.
  • Control-server environment is validated before startup side effects. Malformed or non-Unicode control values fail closed; https:// in either MCP transport/address setting is rejected because the embedded MCP listener is plaintext HTTP rather than silently claiming TLS.
  • SCRIPTBOTS_STORAGE_PATH — optional new-run FrankenSQLite file path. Without it, ScriptBots creates a unique runs/scriptbots-<unix-ms>-<pid>.sqlite. In either case the app reserves the path with create-new semantics and refuses an existing database or stale -wal, -shm, -journal, -wal-fec, or lock sidecar. A cleanly closed run keeps an empty -wal and its -shm beside the database, so remove the database together with its sidecars before reusing a path. The selected path is printed as Run database: ...; save that exact value for later reads and exports.
  • SCRIPTBOTS_RECOVER_STORAGE — existing file-backed run to repair and finalize, equivalent to --recover-storage FILE. Recovery exits after persistence repair; it does not resume the simulation. Run-bundle export/verification and core checkpoint-start replay are separate implemented paths. Full host/session continuation has an implemented bounded CLI candidate whose original qualification remains open under bd-2z0.5.13.

For a deliberate MLP handoff, use a newly chosen database path and an already built scriptbots-app binary:

SCRIPTBOTS_STORAGE_PATH=runs/continued.sqlite scriptbots-app \
  --storage file --brain mlp --threads 1 --bootstrap-ticks 7 \
  --checkpoint-handoff first-cut --set rng_seed=42 \
  --set persistence_interval=1 --set replay_event_tick_cap=65536 \
  --set population_minimum=20 --set food_growth_rate=0.0005
scriptbots-app --continue-host-db runs/continued.sqlite \
  --host-checkpoint-id first-cut --continue-ticks 11 --brain mlp

The second command is a bounded continuation from tick 7 to tick 18. It requires a deliberately handed-off owner and its unchanged science/journal cut; it is not a way to resume an arbitrary interrupted or already shut-down host. Keep the returned checkpoint ID for the next continuation. Opaque factory state, corrupt checkpoints and stale cuts are refused. Ordinary launch manifests retain checkpoint_replay_guarantee=false; the handoff report's scoped guarantee does not discharge the remaining native acceptance.

Source IDs are embedded at build time. RCH's plain hexadecimal commit stamp supplies the revision when SCRIPTBOTS_SOURCE_REVISION was not supplied; explicit ScriptBots identity takes precedence. Unknown, dirty and overlay RCH stamps leave that fallback unavailable. Runtime environment changes cannot replace the embedded identity. A known commit still requires separate verified clean-tree, status/diff and compiler evidence before the manifest can report complete build provenance and reproducibility. Normal Cargo builds capture the full selected compiler identity and the executable's resolved target at build time. The compiler host and executable target are recorded separately, including when cross-compiling. A reviewed SCRIPTBOTS_RUSTC_VV build stamp takes precedence over automatic compiler capture; launch-time environment changes cannot replace either captured fact. Missing target evidence cannot support a complete provenance claim, and missing source/cleanliness evidence remains unknown.

--create-bundle RUN_DB --bundle-output DIRECTORY exports a finished, checkpointed database under its existing writer/path/identity lease. The destination must be new. Live writers, unfinished persistence, nonempty WAL/journal files and changed/aliased source paths are refused; export does not checkpoint or rewrite the source. The copied database is independently opened and compared with the manifest, events, checkpoints, maximum tick and persistence watermarks before the final bundle manifest is written. --verify-bundle DIRECTORY repeats those logical checks alongside artifact hashes. For matched-seed experiment bundles it also restores the included final HostCore checkpoint and compares the actual scientific digest, population and complete V2 endpoint summary with the reports. The printed Scientific final state line names the observed digest and population; renaming or moving the bundle does not require its external continuation file or status. This checks the saved result, not the whole cohort plan or source authenticity, and does not promote incomplete build provenance to reproducibility. Database-free experiment bundles report zero database-persisted events/checkpoints even though their final owner cut is included. A failed export retains partial files without a success manifest.

Dual-window mode (GUI)

  • ScriptBots opens two GPUI windows as one transactional launch and tiles them inside the primary display's visible frame: a flexible World window and a narrow ScriptBots Lab companion. The Lab's Overview, Inspect, Analytics, Timeline, Experiments, Checkpoints and Maps tabs keep one task-focused surface visible at a time, with dense diagnostics closed by default and the active section vertically scrollable. On narrow displays the pair stacks without overlap. This is the optional GPUI route, built with --features gui and selected with --mode gui.
  • Display-local controls—agents, food, outlines, follow, camera fit, zoom, pan, debug overlays, palette, narration, and settings—stay in the World window they affect. Shared run controls—pause, step, speed, spawning, environment, and presets—live in the Lab. If either window cannot be created (for example because of window-manager or remote-session limits), ScriptBots terminates the partial application lifetime and returns an actionable error; it never silently changes the requested layout. GPUI uses QuitMode::LastWindowClosed, and closing either member of the pair closes the application rather than leaving an orphaned window or hidden process.
  • Both GPUI windows read immutable publications from the same HostCore on the application owner thread. Run controls submit commands to that owner; painting and window refresh rates do not advance scientific time.
  • Experiments lists retained batches in pages of 12. Select one to see completed, running and failed counts for every variant, stop active execution or resume unfinished runs. Catalog and active-batch observations refresh every two seconds; manual Refresh is also available. Variant paging keeps all 64 admitted arms reachable even when each has many seeds. Choose a baseline and challenger, then Compare verified population endpoints to analyze alive_agents through the shared bundle/checkpoint verifier. The result shows challenger minus baseline, endpoint tick, paired sample count, confidence interval, p values and paired effect size, including explicit descriptive-only and undefined outcomes.
  • Checkpoints lists retained scientific cuts in pages of 12. Select a cut and Review selected checkpoint in World to reconstruct its verified historical frame. Return World to live restores the current view; a later World-window live/seek/step action also discards an outstanding checkpoint result. Save new cuts through Timeline's Save replay checkpoint action. This reviews saved science without replacing or branching the live simulation owner.
  • Both new panes share one background worker. Discarding a pending result keeps its slot occupied until work finishes; submitted experiment stop/resume actions still take effect. Session, selection and source-generation checks prevent stale results from replacing newer observations, and failed evidence clears an earlier displayed comparison. File and statistics work stays outside painting.

Simulation overview

Deterministic, staged tick pipeline (six seeded, domain-separated RNG streams; explicit staged ordering):

  1. Aging and scheduled tasks
  2. Food respawn/diffusion
  3. Sense (spatial index snapshot)
  4. Brain tick
  5. Actuation (double-buffered state)
  6. Food intake/sharing (deterministic reductions)
  7. Combat and death (queued → commit)
  8. Reproduction (mutation/crossover) in stable order
  9. History and persistence projection (batched to the bounded FrankenSQLite worker)
  10. Preserve the final persistence tail and reset transient runtime flags

Legacy parity (what matches the C++ original and what does not)

  • Transcribed from the C++: the exact two-rotation locomotion (the default model), the 25-input sensor layout (four eyes, smell, sound, hearing, blood, clocks, temperature), carcass sharing (spiked kills only, maturity multiplier, numaround^1.25 split) and the temperature-discomfort formula.
  • Deliberately different: combat runs every tick with reach spike radius + spike length, multiplicative damage bonuses and partial spike retraction, where the C++ checks every second tick for d < 2r within π/8 and snaps the spike to zero; health and energy are separate budgets; reproduction may take a partner (with probability partner_chance, the oldest other agent) and yields one child, where the C++ is asexual with BABIES=2; the population floor defaults to population_minimum = 0 instead of topping up to NUMBOTS=70; food also regrows continuously in every cell (food_growth_rate = 0.05), where the C++ only refills one random cell to FOODMAX every 15 ticks.
  • Launch ecology vs core defaults: a launch without --scenario (scriptbots-app-default-v2 / -layered-v2) uses predominantly food-driven reproduction, retaining a small timer contribution of 0.0001 per tick for both diets, lowers food regrowth to 0.0005, sets a floor of 20 agents, and places its 20 founders at seeded uniform positions across the whole world (seeded-uniform-spread-20-registered-brain-v1) instead of the 4x4 corner grid that scenario documents keep. Measured with spread founders (seeds 11, 42, 137): 185–290 agents at tick 30,000, with 45–63 births per 1,000 ticks (the grid founders gave 180–288 and 42–73). A 60,000-tick run reached 449–575 agents and was still growing slowly, so no plateau has been observed yet. The core ScriptBotsConfig::default(), which every scenario document builds on, still advances the reproduction counter every tick and gives each child full energy at no cost to the parent; with the same founders it passes 3,000 agents between ticks ~5,900 and ~7,900. scenarios/meadow.scenario.toml passes its 360-tick envelope but passes 3,000 agents by tick ~1,200 on all three declared seeds. Tracked in bd-vgsx.
  • Explicit food-funded experiment: select --scenario scenarios/food_funded_meadow_v1.scenario.toml to make both reproduction rates exactly zero. Grazing and spiked-carcass rewards must earn the seven progress units required for a birth; elapsed ticks contribute nothing. This closed scenario has no population-floor or scheduled injections, no random food respawn, regrowth 0.0005, and a parent debit equal to the child's 0.25 starting energy. Its declared 10,000-tick envelope across seeds 11/42/137 is an acceptance study awaiting execution, permits extinction, and makes no equilibrium claim. Five production core tests cover earned births, food-free waiting, carcass eligibility, newborn reset, separate injection accounting and unchanged timed arithmetic. Custom configurations must set both diet rates to zero or both positive; mixed zero/positive pairs are rejected. Existing defaults and the original meadow remain unchanged.
  • There is no C++ oracle harness yet, so parity beyond the transcribed pieces is not measured.

Design principles & determinism

  • No undefined behavior: workspace lints flag unsafe; the remaining platform/environment boundary blocks are explicit and reviewable.
  • Explicit order of effects: floating-point reductions and removals are staged. Before each successful tick, the dense SoA is normalized to ascending stable AgentUid; stable compaction and monotonic insertion preserve that order through death and spawn commits. Physical slot allocation therefore cannot choose reduction, neighbor, parent, or child priority.
  • Restorable domain and agent-keyed RNG state: the world owns six independently derived, versioned streams—Environment, Food, Population, Lineage, Mutation, and Crossover—plus a versioned agent-substream protocol and UID-keyed continuation counters. Agent operations derive isolated streams from the root seed, stable AgentUid, operation tag, and agent-local ordinal; offspring operations derive from ordered parent UIDs plus the primary parent's local birth ordinal. The global demographic AgentIdentity::birth_ordinal remains a separate run-wide lifecycle sequence and is never used as the offspring RNG identity.
  • Transactional stochastic ownership: a reproduction attempt claims its parent's local attempt continuation, and an admitted child claims that parent's local birth continuation. Child body, runtime, brain genome, and evaluator-state operations each receive one distinct derived stream. A rejected transaction restores the exact counter preimage together with energy, reproduction progress, population inserts, and other staged state, so a failed child cannot consume randomness that a retry or unrelated agent would observe.
  • Feature-gated parallelism: scriptbots-core defaults to parallel (Rayon), while web builds disable it for single-thread determinism.
  • Completed-boundary outcome and admission seam: WorldState owns deterministic accumulators plus a payload-free Open/Pending/Sealed boundary marker; it no longer owns a sink, retry payload, acknowledgement error, or admission watermark. A one-lifetime PersistenceAdmissionSession owns those external concerns. Its step APIs stage the exact immutable Arc<PersistenceBatch> before returning, retain that same allocation across definite and indeterminate failures, and seal the world only after acknowledgement. Direct WorldState stepping is intentionally limited to persistence-disabled worlds. Application-owned drivers route TUI, GPUI, Bevy, headless, profiling, and WASM ticks through the matching session without exposing session state to renderers. Completed population faults still travel beside the full StepOutcome; the clock-free traced outcome keeps the same boundary, and profiled session stepping retains the reviewed v2 timing contract. The hidden playback transport queue is also retired: application drains return one ordered Vec<ControlCommand>, while core returns normalized playback as an explicit driver-owned disposition.

Canonical digest and first-divergence trace

  • WorldState::world_digest_v1() emits the exact scriptbots.world-digest.v1.7/codec-7 science-state wire. Every agent transition is canonicalized by stable AgentUid, so physical slot/dense allocation is no longer science state and the temporary V1.1 execution-order lane is retired. The aggregate covers stable-UID agent bodies, brain genomes/evaluator coverage, food, terrain/hydrology, all six restorable RNG-domain checkpoints with per-domain diagnostics, the exact AgentSubstreamProtocolV1, UID-ordered AgentRngCounterStateV1 rows carrying AgentRngCountersV1, global identity counters, legacy factory-state digests or protocol adapter semantic identities, the selected locomotion model and remaining scientific configuration, active effects, derived transition caches, and open ancestry origins. V1.7 removes the orphaned sense_max_neighbors field: the production C++-parity sensor model never consumed that placeholder normalizer, so it can no longer masquerade as a scientific knob or alter provenance without altering a transition. Product-admitted MLP, DWRAON, and Assembly adapters therefore report complete construction-semantics coverage. Operational rendering, analytics, persistence-admission policy, host receipts, and backend error prose do not enter the science digest.
  • WorldState::checkpoint_v1() captures the bounded canonical scriptbots.world-checkpoint.v1.3/codec-6 postcard+blake3-v6 core science envelope only when persistence is disabled and the world is at an open completed boundary. It persists the exact agent-substream protocol, selected locomotion model, and one counter object per stable UID. Decode and restore reject missing, duplicate, reordered, mismatched, or incompatible counter/protocol state before constructing any evaluator or agent. WorldCheckpointV1::decode() also rejects oversized, trailing, noncanonical, checksum-invalid, and semantically malformed bytes; WorldState::restore_checkpoint_v1() allocates fresh physical handles from stable AgentUid order and reconstructs full genome/evaluator state through a caller-prepared exact BrainRegistry. The registry's complete roster, including its next allocation key and every protocol adapter's exact BrainAdapterIdentityV1, must match before reconstruction. The identity is a family-authored semantic attestation, not executable-byte authentication: construction/evaluation changes must change it, while payload interpretation changes must additionally bump the family schema/codec. The checkpoint never deserializes executable adapters and does not claim to restore storage ownership, analytics/history, configuration audit provenance, UI/render state, or an application run bundle. Its unkeyed BLAKE3 checksum detects corruption and canonical drift; it is not authentication.
  • WorldState::step_traced() is an opt-in, clock-free diagnostic API using scriptbots.world-step-trace.v1.7/codec-7. It records exactly six semantic checkpoints—Sense, Brains, Actuation, Food, DeathCleanup, and Population—with separate world, ordered deferred-work, pending output-tail, and resource-ledger hashes. The embedded world and transition lanes bind the same agent-substream protocol, UID-ordered counters, selected locomotion model, and queued offspring identities as the final digest. The trace has its own aggregate hash, typed capture failures, and validate_contract() enforcement for schema, cardinality, order, ticks, coverage, digest shape, and nested aggregate hashes.
  • Both V1 and trace validation prove protocol self-consistency, not artifact authenticity. Their FNV-1a64 hashes are diagnostic first-divergence aids, not signatures or collision-resistant attestations; a durable run bundle will require separate provenance/authentication.
  • DeathCleanup and Population retain the ordered queue state immediately before consumption, while the final completed-boundary V1 and resource report prove traced/untraced parity after finalization. The literal six-point golden is enabled only by the SCRIPTBOTS_WORLD_DIGEST_GOLDEN=1 environment guard in its pinned DSR test lane, so ordinary --all-features tests remain portable; there is no product CLI or replay-file claim yet.

Paired checkpoint branch studies

Run a study directly from an editable JSON plan:

cargo run -p scriptbots-app --no-default-features --bin scriptbots-app -- \
  branch-study --example > study-plan.json
# Edit the seed, checkpoint, horizon, configuration and interventions as needed.
cargo run -p scriptbots-app --no-default-features --bin scriptbots-app -- \
  branch-study --plan study-plan.json --out runs/checkpoint-study

The example includes a control and five treatments: drought, resource shock, temperature shift, closed-world policy and cooperation. The command prints its summary and saves study_plan.json, study_report.json, study_summary.md, and one bundle_<branch_id> directory per branch containing trajectory CSV and intervention evidence. Use a new or empty output directory. Completed and partial studies are preserved; a second writer or rerun cannot replace their artifacts. To repeat a study, choose a different output directory.

JSON plans reject unknown fields. Before reserving output, the runner validates the configuration, brain support, schedules and resource envelope: at most 32 branches, 10,000 transitions per branch, 1,000,000 total baseline-plus-branch transitions, and 262,144 grid cells. History capacity, population floors and per-tick injection counts are each limited to 10,000; enabled archives are limited to 64 MiB. Resolved configuration treatments receive the same checks and cannot change world geometry or enable persistence. Execution stops with an explicit error if an observed population exceeds 10,000, retaining any partial artifacts. Plans must be regular files no larger than 1 MiB. These limits bound individual resources, not total memory use or completion time.

The command uses the library's branch_study::BranchStudyOrchestrator, which restores each branch from one shared checkpoint. base_seed controls world and founder initialization, and persistence is disabled for the study. An intervention's scheduled_tick names the completed boundary after which it applies, before the next transition. It must fall in [checkpoint_tick, checkpoint_tick + horizon_ticks); omitting it applies at the checkpoint. The report records the observed application tick. Divergence compares control and treatment digests at the same tick and identifies a differing digest lane, without claiming to identify an internal transition stage.

Branch reports use schema 3, including an exact terminal_sample in both the report and branch evidence JSON. Each trajectory comparison declares analysis_basis.kind = "single_seed_trajectory": one seed supplies one independent pair, even when many ticks are recorded. The report includes trajectory mean differences and temporal spread, and omits confidence intervals, standardized inferential effects and p-values. Recovery and extinction use the observed population at the actual intervention boundary.

To compare terminal outcomes across independently initialized matched seed pairs, add an explicit seed list to the same plan:

scriptbots-app branch-study --plan study-plan.json \
  --out runs/replicated-checkpoint-study --seeds 42,137,999

Each seed constructs its own founders and checkpoint, then restores its control and treatment branches from that checkpoint. The list accepts at most 32 unique u64 seeds; duplicates are refused because rerunning the same seed does not add an independent pair. With --seeds, the plan's base_seed controls deterministic statistical resampling and is not added to the replicate list. Execution follows the declared seed order and runs one seed at a time. The existing 1,000,000 transition budget covers all seeds combined.

Replicated runs save study_plan.json, replicated_report.json (schema 1), replicated_summary.md, and the complete per-seed studies under seed_<16-digit-hex-seed>/. The aggregate retains each seed's checkpoint digest, terminal observations and report location. For each treatment, exactly one final population, food-total and total-energy observation per seed enters the paired analysis; the statistical sample count is the seed count. Two or more seeds enable 95% paired bootstrap intervals and two-sided sign-flip p-values, each with 1,000 seeded resamples. These are individual endpoint comparisons without a multiple-comparison correction or automatic winner decision. A one-seed list produces descriptive effects without inferential intervals or p-values.

The aggregate success report is written only after every requested seed and its branch bundles complete. A failed or cancelled study retains its exact inputs and completed or partial seed outputs; reruns require a new output directory.

Branch bundle verification checks retained artifact integrity. It does not claim to restore a complete application owner or reproduce the study from the bundle.

Reproducible runs (seed control)

  • Set a fixed seed in config: rng_seed = <u64>. At runtime you can apply via REST:
    { "rng_seed": 42 }
  • The root seed deterministically derives all six domain streams and every stable agent/offspring substream. The canonical launch manifest is scriptbots.run-manifest.v3.3: it records the six-domain checkpoint, exact AgentSubstreamProtocolV1, and UID-ordered AgentRngCounterStateV1 launch rows. Once the tick-zero V1.7 start digest is bound, the bootstrap form is scriptbots.run-manifest.v3.6; it must bind the same root, protocol, counters, registry semantics, locomotion model, and WorldDigestV1 evidence rather than describing a different launch state. Neither form collapses the domains back into one ambiguous global stream.
  • The bd-1kxd keyed-substream schema and the bd-2i1 V1.6 locomotion contract are closed with pinned DSR evidence. The reviewed exact-class full performance baseline was promoted byte-for-byte in 39fc2f0, and the final same-class comparison passed in DSR 0.1.0-bd2i1-perf-compare-quiet1.20260716T160817Z. bd-hiv1 is closed: movement-noise sensing and spike-speed damage now consume a typed peak-wheel-effort lane rather than physical displacement (scriptbots-core wheel_effort; spike_speed_damage_bonus scales peak normalized wheel output, and speed_mag no longer contributes).
  • For CPU thread control in app profiling, use --threads N; RAYON_NUM_THREADS supplies the default only when the app resolves no thread budget.

Data model & spatial indexing

  • SoA layout: agents use cache-friendly columns (AgentColumns) for fast scans during sense/actuation.
  • Two identity layers: slotmap-backed AgentId prevents stale references; monotonic AgentUid is the stable scientific identity used by digests, lineage, replay, and persistence.
  • Spatial index: uniform hash grid. Sense builds a read-only snapshot; alternate backends remain future implementation work and have no placeholder feature flags.

Sensors & outputs

  • Sensors: multi-eye vision cones (angular), smell/sound/blood channels with attenuation, temperature discomfort, and clock/age cues.
  • Outputs: wheel velocities integrated by the exact legacy two-rotation model by default, with conventional differential drive selectable for experiments; color/indicator pulses, spike length easing, give intent (altruistic food sharing), boost control, and sound output.
  • Mapping: outputs drive physics and side-effects (e.g., spike damage scales with spike length and speed) and are logged for analytics.

Brains & evolution

  • Brain trait with tick/mutate/crossover; implementations include MLP and DWRAON by default, plus experimental Assembly.
  • Brain registry: per-run registry attaches runners by key, enabling hybrid populations and runtime selection. Random spawns draw from BrainRegistry::random_key for mixed-species runs. Brain-material crossover is gated to same-family brains (species barrier): scheduled cross-family crossover attempts become fresh random spawns, while natural cross-family mating may blend body/runtime traits but keeps brain heredity unary in the primary parent's family. Brains can optionally expose activation snapshots for visualization.
  • Genome & genetics: genomes capture topology/activations; mutation/crossover create hybrid births with lineage tracking and tests.
  • NeuroFlow (optional): deterministic CPU MLP with runtime toggles; seed-stable outputs verified in tests.

Environment: food, terrain, temperature

  • Food dynamics: configurable growth, decay, diffusion, and fertility capacity; speed-based intake and reproduction bonuses mirror legacy behavior.
  • Topography: tile-based terrain/elevation influence fertility and movement energy (downhill momentum/energy costs).
  • Temperature: gradient and per-agent preference drive discomfort drains; exposed in config and analytics.
  • Closed worlds & seeding: enforce closed ecosystems; maintain population floors and scheduled spawns.

Procedural maps (WFC sandbox; in progress)

  • In the native Lab's Maps tab, choose Pause world, a disclosed seed and map size, then Generate preview. The draft starts with the live food grid's dimensions and cell size; Use live grid restores them after size experiments. Applying requires that exact grid. Large maps display a bounded sample; painting affects the named cell. Paint grass/water/sand cells, undo/redo or clear draft paint, and generate again to preview the edits. Inspect the generator identity and opposite-edge seam measurements, choose an existing-agent policy, then Apply preview to live world. The owner rejects a preview if science has changed since generation. Draft edits never step the world; application and journal status appear separately below the controls. Paint: … cycles between terrain and elevation, moisture, fertility, temperature, permeability, runoff bias, basin rank, channel priority and swim cost. For numeric channels, Value −0.1 / +0.1 adjusts the disclosed brush value: 0–1 for normalized fields, −1–1 for runoff and 0–10 for swim cost. Terrain uses the existing terrain brush. Painting preserves the cell's other overrides and is one undoable draft edit. Repeating the exact same painted override preserves undo/redo and the current preview; a new or changed override still requires regeneration. Changing the brush alone does not change the draft or invalidate its preview. Regenerate to see the actual stored value for the selected channel at the last painted cell; that label names the preview revision, which may precede newer edits. Recipe files preserve every painted channel. Paint source: … (change) switches between the brush value and the current generator's default for the active terrain, numeric or hazard field. Choose generated default, then paint a cell to remove only that field's override; other fields and cells stay painted. Clearing the last override removes the cell's paint entry, while an already-absent field is unchanged. Undo/redo restores the edit. Numeric value controls are disabled in this mode; changing channel returns to brush values. Regenerate to see the resulting field. Hazard override also retains its Generated default / Stamp hazard choices: select one, paint a cell, then regenerate. Stamping sets accent to 1 and swim cost to 10; generated default removes only the hazard override and preserves the other painted fields. Hazards supplied by the generator may remain. Erase cell overrides removes all paint at the clicked cell while preserving other cells; regenerate for the generator's values. Erasure is undoable, and erasing an unpainted cell preserves history and the preview. Palette: … (cycle) is available throughout the map views and uses the same session palette as World and Lab: Natural, Deuteranopia, Protanopia, Tritanopia and High Contrast. It accepts mouse input or Space/Enter when focused. Preview, exemplar and saved-artifact cell colors use the existing shared accessibility transform; Natural colors are retained. A named terrain legend maps D DeepWater, W ShallowWater, S Sand, G Grass, B Bloom and R Rock. Choose any legend entry by mouse or Space/Enter to select that terrain brush, then paint a preview or exemplar cell. Selection alone is not an edit; painting uses the existing undo history. The quick Brush: … cycle is also available. Cells large enough to fit them also show these letters on black/white markers; smaller sampled cells retain terrain and coordinate accessibility labels. Palette changes leave the draft, undo history, generated preview and live science unchanged. Actual native-window and assistive-technology acceptance remains open. Resource controls and native OS acceptance remain open. Generation runs in one bounded background slot. Cancellation discards the result; that slot remains occupied until the underlying generator finishes. Switch rules / sample selects the default rule tileset or the versioned lab_meadow_v1 overlapping sample (3×3 exemplar, 2×2 patterns, periodic extraction, all rotations/reflections). Undo restores the previous configuration. In rules mode, Edit rules opens the existing tileset's prototype defaults. Cycle through its prototypes and all six terrain kinds, adjust selection weight within 1–1,000, or choose an environmental/hydrology field and set its numeric override. Use generated default clears only that field. Prototype edits affect every generated occurrence except cells with painted output overrides; IDs, labels, adjacency, explicit palette/accent and other prototype fields are preserved. A terrain change therefore does not clear earlier explicit defaults. Field ranges match the corresponding output brushes. Imported weights above the editor range are retained; change them through the recipe. Selection and brush changes do not edit the draft; actual edits share undo/redo, and unchanged values preserve preview/history. Return to the draft and generate again to inspect the real rules hash and output before Apply. Edit adjacency opens the ordered rule entries. Select prototypes A/B and A's cardinal side to append a rule joining B's opposite side. Append forbid excludes that neighbor; Append allow-list entry restricts the endpoint/side to its explicit allow list. Order matters, and every entry affects both endpoints; a physical pair must satisfy both facing endpoint lists. Inspect existing entries with Next existing entry, then toggle or remove the selected record. Imported direction spellings and unrelated entries stay intact. Native appends are bounded to 256 entries, and the complete portable recipe must stay within 1 MiB. Empty neighbor lists are refused without changing the draft; a valid rule list may still contradict the requested toroidal dimensions when generated. Entries share undo/redo. Return to the draft and generate before using guarded Apply. Clone prototype copies every field under the first unused prototype-copy-N ID, selects the copy, and expands its ordered adjacency references, including self-rules. The copy has its own weight, increasing the combined selection weight until edited. Remove prototype + its rules prunes all references to that prototype. The editor refuses an empty roster, invalid remaining permissions, more than 64 prototypes, more than 256 resulting adjacency entries, or a portable recipe over 1 MiB. These edits share undo/redo and preserve output-cell constraints; generate again before Apply. Palette editing still requires a recipe. In sample mode, Edit sample opens a separate exemplar view. Use the existing grass/water/sand brush to paint its cells, cycle the pattern size from 1 to the smaller exemplar dimension, or toggle rotations/reflections. Edits retain the sample label, update its computed content hash, and share the draft's undo/redo history. Painting an unchanged cell preserves history and the current preview. Width ±1 and Height ±1 resize the exemplar independently: growth repeats its current cells from the upper-left corner, while shrinking crops them and clamps the pattern size to fit. The controls show the current output-work budget, up to 64 exemplar cells; invalid or over-budget edits and recipes over 1 MiB are refused atomically. Resizing preserves output dimensions, seed and painted constraints, and shares undo/redo. Back to draft returns to generation and guarded Apply; editing alone never changes the live world. Imported recipes can supply other terrain kinds within the same core bounds. Copy draft JSON and Paste draft JSON transfer a versioned editing recipe through the clipboard. Save the copied text to retain it, or edit its seed, dimensions, generator_config and constraints records to author custom rules, exemplars and terrain/environment/hydrology overrides. The recipe schema is scriptbots.map-draft.v1; constraints are a list with explicit x/y coordinates. Imports are limited to 1 MiB, 64 rule prototypes and the existing sample/output work bounds. Invalid imports preserve the current draft and preview. A valid import is one undoable edit and requires a fresh preview before Apply. Session history, owner revisions, receipts and live world state are not imported. Save draft file… opens the platform save dialog and writes the captured draft revision to a new file. Pick an unused filename; existing files are refused. Open draft file… opens one recipe through the same validator and undo history. File reads/writes run in one background slot and retain the 1 MiB recipe limit. A cancelled dialog leaves the draft unchanged. Editing while Open is pending discards its result; Save still writes the revision captured when its dialog opened and reports that revision separately from the current draft. These are input-work bounds, not filesystem latency guarantees. Inspect artifact… opens saved JSON or Postcard map output in a separate inspection view. It validates structure and provenance dimensions, computes the scientific content hash and toroidal seam diagnostics, and shows stored terrain/environment/hydrology values when you select a sampled cell. File decoding and full-map diagnostics run in the background; the view displays at most 32 × 32 sampled cells. Inspection accepts files up to 64 MiB and maps up to the editor's 65,536-cell limit. Draft/history, generated preview and live world stay unchanged; Back to unchanged draft returns to the editor. Viewing does not change the draft or apply the saved map. Use selected … sample explicitly copies a terrain-kind patch starting at the selected cell, wrapping across opposite edges. Patch width ±1 and Patch height ±1 select independent dimensions within the source and the displayed exemplar/output-work budget. Selection starts at at most 3×3 cells for each newly opened artifact and leaves the draft, history and preview unchanged until extraction. Cancelled or failed file opens retain the selection. The new sample label records the source content hash, origin and patch dimensions; its pattern starts at 2, or 1 for a one-cell-wide/tall patch, with periodic extraction and rotations/reflections enabled. This is one undoable generator-config edit that opens the exemplar view. Output dimensions, seed and painted output constraints are retained. Fertility, temperature and hydrology are not copied into the exemplar; they come from generation defaults and output constraints. Generate a fresh preview before applying. Enlarging the draft exemplar repeats its current cells; it does not extract a larger saved-map region; use the inspection patch controls to copy additional saved cells. Resource controls and full native accessibility/input acceptance remain open.

  • The core ships a rule-based Wave Function Collapse (WFC) generator that produces deterministic terrain (TerrainLayer) and optional fertility/temperature fields from a tileset spec. This enables quick scenario bootstrapping and repeatable experiments.

  • Sample generation uses the existing overlapping-pattern backend: CLI map-generate --sample sample.json, or REST/MCP sample: {...}, selects it explicitly. sample and tileset are mutually exclusive; omitting both selects the default rule tileset. Invalid specifications and dimensions are rejected rather than replaced with defaults. Scoped source-pinned tests cover sample output and input validation; interactive native editor acceptance remains open.

  • A sample specifies sample_id, sample_width, sample_height, pattern_size, and row-major sample_tiles terrain kinds. all_orientations and periodic default to true; periodic: false is refused because non-periodic extraction is not implemented. Core bounds (MAX_SAMPLE_CELLS, MAX_SAMPLE_OUTPUT_CELLS, MAX_SAMPLE_CELL_PAIRS) admit at most 64 exemplar cells, 65,536 output cells, and 1,048,576 output/exemplar cell pairs before model construction. These are input-work bounds, not wall-clock or exact-byte guarantees. For example, a 2×2 all-sand sample is:

    {"sample_id":"sand_v1","sample_width":2,"sample_height":2,"pattern_size":2,"sample_tiles":["Sand","Sand","Sand","Sand"]}
  • Live CLI control_cli map-generate/control_cli map-apply, REST /api/v1/map/generate and /api/v1/map/apply, and MCP map_generate/map_apply use the shared map service and acknowledged owner commands. The main binary's offline map-apply command validates an artifact file. existing_agent_policy defaults to retain. CLI control_cli map-apply --file map.json --existing-agent-policy reposition-to-safe-tile, or REST/MCP existing_agent_policy: "reposition_to_safe_tile", moves agents on deep water to the nearest non-deep-water tile using wrapped distance and row-major tie breaking. If no such tile exists for a present agent, application fails without changing the world.

  • CLI --existing-agent-policy cull-incompatible, or REST/MCP existing_agent_policy: "cull_incompatible", records explicit map-incompatibility deaths for deep-water agents and removes their live companions. Culling requires enabled persistence, a bound recording session and a completed open tick after that session's actual binding cut; genesis, same-tick arrivals and pending/sealed or discarded recording cuts refuse atomically. Use a recording cadence greater than one and advance to an open recorded tick before submitting a new culling command. Retain and reposition do not retire agents. Inspect application and journal statuses separately; application alone does not establish durability.

  • To guard a preview against an intervening science change, read scientific_revision from REST /api/status or MCP get_status before preparing it. Pass that exact value as CLI control_cli map-apply --file map.json --expected-scientific-revision REV, or REST/MCP expected_scientific_revision: REV. The owner checks it at ordered application; a stale request ends as rejected without applying the map. Its rejection_reason reports the requested and actual revisions. Omission leaves application unguarded. An identical keyed retry retains its original outcome; changing the guard requires a new idempotency key.

  • The typed policy is included in the durable command and replayed explicitly. Host archive v6 refuses older archives rather than guessing the policy. The full interactive rule/sample sandbox and its real-process/native acceptance remain open under bd-2z0.10.7 and bd-2z0.10.8; the hydrology system builds atop terrain for dynamic water flows (see below).

Hydrology snapshot (experimental)

  • Runtime hydrology state models per-cell flow direction, accumulation, basins, and a water depth field. Use GET /api/hydrology for a snapshot with:
    • width, height, total_water_depth, mean_water_depth, flooded cell counts with thresholds
    • Arrays: water_depth, flow_directions (N/S/E/W/-), basin_ids, accumulation, spill_elevation
  • CLI: scriptbots-control hydrology prints a summary (ratios, thresholds, array sizes). Hydrology integrates with terrain and is deterministic per seed.

Combat & mortality analytics

  • Spikes: damage scales with requested spike length and agent speed; collision resolution is staged for determinism.
  • Carcass sharing: meat distribution honors age scaling and diet tendencies; events persisted for analysis.
  • Analytics: attacker/victim flags (carnivore/herbivore), births/deaths, hybrid markers, age/boost tracking, and per-tick summaries feed FrankenSQLite plus the immutable HUD analytics snapshot.

Rendering & UX

  • GPUI renders food tiles and agents (circles/spikes) in a dedicated World window beside a compact tabbed Lab. The pair launches transactionally under QuitMode::LastWindowClosed; closing either window ends the session, so a launch/close failure cannot leave a degraded or orphaned UI.
  • Camera controls: scroll to zoom, middle-drag to pan, 0 or the World toolbar to fit; display toggles live beside the canvas.
  • Lab tabs separate overview/run controls, agent inspection, analytics/history, and the narrative timeline. Optional diagnostic cards are keyboard disclosures (1, 2, 3) in the scrollable Overview.
  • The Timeline's Save replay checkpoint before future events action saves a reconstruction source. Review World frame first selects the event's exact cached World frame; outside that cache it uses the application's verified checkpoint replay, with the configuration-history and 1,024-tick limits described above. Reconstructed frames are labelled CHECKPOINT REPLAY, including the saved and requested ticks. App-provider and headless GPUI component tests pass; the reality check records the evidence and remaining native-window/GPU acceptance. One background request runs at a time. Return World to live, a changed selection or leaving Timeline discards a pending review result; its worker keeps the slot until it finishes. Errors leave the previous view intact. Lab keeps the current narrative, controls, storage health and receipts. Review does not rewind the scientific owner, and historical coordinates cannot pick or hover live agents. Returning live enables picking after a live frame is selected for rendering.
  • In the terminal, select a narrative event with the rail and press v to review its exact retained canvas frame; outside the cache it uses the same bounded checkpoint replay. Save a checkpoint before the event. Press g to return live. The map title distinguishes cached frames from CHECKPOINT REPLAY and names the reviewed and live ticks. Controls, receipts, narrative and other panels stay current. Missing or unsupported reconstruction sources leave the view unchanged, and historical map coordinates cannot pick or hover live agents. A cached source is the latest publication observed for that tick; sampling can skip ticks. Returning live enables picking after the next canvas paint.
  • Functional search: the settings panel includes a live search bar that filters parameters across all categories via a centralized filter, making it fast to find and tweak knobs.
  • Inspector: per-agent stats and genome/brain views (scoped to plan milestones); mutation-rate adjusters (±) for primary/secondary let you tweak an agent’s evolution parameters live.
  • Optional audio via kira (feature audio).

GPUI performance & diagnostics

  • Adaptive GPU adapter selection; viewport culling for terrain; chart decimation; batched path rendering to reduce draw calls.
  • Troubleshooting flags: --renderer-safe (conservative paint path) and --debug-watermark (tiny on-canvas badge) help isolate rendering issues.

Accessibility & input

  • Colorblind-safe palettes (deuteranopia/protanopia/tritanopia) and a high-contrast mode; UI elements and overlays respect palette transforms.
  • Window-scoped keyboard controls keep canvas presentation commands in World and retained-history/diagnostic commands in Lab, while simulation commands work from either window.
  • Narration hooks prepared for future screen-reader integration; the toggle stays beside the World presentation controls.

Renderer abstraction

  • The app selects GPUI, Bevy, or terminal renderers via --mode {auto|gui|bevy|terminal} (subject to build features); --mode server runs without a renderer. Each mode connects to the same sole-owner host through ChannelHostPort. Full client interaction and native cutover acceptance remain open; selecting a renderer does not create another scientific owner.

The Bevy HUD shows the four most recent native command identities with separately observed application and journal outcomes. An admitted command can still be pending, rejected, or failed; an applied command can still have a pending or failed journal. When an identity leaves the published status mirror, the HUD keeps its last observation and labels it as such. Missing acknowledgements remain unconfirmed. Paused and single-step snapshots settle agent positions, headings, spikes, and idle-body deformation immediately at their recorded poses; camera navigation remains available while paused.

Native Lab experiments and saved checkpoints

In Bevy, use Lab (F6) to open the experiment pane or F7 to open saved checkpoints. Tab or Up/Down selects an enabled action, Enter activates it, and PageUp/PageDown or the mouse wheel scrolls the panel. Escape closes the panel.

The experiment pane reads the same application services as GPUI. It lists retained batches, shows every variant through bounded pages, and reports completed, running and failed runs. Select baseline and challenger arms to compare verified population endpoints from matched seeds. Comparisons retain their plan digest, source generation, endpoint and available statistical results. Stop and resume buttons use the existing experiment runner; its returned status remains the authority. Create new batches through the experiment CLI or API.

The saved-checkpoint pane can save the current live world, list retained scientific cuts and reconstruct a selected cut for inspection. A completed save reports its exact checkpoint ID, tick and world digest and selects that saved cut for review, even when it is outside the current catalog page. Saving uses the existing owner service without advancing the simulation. If the result is uncertain, Retry previous checkpoint save retains the original request identity; a retry does not silently request a second cut. Return to live before starting a save from a historical view. SAVED CHECKPOINT and a return-live banner identify historical presentation while the independent live owner continues running. Live organism picking and simulation commands are disabled during review. Click the banner, choose Return live, or press Escape with the panel closed to restore the newest live publication. Review does not replace or rewind the owner.

Both native frontends share one bounded workflow model. Discarding a pending result keeps its worker slot occupied until the operation finishes; changing session, panel or selection invalidates its result. File reads and experiment verification run outside the render loop. Bevy retains at most one saved presentation and one newest live publication, and reuses a bounded pool of UI rows.

This increment covers experiment inspection/comparison and checkpoint saving and review under bd-2z0.7.6.1. Replay seeking, first-divergence display, artifact export and full native/GPU acceptance remain unfinished parts of that bead. Normal simulation epoch progression preserves a saved view; a change of host session invalidates stale observations and results.

Bevy shared creature appearance

Live Bevy rendering and offscreen capture now use the same shared PBR appearance plugin. Four material classes cover the existing creature alpha, lighting and sidedness combinations. Stable per-part slots hold linear color and emission in a resident storage buffer, while MeshTag selects each instance's row. Identical mesh/material handles let Bevy batch eligible creatures using its normal paths.

Changed colors upload coalesced dirty ranges. Storage grows only when retained capacity is exceeded, and an actual GPU-buffer replacement receives a full upload. Per-row revisions preserve changes across skipped publications; slot generations reject stale ownership after population turnover or capture reset. The actual device binding limit and an independent application ceiling bound storage. Existing geometry, per-part entities, terrain contact, interpolation, picking, accessibility palettes, lighting and alpha/shadow behavior are retained.

This is an implemented, independently reviewed source increment. Changed Rust formatting passed DSR. Native Cargo checks progressed after genuine system prerequisites were supplied, then the 8 GiB host memory limit killed the unchanged bevy_render dependency before project compilation. Six new CPU regressions and GPU capture acceptance remain unexecuted. Entity elimination, measured draw-call reduction and throughput qualification remain open under bd-2z0.7.3.

Keyboard shortcuts (GUI)

Simulation controls and retained-history playback are separate. The unmodified S shortcut returns the invoking view to live and queues one scientific step; when that isolated step succeeds, it advances exactly once and leaves the simulation paused. space, G, and 1/2/3 apply in Lab. Canvas presentation shortcuts (N, Ctrl+P, D, F, Ctrl+Shift+O, Shift+S, O, Shift+F, 0, and ,) apply in World. Simulation and canonical selection commands work from either window.

Action Default shortcut
Toggle playback space
Jump to live G
Toggle narration N
Cycle palette Ctrl + P
Toggle simulation pause P
Step simulation once S
Toggle agent drawing D
Toggle food overlay F
Toggle agent outline Ctrl + Shift + O
Increase simulation speed Shift + =
Decrease simulation speed -
Spawn crossover agent A
Spawn carnivore Q
Spawn herbivore H
Toggle closed environment C
Follow selected agent Shift + S
Follow oldest agent O
Toggle debug overlay Shift + F
Clear selection escape
Select all agents Ctrl + A
Focus first selected agent Ctrl + F
Fit world 0
Toggle settings panel ,
Toggle stats panel 1
Toggle history panel 2
Toggle performance panel 3
Cycle sense probe eye forward .
Cycle sense probe eye backward Ctrl + .
  • Persistence safety: a spawn shortcut is refused after the current tick is admitted under the selected storage guarantee; advance to the next open tick boundary before spawning. An unresolved admission is reported separately and must be resolved by retrying the exact retained batch before either the world or an external arrival can advance. Both typed reasons are logged without consuming simulation RNG.

Audio system

  • Optional kira-backed mixer (feature audio) with event-driven cues (births, deaths, spikes) and accessibility toggles.
  • Channels planned for ambience/effects; platform caveats apply on Linux/WSL2. Audio is disabled in wasm; use Web Audio API from JS if needed.

Terminal mode

The interactive frontend runs FrankenTUI's Program and retains Ratatui widgets; headless mode uses its buffer adapter. Automatic selection chooses terminal mode only before launch; an explicit GPUI/Bevy request or a native window launch failure is surfaced rather than silently changing products.

Terminal-only mode

  • Force the emoji TUI renderer (useful on headless machines):

    SCRIPTBOTS_MODE=terminal cargo run -p scriptbots-app
  • Auto selection: SCRIPTBOTS_MODE=auto (default) chooses a compiled native renderer only for a real native graphical session and otherwise starts the terminal (including macOS SSH sessions).

  • Auto-mode policy overrides:

    • SCRIPTBOTS_FORCE_TERMINAL=1 → choose terminal in Auto mode even when a display server is present.
    • SCRIPTBOTS_FORCE_GUI=1 → require compiled GPUI in Auto mode even if no display variables are set; failures remain visible.
  • CI/headless smoke runs can bypass raw TTY requirements by setting SCRIPTBOTS_TERMINAL_HEADLESS=1, which drives the renderer against an in-memory buffer for a few frames.

  • Emoji mode (terminal renderer):

    • Defaults ON when a modern UTF‑8 terminal is detected; press e to toggle at runtime.
    • Force enable via env: SCRIPTBOTS_TERMINAL_EMOJI=1|true|yes|on; force disable with 0|false|off|no.
    • Heuristic: enabled if TERM is not dumb/linux/vt100, locale contains utf-8|utf8, and CI is unset.
    • Emoji mappings: terrain 🌊/💧/🏜/🌿/🌺/🪨 (lush swaps: 🐟, 🌴, 🌾, barren 🥀); agents single 🐇/🦝/🦊, small groups 🐑/🐻/🐺, large cluster 👥, boosted 🚀, spike peak ⚔ (underline). Heading arrows remain for single agents when available.
    • If emojis render as tofu/misaligned, install an emoji-capable font (e.g., Noto Color Emoji) or toggle off with e.
  • Narrow symbols mode: press n to switch to width-1 friendly symbols while keeping emoji colors off-background; helpful for strict terminals/alignment.

Keybinds: space (pause), +/- (speed), s (single-step), b (toggle metrics baseline), S (save the displayed frame), e (emoji), n (narrow symbols), x (expanded panels), ?/h (help), q/Esc (quit). The terminal HUD shows tick/agents/births/deaths/energy, Insights (rolling metrics), Mortality panel, Brains leaderboard, recent events log, and an emoji world mini-map. The layout is responsive and auto-expands panels on wider terminals; press x to toggle. S saves both ANSI (.ans) and plain text (.txt) under screenshots/frame_<tick>_<pid>_<nonce>, including science screens. The live footer reports completion or a write error.

The live terminal applies its detected palette after every panel and overlay, before presentation and screenshot capture. RGB colors are quantized for 256- and 16-color palettes. NO_COLOR and terminals reporting no color support (including TERM=dumb) suppress all color channels while preserving text and attributes. The pinned presenter still emits RGB SGR for colored cells; the buffer goldens qualify palette values, not native 16/256-color escape encoding. Headless reports keep their fixed evidence palette independently of the invoking terminal.

Storage & analytics

  • One embedded engine: ScriptBots uses the public fsqlite facade from FrankenSQLite with version = "=0.4.6", pinned to immutable revision ad3f23ca94c0f1d38e3d6cbb919b0d095de0b4ee at https://github.com/Dicklesworthstone/frankensqlite. Defaults remain disabled; native, json, fts5, icu, misc, and rtree preserve the previous native feature's implicit extension surface. Create-free existing-file open and expected-identity verification still precede recovery access. Native validation of this dependency migration is pending.
  • Two storage targets: --storage file exclusively reserves SCRIPTBOTS_STORAGE_PATH or a generated runs/scriptbots-<unix-ms>-<pid>.sqlite and prints the selected run database; it refuses reuse or stale sidecars. --storage memory opens volatile :memory: through the same implementation.
  • Explicit interrupted-run recovery: --recover-storage FILE (or SCRIPTBOTS_RECOVER_STORAGE) repairs an existing run database under the OS writer lease. It binds recovery to the identity of the already-open VFS handle, verifies the exact structural schema fingerprint plus the supported migration sequence and persistence invariants, and refuses missing, replaced, unrelated, symlink, and multiply-linked files before replaying admitted-but-unapplied outbox rows and finalizing applied rows. It prints the resulting watermarks and exits. Full-host continuation uses the same leased recovery boundary plus an exact saved owner/science/journal cut through the separate --continue-host-db candidate described above.
  • Thread-confined, single-writer connection: fsqlite::Connection is deliberately !Send + !Sync. The storage worker creates, uses, explicitly closes, and drops its connection on that worker thread. File writers hold a nonblocking OS advisory lease on a persistent companion lock file; process-local path/inode tracking is only defense in depth. No connection-owning value is shared through Arc<Mutex<_>>.
  • Bounded admission, distinct proof levels: persistence batches enter a bounded queue. Configurable StorageDeadlines bound startup, admission-gate, command-enqueue, receipt, flush, and shutdown acknowledgement waits, but cannot cancel a database call already executing on the owner thread or bound the supervised reaper. Validation, closed-gate, queue-send, and rolled-back outbox failures are definitely NotAdmitted; the external admission session retains the exact completed batch and acknowledgement fault while the world's payload-free Pending marker blocks later science ticks until explicit retry succeeds. A lost or timed-out acknowledgement remains typed as Indeterminate at the world boundary, but retrying the unchanged canonical payload is idempotent and reuses its stable batch ID; a conflicting payload is rejected by its BLAKE3 identity. Timed-out shutdown retains the exact pending receipt and worker handle for retry; dropping the controller hands both to an independent supervised reaper rather than abandoning connection ownership. submit_with_receipt returns the batch ID after the exact payload enters the worker outbox and reports Durable for a file database or CommittedVolatile for memory. That receipt proves admission, not scientific-table application. Same-thread Storage::persist now follows the identical outbox identity and watermark protocol; exact duplicates remain idempotent, conflicting payloads are typed refusals, raw insert SQL is confined to a non-production conformance test, and receipt plus shutdown/join retain the same typed terminal cause (bd-2z0.8.9.4.4).
  • Durable recovery and watermarks: each file-backed batch advances three monotonic, separately queryable prefixes: admitted after the outbox transaction, applied in the same transaction as all scientific-table rows, and durable in a later marker transaction that permits outbox-payload compaction. Startup replays admitted-but-unapplied payloads in order and finalizes applied-but-not-durable batches without duplicating rows. Exact duplicate retries reuse the original batch identity; a different payload for an already admitted tick is rejected. Flush and shutdown receipts include all three watermarks.
  • V8 scientific evidence: every durable scientific sequence has an archive-bound projection batch, including honest zero-row boundaries. Exact births, exact deaths, and nonzero aggregate-combat counters retain deterministic local order. Bounded typed evidence/pages reject sequence gaps, duplicate or corrupt ordinals, fabricated cursors, and an expected-but-empty scenario with typed NoEvidence. Pairwise combat and food-share events are queryable in the indexed interactions table, joined one-to-one to their typed replay source.
  • V9 command evidence: normalized records retain the exact command envelope, source/client identity, optional admission order, all three revision guards, terminal boundary, and canonical archive digest. Runtime admitted/applied/rejected/failed transitions remain distinct from storage committed_volatile/durable transitions. Finished files expose bounded StorageReader::command_journal_evidence, command_journal_record, and command_journal_page; a nonempty pre-V9 archive is refused before migration because archive v1 cannot supply missing lifecycle evidence.
  • Complete typed ancestry origins: every agent insertion emits exactly one immutable born, seeded, or injected origin row under a globally unique stable agent UID. Only born rows have a global demographic AgentIdentity::birth_ordinal or contribute to demographic birth totals; ancestry and offline rebuilds consume all three origins plus exact death causes. Natural-offspring RNG instead uses the primary parent's local birth continuation in AgentRngCountersV1, which is directional lineage state and may share the same numeric value in different families without collision because the parent UID also participates. Completing any scientific tick while persistence is disabled creates a history gap, even when that tick has no lifecycle or replay rows, because its summary, metrics, and snapshot were not admitted. That world refuses to re-enable persistence; start a new world and storage identity instead of creating a run database with a hidden interval.
  • Lock-free frontend reads: the worker atomically publishes immutable Arc<AnalyticsSnapshot> latest-value state. GUI, TUI, and API consumers load it without a mutex and may skip stale snapshots; they never run SQL while rendering.
  • Hard-bounded SQL is refused: the dependency migration does not establish a guaranteed wall-clock stop across engine work or blocking I/O on the !Send + !Sync connection-owner worker. AsyncReadLane::open(path, maximum_duration) therefore still always returns a typed ReadExecutionBoundUnavailable before the path is opened or inspected; there is no async SQL escape hatch. Use AnalyticsSnapshotProvider::snapshot() for lock-free, non-SQL frontend latest-state access. Offline/reporting callers that can wait may use the synchronous, create-free, read-only StorageReader; its row limits bound results and allocation, not scan, aggregation, sort, open, close, or wall-clock work.

Tables and query examples

The V6 base schema run-scopes scientific and operational tables for matched-seed experiments. V7 adds the canonical host archive/ledger, V8 adds per-scientific-boundary domain evidence, and V9 adds normalized command records with separate application/storage transitions. Later migrations through the current V19 (SCRIPTBOTS_SCHEMA_VERSION) add replay interaction edges, command claims, full-text narrative search rebuilds, and the MAP-Elites archive. Unsupported pre-release data is refused rather than guessed or destructively rewritten. Use the result- and allocation-bounded typed command/domain readers above for journal evidence; those bounds do not promise a wall-clock execution deadline. The SQL below illustrates explicitly unbounded, run-scoped scientific reporting only.

Representative SQLite-compatible query shapes include:

-- Latest metrics snapshot
select name, value
from metrics
where run_id = ?1
  and tick = (select max(tick) from metrics where run_id = ?1)
order by name;

-- Top predators by average energy
select agent_id,
       avg(energy) as avg_energy,
       max(spike_length) as max_spike_length,
       max(tick) as last_tick
from agents
where run_id = ?1
group by agent_id
order by avg_energy desc
limit 10;

-- Event totals for a run report
select kind, sum(count) as total
from events
where run_id = ?1
group by kind
order by kind;

JSON replay payloads are validated by ScriptBots and stored as ordinary TEXT. Integer flags are decoded at the storage boundary into Rust booleans.

Offline narrative timelines

Use the finished database printed by the application to read the actual emergent-event explanations, including their stable identities, subjects, detection windows and numeric evidence:

sb-analyze runs/example.sqlite run narrative-timeline --params limit=100 --json narrative.json --md narrative.md
sb-analyze runs/example.sqlite run replay-timeline --params limit=100 --json replay.json

narrative-timeline uses report schema 2 and reads the typed run_events stream. Each JSON event contains identity and the complete record; run_id identifies the selected run. Its newest bounded page is returned in canonical chronological order. event_counts_scope: "returned_page" makes the kind-count coverage explicit, and truncated_to is set only after an additional stored event was observed. The default limit is 1,024; the maximum is 4,095, leaving one SQL row for that truncation check. An empty stream and an explicitly requested zero-length page are reported separately.

The former low-level replay payload remains available through replay-timeline at schema 1, including whole-run replay-kind counts and individual replay records. This is the schema migration for the narrative timeline; unrelated reports retain their existing versions. Both reports use the create-free finished-reader lease. For a multi-run database, select its canonical ID with --run-id.

To reconstruct the narrative independently from the complete recorded detector inputs, use:

sb-analyze runs/example.sqlite run narrative-reconstruct --params limit=100 --json reconstruction.json --md reconstruction.md

narrative-reconstruct replays every input through the production detector in bounded pages, preserves the recorded cadence and history, and returns the newest events in canonical order. Its event counts cover the complete run, including events evicted from the live event ring. The default output limit is 1,024 and the maximum is 4,096; limit=0 still validates and reconstructs the entire input stream. The version-2 JSON includes input provenance, coverage, output truncation, eviction counts, the number of effective policy changes and the final detector policy. Journal-authenticated changes to detector interval, history capacity and event capacity are applied at their completed tick boundaries. Shrinking a buffer keeps its newest entries; growing it preserves the available history. Disabling and re-enabling narration preserves event cooldowns and pending persistence records. Missing, corrupt or unauthenticated inputs are refused, so older databases without canonical detector inputs cannot use this report. Reconstruction uses the current detector implementation and does not assert historical equality across source revisions. Saved narrative outputs never supply its reconstructed events.

Streaming demographic and metric summaries

sb-analyze runs/example.sqlite summarize --epoch-size 100 --rolling-window 10 --json summary.json --md summary.md

Summaries read agent, metric and lineage inputs in pages of at most 1,024 rows. Per-epoch diet and brain counts represent recorded agent observations; repeated observations of an agent contribute separately. Two agent passes preserve the existing source-order means and sample standard deviations without retaining every raw sample.

The rolling window counts observations of each metric, including the current observation. Sparse tick gaps remain sparse. The pinned FrankenPandas rolling implementation processes each complete metric series, preserving its arithmetic across storage page boundaries. The final report, descendant graph and workspace for one metric series still require memory proportional to their sizes. Source paging does not impose a total-memory or SQL execution-time bound.

Matched-seed endpoint comparisons

Use compare-runs with a cohort manifest to compare independent simulation runs. Declare one endpoint tick and the complete family of metrics to test. Each run contributes exactly one observation per metric; longer trajectories and denser sampling do not increase the number of independent pairs.

For example, save this as runs/study.json, with database paths relative to that file:

{
  "schema": "scriptbots.run-comparison-cohort.v1",
  "endpoint_tick": 600,
  "metrics": ["total_energy", "average_energy"],
  "control": [
    {"db": "control-seed-7.sqlite"},
    {"db": "control-seed-8.sqlite"}
  ],
  "treatment": [
    {"db": "treatment-seed-8.sqlite"},
    {"db": "treatment-seed-7.sqlite"}
  ]
}
sb-analyze runs/control-seed-7.sqlite run compare-runs --params cohort_file=runs/study.json --json comparison.json --md comparison.md

Pairing uses the root seeds in revalidated run manifests, regardless of array order or filename. Every source must have completed its declared finite tick budget and contain every requested metric at the exact endpoint. An explicitly chosen endpoint may precede the terminal tick; a missing observation is refused instead of replaced with a recent sample. Duplicate seeds, unmatched seed sets, reused run identities, unattributed seed evidence and foreign-island data are also refused. Within each arm, launch configuration other than rng_seed, population recipe, scheduled interventions, brain roster, build identity and execution policy must agree. The selected CLI database/run must be one of the declared controls. Add "run_id": "<32 lowercase hex digits>" to each entry when its database contains multiple runs. A finished database can contribute several runs to either arm. Runs in the selected CLI database borrow its existing connection and file lease; inspecting them leaves the CLI's selected run unchanged. The selected run itself must appear among the declared controls.

The manifest is limited to 1 MiB, 128 pairs and 64 metrics. With at least two matched pairs, the report bootstraps paired endpoint differences, uses paired sign-flip tests and applies Benjamini–Hochberg FDR across the declared metrics. The machine output includes the exact endpoint values, source run IDs, seed and manifest/configuration digests, build provenance and resampling parameters.

For a descriptive comparison of just two runs, the existing form remains useful:

sb-analyze runs/control.sqlite run compare-runs --params treatment_db=runs/treatment.sqlite --params endpoint_tick=600 --json pair.json

For two runs in one database, use --run-id to select the control and --params treatment_run_id=<run-id> to select the treatment, with the same database path in treatment_db. The two run IDs must differ. Omitting a run ID in a multi-run source is refused, including when that source is already open.

endpoint_tick can be omitted when both runs share a terminal tick. This mode, and a cohort with only one matched pair, reports endpoint differences with inference_status: "insufficient_independent_pairs", null confidence intervals, null p-values and no FDR discoveries. Unknown or mismatched seed provenance is explicit in seed_pairing. Differences use shared endpoint metrics; conditionally emitted metrics found in only one run are disclosed in control_only_metrics or treatment_only_metrics and retained in that source's values. compare-runs now uses report envelope schema 2 and machine schema scriptbots.run-comparison.v2; consumers of the old trajectory-based inference must migrate to the cohort contract.

Pipeline and maintenance

  • A persistence transaction either commits the entire accepted batch or rolls it back; a failed statement may not leave the connection in an active transaction.
  • The published health snapshot exposes revision, last committed tick, committed agent count, admitted/applied/durable batch watermarks, structured last failure, and stopped state. GUI/TUI code derives lag from live and committed ticks without issuing SQL. Queue depth is not published yet.
  • The same-thread Storage boundary provides explicit flush, close/checkpoint, and VACUUM operations. The asynchronous pipeline currently exposes flush and shutdown barriers; maintenance must stay on the connection-owning worker and never run on a GUI/TUI paint path.
  • The exact-revision file-backed conformance test closes and reopens the database and verifies committed data and integrity. Dedicated durability and concurrent-reader/writer gates must use independent connections rather than sharing one connection across threads.

Development workflow

  • Coding standards: See RUST_SYSTEM_PROGRAMMING_BEST_PRACTICES.md. Embrace Result-based errors, clear traits, and avoid unsafe.
  • Linting: cargo clippy --workspace --all-targets --all-features -W clippy::all -W clippy::pedantic -W clippy::nursery
  • Formatting: cargo fmt --all
  • Tests: cargo test --workspace (simulation and GPUI tests will be added as systems land)
  • Profiles: Release uses LTO, single codegen unit, and abort-on-panic for optimal binaries.
  • rust-analyzer artifacts: The repository lsp.json configures Oh My Pi with cargo.targetDir = true at initialization and configuration updates. Analyzer checks and build-script/proc-macro builds use <Cargo target directory>/rust-analyzer, leaving ordinary CLI/RCH target selection unchanged. Other editors must set their equivalent rust-analyzer.cargo.targetDir option; they do not consume this file. Reload the affected language server after changing settings. This separates analyzer artifacts from agent builds, not different analyzer sessions from each other, and does not resolve package-cache locks or filesystem hangs.

Authoritative tracker triage

br sync --flush-only exports the tracked source of truth to .beads/issues.jsonl. Do not invoke BV directly in this repository: BV can silently prefer the separate .beads/beads.jsonl snapshot. Run every data-bearing robot command through the fail-closed integration instead:

scripts/bv_authoritative.sh --robot-triage
scripts/bv_authoritative.sh --robot-plan  # fails closed if BV and BR claim sets diverge
scripts/bv_authoritative.sh --robot-insights | jq '.status'
scripts/test_bv_authoritative.sh

The wrapper creates a unique external read-only view, forces JSON robot mode, and emits a result only after BR's ID/status/dependency-count projection agrees with the tracked export, BV's issue/status/blocking-edge counts and data_hash agree, BV's native actionable count agrees with its complete plan, and that plan covers every BR-ready issue. Because BV 0.16.0 includes in-progress work and uses different hierarchy semantics, its native actionable set need not equal br ready. Every BV next result and triage top pick must be BR-ready; an unscoped plan must equal the BR-ready set and a scoped plan must be its subset. Unsafe claim-oriented output fails closed. Graph-ranked recommendations may be blocked and never authorize a claim; br ready remains the sole actionability and claim authority. The wrapper refuses caller-selected databases/workspaces, missing or empty exports, non-JSON graph output, every unrecognized or mutating BV option, and a source export that changes during analysis. Historical --as-of sources are refused. Neither repository snapshot is overwritten or deleted.

BV history and diff are also refused until their handlers honor the explicitly isolated tracker source; otherwise a stale checkout snapshot can contaminate the result.

Testing & verification

  • Core tests: unit and property tests for reproduction math, spike damage, food sharing/consumption; determinism tests run seeded scenarios and assert stable summaries.
  • Render tests: GPUI compile-time view tests; terminal HUD headless smoke tests (SCRIPTBOTS_TERMINAL_HEADLESS=1).
  • Benchmarks: criterion harness for ticks/sec at various agent counts.
  • Batch verification: the pinned Doodlestein Self-Releaser (dsr) profile is the only build, lint, test, WASM, and release evidence lane. Hosted workflow results are not used.

Performance & profiling

  • CPU profiling (Linux/macOS): run with RUSTFLAGS='-g' and use perf record/perf report or dtrace/Instruments; annotate hot paths in sense/actuation.
  • Tracy (optional): integrate client in dev builds to visualize frame times and background worker activity.
  • Threading: tune RAYON_NUM_THREADS to match physical cores; verify determinism with seeded runs.
  • Rendering: measure Lab/canvas frame times; avoid per-frame allocations; prefer batched path building.
  • Built-in tools:
    • --profile-steps N and --profile-storage-steps N to run headless micro-benchmarks
    • --profile-sweep N and --auto-tune N to explore and auto-pick thread/flush settings
    • --renderer-safe for a conservative paint path; --debug-watermark overlays a diagnostics badge
  • Low-power mode: in addition to capping threads (--low-power), the app lowers OS process priority (Unix niceness +10; Windows BELOW_NORMAL) to be a better background citizen.

Tracing & logging

  • Logging uses tracing with RUST_LOG filters (e.g., RUST_LOG=info,scriptbots_core=debug).
  • Categories of interest:
    • scriptbots_core::world — tick summaries, seeding, closed/open flips
    • scriptbots_storage — transaction attempts, structured worker errors (including commit state), committed-tick publication, and flush/shutdown receipts. The GUI/TUI derive live-versus-committed lag from the published snapshot; no queue-depth metric is exposed yet.
    • scriptbots_app::servers — REST and MCP server lifecycle, tool invocations
    • scriptbots_render — window lifecycle, input bindings
  • Prefer structured fields (e.g., tick = summary.tick.0) for machine-readable logs. Avoid panics in production; release profile uses panic = abort.

Runtime control surfaces

For an interactive run, ScriptBots parses the control environment and transactionally reserves every enabled REST/MCP socket before writing config output, tuning, changing process priority, constructing the world, or reserving FrankenSQLite storage. The runtime adopts those exact listeners. REST and MCP are supervised independently; an unexpected exit from either stops the other, publishes failed health, and causes the active TUI, GPUI, or Bevy frontend to return the preserved root error.

REST Control API (with Swagger UI)

  • Default address: http://127.0.0.1:8088 (override SCRIPTBOTS_CONTROL_REST_ADDR)
  • Swagger UI path: /docs (override SCRIPTBOTS_CONTROL_SWAGGER_PATH)
  • OpenAPI JSON: /api-docs/openapi.json
  • Enable/disable: SCRIPTBOTS_CONTROL_REST_ENABLED=true|false
  • Endpoints:
    • GET /api/knobs → list flattened config knobs
    • GET /api/config → fetch entire config snapshot
    • PATCH /api/config → apply JSON object patch { ... }
    • POST /api/knobs/apply → apply list of { path, value } updates
    • GET /api/ticks/latest → latest tick summary (JSON)
    • GET /api/ticks/stream → server-sent events stream of tick summaries (SSE)
    • GET /api/ticks/ndjson → newline-delimited JSON stream of tick summaries (NDJSON)
    • GET /api/screenshot/ascii → the last presented terminal frame, including all panels (text/plain); ?format=ansi preserves colors and text styles. Both formats return x-scriptbots-frame-schema: scriptbots.terminal-frame.v1, x-scriptbots-frame-format, x-scriptbots-frame-tick, and x-scriptbots-frame-size (WIDTHxHEIGHT). The default remains plain text; unknown formats return 400 and a process without a presented terminal frame returns 409.
    • GET /api/screenshot/png → offscreen PNG snapshot (requires GUI feature)
    • GET /api/hydrology → hydrology snapshot (flow directions, accumulation, basins) if available
    • GET /api/events/tail → recent events (birth/death/combat) ring buffer
    • GET /api/scoreboard → top carnivores and oldest agents at a glance
    • GET /api/agents/debug → lightweight agent debug table (filters: ids, diet, selection, brain)
    • POST /api/selection → queue a selection update (modes: set/add/clear; optional state: none|hovered|selected)
    • GET /api/presets → list scenario presets
    • POST /api/presets/apply → apply preset by name
    • GET /api/config/audit → recent config patches (audit ring buffer)
    • GET /api/scenario → the launch scenario identity bound to this run
    • GET /api/ws/stream → negotiated binary telemetry, canvas and narrative subscriptions with acknowledged JSON controls
    • GET /api/narrative/search → search the recent birth/death/combat narrative
    • POST /api/v1/experiments → start a matched-seed batch (variants × seeds, ticks_per_run) that executes on a background worker; GET /api/v1/experiments/{id} reports per-run state, final digest and bundle path; POST .../cancel stops active runs between durable ticks and prevents another wave; POST .../resume continues pending runs and unfinished runs from validated owner/journal cuts, and recovers verified completed bundles saved before their final status write. Missing or incompatible cuts are refused. Arms support MLP, DWRAON and Assembly; builds with --features brain-ft additionally accept ft or frankentorch, recorded canonically as ft. The same compiled adapter restores continuation cuts and independently verifies the final bundle state. A build without brain-ft refuses these arms before starting a worker or writing files.
    • POST /api/v1/experiments/{id}/compare → compare one canonical endpoint metric across two completed variant cohorts using verified bundles and exact matched seeds.
    • POST /api/v1/checkpoints → capture a WorldCheckpointV1 and record it in the run database (usable by --checkpoint-start); GET /api/v1/checkpoints, /api/v1/artifacts
    • Playback aliases (two-axis command status): POST /api/pause, POST /api/resume, POST /api/step, POST /api/speed, and GET /api/status
    • Playback (two-axis command status): POST /api/control/pause, POST /api/control/resume, POST /api/control/step, POST /api/control/speed, POST /api/control/shutdown, and GET /api/control/status/{command_id}

WebSocket control protocol version 1 accepts JSON text such as:

{"protocol_version":1,"request_id":"my-step-42","command":"step"}

Commands are pause, resume, step, speed (with a finite nonnegative speed), and status (with the returned command_id). Replies contain protocol_version, request_id, and either type: "receipt" with the canonical two-axis receipt, or type: "error" with an HTTP-style status and diagnostic message. Admission does not establish application or durability. Use status or the REST command-status endpoint to observe those independent outcomes.

For mutating commands, request_id is the host's idempotency key. Reuse the same ID and command after a lost response or reconnect to the same host session: a step is applied at most once while its identity remains in the host ledger. Reusing an ID with a different command returns 409. IDs share the canonical HTTP/MCP key namespace and must contain 1–1,024 bytes after trimming. A new host session has a new identity namespace; this is not cross-session deduplication. Plain pause, resume, and step, and unkeyed JSON controls remain available; each unkeyed submission is a new command. An omitted version means version 1.

Inbound control messages and frames are limited to 16 KiB. Invalid JSON, unsupported versions, unknown commands and unrelated fields are refused before admission; invalid input cannot silently become a step. A malformed request has a null reply ID because no validated identity was admitted. Client binary control frames receive an explicit refusal. Before a subscription is negotiated, the server sends Postcard-encoded TickSummaryDto values at a 50 ms sampling cadence.

Resumable SSE and NDJSON monitoring

GET /api/ticks/stream (SSE) and GET /api/ticks/ndjson provide two explicit monitoring modes. With no cursor, or with after_tick=N, they send canonical tick summaries and catch up from the bounded retained history. Every unavailable tick range is reported as a gap with inclusive first_missing/last_missing values, including an empty history ring or gaps between retained samples. These streams are observations, not durable replay journals.

Use after_revision=0 to select latest-publication mode. It includes owner changes while science remains paused, such as speed, control revision, health and lifecycle. Each JSON record has schema: "scriptbots.tick-publication.v1", the canonical tick summary, observed playback, health and lifecycle, plus decimal-string session, publication, scientific, control and config revisions. coalesced_publications counts revisions skipped since the previous cursor; the server does not invent historical publications from tick summaries.

curl -N 'http://127.0.0.1:8088/api/ticks/stream?after_revision=0'
curl -N 'http://127.0.0.1:8088/api/ticks/ndjson?after_revision=42&session_id=891'

SSE publication records use event name publication and an ID such as pub:891:42. An EventSource reconnect's Last-Event-ID supersedes its original revision query, preserving the consumed session and revision. Manual clients resume using both after_revision and its original session_id. An omitted session binds a new connection to the current owner; it does not establish cross-session continuity. A foreign session or future revision returns HTTP 409 before streaming. Conflicting cursor modes, malformed reconnect IDs and zero session identities return 400. The legacy explicit after_tick query continues to override a tick reconnect header.

Publication mode samples at 250 ms and retains at most one prepared publication per consumer. Same-revision polls produce nothing. If the source becomes unavailable or changes session after connection, the stream emits a typed error record and closes; clients must handle that refusal explicitly.

Browser creature selection and inspection

Click a creature in either Canvas 2D or WebGPU, or enter its stable decimal UID in Creature Inspector. Both renderers highlight the selected creature. The panel reports health, age, generation, energy, lifetime net food balance, reproduction progress, lineage, sensory traits, and the brain's recorded inputs and outputs. Selection and inspection are presentation operations and do not advance the simulation.

Local viewing reads the WASM owner's completed boundary through SimHandle.inspectAgent(uid). Remote viewing uses GET /api/agents/inspect?uid=UID&session_id=SESSION&epoch=EPOCH under the existing Host and Origin policy. The result identifies its owner, epoch, inspected tick, publication and scientific revisions with exact decimal strings. The panel distinguishes an owner observation from the displayed frame and discards replies from a previous selection, reset, owner or epoch. Missing creatures and source changes are explicit states.

Automatic refresh is limited to four reads per second, with one current request; remote reads have a two-second client timeout and a 16 KiB response limit. The native owner query has a 250 ms deadline. The projection contains fixed signal arrays and a bounded brain label; it does not load genomes or histories, so basic inspection also works for brains without a genome-locus browser schema.

Expand Brain activity and output explanations to inspect the selected creature's named layers, signed activation heatmap, exact node values, actual connection weights and canonical output channels. Connection pages retain the original weights, and view navigation does not request another observation. Local WASM uses SimHandle.inspectBrain(uid); remote viewing uses GET /api/agents/brain?uid=UID&session_id=SESSION&epoch=EPOCH. Both expose the same bounded owner projection and explicitly identify retained evaluator state versus verified feed-forward reconstruction.

Brain reads stop while the panel or page is hidden. The panel permits one current request, refreshes at most four times per second when publications advance, and rejects late selection/source replies. Remote brain responses have a separate 512 KiB streamed ceiling. Heatmaps contain at most 64 by 64 cells. Core graph clipping, unavailable activity, numerical overflow and exhausted explanation work are visible outcomes; none is presented as a complete input explanation. Path attribution additionally caps edge examinations, pending paths and retained contribution rows, so dense cyclic graphs cannot expand without a fixed bound.

DSR passed all 36 Node tests, JavaScript syntax checks and changed Rust formatting. It type-checked the current core library and complete runtime test source using the pinned compiler and retained locked Cargo dependencies. All 16 tests in the actual final attribution module passed against verified unchanged shared types; this isolated module lane does not qualify current-core integration. Full web and app Cargo checks were attempted but killed by the host memory limit in core and asupersync respectively. WASM, actual DOM/WebGPU journeys, HTTP integration and the authored native owner execution regressions remain unqualified.

Remote browser viewing and stream subscriptions

The web demo's Remote Server controls connect its existing Canvas 2D or WebGPU renderer to a native server. Enter the server's WebSocket URL, then choose Connect to Server. The browser freezes its local simulation while displaying the remote world; Return to Local Simulation explicitly resumes that saved local owner. Server pause, resume and single-step commands have retry identities, and the UI displays the application and journal states actually returned in their receipts. Refresh Command Outcome observes later settlement; Retry Last Command with Same ID recovers a lost receipt without inventing a new step. PNG export uses the displayed remote frame's exact host and revision identity. Build the WASM package from the same source as the viewer and server.

Browser origin checks also apply to WebSocket upgrades. If the static demo is served from a different origin, include that exact origin in SCRIPTBOTS_CONTROL_ALLOWED_ORIGINS; use wss:// when the browser's HTTPS policy requires it. Existing Host/origin validation remains in force.

Send a subscription as JSON text:

{"protocol_version":1,"request_id":"viewer-1","command":"subscribe","channels":["canvas","telemetry","events"],"max_fps":60}

The server acknowledges with type: "subscribed", the correlation request_id, protocol_version: 1, stream_protocol_version: 2, decimal-string session_id, selected channels, and max_fps. Ignore any initial binary summaries until that acknowledgment. Every subsequent binary message begins with ASCII SBWS, a little-endian u16 version (2), and exactly one Postcard RemoteFrame from scriptbots_runtime::remote. Its identity contains the actual host session, publication, scientific, control and configuration revisions, and completed tick. Every frame also carries observed playback state and coalesced_publications. The WASM decode_remote_frame_binary export validates this envelope and exposes all identity/cursor integers as decimal strings under schema: "scriptbots.remote-frame.v2". The dynamic canvas payload preserves the existing world-v2 schema used by both renderers. Stream v2 also carries a bounded environment overview from that same publication. JSON controls, subscriptions and consumption acknowledgments remain protocol version 1. Rebuild the server, WASM decoder and browser together; binary stream v1 is rejected explicitly.

Channel Payload and delivery behavior
telemetry Canonical TickSummaryDto from one host publication; latest value only.
canvas Complete dynamic-world snapshot plus coherent terrain, food and water-depth overview; latest value only, including paused control changes.
events Up to 64 canonical narrative records, oldest first, with session-bound sequence numbers and an exact missing-prefix gap when retention overtakes a reader. Backlogged pages drain even while science is paused.

Subscriptions contain one through three unique channels. Omitted channels do no projection work. max_fps defaults to 60 and accepts 1–120; it bounds sampling frequency, not simulation speed. Binary frames are capped at 8 MiB, canvas frames at 65,536 agents, and narrative pages at 64 records with bounded text. An unrepresentable source is refused instead of silently truncated. The shared decoder rejects unknown versions, trailing data, invalid lengths, non-finite presentation values, mismatched ticks and noncontiguous event pages. Environment overviews contain at most 128 × 128 cells and must cover the exact source world. Small grids retain every cell; larger grids select the source cell at each overview cell's center. This sampling is labelled and does not replace metrics with inferred averages. Terrain, food and hydrology revisions remain exact decimal strings at the JavaScript boundary. Other stream channels carry no environment.

Each channel has one consumption credit. After consuming a frame, acknowledge its exact identity before another frame in that channel can be sent:

{"protocol_version":1,"command":"stream_ack","session_id":"891","channel":"canvas","publication_revision":"42"}

For events, also include after_event as a decimal string: the last record's sequence, the declared gap's last missing ordinal if the page has no records, or the page's unchanged cursor if it is empty. Canvas and telemetry acknowledgments must omit that field. The supplied browser client sends this acknowledgment only after synchronous validation and consumption. A wrong, duplicate or expired acknowledgment closes the stream; it never releases another channel's credit. Subscription replacement requires all outstanding frames to be acknowledged.

One control request per connection may wait for its owner receipt while frame acknowledgments and subscription messages continue to be processed. A further valid control request receives a correlated 429 response; retry it after the pending reply, preserving its request identity. Disconnect cancels control work that is still queued for a blocking worker. Work already admitted by the owner may finish, so recover its outcome with the same retry identity after reconnect.

Each connection prepares at most one frame per selected channel from an immutable publication and has one socket write in flight. Until the browser consumes that frame, newer publications coalesce in the host's latest-value slot. This also bounds traffic entering a browser whose main thread has fallen behind. No per-tick snapshot queue or simulation lock is retained. Projection, socket writes and consumption acknowledgments each have a five-second deadline; expired credit is checked at the next sampling boundary. Queued blocking preparation is cancelled when the connection closes or its preparation deadline expires. Missed timer intervals are skipped. Preparation/write work or observed consumption round trips exceeding the current sample interval back sampling off to twice the observed duration, capped at one second. Eight cheap samples permit a 25% recovery toward the requested rate. A stream_rate JSON notice reports the requested/effective intervals in microseconds and the slow_consumer or recovering decision. Snapshot frames report skipped revisions; narrative frames preserve contiguous records or explicitly declare retention loss.

For reconnect, retain only frames successfully consumed by the client and send their session-bound cursors:

{"protocol_version":1,"request_id":"viewer-resume","command":"subscribe","channels":["canvas","events"],"max_fps":60,"resume":{"session_id":"891","after_revision":"42","after_event":"7"}}

Use the minimum last-consumed revision across enabled latest-value channels. Foreign sessions or future cursors return 409 and leave an existing subscription unchanged. Narrative pages report after_event, earliest_retained, latest_event, optional gap, and sequenced records; accepting a gap explicitly advances past that unavailable prefix. The browser reconnects only on request, retains exact cursors, and never silently retries a command or discards a changed host session. A fresh Connect to Server is the explicit choice to start without old cursors.

This provides the functional versioned transport and browser consumer under bd-ac4l. It samples the latest publication; event-driven sub-16 ms delivery, multi-client soak/latency measurements and the full original DSR/hardware acceptance remain open. A requested 60 Hz rate is not measured latency evidence.

The REST step routes (/api/step and /api/control/step) accept an Idempotency-Key header, and MCP step accepts idempotency_key. For count: 1 (the default), the same key returns the same host receipt even when retrying through a different transport, including WebSocket. Counts must be integers in 1–100,000; malformed counts or unknown step fields are refused before admission. A key with count > 1 is refused because a batch still consists of independent commands and has no atomic retry identity. For retryable batches, submit one step per distinct key. Unkeyed batches remain available and return only the last step's receipt, which does not establish the outcome of the whole batch.

GET /api/v1/checkpoints also reports actual file/SQL usage, observed file high-water counts, pending request identities, retained directory leases and their limit, and inventory/query errors. Checkpoint quota exhaustion returns HTTP 507; an unconfirmed file/storage receipt returns HTTP 503 and retains the exact request for retry. Changing artifact directories keeps earlier occupancy and leases charged; the count policy also bounds retained directory bookkeeping, with room for the initial and configured roots. Reusing an already leased directory remains possible at that limit. Startup counts existing binary artifacts without labelling them current-run checkpoints. Set SCRIPTBOTS_ARTIFACTS_DIR for an explicit directory; otherwise each control service reserves a unique temporary directory. Files, including partial failed captures, are never automatically removed or overwritten.

Completed experiment bundles expose these final-state outcomes in exports/summary.csv. The same metric names are available to Lab proposals, paired analysis and notebook reports:

Metric Observation at the final tick Empty population
alive_agents Number of living agents 0
total_energy Sum of living agents' energy reserves 0
average_energy Mean living-agent energy Unavailable
average_health Mean living-agent health Unavailable
mean_age Mean current age counter Unavailable
max_age Largest current age counter Unavailable
max_generation Largest living lineage generation Unavailable
total_food Sum of current food-grid cell values Observed grid total

Age counters advance at the configured aging cadence. Agent measurements use f64 reductions in stable agent-UID order; food uses row-major cell order. The portable verifier recomputes these observations from the final checkpoint and requires exact canonical summary bytes. Lab takes its analysis values from that verified projection and checks the selected manifest and summary digests. A proposal can request, for example, "metrics": ["average_energy", "total_food"]. Every requested endpoint must be available in every matched run. Unavailable population statistics use empty CSV cells and cause analysis to refuse that requested metric; they are never replaced with zero.

Lab proposals can also compare executable brain families directly:

{
  "hypothesis": "MLP and DWRAON differ in final energy under the same environment",
  "falsifier": "The paired energy difference remains compatible with zero",
  "factors": [],
  "brain_families": ["mlp", "dwraon"],
  "seeds": {"base": 41, "count": 8},
  "ticks_per_run": 1000,
  "metrics": ["average_energy", "total_food"],
  "budget": {"runs": 16, "ticks": 16000}
}

Omitting brain_families selects the existing MLP default. The proposal tool lists the canonical families installed in the current build; accepted aliases resolve through the runner's registry. Unknown or unavailable families and duplicate aliases are refused before execution. Configuration-factor combinations expand in declaration order, with families and then intervention schedules inside each combination. Every arm receives the same seed cohort. Run and tick budgets include the full product, subject to the existing 32-arm ceiling. Empty factors requires at least two distinct families or schedules. The first expanded arm is the statistical control; every later arm is compared with it through the existing matched-seed analysis. Result ingestion and notebook reproduction bind each arm to its actual family, launch configuration and exact ordered schedule.

The experiment REST API (POST /api/v1/experiments) and MCP experiment_create also accept timed configuration treatments on each variant:

{
  "experiment_id": "food-pause-recovery",
  "variants": [
    {"variant_id": "control", "brain_family": "mlp", "config_overrides": {}},
    {
      "variant_id": "pause-recovery",
      "brain_family": "mlp",
      "config_overrides": {},
      "interventions": [
        {"tick": 0, "set": {"food_growth_rate": 0.0}},
        {"tick": 500, "set": {"food_growth_rate": 0.04}}
      ]
    }
  ],
  "seeds": [41, 42],
  "ticks_per_run": 1000,
  "max_concurrency": 2
}

tick names a completed-tick boundary: tick 0 applies before the first science step. Statements must be in nondecreasing tick order, with every tick strictly before ticks_per_run; statements at the same tick execute in document order. Each arm admits at most 64 statements, each at most 4,096 canonical JSON bytes. The set object uses nested configuration keys and accepts exposed numeric live knobs. Every cumulative patch must satisfy the existing type, range and complete configuration constraints before the batch creates files or starts workers.

Schedules participate in arm identity and saved plan checks. The original launch configuration stays in the manifest alongside the full treatment declaration. Resume verifies completed input receipts and the exact remaining queue, then continues it without reapplying completed treatments. Portable verification checks that same evidence and the resulting config before recomputing the final science digest and endpoint summary.

Lab proposals expose the same treatments through intervention_schedules, an ordered list of at most eight schedules. Omission defaults to [[]], one untreated schedule. Put an empty schedule first to compare delayed treatments against an untreated control. For example:

{
  "hypothesis": "Pausing food growth changes final food availability",
  "falsifier": "Matched-seed total-food differences remain compatible with zero",
  "factors": [],
  "brain_families": ["mlp"],
  "intervention_schedules": [
    [],
    [
      {"tick": 0, "set": {"food_growth_rate": 0.0}},
      {"tick": 500, "set": {"food_growth_rate": 0.04}}
    ]
  ],
  "seeds": {"base": 41, "count": 8},
  "ticks_per_run": 1000,
  "metrics": ["total_food", "alive_agents"],
  "budget": {"runs": 16, "ticks": 16000}
}

The runner preflights every expanded treatment before execution. Lab ingestion requires the bundle's schedule to equal the planned arm, and notebook reproduction re-executes that schedule. Lab scientific-row provenance is now version 4 and the reproduction input envelope is version 2. Earlier provenance is explicitly not comparable; changing a schedule cannot be hidden by retaining the same launch configuration. Reproduction inputs are bounded to 32 MiB before output is written.

The summary now declares schema_version=2, bound by scriptbots.experiment-run-evidence.v2. Verification and completed-run recovery refuse earlier V1 experiment summaries/evidence. Existing files are preserved; there is no implicit conversion to the new measurement contract.

For experiment recovery after a server restart, configure the same explicit SCRIPTBOTS_ARTIFACTS_DIR. Experiment creation saves a versioned, checksummed definition before starting its worker. List/status discover those definitions without starting science; unfinished jobs report stopped until an explicit POST /api/v1/experiments/{id}/resume. The original create payload is no longer required. Keyed create retries recover their admitted ID and still reject a changed payload. Discovery admits at most 1,024 experiments and reads at most 1 MiB per definition, with the runner's existing plan/build, status, checkpoint and bundle checks retained. These are input bounds, not filesystem deadlines. Corrupt, foreign and incomplete definitions produce an error and preserve their files; direct status access to a healthy companion remains available. Older directories without a definition require explicit reconciliation. Checksums detect corruption and do not authenticate an artifact's author. Complete resource/fault/platform qualification remains open under bd-2z0.5.11; see the current reality check.

Resume also recovers a complete interrupted status publication when it is the exact initial state or the valid immediate successor of the committed status. Any claimed completion is verified against its bundle and restored owner cut before publication. Exports are assembled in <run_id>.bundle.tmp, verified against the exact final checkpoint, synchronized, and renamed to the final directory. A complete staged export can be promoted; one incomplete export is retained as <run_id>.bundle.interrupted and rebuilt from that final checkpoint without rerunning ticks. A second partial incident, unsafe paths, conflicting status, or an invalid checkpoint produces a refusal and preserves the evidence. Existing final bundle directories are never overwritten; legacy incomplete final directories still require explicit reconciliation.

Completed experiment files also reappear through artifact list/get/download after restart, using their original IDs. A first request verifies the saved scientific evidence and complete bundle before publishing its files; no create or resume request is required. Whole-list discovery reports an invalid saved batch, while a known ID from another healthy batch remains readable. Successful publication is cached by saved status generation; downloads still check the file size, BLAKE3 and SHA-256. These reads neither run the experiment nor rewrite its status.

Cancellation is cooperative: a request can report cancelling while the current host or checkpoint operation finishes. A successfully stopped unfinished batch reports cancelled; its unfinished run records retain running, with actual progress in validated owner/journal cuts for resume. A batch that finishes before the request takes effect still reports completed.

Read per-run checkpoint progress through GET /api/v1/experiments/{id}, MCP experiment_status, or control_cli experiment status ID. Each run includes target_ticks, the validated plan's requested horizon, and a separate typed checkpoint_progress:

  • state: "observed" supplies the saved tick, a checkpoint_digest containing the BLAKE3 of the complete encoded checkpoint, and its observation source. source: "published" means the runner successfully wrote, synced and published that cut. source: "recovered" means the runner read an existing committed cut, validated its plan/run/build/family identities, and restored its world, owner and journal without advancing science.
  • state: "unavailable" identifies not-started work, a pending publication or recovery, or a missing committed checkpoint. It does not imply tick zero.
  • state: "refused" distinguishes invalid or unreadable checkpoints and conflicting observations. Explicit resume retries repaired cuts through the existing validation path.

total_ticks remains terminal status evidence and stays zero for pending and running records, including cancelled unfinished runs. For example, a running record can have total_ticks: 0, target_ticks: 1000, and an observed checkpoint at tick 317. The terminal Experiments screen displays this as Saved/Target; an unavailable observation stays unavailable instead of becoming a zero estimate.

Active status polls read a bounded latest-value cache. A stopped detail request recovers at most one cold checkpoint, with at most one recovery in flight per runner; repeat detail requests to observe additional retained cuts. Summary listings perform no checkpoint recovery. These bounds do not impose a filesystem deadline. An observation describes the exact previously seen cut, not continuous integrity verification of its current file; downloads and resume retain their own validation. Progress reads neither advance science nor rewrite saved status.

Experiment create and resume share one execution budget across REST, MCP and cloned control handles. Each worker reserves the smaller of its concurrency and unfinished-run count, and keeps those slots through preparation and artifact publication. Exhaustion returns REST 503 or an actionable MCP tool result with isError=true before admitting a new job; a refused resume preserves its saved state. Retry after slots are released. Exact keyed retries of an existing job remain readable at capacity. GET /api/v1/experiments includes execution_capacity: max_run_slots, reserved_run_slots and reserved_batches. Reservations are not a measurement of simultaneous science activity. This budget does not bound Rayon threads, other processes, disk bytes or executing filesystem/host-call duration.

Completed experiment variants can be compared directly through the terminal's Experiments screen, MCP experiment_compare, or this read-only analysis endpoint:

curl -s -X POST http://127.0.0.1:8088/api/v1/experiments/food-pause-recovery/compare \
  -H 'content-type: application/json' \
  -d '{"baseline_variant":"control","challenger_variant":"pause-recovery","metric":"alive_agents"}'

For MCP, call experiment_compare with the same three fields plus "experiment_id": "food-pause-recovery". tools/list publishes the supported metric names from the runner's canonical endpoint contract. All four fields are required; unknown fields, invalid IDs and equal variants are refused. The result has the same comparison and provenance fields as REST, so an agent can create a batch, observe completion and compare its outcomes through one MCP connection.

Both selected variants must contain the complete planned seed cohort at the same final tick. Each retained bundle is verified and its final checkpoint is restored before observed endpoint values enter the existing matched-seed statistics engine. Missing, incomplete, changed or non-finite evidence is refused. The request requires an explicit supported metric; the terminal uses alive_agents, including the measured zero population after extinction.

The response identifies the experiment, plan digest, status generation, exact matched seeds and endpoint tick. It reports challenger minus baseline as mean_difference, optional ci_95, optional paired Cohen's dz as standardized_effect, and paired sign-flip p-values with the existing multiplicity adjustment. A one-seed result has descriptive_only: true and null inferential fields. Zero-spread standardized effects and small cohorts retain their explicit undefined/underpowered reasons. Each request analyzes one metric and one variant pair; separate requests are separate analyses.

Comparison work shares a single admission slot across terminal, REST and MCP callers. An occupied slot returns REST 503 or an actionable MCP tool result with isError: true; the slot remains held until admitted work finishes, including after a client disconnects. REST also bounds requests before its blocking-worker queue and limits the JSON body to 4 KiB. MCP uses the server's existing serialized session dispatch. Analysis does not advance or modify the live world.

GET /api/status and MCP get_status report one immutable owner publication: paused, lifecycle, tagged health (including blocker/fault detail), last_applied_command, command_queue_depth, and snapshot_revision, alongside tick, population, closed-world mode, and configuration revision. These are observed states, not queued intentions. A busy owner may leave the last publication unchanged; an applied command identity does not establish journal durability. Use the two-axis command status endpoint for that command's independent journal outcome.

Every route above is registered in the published OpenAPI document, so /docs and /api-docs/openapi.json are the authoritative, machine-readable version of this list.

Examples:

# Filter debug table by selected agents only, limit 20, sort by age
curl -s 'http://127.0.0.1:8088/api/agents/debug?selection=selected&limit=20&sort=age' | jq .

# Select a cohort (replace selection with ids [1,2,3])
curl -s -X POST http://127.0.0.1:8088/api/selection \
  -H 'content-type: application/json' \
  -d '{"mode":"set","agent_ids":[1,2,3]}'

# Add agents to current selection and mark them highlighted
curl -s -X POST http://127.0.0.1:8088/api/selection \
  -H 'content-type: application/json' \
  -d '{"mode":"add","agent_ids":[4,5],"state":"highlighted"}'

More examples:

# List and apply a preset via REST
curl -s http://127.0.0.1:8088/api/presets | jq
curl -s -X POST http://127.0.0.1:8088/api/presets/apply -H 'content-type: application/json' -d '{"name":"arctic"}' | jq .

# Recent events (tail)
curl -s 'http://127.0.0.1:8088/api/events/tail?limit=10' | jq .

# Scoreboard (top predators, oldest agents)
curl -s 'http://127.0.0.1:8088/api/scoreboard?limit=10' | jq .

# SSE tick stream (press Ctrl+C to stop)
curl -N -H 'Accept: text/event-stream' http://127.0.0.1:8088/api/ticks/stream | sed -n '1,10p'

REST quickstart:

# 1) Start the app
cargo run -p scriptbots-app

# 2) Open Swagger UI in a browser
#    http://127.0.0.1:8088/docs

# 3) List knobs
curl -s http://127.0.0.1:8088/api/knobs | jq '.[0:10]'

# 4) Patch configuration (enable NeuroFlow, set layers, activation)
curl -s -X PATCH http://127.0.0.1:8088/api/config \
  -H 'content-type: application/json' \
  -d '{"patch":{"neuroflow":{"enabled":true,"hidden_layers":[64,32,16],"activation":"relu"}}}' | jq .

# 5) Apply typed updates
curl -s -X POST http://127.0.0.1:8088/api/knobs/apply \
  -H 'content-type: application/json' \
  -d '{"updates":[{"path":"food_max","value":0.6}]}' | jq .

# 6) Stream ticks as NDJSON (Ctrl+C to stop)
curl -s http://127.0.0.1:8088/api/ticks/ndjson | head -n 5

# 7) Save the presented terminal frame as text or ANSI; PNG requires the GUI feature
curl -s http://127.0.0.1:8088/api/screenshot/ascii > frame.txt
curl -f 'http://127.0.0.1:8088/api/screenshot/ascii?format=ansi' > frame.ans
curl -s http://127.0.0.1:8088/api/screenshot/png > frame.png

Example PATCH body:

{ "food_max": 0.6, "neuroflow": { "enabled": true, "hidden_layers": [64,32,16], "activation": "relu" } }

Control CLI (scriptbots-control)

  • Points to the REST API (default SCRIPTBOTS_CONTROL_URL=http://127.0.0.1:8088):
cargo run -p scriptbots-app --bin control_cli -- list
cargo run -p scriptbots-app --bin control_cli -- get
cargo run -p scriptbots-app --bin control_cli -- set neuroflow.enabled true
cargo run -p scriptbots-app --bin control_cli -- patch '{"food_max":0.6}'
cargo run -p scriptbots-app --bin control_cli -- watch --interval-ms 750
# `--db` is required: paste the exact path printed as `Run database: ...` by the file-mode app.
# `--out` must name a fresh path; export refuses every existing file, symlink, or database sidecar.
RUN_DB='runs/scriptbots-1773264512345-4242.sqlite' # example shape; replace with the printed path
cargo run -p scriptbots-app --bin control_cli -- export metrics --db "$RUN_DB" --last 1000 --out latest_metrics.csv
# Births, deaths and aggregate combat from the durable host journal (a finished run; payload_json per row):
cargo run -p scriptbots-app --bin control_cli -- export domain-events --db "$RUN_DB" --last 100000 --out domain_events.csv
# New commands:
cargo run -p scriptbots-app --bin control_cli -- presets
cargo run -p scriptbots-app --bin control_cli -- apply-preset arctic
cargo run -p scriptbots-app --bin control_cli -- screenshot --out screenshots/frame_0001.txt
cargo run -p scriptbots-app --bin control_cli -- screenshot --ansi --out screenshots/frame_0001.ans
cargo run -p scriptbots-app --bin control_cli -- screenshot --png --out screenshots/frame_0001.png
cargo run -p scriptbots-app --bin control_cli -- hydrology

set, patch and apply-preset print the owner's command receipt, including separate application and journal states. Follow the printed lookup-status command against the same server; use get to inspect the resulting configuration. An admission receipt alone does not prove application or durable storage. Configuration patches carry the revision of the configuration they were merged against. If another client changes it before application, the owner returns config_revision_conflict; read the current configuration and submit a fresh patch to retain the intervening edit. Playback-only changes do not invalidate that guard.

Experiments from the shell

The control CLI exposes the same matched-seed experiment service as REST and MCP. Save an experiment request such as the food-pause-recovery example above to experiment.json, then submit it to a running server:

cargo run -p scriptbots-app --bin control_cli -- \
  --idempotency-key food-study-1 experiment create --file experiment.json
cargo run -p scriptbots-app --bin control_cli -- experiment list --limit 20
cargo run -p scriptbots-app --bin control_cli -- experiment status food-pause-recovery
cargo run -p scriptbots-app --bin control_cli -- experiment compare food-pause-recovery \
  --baseline control --challenger pause-recovery --metric alive_agents

create --file - reads one bounded JSON request from standard input. List output retains the server's opaque next_cursor; pass that value unchanged with --cursor to request the next page. Successful commands print the complete JSON result so scripts can inspect run state, execution capacity and comparison provenance. Server refusals retain their status and response body in the reported error. Comparison requires both selected cohorts to be complete and passes through the existing bundle and checkpoint verification.

Use experiment cancel ID to request a cooperative stop and experiment resume ID to continue the saved batch. Cancellation can return cancelling, and a batch that already finished can still report completed; inspect experiment status ID for the observed outcome. Resume uses the validated saved owner/journal cuts and does not start an unrelated run. Reuse the original create payload and --idempotency-key after a lost create response.

Checkpoints and artifacts from the shell

The same control CLI captures checkpoints and discovers retained artifacts. Use the identifiers returned in the JSON output for status and download requests:

cargo run -p scriptbots-app --bin control_cli -- \
  --idempotency-key baseline-cut-1 checkpoint create --description "Before treatment"
cargo run -p scriptbots-app --bin control_cli -- checkpoint list --limit 20
cargo run -p scriptbots-app --bin control_cli -- checkpoint status CHECKPOINT_ID
cargo run -p scriptbots-app --bin control_cli -- checkpoint download CHECKPOINT_ID \
  --out runs/baseline.checkpoint
cargo run -p scriptbots-app --bin control_cli -- artifact list --limit 20
cargo run -p scriptbots-app --bin control_cli -- artifact status ARTIFACT_ID
cargo run -p scriptbots-app --bin control_cli -- artifact download ARTIFACT_ID \
  --out runs/retained-artifact.bin
cargo run -p scriptbots-app --bin control_cli -- schema

Checkpoint and artifact lists preserve opaque cursors with the same --cursor option as experiment lists. Downloads require an explicit new --out path, enforce the server's 64 MiB ceiling, and verify the returned identity, byte count, content type, BLAKE3 and SHA-256 checksums before creating the output. Checkpoint downloads additionally bind the artifact to the checkpoint metadata. Success prints the path, byte count and both hashes as JSON.

Existing files and symlinks are refused, including a destination created during the request. Validation failures create no destination file; write or sync errors report and preserve any partial output. A downloaded checkpoint contains the core science state; complete application-owner continuation remains a separate workflow.

Run a future from a saved checkpoint

Start an independent scientific future from a checkpoint while the live simulation continues under its existing owner. Save this request as branch.json, replacing CHECKPOINT_ID with an identifier returned by checkpoint create or checkpoint list:

{
  "checkpoint_id": "CHECKPOINT_ID",
  "branch_name": "food-treatment",
  "ticks": 240,
  "intervention": {"type": "ConfigPatch", "params": {"food_growth_rate": 0.0}},
  "idempotency_key": "food-treatment-1"
}
cargo run -p scriptbots-app --bin control_cli -- checkpoint branch create --file branch.json
cargo run -p scriptbots-app --bin control_cli -- checkpoint branch status BRANCH_ID
cargo run -p scriptbots-app --bin control_cli -- checkpoint branch cancel BRANCH_ID
# After status reports completed, download its artifact_id:
cargo run -p scriptbots-app --bin control_cli -- artifact download ARTIFACT_ID \
  --out runs/branch-report.json

Omit intervention for one unchanged future; supplying it runs matched control and treatment branches from the same saved state. ticks is an additional horizon of 1–10,000 transitions. Requests are limited to 16 KiB, branch names to 64 ASCII letters/digits/underscores/hyphens, and the required retry key to 1,024 bytes. Repeat the exact request and key after an uncertain response. An optional global --idempotency-key must match the JSON key.

REST uses the same JSON with POST /api/v1/checkpoints/branches (HTTP 202), GET /api/v1/checkpoints/branches/{branch_id} and POST /api/v1/checkpoints/branches/{branch_id}/cancel. MCP exposes checkpoint_branch_create, checkpoint_branch_status and checkpoint_branch_cancel. Admission does not establish completion: poll until completed, cancelled or failed. Cancellation can first report cancelling; completion may win the race. world_digest_v1 identifies the source cut, and only completion publishes the report artifact_id. Jobs belong to the current control-service process; retained files are preserved, but branch execution/status is not resumed after a service restart.

In the simulation terminal, open Replay (7), select a saved checkpoint, and press N. Choose the horizon with Up/Down or +/- and the treatment with Left/Right, then press Enter to start. Esc/X discards the draft; X in Replay requests cancellation of an active study. The status panel identifies the source and target ticks, observed execution state, and completed report artifact.

The report compares one source trajectory and does not count its ticks as independent replicates. The saved cut restores science state; the original owner's pending commands, session and storage ownership remain with the live run.

The published study_plan.json names the retained source_checkpoint.bin, allowing offline study execution to reproduce the same saved cut. If you download or move these files, update the plan's source_checkpoint to the source file's new path before running it into a fresh output directory.

Interactive dashboard:

# Live TUI dashboard of knobs and their current values; press 'q' to quit, 'r' to refresh
cargo run -p scriptbots-app --bin control_cli -- watch --interval-ms 500

Scenario layering & replay CLI scaffold

  • Layered configs: pass one or more --config path/to/file.toml (or .ron) flags—or set SCRIPTBOTS_CONFIG with semicolon-separated paths—to build scenarios from reusable fragments (e.g., base.toml → arctic_biome.toml → evolution_study.toml). Layers merge in order before env overrides, unlocking repeatable experiments without editing code.
  • Config inspection: add --print-config to dump the merged configuration (default JSON) or --write-config output.toml to persist it; choose --config-format json|toml|ron and combine with --config-only for a dry run in CI/tooling workflows.
  • Replay status: --replay-db and --compare-db load, re-simulate, and diff encoded event streams. Production instrumentation projects per-agent actions in canonical AgentUid order through replay_event_tick_cap (default 512), budgeted per tick (bd-a9h1, fixed). Typed combat and food-share edges preserve source tick, core ordinal, stable actor/target UIDs, positions, and magnitude in the indexed FrankenSQLite interactions table. interaction_event_tick_stride=1 (the default) selects every tick, N > 1 selects ticks divisible by N, and 0 selects aggregates-only; interaction_event_tick_cap (default 512, 0 also aggregates-only) is the hard ceiling on each selected tick. Both knobs are serialized with run provenance. Durable interaction_events_observed, interaction_events_persisted, interaction_events_sampled_out, and interaction_events_truncated counters make completeness auditable, while shutdown logs the corresponding run totals at info. The default 5k-agent shape retains at most 512 edges per selected tick and is covered by the bounded-admission/flush gate; raise the cap only after checking the run's payload budget. The mock-free terminal→FrankenSQLite→export→replay E2E is crates/scriptbots-app/tests/replay_e2e.rs, and nonzero empty-vs-empty runs fail closed instead of claiming verification.
  • Storage helpers: FrankenSQLite-backed accessors (max_tick, load_replay_events, replay_event_counts) underpin the CLI so analytics pipelines or external tools can reuse the same deterministic data.

--replay-db FILE --tick-limit N verifies through completed world tick N, inclusive. Recorded events, comparison events and displayed counts use that same window; checkpoint-start replay begins after its validated checkpoint. Without an explicit cutoff, full-run comparison still checks the entire candidate, including extra trailing ticks. A nonzero prefix needs recorded canonical digest evidence within its window.

MCP HTTP server (Model Context Protocol)

  • Default: 127.0.0.1:8090 over HTTP; disable with SCRIPTBOTS_CONTROL_MCP=disabled.
  • Override bind address: SCRIPTBOTS_CONTROL_MCP_HTTP_ADDR=127.0.0.1:9090.
  • Implemented with fastmcp-rust; the server shares the same ControlHandle as REST.
  • Tools exposed (31):
    • Configuration: list_knobs → array of knob entries; get_config → full config snapshot; apply_updates → accepts { updates: [{ path, value }, ...] }; apply_patch → accepts { patch: { ... } }
    • Scenarios: list_presets → available scenario presets; apply_preset → accepts { name }; intervene → scheduled intervention
    • Playback: pause, resume, step (accepts { count, idempotency_key }), set_speed, shutdown. The first four expose optional idempotency_key in tool discovery; a keyed step requires count: 1.
    • Observation: get_status → current simulation status; get_command_status → two-axis status by command ID; narrative_search, narrative_around → narrative events; get_version, get_schema
    • Maps: map_generate → procedural sandbox map generation; map_apply → apply map artifact to running simulation
    • Experiments: experiment_create runs a real matched-seed batch (MLP/DWRAON/Assembly arms × seeds, plus FtBrain when built with brain-ft) on a background worker and writes a verified run bundle per run; experiment_status, experiment_list, experiment_cancel (stops active runs between durable ticks), experiment_resume (continues pending runs and unfinished runs from validated owner/journal cuts, and recovers verified completed bundles saved before their final status write; missing or incompatible cuts are refused). The same saved-definition discovery supports status/list/resume by ID after restart. experiment_compare verifies two completed cohorts at their declared endpoint and returns the matched-seed contrast, uncertainty and provenance; one-seed cohorts explicitly return descriptive results without inferential claims.
    • Checkpoints and artifacts: checkpoint_create (captured from the world owner and recorded in the run database through the storage worker), checkpoint_list, checkpoint_status, artifact_list, artifact_get Notes: Only HTTP transport is supported here; stdio/SSE are not used.

MCP quickstart:

  • Start the app; verify MCP binds on 127.0.0.1:8090 (override via SCRIPTBOTS_CONTROL_MCP_HTTP_ADDR).
  • Connect an MCP HTTP client to the endpoint and call tools/list for the authoritative roster and JSON schemas; the list above is the same set the server registers at startup.
  • Each tool returns structured JSON; use your MCP-compatible agent to orchestrate parameter sweeps and log findings to FrankenSQLite.

Configuration files & scenarios

  • Scheduled patches: scenario interventions run on the owner immediately before the transition out of their declared tick, including tick zero and bootstrap. Entries run in tick order, with document order preserved for the same tick, and merge against the current configuration. Each outcome records its schedule identity, actual boundary revisions, and changed fields separately from journal commitment; later science waits for that commitment. Invalid patches stop science and initiate ordered shutdown. The TUI reports observed outcomes and any gaps in its retained history, separately from core drought/expiry interventions.- Current state: repeatable scenarios can layer TOML or RON files with repeated --config flags or the semicolon-separated SCRIPTBOTS_CONFIG variable; later layers override earlier ones before environment overrides.
    base.toml → arctic_biome.toml → evolution_study.toml
    
  • Inspection/export: use --print-config, --write-config, --config-format, and --config-only to inspect or persist the composed configuration without launching a renderer.
  • Value: researchers gain repeatable, composable scenarios without hand-editing large monolithic files, making it easy to swap biomes, mutation parameters, or analytics presets on demand.

Deterministic replay roadmap

  • Already implemented
    • ✅ Event-log schema (replay_events table) and typed event encoding.
    • ✅ Type-safe encoding for replay artifacts shared by storage and analytics crates.
    • ✅ Storage plumbing to persist replay batches alongside standard metrics.
    • ✅ Headless runner and CLI event comparison that refuses vacuous nonzero runs.
    • ✅ Production RNG, brain-output, action and world-digest event instrumentation, with the action cap budgeted per tick (bd-a9h1).
    • ✅ Mock-free positive and perturbed-candidate event-replay test implementation in crates/scriptbots-app/tests/replay_e2e.rs; this is separate from checkpoint-start replay.
    • ✅ Core science checkpoint with strict restore and next-transition proof. Its envelope excludes host/session ownership and retained frontend history.
    • ✅ Checkpoint-start replay: --checkpoint-start restores the latest valid checkpoint before the replay limit and verifies the run from its tick (bd-2z0.5.13). Interactive runs record one automatically every --checkpoint-interval ticks (default 1000, 0 disables, env SCRIPTBOTS_CHECKPOINT_INTERVAL) together with a canonical world digest, so interactive and server runs can be replay-verified; REST (POST /api/v1/checkpoints) and MCP (checkpoint_create) add checkpoints on demand. All go through the storage worker (bd-1dvs).
  • Planned
    • ❌ Full host/session restore qualification: a bounded CLI candidate now captures and restores the owner/session cut, command identities/revisions, schedule cursor and persistence journal. Its original bd-2z0.5.13 acceptance remains open; implemented source and the existing real-file/subprocess test are not completed acceptance. Launch manifests keep checkpoint_replay_guarantee=false until that complete boundary is implemented and verified; the independently supported restorable RNG capability remains enabled.
    • ❌ Branch/diff workflows comparing Rust vs. Rust PR builds vs. the legacy C++ baseline.
    • ❌ FrankenSQLite-backed analysis views for quick triage of regressions and experiment outcomes.
  • Use cases
    • Parity testing between the Rust port and the original C++ implementation.
    • Regression prevention by replaying critical seeds in CI or pre-merge checks.
    • Debugging elusive bugs by reproducing exact agent decisions tick-by-tick.
    • Long-running research experiments that demand bitwise-stable replays.

Security & operations

  • REST and MCP servers bind to loopback by default and are plaintext HTTP. If you expose them externally, terminate TLS in a separate trusted proxy and configure CORS appropriately; https:// control settings fail closed rather than pretending the embedded listener implements TLS. The WASM path requires COOP/COEP headers only when enabling multithreading; single-thread builds avoid this.

Configuration knobs (examples)

All configuration can be inspected and updated at runtime via REST/CLI/MCP. Common knobs:

  • World: world_width, world_height, closed
  • Population: population_minimum, population_spawn_interval
  • Food: food_max, food_regrowth_rate, food_diffusion, food_decay, fertility_strength
  • Temperature: temperature_gradient, temperature_offset
  • Reproduction: reproduction_rate_carnivore, reproduction_rate_herbivore, mutation.{primary,secondary}
  • Traits: trait_modifiers.{smell,sound,hearing,eye,blood}
  • NeuroFlow: neuroflow.{enabled,hidden_layers,activation}

Use GET /api/knobs to discover the full flattened list with current values.

Runtime constraints:

  • Changing world_width/world_height at runtime is rejected; restart with new dimensions.
  • Some composite changes may be coerced (e.g., number/string parsing) but type mismatches are rejected with a clear error.

Owner command architecture

  • The live native app transfers its world to HostThread. REST/MCP, GPUI, Bevy, TUI, and headless clients use channel ports to that same owner.
  • scriptbots-runtime provides stable command identity, one external admission order, typed revision guards checked at the application boundary, independent application/journal statuses, immutable snapshots, and independent event cursors.
  • HostCore applies commands and advances science. Its fixed-deadline driver handles wakeups and bounded catch-up, while ordered shutdown waits for the required journal commitment. Browser ownership is a separate path.

Contributing

  • Keep changes scoped to the relevant crate; prefer improving existing files over adding new ones unless functionality is genuinely new.
  • Update docs where it helps future maintainers understand decisions and invariants.
  • For larger tasks, update PLAN_TO_REARCHITECT_AND_REVIVE_RUST_SCRIPTBOTS.md inline to mark progress.

WebAssembly (sibling crate plan)

We maintain a sibling browser-targeted crate, scriptbots-web, that reuses core crates without invasive changes. See PLAN_TO_CREATE_SIBLING_APP_CRATE_TARGETING_WASM.md and docs/wasm/ (ADRs, audits, capability matrix). Initial MVP runs single-threaded by disabling scriptbots-core’s parallel feature on wasm; WebGPU vs Canvas2D rendering is under evaluation.

Quick peek: crates/scriptbots-web/web/ ships a Canvas demo harness that consumes the wasm snapshots, surfaces live metrics, and can be served locally via python -m http.server. Binary snapshots (snapshot_format: "binary") and custom seeding strategies are already wired in for experimentation.

The World layers selector offers combined terrain/food/water, terrain, food availability, water depth and agents-only views in both Canvas and WebGPU. Environment and agents come from the same immutable owner publication in local and remote mode. Layer switching does not tick or edit the world. The status line identifies exact cells versus a bounded center-sampled overview and reports disabled hydrology or unavailable layers. Empty or extinct populations still show their environment, and missing observations clear the previous background.

The browser supports explicit saved continuations for MLP and Unbound worlds. Choose the brain for a new world, Reset, then use Save in This Browser to replace one IndexedDB slot. Reload shows the saved tick and time; Restore Saved World validates that checkpoint and resumes it paused, without offline ticks. Save acknowledgement waits for transaction completion. Failed writes preserve the prior save, and failed or stale restores preserve the active world. The download/import controls remain available for portable continuation files. Saves are manual, browser storage can be cleared or evicted, and remote mode disables these local controls. This stores complete owner checkpoint bytes; the full SQLite-image and ordered batch-journal durability path remains separate.

Helpful docs:

  • docs/wasm/adrs/ADR-001-wasm-rendering.md — rendering stack decision record
  • docs/wasm/adrs/ADR-002-browser-persistence.md — browser persistence approach
  • docs/wasm/adrs/ADR-004-component-model.md — component model/WASI Preview assessment
  • docs/wasm/browser_matrix.csv — browser capabilities (WebGPU, SAB, SIMD)
  • docs/franken_integration.md — franken-library integration program: verdicts, constraints, boundary rules (bd-2js6)
  • docs/licenses.md — dependency license audit incl. the franken MIT+rider analysis

WASM snapshot format & APIs

  • snapshot_format: json (default) or binary (Postcard Uint8Array).
  • APIs: default_init_options(), init_sim(options), tick(steps), snapshot(), reset(seed?), registerBrain("wander"|"mlp"|"none").
  • Determinism: wasm-vs-native parity tests compare snapshots for fixed seeds; single-thread fallback is default (Rayon disabled).

WASM hosting guide (COOP/COEP)

  • For multithreading (future), browsers require SharedArrayBuffer with headers:
    • Cross-Origin-Opener-Policy: same-origin
    • Cross-Origin-Embedder-Policy: require-corp
  • Local dev: serve with a static server that sets these headers (or use a service worker). For now, single-thread builds avoid the requirement.
  • DSR: the pinned rust_scriptbots profile builds the WASM package and runs its browser parity checks; hosted workflow runs are not accepted as evidence.

Licensing

ScriptBots is licensed under LicenseRef-MIT-OpenAI-Anthropic-Rider — MIT with an additional rider (see LICENSE): no rights are granted to OpenAI, Anthropic, their affiliates, or parties acting for them, and any distribution of the software or derivative works must include the rider unmodified. This is the same license the embedded FrankenSQLite/asupersync components carry, so the whole product ships under one uniform license (owner relicensing decision, 2026-07-13; previously the first-party code was declared MIT OR Apache-2.0). Release archives bundle THIRD-PARTY-LICENSES.md for embedded-component notices; full audit: docs/licenses.md.

Credits

  • Original ScriptBots by Andrej Karpathy (reference snapshot included under original_scriptbots_code_for_reference/).
  • This Rust port is an independent, from-scratch implementation guided by parity goals and modern Rust/GPUI best practices.

FAQ

  • What platforms are supported? Linux, macOS, and Windows 11 are targeted. Windows is supported natively (MSVC toolchain) and via WSL2. Early UI milestones may see platform-specific polish arriving at different times.
  • Where do I start hacking? scriptbots-core for the world model; scriptbots-runtime for host/client protocol work; scriptbots-render for the GPUI view; scriptbots-brain for brain interfaces; scriptbots-storage for persistence.

Troubleshooting

  • Fresh clone fails inside the fsqlite git dependency (failed to update submodule legacy_sqlite_code/sqlite: object not found - no match for id 450a9009...): the pinned frankensqlite revision records a sqlite submodule commit that is not reachable from any branch/tag on github.com/sqlite/sqlite. The checked-in .cargo/config.toml sets [net] git-fetch-with-cli = true, which routes submodule fetches through the git CLI (it retries by exact OID, and GitHub honors fetch-by-SHA), so current checkouts build on a fresh cache. If you build with a cargo older than 1.46 or deliberately bypass the repo config, pre-populate the submodule once in the failed checkout (git init && git remote add origin https://github.com/sqlite/sqlite && git fetch --depth 1 origin 450a90097fabf4eac7568a9688b34278b4d72122 && git checkout FETCH_HEAD, then set submodule.legacy_sqlite_code/sqlite.update=none in the checkout's .git/config).
  • MSVC/SDK link errors on Windows: Ensure VS Build Tools "Desktop development with C++" and Windows 11 SDK are installed. Install the pinned nightly-2026-08-31 MSVC toolchain; this checkout's rust-toolchain.toml selects it.
  • Blank or crashing window: Update GPU drivers. On WSL2, update the WSL kernel and try again. Verify that your system supports D3D12 (Windows) or Vulkan/Metal (Linux/macOS).
  • Storage admission or commit failure: Compare the live tick with the published committed tick and compare the admitted, applied, and durable batch watermarks. Inspect the structured last error, operation, attempt, and commit state. A definite synchronous NotAdmitted fault pauses later science ticks and retains the exact batch for explicit retry. A file admission receipt proves that the exact payload can be recovered; application and terminal durability remain separately visible until the later watermarks advance.
  • Determinism regressions: Ensure you haven't introduced unordered parallel reductions; stage results and apply in a stable commit phase.

Releases

  • Releases are built, verified, and published only through Doodlestein Self-Releaser (dsr) using the pinned rust_scriptbots repository profile. Use dsr build --tool rust_scriptbots ... for artifacts and dsr release --tool rust_scriptbots ... for publication; hosted workflow execution is never release evidence.
  • The DSR release profile is responsible for producing and retaining the platform archives and their verification evidence. Inspect the DSR result bundle before publication, and publish that exact blessed bundle rather than rebuilding it through another system.
  • macOS codesigning: configure the signing identity and certificate through DSR's protected release environment. Never put signing credentials in the repository or substitute a hosted workflow's secret store for the pinned DSR release path.
  • DSR imports signing material into an isolated temporary keychain, signs binaries and .app bundles, repacks the archives, and retains the resulting checksums in the release evidence. Release operators should verify that exact bundle (codesign --verify --deep on macOS and shasum -a 256 on every platform) before publication.

Reproducing correctness verification on a fresh Linux host

ci/dsr_verify.yaml and scripts/dsr_verify.sh provide a source-pinned correctness profile. This is separate from release packaging and the exact-class performance golden. It supports workspace, graphs, recipes, and graphs-and-recipes lanes (the last shares one dependency build for both focused suites); a lane pass only certifies that lane. GUI, PTY, browser and performance acceptance require their own actual execution.

Use an external DSR configuration directory and a clean main checkout. Copy the profile into repos.d/scriptbots-verify.yaml, then set its local_path, full reviewed SCRIPTBOTS_EXPECTED_COMMIT, SCRIPTBOTS_VERIFY_PROFILE, SCRIPTBOTS_PROOF_ROOT, and CARGO_TARGET_DIR to real absolute host paths. Create the proof root outside the checkout; each invocation creates a new child directory and refuses reuse. Use the toolchain pinned in rust-toolchain.toml. The host needs DSR's native-build prerequisites, including Mike Farah's yq v4, jq, Git, Bash, Python 3 and Rustup, plus the system libraries required by the selected Cargo lane. dsr config validate checks the materialized configuration; it does not compile the workspace or prove those system libraries are installed.

On workers with SBH installed, the runner protects the external Cargo home, target directory and proof root before running Cargo. This prevents the cleanup daemon from reclaiming active dependencies: a source checkout's Git protection does not cover DSR's sibling Cargo cache. Protection failures stop verification; the markers stay outside the clean source checkout, and fleet cleanup stays enabled.

The external config.yaml needs schema_version: "1.0.0". For native execution on the Linux host where DSR runs, use this external hosts.yaml:

schema_version: "1.0.0"
hosts:
  scriptbots-linux:
    platform: linux/amd64
    connection: local
    concurrency: 1
    capabilities: [rust]
platform_mapping:
  linux/amd64: scriptbots-linux

Run the profile with a unique proof version:

DSR_CONFIG_DIR=/absolute/path/to/dsr-config \
  bash scripts/dsr_verify.sh --run scriptbots-verify proof-20260905-001

An optional profile env.CARGO_HOME selects DSR's seed cache through this launcher. Create that absolute directory first; missing directories and symlink roots are refused before a build starts. DSR copies only cache inputs into a private Cargo home. Use an empty external directory for a fresh download lane; dependency-link and final collection guards still apply. If the profile omits it, DSR uses the caller's cache selection.

An optional profile env.DSR_BUILD_TIMEOUT also sets the orchestration deadline through the launcher. Its value must be a nonzero integer number of seconds. This binds the actual coordinator timeout, as well as the recipe environment; omitting the field preserves the caller's selection or DSR's default.

The launcher rejects undeclared hosts and calls dsr build with the profile's explicit target, --only-native, --no-sync and the unique version. The runner checks clean main, expected commit, actual host target, external output locations and native DSR execution before compiling. It retains the exact profile, toolchain and source identity, command lines, full stdout/stderr logs, executed-test counts and verdict.json. Acceptance requires both a successful DSR run and a parsed status: "pass" verdict for the expected source and lane. The same runner's --verify-evidence DIRECTORY EXPECTED_COMMIT LANE mode rechecks the required commands, log hashes, executed-test counts, profile and source/target identity. It refuses missing or changed evidence even if the verdict says pass. The workspace lane runs all-target check, strict Clippy, workspace tests and the separate core economy-faults tests. Pin/license/WASM dependency guards run in every lane. Missing profiles, hosts or toolchains are infrastructure refusals, not test outcomes. Relevant ignored native acceptance tests still need explicit profiles; this runner does not infer that they ran from a green default suite.

For the literal architecture examples, materialize a profile with SCRIPTBOTS_VERIFY_LANE: recipes, then run DSR_CONFIG_DIR=/absolute/path/to/dsr-config scripts/e2e_architecture_recipes.sh scriptbots-verify proof-recipes-001. That wrapper runs DSR, verifies the typed source-bound verdict and requires actual executed documentation and integration test counts. Its scope is the documented library recipes; production GUI, PTY and browser journeys remain separate.

For graph selection and attributed exports, select graphs (or the combined graphs-and-recipes lane) and run DSR_CONFIG_DIR=/absolute/path/to/dsr-config scripts/e2e_analytics.sh scriptbots-verify proof-graphs-001. This executes the existing real FrankenSQLite and sb-analyze subprocess tests, retaining their fixtures and outputs. It covers graph acceptance; the complete seeded simulation and report journey remains open under bd-2z0.11.9.

The analytics DSR lane runs both declared analytics pipeline tests and requires separate retained manifests for the statistical fixture and the actual seeded world. The world drives every registered report through sb-analyze, compares demographic counts to simulation observations, verifies Parquet row counts against SQL, and probes missing, empty and corrupt databases plus an unknown report. Its manifest names the remaining real intervention, narrative-search and interaction-export acceptance; a passing lane does not close those requirements.

CI's source_bound_dsr matrix connects the complete connectivity and tournament-smoke-and-analytics lanes to the existing DSR runner. It requires a controller labelled self-hosted, linux, x64, scriptbots-dsr, with DSR, yq, and the pinned native toolchain installed. Set the repository variables SCRIPTBOTS_DSR_BASE_CONFIG_DIR to an external directory containing the actual DSR config.yaml and hosts.yaml, and SCRIPTBOTS_DSR_LINUX_HOST to the declared native host key. This workflow requires that key to have connection: local and platform: linux/amd64 on the same controller: its generated source and proof paths are controller-local. An SSH-backed DSR profile requires its source, profile and proof paths to be explicitly staged on the remote host before --no-sync; the CI preparation refuses that configuration before compilation. Each job materializes a separate profile and clean main copy at the event's exact source, uses a unique proof version, parses the complete lane evidence, and uploads its raw logs and observations even after a failed run. Unprovisioned controllers leave execution pending; workflow wiring does not prove that CI ran. The original wire-level control probe remains a separate CI job. This matrix covers bounded tournament smoke, not the full publication protocol.

Comparing FtBrain with MLP

The tournament runner accepts the versioned FtBrain family when the application is built with brain-ft. The bundled opt-in profile exercises real founding genomes, both spawn orders, equal founder cohorts, result rows and leaderboard generation:

cargo run -p scriptbots-app --features brain-ft -- tournament \
  --spec tournament/ft_comparison.toml --smoke --out runs/ft-comparison

The smoke profile uses two seeds, two orders, eight founders and 32 ticks per match; omit --smoke for four seeds, 16 founders and 240 ticks. Both require an identical rerun. These are bounded architecture comparisons, not evidence of long-horizon evolution or a superior family. Ft uses its default dense hidden layers [48, 32, 24]; the existing MLP architecture differs. The report retains the actual initial genome digests and source-scalar counts. Ft's initial count comes from validated genome structure, without claiming recorded activity before the first scientific tick.

ft and frankentorch select the same family in CLI/spec inputs. Explicit labels such as ft-control remain distinct experimental arms. A build without brain-ft refuses the family before starting matches. NeuroFlow remains unavailable to this heritable tournament because its legacy runner lacks the canonical genome/evaluator adapter. The canonical tournament/spec.toml retains its existing 200-source-scalar requirement; the new mixed-architecture profile explicitly omits that requirement instead of weakening it globally.

Roadmap (condensed)

  1. Core data structures and config (done); expand parity (metabolism, locomotion, food math, carcass sharing).
  2. World mechanics and determinism under parallelism; spatial index tuning.
  3. Brains: MLP shipped; DWRAON + Assembly (feature-gated) and NeuroFlow optional.
  4. Storage: durable outbox, exact identity/schema recovery, direct-write/root-cause unification, V6/V7 base/archive lineage, indexed pairwise interaction edges, run bundles, V8/V9 typed evidence readers and automatic checkpoints are integrated. Remaining work includes complete host/session continuation and retention acceptance, persistent-run liveness/throughput and in-memory commit scaling (bd-kgob).
  5. Runtime: renderer-neutral protocol, sole-owner HostCore, fixed-deadline native lifecycle, and frontend ports are integrated; complete remaining client interactions and native acceptance for the host cutover.
  6. Rendering: Lab/overlays/inspector polish; performance diagnostics.
  7. DSR packaging and verification: release builds, binaries, and WASM/browser evidence from the pinned repository profile.

Mixed brain families (default)

  • The default mixed founders use the versioned MLP, DWRAON and experimental Assembly families, plus FtBrain when brain-ft is enabled. Optional NeuroFlow is registered but withheld from mixed founders because it lacks the versioned heredity contract; --brain neuro explicitly selects its legacy runner when the neuro feature is enabled.
  • NeuroFlow is enabled in the default config; edit at runtime via REST/CLI or env (e.g., SCRIPTBOTS_NEUROFLOW_*).
  • Brain-material crossover only occurs within the same family (species barrier). On the scheduled population-crossover path, incompatible selected parents cause that arrival to become a fresh spawn sampled from the brain registry.
  • Natural reproduction does not use that fallback: a cross-family partner may contribute body/runtime traits and whole-agent lineage, while the child's brain clones and mutates only the primary parent's genome. The incompatible partner is excluded from brain provenance, so no hybrid brain is fabricated.
  • To force a single brain for new agents, bind a chosen brain_key to agents via WorldState::bind_agent_brain or modify the seeding function to always pick that key.

About

Deterministic artificial-life simulator in Rust: agent-based evolution with pluggable brain implementations, GPU-accelerated UI, DuckDB analytics, and LLM-in-the-loop experimentation

Topics

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages