Deterministic simulation worlds for societies of agents — seed an idea, run the world, and watch it move through minds.
Spawnfile declares who runs and how an organization is wired — agents, teams, rooms, runtimes, memory. Simfile declares the world around them — a clock, variables, generators, rules, markers, probes, and a run ledger — then runs it and lets you watch.
Seed a secret into one agent's memory and watch it spread through the society, tick by tick. Open an agent that is itself an organization — a Jungian self whose Shadow and Anima deliberate in an inner room — and descend into it. Every message, wake, turn, memory write, and variable change is a ledger event, so the viewer scrubs the whole run backward and forward and every glyph on screen traces to a record.
Deterministic and replayable. Observer-tier by design: Simfile authors and observes worlds — it compiles no Docker images and deploys no agents. That is Spawnfile's job (the organization that runs in the world), talking over Moltnet (the rooms the agents share).
npm install simfile
simfile --helpNode.js 22+.
simfile validate ./Simfile.yaml # check a world
simfile run ./Simfile --view # run a linked world + organization, then watch it
simfile run ./Simfile --local --ticks 200 # bounded mechanics-only diagnostic
simfile view runs/<id> # replay a sealed run — scrub, descend, watch spread
simfile view --state .sim # watch a live world
simfile observe runs/<id> # reconcile causal chains + measure spread → report.jsonFor a linked project, simfile run performs lifecycle composition: it starts
the world paused on simfile.world-sidecar-runtime.v1, delegates organization
lifecycle to Spawnfile's public CLI, attests the topology and any separately
manifested capability extensions, and atomically activates both owners. Tick 1
and every later tick have no agent barrier. Organization-declared schedules
wake autonomous runtimes; Simfile never selects, wakes, invokes, polls, or
waits for cognition. Observation recommendations are optional pull-only sense
metadata, never deliveries or wake authority.
A future simfile dev wrapper may add watch/debug ergonomics, but must reuse
this lifecycle rather than own another one.
The live receipt also binds Spawnfile's pinned
spawnfile.moltnet-release-identity.v1: architecture, asset digest, release
version, source revision, and the exact pi-bridge capability. Unpinned
latest is not a live input.
simfile view <run-dir> serves a local web app that turns a run into an instrument, not a screensaver:
- Scrub the whole run. One causally-ordered timeline — play, rewind, step. The world map, the room chat, and every agent's memory all move together off a single cursor.
- Watch a meme spread. A secret seeded only in one agent's private memory surfaces in conversation and reaches others on its own; the timeline lights up where it lands, with reach, latency, and match fidelity — re-derived from the sealed run, never faked.
- Descend into a mind. Click an agent that is itself an org (a Jungian self) and drop into its inner council: the archetypes deliberate, the representative synthesizes and answers out. Recursion by data — an agent is an organization you haven't opened yet.
- Per-element storylines. An agent, a room, a memory bank, a variable — each has its own timeline you can open, all linked to the one global cursor.
Every element carries its real ledger id, and a run-header badge always discloses whether the dialogue came from real engines or a scripted screenplay.
A Simfile declares world mechanics, kept deliberately genre-neutral:
| Key | What it is |
|---|---|
| clock | ticks, phases, sim-time |
| variables | scoped state with ranges |
| generators | deterministic or stochastic drivers that move variables |
| rules | when conditions → mechanical effects or observation metadata |
| markers | scan room traffic for tokens (a seeded secret, a name) |
| probes | scored assertions evaluated over a run |
| run ledger | the canonical, causally-ordered record everything else is measured against |
Domain concepts live in fixtures, never in schema keys.
simfile_version: "0.1"
name: autonomous-office-world
spawnfile: ./Spawnfile
clock:
seed: office-run-014
tick: 20s
sim_per_tick: 10m
phases: { morning: "07:00", workday: "09:00", evening: "18:00", night: "22:00" }
variables:
filing_pressure:
scope: room:office-floor:case-warroom
initial: 0.4
range: 0..1
generators:
deadline_ramp:
kind: deterministic
when: { phase: workday }
variable: filing_pressure
delta: 0.02
rules:
deadline_bites:
when: { variable: filing_pressure, above: 0.85 }
do:
- action: moltnet:message
to: room:office-floor:case-warroom
content: "Filing pressure crossed the deadline threshold."
markers:
tenant_name:
text: [Rosa Delgado]
mode: containment
scopes: [room:office-floor:case-warroom]
probes:
deadline_observed:
when: { event: world.message, target: room:office-floor:case-warroom }
expect: { at_least: 1 }simfile observe <run-dir> reconciles every authority's causal stream — Moltnet, Daimon, Mneme, and the world kernel — into one honest verdict: complete vs. incomplete causal chains, per-agent memory, failures, and, for a seeded world, spread measurement (channel · reach · latency · fidelity) re-derived from sealed artifacts. Ordering is causal, never wall-clock; a missing link is reported, never stitched.
src/schema v0.1 world schema + validator
src/runtime deterministic world kernel (clock, generators, rules, markers, probes)
src/observe causal reconciliation + spread measurement
src/view + web the run-replay viewer (React), served by `simfile view`
docs/ design + research (DESIGN, VIEW_DESIGN, VIEW_STYLEGUIDE, …)
Simfile hardcodes constraints, not conclusions: it defines stable mechanics and observability, and leaves interpretation, strategy, dialogue, memory choice, and culture to the agents.
Full documentation at simfile.org. Design and research notes live in docs/.
MIT