# Civilization simulator — implementation plan

**September 14 clarification:** Pupbro distributes discovered geography across the explorer's
whole cluster. Record the explorer's credit separately. A shared map does not expose live enemies
or current conditions. See [CM-04](community-milestones-discovery-2026-09-13.md). The local Orbit
surface survey does not yet publish shared discovery or contribution events.

**September 13 refinement:** [community milestones and progressive discovery](community-milestones-discovery-2026-09-13.md)
adds active-member baseline shares, bounded contribution weights, and a frontier that reveals
through validated play. Ambient NPC work does not reduce a milestone's pool. Compare different
active populations, passive members, affiliation windows, and illustrative 1×/2×/3× weights.
EXP triggers only at community milestones, not daily check-ins or individual tile reveals.
Add survey/remote-sensing, shared-map, chunk-history, and frontier-exhaustion scenarios. Existing
fog reports are not reward-grade evidence. These are test requirements, not implemented systems.

**September 11 refinement:** the [current model](daily-life-rewards-token-model-2026-09-11.md)
sets a one-human-plus-NPC 23-year reference and keeps a zero-human control. Add reward-disabled and
finite-reward scenarios, contribution attribution, nested milestone budgets, Sybil cohorts,
circulating supply, and USDC-reserve stress tests. These are experiments to build, not forecasts.
Daily check-ins must never replay production. Public observation is read-only and costed separately.

**September 10 refinement:** use the [Return Chronicle model](chronicle-return-model-2026.md)
and [build checklist](chronicle-return-checklist-2026.md) for the next narrow experiment. Start with
one measured production chain before the larger first slice below. Add 0 and 10-player reference
cases. Model actual useful work, not registration-driven acceleration. The new pacing calculator
is an isolated arithmetic illustration, not completion of this simulator or its Monte Carlo runner.

**Accepted update, 2026-09-07:** follow [the settlement delivery plan](settlement-delivery-plan.md)
and [civilization integrity specification](civilization-integrity-spec.md). Monitor all catalog
worlds, but compare civilization metrics only where applicable. Universal maturity is not a goal.
The scenario adapter and [Observatory preview](chronicle-laboratory-draft.md) now exist. The preview
was deployed September 7. It uses toy rules, not a calibrated galaxy simulator or live telemetry.
Use [current project status](project-status-2026-09-08.md) for the current build order.

**Original scope, 2026-09-04:** approved planning task. This plan defines a separate design
laboratory for testing the Living Frontier from Genesis Day through the 23-year Chronicle. It does
not authorize a production simulation, database migration, deployment, or Genesis clock.

## 1. Purpose

The [full-game rollout plan](exp-rollout-plan-2026.md) places S0–S7 inside the release sequence. It
adds statistical stopping criteria, detailed-versus-coarse comparisons, operating budgets, and
human playtest gates. Reuse only stable domain transitions between this lab and live adapters;
keep experimental policies, acceleration, and reporting separate.

Build a repeatable Monte Carlo simulator that can test civilization rules before they become
persistent history. It must show which assumptions support survival, which produce exploitation or
collapse, and which outcomes remain sensitive to small changes.

The simulator does not predict one future. It maps ranges, dependencies, bottlenecks, failure
chains, and safe operating boundaries.

## 2. Questions it must answer

- What minimum population can sustain essential services?
- What changes with 100, 1,000, 10,000, or 100,000 human players?
- Which of about 100 occupations become critical bottlenecks?
- How much work can AGI and robots perform under realistic energy and maintenance limits?
- When do Ark food, medicine, parts, vehicles, machines, and seed reserves run out?
- Which material, ecological, transport, knowledge, or governance failures cascade into collapse?
- Which worlds flourish, stagnate, fracture, recover, remain wild, or disappear?
- Can a settlement support safe water, food, shelter, health, power, education, and succession?
- When can a world build orbital capacity, trade with another world, or become Ark-independent?
- Which Coin policies produce stability, inflation, deflation, corruption, or default?
- How many worlds can the available player population influence at once?
- Can the 23-year Chronicle targets remain plausible under conservative, expected, and ceiling
  participation?
- Which immutable Genesis rules fail under adversarial play?

## 3. Product boundary

Start with an internal command-line application and machine-readable reports. Do not begin with a
public dashboard. A deterministic simulation engine, scenario files, batch runner, and validated
outputs provide more value than presentation during the first phase.

Add a local browser dashboard after the engine can reproduce runs and explain results. Never connect
the laboratory directly to production state. Production may later reuse proven domain rules, but it
must not import an experimental engine as one large dependency.

## 4. Proposed architecture

