# lochheadr92-creator/simulation-3 architecture

> Architecture diagram of the GitHub repository lochheadr92-creator/simulation-3, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lochheadr92-creator/simulation-3
- Repository: https://github.com/lochheadr92-creator/simulation-3

## Overview

This repository implements a deterministic simulation: seeded scenarios produce proposals, a kernel settles each tick into immutable world state, and stream tooling records, resumes, replays, and presents runs. The world package adds a broader simulation domain—decision-making, ecology, resources, social behavior, and observation—with viewer components. The excerpts establish the kernel and stream relationships; most world modules were not sampled, so their internal wiring is intentionally not inferred.

Main entry points: [`stream/run.py`](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/run.py) (Run orchestration), [`kernel/engine.py`](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/engine.py) (Tick engine), [`stream/run_file.py`](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/run_file.py) (Append-only run file), [`kernel/settlement.py`](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/settlement.py) (Tick settlement)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_kernel["Simulation kernel"]
  node_engine["Tick engine<br/>[engine.py]"]
  node_proposals["Proposal expansion<br/>[proposals.py]"]
  node_settlement["Tick settlement<br/>[settlement.py]"]
  node_state["Immutable state<br/>[state.py]"]
  node_outcomes["Tick outcomes<br/>[outcomes.py]"]
  node_canonical["Canonical identity<br/>[canonical.py]"]
  node_diagnostics["Diagnostics<br/>[diagnostics.py]"]
end

subgraph group_stream["Run lifecycle"]
  node_scenario["Seeded scenario<br/>[scenario.py]"]
  node_runner["Run orchestration<br/>[run.py]"]
  node_runfile["Append-only run file<br/>[run_file.py]"]
  node_recovery["Run recovery<br/>[recover.py]"]
  node_replay["Run replay<br/>[replay.py]"]
end

subgraph group_world["World simulation"]
  node_worldrun["World runner<br/>[run.py]"]
  node_decision["World decisions<br/>[decide.py]"]
  node_process["World processes<br/>[process.py]"]
  node_ecology["Ecology<br/>[ecology.py]"]
  node_resources["Resource activities<br/>[foraging.py]"]
  node_social["Social behavior<br/>[social.py]"]
  node_observation["World observation<br/>[observe.py]"]
  node_storage["World storage<br/>[storage.py]"]
end

subgraph group_presentation["Views and inspection"]
  node_streamview["Run viewer<br/>[viewer.py]"]
  node_worldview["World view<br/>[world_view.py]"]
  node_webviewer["Interactive viewer<br/>[viewer.js]"]
end

node_user(("Simulation user"))

node_runner -->|"generates inputs"| node_scenario
node_runner -->|"runs ticks"| node_engine
node_runner -->|"writes run"| node_runfile
node_runner -->|"uses recovery"| node_recovery
node_runner -->|"uses replay"| node_replay
node_runner -->|"uses viewer"| node_streamview
node_engine -->|"settles tick"| node_settlement
node_engine -->|"builds record"| node_outcomes
node_engine -->|"publishes to"| node_diagnostics
node_settlement -->|"expands proposals"| node_proposals
node_settlement -->|"commits state"| node_state
node_scenario -->|"creates proposals"| node_proposals
node_runfile -->|"uses identity"| node_canonical
node_recovery -->|"reads run"| node_runfile
node_replay -->|"reads run"| node_runfile
node_replay -->|"replays through"| node_engine
node_streamview -->|"reads run"| node_runfile
node_storage -->|"uses observation"| node_observation
node_user -.->|"starts simulation"| node_runner
node_user -.->|"inspects world"| node_worldview
node_user -.->|"views simulation"| node_webviewer

