Operational facts a fresh session needs. Updated at the close of every work session (section 0.7).
What this project is. A headless, deterministic 2D village economy simulation in Go, where a small population of agents works a two-chain economy (beer/food and housing), eventually driven by small neural networks. The long-term UI is a Godot townscape, out of scope. The binding process rules are in section 0; the design is the body of this file; the current numbers are in Appendix A.
Repository layout.
nn-village-sim/
├── SPEC.md # this file: spec + architecture + decisions + progress + handover
├── go.mod # module nnvillage, Go 1.22, standard library only
├── cmd/
│ ├── village/main.go # run one sim; -seed -ticks -json -fire -storm
│ └── sweep/main.go # parameter sweeps; -runs -seeds -days -jobs -out
├── internal/
│ ├── config/config.go # all world parameters + Hash()
│ ├── world/ # graph, grid generator, Dijkstra/A*, sites, lots
│ ├── policy/policy.go # Policy interface; scripted + random
│ ├── sim/ # sim loop, state, tasks, needs, population, disasters, metrics, tests
│ └── sweep/sweep.go # sampling, parallel execution, early kill, CSV
└── budget/
├── flow_budget.py # iteration-2 budget generator (writes CSV/XLSX)
├── flow_budget.csv # canonical computed output
├── flow_budget.xlsx # spreadsheet (parameters + derived)
└── build_site.py # renders SPEC appendices to the public site
Reproduce the budget. python3 budget/flow_budget.py. Build-time Python deps: openpyxl,
markdown (installed via pip install --user --break-system-packages). The CSV is canonical.
Public URL. https://nn-village-sim.bernie-dev.de/ (Caddy file_server on the /var/www
mount; config /root/caddy/sites/nn-village-sim.caddy). Regenerate with
python3 budget/build_site.py; reload Caddy only when the site config changes. Every session must
republish here before finishing.
Verify. go test ./... (determinism, item conservation over 6000 ticks, beer-chain end-to-end,
foraging switch, immigration/emigration/age-death, fire/storm scenarios, sweep worker determinism, and
the per-stage regression suite). Also: go vet ./..., gofmt -l . (empty),
go run ./cmd/village -seed 12345 -ticks 3000 -json twice → identical output;
go run ./cmd/sweep -runs 10 -seeds 1,2,3,4,5 -days 5 -jobs 1 vs -jobs 4 → identical CSV.
Do not decide [OPEN] items (section 16); collect them for the owner in this handover. Prefer Go standard library; log any added dependency. Use subagents for focused implementation tasks.
Where the last session left off (run complete). Spec is at iteration 2 and its flow budget passes
all acceptance targets (utilization 84% at P=13). M0–M6 are all complete and tested, Go standard
library only:
- M0 skeleton, M1 housing chain, M2 wheat chain, M3 beer chain (scripted two-chain economy at a stable
equilibrium; measured utilization 0.86 matches the 0.84 budget), M4 population dynamics (village
settles at population 14), M5 disasters (fire + storm, opt-in, scenario harness), M6 sweep tooling +
regression suite (deterministic across workers; the suite caught and fixed a conservation leak).
- Next actions (NOT started, for the owner to prioritise): M7 (NN agents: MLP policy, decision
logging, imitation pretraining, residual policy) and M8 (handover experiments); M9 (snapshot/replay
+ Godot) is a separate project. Nothing beyond M6 was built.
- Open questions for the owner are in section 16 and are unchanged: training method (evolution vs
RL), immigrant network source, pride/village-welfare weights, townhall vote, and final numeric
parameters. Also worth a decision: whether the immigration gate should target 12–14 explicitly or
stay purely margin-based, and calibration of the disaster probabilities.
- Regenerate the public site with python3 budget/build_site.py; run go test ./... before any change.