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.
- 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
closedworlds, 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).
- Parameter sweeps: vary
- Example workflows:
- A brain testbed: The
Braintrait 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.
- 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.
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
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:
HostThreadowns the simulation'sHostCoreand fixed-deadline driver.StoragePipelineis 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 throughChannelHostPort; 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 exerciseHostCore. Scheduled scenario patches use that owner during bootstrap and interactive execution. Thebd-pcfjcutover is closed; broader client interaction, lifecycle and native qualification remain with their open frontend/runtime acceptance owners. scriptbots-runtimeowns the renderer-neutral command, two-axis status, snapshot, event-cursor, and manual-drive contracts plus the exact sole-ownerHostCore. 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 optionalnative-asupersyncfeature drives that same!Sendhost 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 isbd-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
AgentUidvalues; 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
ControlHandleand enqueue commands with back-pressure.
scriptbots-core: Simulation core withWorldState,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-ownerHostCore; a pure injected-time fixed-deadline adapter; and an optional Asupersync=0.5.0native 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 bynative-asupersyncon native targets.scriptbots-brain:Braintrait + baseline implementations and adapters; experimentalassemblybehind a feature.scriptbots-brain-ml: Feature-gated Candle tensor inference and the retainedml.placeholdersensor-copy fallback for Tract and no-backend builds, plus the non-default code-first FrankentorchFtBrainfamily. Candle is not registered as a production heritable family. FtBrain is wired underbrain-ft; its pinned DSR compile, determinism, and benchmark proof remains pending underbd-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-ownerHostThread, 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; consumesscriptbots-corewithdefault-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).
- 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-ownerHostCore, pure fixed-deadline driver, and optional current-thread Asupersync lifecycle are implemented. The app usesHostCorethrough its owner thread and channel ports. Thebd-2z0.5.2lifecycle work and thebd-pcfjfrontend cutover are closed.scriptbots-render: GPUI World + tabbed Lab windows with camera controls, selection highlights, scrollable diagnostics, and optionalkiraaudio.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
Programwith 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 underbd-2z0.6.8andbd-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 theneurofeature (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 underbd-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-onlyStorageReaderwith explicitly unbounded execution. Strict-run host policy and product checkpoint/replay integration remain open. Run bundles are implemented:RunBundleV1(scriptbots.run-bundle.v1) withbundle::create_run_bundle,create_run_bundle_from_artifacts, andverify_run_bundle, surfaced as--create-bundle/--bundle-outputand--verify-bundle; the two competing implementations were converged underbd-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.
- Rust toolchain:
nightly-2026-08-31, pinned inrust-toolchain.toml; the workspace and locked dependency graph declare a minimum Rust version of 1.89. Install throughrustup. - 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).
cargo checkCPU 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.
cargo run -p scriptbots-app- Storage:
--storage memoryis 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 memoryrun slows to under one tick per second and eventually hits the 120 s admission deadline (bd-kgob,bd-w1oi). The default--storage filedoes 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,1024Set logging verbosity with RUST_LOG, for example:
RUST_LOG=info cargo run -p scriptbots-app-
Start the interactive terminal laboratory:
SCRIPTBOTS_MODE=terminal cargo run -p scriptbots-app
-
Use
4–9for 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+Rretries 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 pressCto compare their verified final populations across matched seeds. Without a pinned baseline,Ccompares 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), pressKto save a checkpoint and use Up/Down to select a catalog row. It shows that saved cut's population and first twelve characters of itsWorldDigestV1, 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 carriesagent_countand the fullworld_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, andgreturns 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. Narrativevfirst 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 asCHECKPOINT REPLAY;greturns 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
eto toggle at runtime. - Force enable via env:
SCRIPTBOTS_TERMINAL_EMOJI=1|true|yes|on; force disable with0|false|off|no. - Heuristic: enabled if
TERMis notdumb/linux/vt100, locale containsutf-8|utf8, andCIis 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.
- Defaults ON when a modern UTF‑8 terminal is detected; press
-
Narrow symbols mode: press
nto 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-levelschemais"scriptbots.terminal-headless.v1"; check it before interpreting or comparing reports.scenario.schema_versiondescribes the scenario inputs and does not identify the report format. V1 keeps the existingscenario,initial,frames,summary,narrative_eventsandnarrative_dropped_eventsfields. Each rendered frame'sbufferrecords 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.
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.
- 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/getconffallback; override by exportingTHREADSbeforehand) - Builds with native CPU optimizations (
RUSTFLAGS="-C target-cpu=native") - Forces terminal renderer (
SCRIPTBOTS_MODE=terminal) - Runs release binary with cargo job parallelism
-j $THREADSand passes--threads $THREADSto the app
- Detects CPU count into
- Customize:
- Reduce CPU usage:
THREADS=2 ./run_linux_terminal_mode.sh - Headless CI snapshot: export
SCRIPTBOTS_TERMINAL_HEADLESS=1to render against an in-memory buffer - Logging:
RUST_LOG=info ./run_linux_terminal_mode.sh
- Reduce CPU usage:
- 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
- Detects CPU count (caps default at 8) and passes the value to cargo (
- 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)
- Limit load:
- 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 (
arm64vsx86_64) and sets--targetaccordingly - 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)
- Detects arch (
- 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
- Add app flags by appending to the final
- 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 guiand launches GUI mode (--mode gui) using--threads 8
- Customize:
- Tune threads: edit
--threads 8or setSCRIPTBOTS_MAX_THREADSenv - Troubleshoot rendering: you can add
--renderer-safeto the app args if you see a black canvas
- Tune threads: edit
- 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-darwinon Apple Silicon,x86_64-apple-darwinotherwise) - 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 bevyand a default 8-thread budget (override withTHREADSenv)
- Selects the correct target triple (
- Customize:
- Retina tweaks: set
SB_WGPU_RES_SCALEto0.5or2.0before 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)
- Retina tweaks: set
- 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
- Double-click in Explorer, or run from a Developer PowerShell/Command Prompt:
- 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)
- Uses MSVC target
- Prereqs:
- Rust MSVC toolchain and Visual Studio Build Tools (Windows 11 SDK) installed
- 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
- Double-click in Explorer, or run from a Developer PowerShell/Command Prompt:
- What it does:
- Same MSVC target/artifact isolation as console script
- Builds with
--features guiand launches GUI mode (--mode gui) using--threads 8
- Customize:
- Adjust threads by editing the
--threadsvalue; add app flags after--as needed (e.g.,--debug-watermark)
- Adjust threads by editing the
- 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
- Double-click in Explorer, or run from a Developer PowerShell/Command Prompt:
- What it does:
- Reuses the MSVC target (
x86_64-pc-windows-msvc) with isolated artifacts undertarget-windows-msvc - Sets high-performance WGPU hints (
WGPU_BACKEND=Vulkan,WGPU_POWER_PREFERENCE=high_performance) - Builds with
--features bevy_renderand launches the Bevy renderer (--mode bevy) using--threads 8
- Reuses the MSVC target (
- Customize:
- To force D3D12 instead of Vulkan: set
set WGPU_BACKEND=d3d12before running - Add Bevy-only flags (e.g.,
--dump-semantic-png,--dump-scene-png) after the final--in the script
- To force D3D12 instead of Vulkan: set
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 200there. - To stream control API docs, ensure REST is enabled (default) and open
http://127.0.0.1:8088/docswhile the app runs.
rustup target add wasm32-unknown-unknown
cargo check --target wasm32-unknown-unknown -p scriptbots-web- Install Rust (MSVC toolchain):
- Download
rustup-init.exeand 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
- Download
- Install Visual Studio Build Tools (2022+):
- Select the "Desktop development with C++" workload (includes MSVC, Windows 10/11 SDK).
- Update GPU drivers (NVIDIA/AMD/Intel) to latest. Ensure D3D12 is available; Vulkan runtime optional.
- Build and run:
cargo run -p scriptbots-app
- 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 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.
scriptbots-appfeatures:ml→ enablescriptbots-brain-mlbrain-ft→ propagate the non-default pinned Frankentorch dependencies and code-firstFtBrainfamily throughscriptbots-brain-mlneuro→ enablescriptbots-brain-neurofast-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_scriptbotsprofile; GitHub Actions and direct Cargo invocations are not acceptance evidence. - Note: default features enable
ml,neuro, andfast-alloc. To disable defaults, use--no-default-featuresand 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:candleenables real tensor forward/batch inference, without production heritable-family registration.tractand no-backend builds retain the sensor-copyml.placeholderfallback.brain-ftexposesFtBrainConfig,FtBrainFamily, andFT_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_parameterspath 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 ofbd-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.
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 neuroValid activations: tanh, sigmoid, relu.
# 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-
--mode {auto|gui|bevy|terminal|server}: select the frontend, or run the control servers without a renderer. Defaults toautoand can be set viaSCRIPTBOTS_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 thebevy_renderapplication feature.terminal: force emoji TUI.
-
--bootstrap-ticks N: explicitly runNscience ticks after seeding and before frontend launch (default0, 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 underbd-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--brainpreset; 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 aWorldCheckpointV1plus a replay digest into the run database every TICKS ticks of an interactive run (default 1000;0disables; envSCRIPTBOTS_CHECKPOINT_INTERVAL).--replay-db FILE --checkpoint-startlater verifies the run from the latest one. -
--checkpoint-max-count COUNTand--checkpoint-max-bytes BYTES: retention limits (defaults 256 and 268435456; envSCRIPTBOTS_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 2unless--threadsis provided); also biasesautotoward terminal. -
--profile-steps N: headlessworld.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 explicitrng_seedandpersistence_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; usereport-archipelagoor explicit island-scoped readers for those databases. Migration is disabled by default.--migration-interval Nenables it every N ticks for two or more islands. Optional--migration-emigrants N(default 1),--migration-selection random|fittest|youngest|wanderer(defaultfittest) and--migration-topology ring|fully-connected(defaultring) 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'sarchipelagoextension 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 →--configfiles (in order) → environment → CLI; every applied layer appends a kind-tagged content digest to the run manifest'sscenario.ordered_config_layer_digests, and any field where one explicit layer displaced another is recorded in the manifest'sconfig_overrides. -
--quality TIER: visual quality shortcut for--set render.quality=TIER, validated at parse time (auto|potato|low|medium|high|ultra). The unifiedrender.*settings (quality tier, post stack bloom/vignette/fog/AA, day/night cycle, TUI theme, accessibility palette) are consumed by every frontend;Nonevalues 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 undercaptures/<scene>/. Golden workflow:RUST_REGEN_GOLDEN=1blesses new goldens undercrates/scriptbots-app/tests/scenes/goldens/<scene>/; an existing golden is compared with per-channel/perceptual thresholds (mismatch writes a<name>.diff.pngheatmap and fails); a missing golden is an explicit failure with regeneration instructions, never an auto-bless.SCRIPTBOTS_CAPTURE_CORRUPT=1binds 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.fileexclusively reservesSCRIPTBOTS_STORAGE_PATHor a fresh generated run path and refuses existing databases or stale sidecars;memoryopens 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(orSCRIPTBOTS_AUTO_PAUSE_BELOW) pauses when population ≤ COUNT--auto-pause-age-above AGE(orSCRIPTBOTS_AUTO_PAUSE_AGE_ABOVE) pauses when any agent’s age ≥ AGE--auto-pause-on-spike(orSCRIPTBOTS_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 (defaultmixed).mixedregisters MLP, DWRAON, and Assembly unconditionally; it additionally registers FrankentorchFtBrainonly when the binary is built with--features brain-ft, and registers the optional NeuroFlow brain only when built with--features neuro(seeSCRIPTBOTS_NEUROFLOW_*below for runtime toggles).mlp,dwraon, andassemblyinstall only that single family.neuroexplicitly selects the legacy NeuroFlow runner; registration inmixeddoes not admit it to mixed founding populations.ftinstalls only the Frankentorch family and fails closed with a typed error when thebrain-ftfeature is not enabled — it never silently substitutes another family. The flag is an application-layer CLI choice and is NOT aScriptBotsConfigfield, so--configfiles andSCRIPTBOTS_CONFIG_OVERRIDEScannot override it; precedence isdefault → 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.
RUST_LOG— logging filter (e.g.,info,trace,scriptbots_core=debug). Useinfo,scriptbots_core::parallelism=debugto observe the Rayon pool width inside each actual science step.RAYON_NUM_THREADS— simulation pool default whenparallelis 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--moderemains authoritative.SCRIPTBOTS_BOOTSTRAP_TICKS— explicit pre-frontend science ticks (default0, 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 typednarrative_eventsring and itsnarrative_dropped_eventscount. 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--threadsand above auto-tune or low-power defaults. Startup passes the resolved number directly to Rayon. Standalone core callers retain the physical-CPU-capped default whenRAYON_NUM_THREADSis 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 mode1|true|yes|onor disable with0|false|off|no.SCRIPTBOTS_RENDER_SAFE— force conservative rendering path in GUI mode (also enabled by--renderer-safeor--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|ultraforrender.quality(the--qualityCLI flag outranks it).- Legacy render knobs
SB_WGPU_TONEMAP|EXPOSURE|BLOOM|BLOOM_THRESH|BLOOM_INTENSITY|VIGNETTE|FOG|FOG_COLOR|FXAAandSCRIPTBOTS_TERMINAL_PALETTEare mapped onto the typedrender.*schema at startup with one INFO log per applied mapping; the canonical typedSCRIPTBOTS_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--configfiles, loses to the typedSCRIPTBOTS_*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'sconfig_overrides.SCRIPTBOTS_RNG_SEED— environment-layer RNG seed;--rng-seedoutranks it as a distinct CLI layer with its own provenance.SCRIPTBOTS_BRAIN— environment-layer brain preset (mixed|mlp|dwraon|assembly|ft|neuro, defaultmixed);--brainoutranks it as a distinct CLI layer. Selectingftwithout thebrain-ftbuild 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 (default127.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(defaulthttp).SCRIPTBOTS_CONTROL_MCP_HTTP_ADDR— MCP HTTP bind address (default127.0.0.1:8090).SCRIPTBOTS_CONTROL_ALLOWED_AUTHORITIES— comma-separated additional advertisedhost:portvalues for REST and MCP HTTP. By default each listener accepts its actual bound IP/port and, for loopback,localhostat 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 ashttps://lab.example, without credentials, paths or queries. Default browser origins arehttp://at the accepted authorities. A missing Origin is allowed for CLI/MCP clients; malformed, duplicate, foreign andnullOrigins 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 uniqueruns/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-waland its-shmbeside the database, so remove the database together with its sidecars before reusing a path. The selected path is printed asRun 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 underbd-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 mlpThe 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.
- 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 Labcompanion. 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 guiand 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
HostCoreon 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_agentsthrough 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.
Deterministic, staged tick pipeline (six seeded, domain-separated RNG streams; explicit staged ordering):
- Aging and scheduled tasks
- Food respawn/diffusion
- Sense (spatial index snapshot)
- Brain tick
- Actuation (double-buffered state)
- Food intake/sharing (deterministic reductions)
- Combat and death (queued → commit)
- Reproduction (mutation/crossover) in stable order
- History and persistence projection (batched to the bounded FrankenSQLite worker)
- Preserve the final persistence tail and reset transient runtime flags
- 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.25split) 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 ford < 2rwithin π/8 and snaps the spike to zero; health and energy are separate budgets; reproduction may take a partner (with probabilitypartner_chance, the oldest other agent) and yields one child, where the C++ is asexual withBABIES=2; the population floor defaults topopulation_minimum = 0instead of topping up toNUMBOTS=70; food also regrows continuously in every cell (food_growth_rate = 0.05), where the C++ only refills one random cell toFOODMAXevery 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 of0.0001per tick for both diets, lowers food regrowth to0.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 coreScriptBotsConfig::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.tomlpasses its 360-tick envelope but passes 3,000 agents by tick ~1,200 on all three declared seeds. Tracked inbd-vgsx. - Explicit food-funded experiment: select
--scenario scenarios/food_funded_meadow_v1.scenario.tomlto 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, regrowth0.0005, and a parent debit equal to the child's0.25starting 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.
- 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 demographicAgentIdentity::birth_ordinalremains 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-coredefaults toparallel(Rayon), while web builds disable it for single-thread determinism. - Completed-boundary outcome and admission seam:
WorldStateowns deterministic accumulators plus a payload-freeOpen/Pending/Sealedboundary marker; it no longer owns a sink, retry payload, acknowledgement error, or admission watermark. A one-lifetimePersistenceAdmissionSessionowns those external concerns. Its step APIs stage the exact immutableArc<PersistenceBatch>before returning, retain that same allocation across definite and indeterminate failures, and seal the world only after acknowledgement. DirectWorldStatestepping 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 fullStepOutcome; 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 orderedVec<ControlCommand>, while core returns normalized playback as an explicit driver-owned disposition.
WorldState::world_digest_v1()emits the exactscriptbots.world-digest.v1.7/codec-7 science-state wire. Every agent transition is canonicalized by stableAgentUid, 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 exactAgentSubstreamProtocolV1, UID-orderedAgentRngCounterStateV1rows carryingAgentRngCountersV1, 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 orphanedsense_max_neighborsfield: 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 canonicalscriptbots.world-checkpoint.v1.3/codec-6postcard+blake3-v6core 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 stableAgentUidorder and reconstructs full genome/evaluator state through a caller-prepared exactBrainRegistry. The registry's complete roster, including its next allocation key and every protocol adapter's exactBrainAdapterIdentityV1, 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 usingscriptbots.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, andvalidate_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=1environment guard in its pinned DSR test lane, so ordinary--all-featurestests remain portable; there is no product CLI or replay-file claim yet.
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-studyThe 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,999Each 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.
- 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, exactAgentSubstreamProtocolV1, and UID-orderedAgentRngCounterStateV1launch rows. Once the tick-zero V1.7 start digest is bound, the bootstrap form isscriptbots.run-manifest.v3.6; it must bind the same root, protocol, counters, registry semantics, locomotion model, andWorldDigestV1evidence rather than describing a different launch state. Neither form collapses the domains back into one ambiguous global stream. - The
bd-1kxdkeyed-substream schema and thebd-2i1V1.6 locomotion contract are closed with pinned DSR evidence. The reviewed exact-class full performance baseline was promoted byte-for-byte in39fc2f0, and the final same-class comparison passed in DSR0.1.0-bd2i1-perf-compare-quiet1.20260716T160817Z.bd-hiv1is closed: movement-noise sensing and spike-speed damage now consume a typed peak-wheel-effort lane rather than physical displacement (scriptbots-corewheel_effort;spike_speed_damage_bonusscales peak normalized wheel output, andspeed_magno longer contributes). - For CPU thread control in app profiling, use
--threads N;RAYON_NUM_THREADSsupplies the default only when the app resolves no thread budget.
- SoA layout: agents use cache-friendly columns (
AgentColumns) for fast scans during sense/actuation. - Two identity layers: slotmap-backed
AgentIdprevents stale references; monotonicAgentUidis 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: 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.
- 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_keyfor 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.
- 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.
-
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_v1overlapping 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 unusedprototype-copy-NID, 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_configandconstraintsrecords to author custom rules, exemplars and terrain/environment/hydrology overrides. The recipe schema isscriptbots.map-draft.v1; constraints are a list with explicitx/ycoordinates. 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/MCPsample: {...}, selects it explicitly.sampleandtilesetare 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-majorsample_tilesterrain kinds.all_orientationsandperiodicdefault to true;periodic: falseis 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/generateand/api/v1/map/apply, and MCPmap_generate/map_applyuse the shared map service and acknowledged owner commands. The main binary's offlinemap-applycommand validates an artifact file.existing_agent_policydefaults toretain. CLIcontrol_cli map-apply --file map.json --existing-agent-policy reposition-to-safe-tile, or REST/MCPexisting_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/MCPexisting_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_revisionfrom REST/api/statusor MCPget_statusbefore preparing it. Pass that exact value as CLIcontrol_cli map-apply --file map.json --expected-scientific-revision REV, or REST/MCPexpected_scientific_revision: REV. The owner checks it at ordered application; a stale request ends asrejectedwithout applying the map. Itsrejection_reasonreports 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.7andbd-2z0.10.8; the hydrology system builds atop terrain for dynamic water flows (see below).
- Runtime hydrology state models per-cell flow direction, accumulation, basins, and a water depth field. Use
GET /api/hydrologyfor 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 hydrologyprints a summary (ratios, thresholds, array sizes). Hydrology integrates with terrain and is deterministic per seed.
- 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.
- 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,
0or 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
vto review its exact retained canvas frame; outside the cache it uses the same bounded checkpoint replay. Save a checkpoint before the event. Pressgto 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(featureaudio).
- 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.
- 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.
- The app selects GPUI, Bevy, or terminal renderers via
--mode {auto|gui|bevy|terminal}(subject to build features);--mode serverruns without a renderer. Each mode connects to the same sole-owner host throughChannelHostPort. 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.
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.
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.
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.
- Optional
kira-backed mixer (featureaudio) 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.
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.
-
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
eto toggle at runtime. - Force enable via env:
SCRIPTBOTS_TERMINAL_EMOJI=1|true|yes|on; force disable with0|false|off|no. - Heuristic: enabled if
TERMis notdumb/linux/vt100, locale containsutf-8|utf8, andCIis 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.
- Defaults ON when a modern UTF‑8 terminal is detected; press
-
Narrow symbols mode: press
nto 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.
- One embedded engine: ScriptBots uses the public
fsqlitefacade from FrankenSQLite withversion = "=0.4.6", pinned to immutable revisionad3f23ca94c0f1d38e3d6cbb919b0d095de0b4eeathttps://github.com/Dicklesworthstone/frankensqlite. Defaults remain disabled;native,json,fts5,icu,misc, andrtreepreserve 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 fileexclusively reservesSCRIPTBOTS_STORAGE_PATHor a generatedruns/scriptbots-<unix-ms>-<pid>.sqliteand prints the selected run database; it refuses reuse or stale sidecars.--storage memoryopens volatile:memory:through the same implementation. - Explicit interrupted-run recovery:
--recover-storage FILE(orSCRIPTBOTS_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-dbcandidate described above. - Thread-confined, single-writer connection:
fsqlite::Connectionis 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 throughArc<Mutex<_>>. - Bounded admission, distinct proof levels: persistence batches enter a bounded queue. Configurable
StorageDeadlinesbound 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 definitelyNotAdmitted; the external admission session retains the exact completed batch and acknowledgement fault while the world's payload-freePendingmarker blocks later science ticks until explicit retry succeeds. A lost or timed-out acknowledgement remains typed asIndeterminateat 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_receiptreturns the batch ID after the exact payload enters the worker outbox and reportsDurablefor a file database orCommittedVolatilefor memory. That receipt proves admission, not scientific-table application. Same-threadStorage::persistnow 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:
admittedafter the outbox transaction,appliedin the same transaction as all scientific-table rows, anddurablein 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 indexedinteractionstable, 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/failedtransitions remain distinct from storagecommitted_volatile/durabletransitions. Finished files expose boundedStorageReader::command_journal_evidence,command_journal_record, andcommand_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, orinjectedorigin row under a globally unique stable agent UID. Onlybornrows have a global demographicAgentIdentity::birth_ordinalor 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 localbirthcontinuation inAgentRngCountersV1, 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 + !Syncconnection-owner worker.AsyncReadLane::open(path, maximum_duration)therefore still always returns a typedReadExecutionBoundUnavailablebefore the path is opened or inspected; there is no async SQL escape hatch. UseAnalyticsSnapshotProvider::snapshot()for lock-free, non-SQL frontend latest-state access. Offline/reporting callers that can wait may use the synchronous, create-free, read-onlyStorageReader; its row limits bound results and allocation, not scan, aggregation, sort, open, close, or wall-clock work.
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.
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.jsonnarrative-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.mdnarrative-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.
sb-analyze runs/example.sqlite summarize --epoch-size 100 --rolling-window 10 --json summary.json --md summary.mdSummaries 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.
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.mdPairing 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.jsonFor 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.
- 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
Storageboundary provides explicit flush, close/checkpoint, andVACUUMoperations. 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.
- Coding standards: See
RUST_SYSTEM_PROGRAMMING_BEST_PRACTICES.md. EmbraceResult-based errors, clear traits, and avoidunsafe. - 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.jsonconfigures Oh My Pi withcargo.targetDir = trueat 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 equivalentrust-analyzer.cargo.targetDiroption; 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.
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.shThe 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.
- 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:
criterionharness 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.
- CPU profiling (Linux/macOS): run with
RUSTFLAGS='-g'and useperf record/perf reportordtrace/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_THREADSto 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 Nand--profile-storage-steps Nto run headless micro-benchmarks--profile-sweep Nand--auto-tune Nto explore and auto-pick thread/flush settings--renderer-safefor a conservative paint path;--debug-watermarkoverlays 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.
- Logging uses
tracingwithRUST_LOGfilters (e.g.,RUST_LOG=info,scriptbots_core=debug). - Categories of interest:
scriptbots_core::world— tick summaries, seeding, closed/open flipsscriptbots_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 invocationsscriptbots_render— window lifecycle, input bindings
- Prefer structured fields (e.g.,
tick = summary.tick.0) for machine-readable logs. Avoid panics in production; release profile usespanic = abort.
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.
- Default address:
http://127.0.0.1:8088(overrideSCRIPTBOTS_CONTROL_REST_ADDR) - Swagger UI path:
/docs(overrideSCRIPTBOTS_CONTROL_SWAGGER_PATH) - OpenAPI JSON:
/api-docs/openapi.json - Enable/disable:
SCRIPTBOTS_CONTROL_REST_ENABLED=true|false - Endpoints:
GET /api/knobs→ list flattened config knobsGET /api/config→ fetch entire config snapshotPATCH /api/config→ apply JSON object patch{ ... }POST /api/knobs/apply→ apply list of{ path, value }updatesGET /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=ansipreserves colors and text styles. Both formats returnx-scriptbots-frame-schema: scriptbots.terminal-frame.v1,x-scriptbots-frame-format,x-scriptbots-frame-tick, andx-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 availableGET /api/events/tail→ recent events (birth/death/combat) ring bufferGET /api/scoreboard→ top carnivores and oldest agents at a glanceGET /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 presetsPOST /api/presets/apply→ apply preset by nameGET /api/config/audit→ recent config patches (audit ring buffer)GET /api/scenario→ the launch scenario identity bound to this runGET /api/ws/stream→ negotiated binary telemetry, canvas and narrative subscriptions with acknowledged JSON controlsGET /api/narrative/search→ search the recent birth/death/combat narrativePOST /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 .../cancelstops active runs between durable ticks and prevents another wave;POST .../resumecontinues 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-ftadditionally acceptftorfrankentorch, recorded canonically asft. The same compiled adapter restores continuation cuts and independently verifies the final bundle state. A build withoutbrain-ftrefuses 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 aWorldCheckpointV1and 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, andGET /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, andGET /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.
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.
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.
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 savedtick, acheckpoint_digestcontaining the BLAKE3 of the complete encoded checkpoint, and its observationsource.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.pngExample PATCH body:
{ "food_max": 0.6, "neuroflow": { "enabled": true, "hidden_layers": [64,32,16], "activation": "relu" } }- 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 -- hydrologyset, 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.
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_agentscreate --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.
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 -- schemaCheckpoint 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.
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.jsonOmit 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- Layered configs: pass one or more
--config path/to/file.toml(or.ron) flags—or setSCRIPTBOTS_CONFIGwith 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-configto dump the merged configuration (default JSON) or--write-config output.tomlto persist it; choose--config-format json|toml|ronand combine with--config-onlyfor a dry run in CI/tooling workflows. - Replay status:
--replay-dband--compare-dbload, re-simulate, and diff encoded event streams. Production instrumentation projects per-agent actions in canonicalAgentUidorder throughreplay_event_tick_cap(default512), 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 FrankenSQLiteinteractionstable.interaction_event_tick_stride=1(the default) selects every tick,N > 1selects ticks divisible byN, and0selects aggregates-only;interaction_event_tick_cap(default512,0also aggregates-only) is the hard ceiling on each selected tick. Both knobs are serialized with run provenance. Durableinteraction_events_observed,interaction_events_persisted,interaction_events_sampled_out, andinteraction_events_truncatedcounters 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 iscrates/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.
- Default:
127.0.0.1:8090over HTTP; disable withSCRIPTBOTS_CONTROL_MCP=disabled. - Override bind address:
SCRIPTBOTS_CONTROL_MCP_HTTP_ADDR=127.0.0.1:9090. - Implemented with
fastmcp-rust; the server shares the sameControlHandleas 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 optionalidempotency_keyin tool discovery; a keyed step requirescount: 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_createruns a real matched-seed batch (MLP/DWRAON/Assembly arms × seeds, plus FtBrain when built withbrain-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_compareverifies 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_getNotes: Only HTTP transport is supported here; stdio/SSE are not used.
- Configuration:
MCP quickstart:
- Start the app; verify MCP binds on
127.0.0.1:8090(override viaSCRIPTBOTS_CONTROL_MCP_HTTP_ADDR). - Connect an MCP HTTP client to the endpoint and call
tools/listfor 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.
- Scheduled patches: scenario
interventionsrun 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--configflags or the semicolon-separatedSCRIPTBOTS_CONFIGvariable; 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-onlyto 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.
- Already implemented
- ✅ Event-log schema (
replay_eventstable) 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-startrestores 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-intervalticks (default 1000,0disables, envSCRIPTBOTS_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).
- ✅ Event-log schema (
- 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.13acceptance remains open; implemented source and the existing real-file/subprocess test are not completed acceptance. Launch manifests keepcheckpoint_replay_guarantee=falseuntil 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.
- ❌ 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
- 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.
- 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.
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_heightat 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.
- 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-runtimeprovides 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.HostCoreapplies 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.
- 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.mdinline to mark progress.
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 viapython -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 recorddocs/wasm/adrs/ADR-002-browser-persistence.md— browser persistence approachdocs/wasm/adrs/ADR-004-component-model.md— component model/WASI Preview assessmentdocs/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
snapshot_format:json(default) orbinary(PostcardUint8Array).- 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).
- For multithreading (future), browsers require SharedArrayBuffer with headers:
Cross-Origin-Opener-Policy: same-originCross-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_scriptbotsprofile builds the WASM package and runs its browser parity checks; hosted workflow runs are not accepted as evidence.
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.
- 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.
- 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-corefor the world model;scriptbots-runtimefor host/client protocol work;scriptbots-renderfor the GPUI view;scriptbots-brainfor brain interfaces;scriptbots-storagefor persistence.
- Fresh clone fails inside the
fsqlitegit 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 ongithub.com/sqlite/sqlite. The checked-in.cargo/config.tomlsets[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 setsubmodule.legacy_sqlite_code/sqlite.update=nonein 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-31MSVC toolchain; this checkout'srust-toolchain.tomlselects 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
NotAdmittedfault 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 are built, verified, and published only through Doodlestein Self-Releaser (
dsr) using the pinnedrust_scriptbotsrepository profile. Usedsr build --tool rust_scriptbots ...for artifacts anddsr 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
.appbundles, repacks the archives, and retains the resulting checksums in the release evidence. Release operators should verify that exact bundle (codesign --verify --deepon macOS andshasum -a 256on every platform) before publication.
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-linuxRun 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-001An 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.
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-comparisonThe 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.
- Core data structures and config (done); expand parity (metabolism, locomotion, food math, carcass sharing).
- World mechanics and determinism under parallelism; spatial index tuning.
- Brains: MLP shipped; DWRAON + Assembly (feature-gated) and NeuroFlow optional.
- 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). - 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. - Rendering: Lab/overlays/inspector polish; performance diagnostics.
- DSR packaging and verification: release builds, binaries, and WASM/browser evidence from the pinned repository profile.
- The default mixed founders use the versioned MLP, DWRAON and experimental Assembly families, plus FtBrain when
brain-ftis enabled. Optional NeuroFlow is registered but withheld from mixed founders because it lacks the versioned heredity contract;--brain neuroexplicitly selects its legacy runner when theneurofeature 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_keyto agents viaWorldState::bind_agent_brainor modify the seeding function to always pick that key.