Use TypeScript to match the game repository and share validated types deliberately.

1. **Domain kernel:** Pure functions for time, population, work, matter, ecology, infrastructure,
   economy, governance, risk, travel, and milestones.
2. **Scenario schema:** Versioned JSON or YAML inputs with validation, units, defaults, bounds, and
   source notes.
3. **Deterministic runner:** A seed and rule version produce the same event stream and state.
4. **Monte Carlo coordinator:** Runs thousands of seeds across parameter ranges and worker threads.
5. **Policy agents:** Bounded decision strategies for households, workers, institutions,
   settlements, and governments. They are not language models in the core loop.
6. **Event and state store:** Append-only run events plus periodic snapshots. Start with local files
   and columnar results. Add a separate analysis database only when run volume requires it.
7. **Metrics engine:** Computes outcomes, distributions, sensitivity, bottlenecks, and failure
   attribution.
8. **Report layer:** Produces JSON, CSV, charts, timelines, comparisons, and human-readable run
   summaries.
9. **Local dashboard:** Explores scenarios, worlds, causal chains, maps, and parameter sweeps.

The simulator must use integer or fixed-point units where conservation matters. Floating-point
rounding must not create food, matter, energy, Coins, people, or time.

## 5. Time model

The runner supports two clocks:

- **Ark time:** 23 simulated days per active Earth day and the Still Hour boundary.
- **planning time:** accelerated execution of any interval from one hour to 23 real years.

One tick must not mean the same thing for every subsystem. Immediate risk may resolve in seconds or
minutes. Work and travel may update hourly. Markets may clear at defined intervals. Crops, forests,
demography, and institutions may use daily, monthly, or annual transitions.

The scheduler must preserve causality across these rates. A daily crop update cannot consume water
that an hourly transport failure prevented from arriving.

## 6. Input model

### Population and participation

- human-player count and arrival curve;
- autonomous population by world, species, age, household, and health;
- active, intermittent, absent, retired, and returning player proportions;
- session frequency, session length, and offline-plan duration;
- cooperation, trust, risk tolerance, migration, conflict, and rule compliance;
- frontier PvP, surrender, capture, permanent death, detention, restitution, rehabilitation, and
  Unsettled Legacy behavior;
- births, pregnancy, health, aging, death, rejuvenation, and household formation;
- nonlinear childhood development, slowed adult aging, generational succession, inheritance, and
  kinship constraints;
- partnership dissolution, custody, guardian succession, and public care capacity;
- education, mentorship, skill loss, and generational transfer.

Children remain protected demographic and NPC records. They are never playable agents. The
simulation tracks care, health, education, and future adulthood without modeling sexual activity.

### Roles and capability

Define about 100 occupations as work packages rather than character classes. Each role references
several of the 23 skill trees, required tools, facilities, inputs, working conditions, and service
outputs.

Initial families should include food, water, medicine, construction, textiles, materials, energy,
maintenance, transport, science, education, communication, governance, care, trade, ecology,
security, rescue, and culture.

Inputs include role distribution, competence bands, training time, substitution, cross-training,
mentorship capacity, fatigue, injury, aging, and minimum staffing.

### AGI and robots

- model availability, capability, reliability, latency, permissions, and compromise rate;
- robot class, count, duty cycle, energy, parts, maintenance, supervision, and environment;
- task substitution and complementarity with people;
- performance loss in novelty, damaged infrastructure, and unknown terrain;
- robotic-person population, rights, labor choices, damage, and repair.

### Ark inheritance

- verified manifest and Late Awakened reserve;
- preserved food, seed, medicine, garments, tools, machines, vehicles, robots, archives, and parts;
- cache size, location, condition, accessibility, and discovery rate;
- fabrication capability, feedstocks, energy, calibration, and failure;
- original and surviving infrastructure.

### Natural systems

- terrain, climate, weather, soil, water, vegetation, wildlife, minerals, and salvage;
- growth, reproduction, succession, migration, regeneration, and depletion;
- disturbance, fire, disease, pollution, erosion, and restoration;
- survey confidence, deposit grade, access, recovery, and waste;
- land rights, protected areas, harvest limits, and external costs.

### Production and infrastructure

- bills of materials, labor, energy, time, tools, facilities, quality, and by-products;
- storage, spoilage, transport, repair, recycling, and substitution;
- water, sanitation, food, shelter, health, energy, communication, education, and roads;
- civic shelter capacity, household formation, housing pathways, land access, and displacement;
- settled boundaries, frontier claims, homestead viability, mutual defense, rescue coverage, and
  outpost formation;
- capacity, condition, redundancy, maintenance debt, and critical dependencies.