click node_scenario "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/scenario.py"
click node_runner "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/run.py"
click node_engine "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/engine.py"
click node_proposals "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/proposals.py"
click node_settlement "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/settlement.py"
click node_state "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/state.py"
click node_outcomes "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/outcomes.py"
click node_canonical "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/canonical.py"
click node_diagnostics "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/diagnostics.py"
click node_runfile "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/run_file.py"
click node_recovery "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/recover.py"
click node_replay "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/replay.py"
click node_streamview "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/viewer.py"
click node_worldrun "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/run.py"
click node_decision "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/decide.py"
click node_process "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/process.py"
click node_ecology "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/ecology.py"
click node_resources "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/foraging.py"
click node_social "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/social.py"
click node_observation "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/observe.py"
click node_storage "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/storage.py"
click node_worldview "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/viewer/world_view.py"
click node_webviewer "https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/viewer.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_engine,node_proposals,node_settlement,node_state,node_outcomes,node_canonical,node_diagnostics,node_user toneBlue
class node_scenario,node_runner,node_runfile,node_recovery,node_replay toneAmber
class node_worldrun,node_decision,node_process,node_ecology,node_resources,node_social,node_observation,node_storage toneMint
class node_streamview,node_worldview,node_webviewer toneRose
```

## Components

### Simulation kernel

- [Tick engine](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/engine.py): `kernel/engine.py`
- [Proposal expansion](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/proposals.py): `kernel/proposals.py`
- [Tick settlement](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/settlement.py): `kernel/settlement.py`
- [Immutable state](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/state.py): `kernel/state.py`
- [Tick outcomes](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/outcomes.py): `kernel/outcomes.py`
- [Canonical identity](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/canonical.py): `kernel/canonical.py`
- [Diagnostics](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/kernel/diagnostics.py): `kernel/diagnostics.py`

### Run lifecycle

- [Seeded scenario](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/scenario.py): `stream/scenario.py`
- [Run orchestration](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/run.py): `stream/run.py`
- [Append-only run file](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/run_file.py): `stream/run_file.py`
- [Run recovery](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/recover.py): `stream/recover.py`
- [Run replay](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/replay.py): `stream/replay.py`

### World simulation

- [World runner](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/run.py): `world/run.py`
- [World decisions](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/decide.py): `world/decide.py`
- [World processes](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/process.py): `world/process.py`
- [Ecology](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/ecology.py): `world/ecology.py`
- [Resource activities](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/foraging.py): `world/foraging.py`
- [Social behavior](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/social.py): `world/social.py`
- [World observation](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/observe.py): `world/observe.py`
- [World storage](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/storage.py): `world/storage.py`

### Views and inspection

- [Run viewer](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/stream/viewer.py): `stream/viewer.py`
- [World view](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/viewer/world_view.py): `viewer/world_view.py`
- [Interactive viewer](https://github.com/lochheadr92-creator/simulation-3/blob/codex/kernel-first-slice/world/viewer.js): `world/viewer.js`

### Other components

- **Simulation user**

## Connections

- Run orchestration → Seeded scenario: generates inputs (evidence: `stream/run.py`)
- Run orchestration → Tick engine: runs ticks (evidence: `stream/run.py`)
- Run orchestration → Append-only run file: writes run (evidence: `stream/run.py`)
- Run orchestration → Run recovery: uses recovery (evidence: `stream/run.py`)
- Run orchestration → Run replay: uses replay (evidence: `stream/run.py`)
- Run orchestration → Run viewer: uses viewer (evidence: `stream/run.py`)
- Tick engine → Tick settlement: settles tick (evidence: `kernel/engine.py`)
- Tick engine → Tick outcomes: builds record (evidence: `kernel/engine.py`)
- Tick engine → Diagnostics: publishes to (evidence: `kernel/engine.py`)
- Tick settlement → Proposal expansion: expands proposals (evidence: `kernel/settlement.py`)
- Tick settlement → Immutable state: commits state (evidence: `kernel/settlement.py`)
- Seeded scenario → Proposal expansion: creates proposals (evidence: `stream/scenario.py`)
- Append-only run file → Canonical identity: uses identity (evidence: `stream/run_file.py`)
- Run recovery → Append-only run file: reads run (evidence: `stream/recover.py`)
- Run replay → Append-only run file: reads run (evidence: `stream/replay.py`)
- Run replay → Tick engine: replays through (evidence: `stream/replay.py`)
- Run viewer → Append-only run file: reads run (evidence: `stream/viewer.py`)
- World storage → World observation: uses observation (evidence: `world/storage.py`)
- Simulation user → Run orchestration: starts simulation
- Simulation user → World view: inspects world
- Simulation user → Interactive viewer: views simulation
