Architecture

WorldFork is backend-first and CLI-first. Conceptually, it is a Monte Carlo tree search of the real world: the backend owns the branching search tree, simulated rollouts, terminal outcome evidence, and reports, while the CLI provides the stable control surface for operators and agents.

Runtime Stack

Layer	Responsibility
FastAPI	Canonical HTTP API and agent discovery
Celery	Queue-backed execution for long-running jobs
Postgres	Durable Big Bang, multiverse, tick, job, report, and log state
Redis	Broker, result backend, and runtime coordination
LangGraph	Checkpointed tick graph execution
OpenRouter	LLM provider surface for the default DeepSeek Flash fast lane and optional strong-model substitutes
OpenAI Codex	Default strong-model route for initializer, governance, endpoint-ledger, and final-report work
Artifact store	Non-regenerable evidence and audit payload files
`worldfork` CLI	Operator and AI-agent command surface

Core Concepts

Big Bang

A Big Bang is the root scenario and the root node of the search tree. It stores scenario input, simulation config, model config, branch policy, initialization output, and the root multiverse.

Multiverse

A multiverse is one timeline node in the Big Bang tree. It can inherit ticks from a parent, execute new ticks, branch into children, terminate, report, and later continue with a higher tick limit.

Tick

A tick is one simulation step. Tick execution records node attempts, checkpoints, tool calls, graph updates, sociology signals, God-agent review, and the final tick snapshot.

Tick execution is a checkpointed runtime graph. Cohort decisions run in bounded parallel batches, hero decisions run after cohort checkpoints, and downstream event, sociology, graph, God-review, endpoint-ledger, tool-call, summary, and commit stages run in order. See Runtime Walkthrough for the full stage order and resume behavior.

Endpoint Ledger

An endpoint ledger tracks terminal predicates and evidence for a multiverse or Big Bang. Endpoint status answers whether a terminal condition is yes, no, unresolved, or unresolved due to insufficient ticks. Branch/path probability is accounted for separately through path mass and final timeline adjudication.

Cost Summary

Cost summaries are derived from audited LLM calls and model price estimates. They are available at run, tick, report-version, and estimate surfaces so operators can inspect actual and projected spend in USD.

Report

A report is a logical slot. A report version is a generated revision containing structured content and metadata. Markdown and PDF outputs are ephemeral renders generated from that version on request.

Data Flow

Scenario dossier
      |
      v
Big Bang initialization
      |
      v
Root multiverse
      |
      v
Tick runtime graph
      |
      +-- events
      +-- actor/cohort/hero state
      +-- sociology and graph pressure
      +-- God-agent review
      +-- tool-call checkpoints
      |
      v
Branch decisions, endpoint ledgers, and terminal outcomes
      |
      v
Structured reports and ephemeral renders

Initialization

worldfork init posts to POST /api/big-bangs and waits for the blocking initializer to finish. Initialization snapshots the source scenario, optionally chunks long scenario text, calls the initializer agent, validates structured JSON, and persists root M1 state with T0 cohorts, heroes, graphs, events, endpoint ledgers, and config artifacts.

The initializer output is population-aware. Population archetypes include population totals, and cohort states include represented population, population share, and representation mode. That population data flows into later sociology, split, merge, and report reasoning.

Branching

Branches are constrained by branch policy:

maximum branch depth
maximum active multiverses
maximum branches per tick
branch score threshold
idle termination behavior

Child multiverses inherit parent ticks through lineage references and receive their own executable state after the fork point. When a tick’s branch_score crosses the configured threshold, backend policy creates a create_branch tool call if the God-agent did not supply one. A plain continue_timeline response is not allowed to veto threshold-crossing branch pressure.

Jobs And Control

The backend models queued work as jobs. Operators can pause, resume, interrupt, requeue, claim, or synchronously run jobs through the API and CLI. Agent code should use worldfork jobs wait with a bounded timeout.

The queue sees one tick job per multiverse tick. Cohort fan-out happens inside that job through bounded in-process parallelism rather than as one Celery job per cohort. This keeps checkpoint/resume semantics tied to the tick execution while still allowing high-volume cohort LLM calls to run concurrently.

Storage Boundaries

Postgres is canonical for domain state. Artifacts store non-regenerable evidence and audit payloads. Report renders are regenerable from the corresponding database report version and should be generated only on request.

Agent Surface

Agents should start with:

worldfork agent discover
worldfork status

The discovery route is the contract for supported commands, verbosity tiers, known job types, and recommended flows.