### Economy and government

- Coin issuers, supply, budgets, taxes, fees, debt, credit, reserves, and exchange regimes;
- prices, wages, contracts, inventories, markets, clearing, and trade;
- government form, offices, competence, legitimacy, participation, law, and succession;
- corruption incentives, separation of duties, audit quality, enforcement, and recovery;
- rights, property, commons, extraction policy, diplomacy, and conflict.

### Risk and geography

- environmental, mechanical, medical, logistical, knowledge, social, and conflict hazards;
- incident frequency, severity, safeguards, rescue, and causal dependencies;
- world and cluster count, distance, route capacity, travel time, communication delay, and outage;
- player placement, world capacity, migration, discovery, and progressive inhabitation.

### Rule configuration

- death, injury, retirement, rebirth, custody, and rejuvenation rules;
- offline consent, stop, retreat, and unattended limits;
- milestone definitions and evidence duration;
- Still Hour behavior and correction rules;
- simulation version and migration policy.

## 7. Output model

Each run produces:

- population size, age structure, households, births, deaths, migration, and dependency ratios;
- player distribution, participation, retention, and world influence;
- occupation coverage, competence, vacancies, training queues, and role bottlenecks;
- robot and AGI work share, failures, maintenance burden, and human dependencies;
- civic-safe-zone coverage, defensive-guardian allocation, witness coverage, wanted populations,
  bounty outcomes, prison population, recidivism, and justice-system capacity;
- non-sentient and sentient robot populations, creation-covenant duration, emancipation, retention,
  and personhood disputes;
- resource stocks, harvests, regeneration, depletion, pollution, and restoration;
- production throughput, shortages, waste, repair, and infrastructure condition;
- water, food, shelter, medical, energy, education, transport, and rescue coverage;
- prices, wages, Coin supply, inflation, exchange rates, debt, defaults, and trade balances;
- government legitimacy, service quality, participation, corruption, disputes, and succession;
- incidents, injuries, permanent deaths, collapses, recoveries, and causal chains;
- milestones reached, regressed, delayed, failed, and forecast;
- world outcomes and galaxy-wide capacity through the Chronicle.

Aggregate reports show medians, ranges, percentiles, failure probability, time to outcome, and
confidence. Averages alone can hide catastrophic tails.

## 8. Required views

- scenario comparison;
- 23-year galaxy timeline;
- world and cluster outcome map;
- population pyramid and migration flow;
- role coverage and training bottleneck heat map;
- stock-and-flow diagrams for matter, energy, food, water, and Coins;
- infrastructure dependency graph;
- ecology and land-use change;
- price, currency, debt, and trade history;
- government health and corruption investigations;
- risk-chain explorer;
- milestone evidence and critical path;
- sensitivity and threshold report;
- run replay with rule version and random seed.

## 9. Scenario families

### Conservative

Low player population, weak retention, uneven skills, damaged Ark stores, limited robots, poor
coordination, frequent shocks, and slow trade. This scenario tests survival and recovery.

### Expected

Plausible player growth, mixed institutions, uneven world outcomes, useful AGI, constrained robots,
normal ecological pressure, and periodic crises. This scenario guides ordinary balance.

### Ceiling

Strong participation, mature coordination, effective institutions, high robot availability, and
rapid parallel development. This scenario tests the upper 23-year Chronicle target without making
it a promise.

### Adversarial

Coordinated exploitation, hoarding, circular trade, treasury capture, botting, false delivery,
market manipulation, destructive harvesting, griefing, absentee leadership, and deliberate cascade
attempts. This scenario tests whether fictional freedom can break the real system.

Every family runs at 100, 1,000, 10,000, and 100,000-player scales where applicable.

## 10. Validation laws

The September 13 addition requires separate ledgers for milestone eligibility, contribution,
knowledge, survey authorship, and wallet collection. A positive baseline share does not require
useful project output; its active-membership rules remain open. Same-milestone members share an
entitlement settlement time even when actual collections differ. Background NPC and authorized
player-offline work must remain distinct. Test generation order and chunk reload against the same
compact history; visibility does not advance work, restore resources, or mint discovery credit.

Required incentive stress cases: passive majority, last-minute join, identity farming, communities
excluding recruits, stopping at a contribution cap, delaying completion to alter shares, discovery
collusion, hidden-map leaks, and rapid simultaneous milestone releases. Do not assume slow NPC
progress makes these cases safe. No reward-date or token-demand guarantee follows from calibration.

- Matter and energy reconcile within defined loss and measurement error.
- Population changes have a recorded cause.
- Coin entries balance by issuer and transaction.
- No event spends one object in two places.
- No child becomes a playable or economic agent.
- No token or real-money payment directly grants civilization capability. Measure indirect
  advantages from preserved equipment; the September 8 claim policy does not call them cosmetic.
- Identical seed, input, and version reproduce the same run.
- Parallel execution produces the same result as ordered reference execution.
- Every milestone cites sufficient state and duration evidence.
- Every correction preserves the original event.
- Failed invariants stop the run instead of silently repairing it.

## 11. Calibration and evidence

Each parameter receives a source class:

- measured game behavior;
- current engineering or scientific evidence;
- historical analogue;
- expert estimate;
- design assumption;
- stress-test extreme;
- in-world law.

Store the value, unit, range, date, source, uncertainty, and owner. Do not hide a design preference
inside a scientific-looking constant.

Calibrate in layers. First validate conservation and simple production. Then compare demographic,
ecological, infrastructure, market, and institutional behavior with known patterns. Finally test the
fictional technology and galaxy scale.

## 12. Implementation phases

### S0 — contracts and fixtures

Define units, schemas, seeds, events, state, invariants, and ten tiny hand-calculated scenarios.
Exit when every scenario reproduces its expected ledger exactly.

### S1 — one settlement survival model

Implement time, population, 20 essential roles, Ark stores, water, food, shelter, health, power,
simple work, and incident chains. Test 100 to 10,000 inhabitants.

### S2 — matter and living land

Add the first complete water, food, wood, hemp, medicine, mineral, and salvage chains. Add growth,
depletion, waste, repair, and restoration.

### S3 — skills, AGI, robots, and 100 roles

Map the 23 skill trees into about 100 occupations. Add training, mentorship, substitution, robot
work, AGI support, maintenance, and failure.

### S4 — economy and government

Add Coin issuance, budgets, prices, contracts, credit, taxes, corruption, audits, offices,
legitimacy, policy, and succession.

### S5 — world network

Add multiple settlements, worlds, travel, communication delay, trade, exchange rates, clearing,
migration, diplomacy, and progressive inhabitation.

### S6 — Chronicle scale

Add clusters, lightweight background worlds, milestones, 23-year scenarios, batch execution,
sensitivity analysis, and conservative, expected, ceiling, and adversarial reports.

### S7 — decision dashboard

Build the local browser interface only after the simulation contracts stabilize. Add comparison,
replay, maps, charts, thresholds, and export.

## 13. Test strategy

- unit tests for every transition and conservation rule;
- property tests across generated states;
- golden fixtures for hand-calculated scenarios;
- deterministic replay across machines and worker counts;
- metamorphic tests for unit scaling and equivalent event order;
- long-run soak tests for drift and memory;
- adversarial strategy tests;
- performance tests at each player and world scale;
- sensitivity tests that perturb one assumption at a time;
- independent review of demographic, ecological, economic, and safety models.

## 14. Decision gates before Genesis Day

The simulator cannot prove the game safe. It can disprove weak rules. A Genesis rule may lock only
after:

1. its units and invariants pass;
2. conservative scenarios retain a recovery path;
3. expected scenarios avoid routine collapse or runaway abundance;
4. ceiling scenarios avoid overflow and infinite growth;
5. adversarial scenarios cannot create profitable real exploits;
6. sensitivity analysis identifies its dangerous thresholds;
7. the team publishes the remaining uncertainty;
8. the operator and required reviewers accept the risk.

## 15. Deliverables

- versioned scenario schema;
- domain and event contracts;
- 100-role working taxonomy;
- reference scenarios at four player scales;
- deterministic simulation engine;
- Monte Carlo batch runner;
- invariants and test suite;
- local results store;
- report generator and exports;
- decision dashboard;
- calibration and source registry;
- Genesis readiness report;
- operations guide for rerunning scenarios after every rule change.

## 16. First implementation slice

Build one settlement for one Ark year with 1,000 people. Include 20 essential roles, water, food,
shelter, medicine, power, wood, hemp, one mineral, Ark stores, simple Coins, one council, weather,
five incident chains, AGI support, and three robot classes.

Run four variants:

1. balanced population and stores;
2. missing medical staff;
3. water-system failure;
4. excess robot capacity with insufficient maintenance.

This slice should reveal whether the architecture can explain cause and consequence before the team
adds a galaxy.

## 17. Task status

- **Priority:** major, pre-Genesis.
- **State:** planned; implementation not started.
- **Dependencies:** stable time, matter, risk, population, skill, economy, government, and milestone
  contracts.
- **First gate:** approve S0 schemas, units, invariants, and hand-calculated fixtures.
- **Deployment:** none. The first version remains a local design tool.