# GENESIS model specification

This document describes the implemented rules in `src/engine.js`, model version 1. A tick is an abstract model step, not a calibrated day or year. Numbers are assumptions for this computational laboratory, not measurements of human behavior. Actual experimental results and their controls are in [EXPERIMENTS.md](EXPERIMENTS.md).

## State and determinism

The world is a bounded rectangular lattice with no wrapping. Default size is 32 × 22 cells with 140 initial agents. The engine accepts dimensions 8–128, subject to at most 8,192 cells. Population is capped by a parameter, default 3,000; this input limit is not a performance guarantee.

All relevant dynamic state is JSON: tick, seeded random-generator state, tiles, agents, current parameters, active shocks, cumulative ledgers/counters, next agent ID, events, and observations. There is no hidden world-specific module state. `cloneWorld` serializes and validates a complete independent copy. Rendering, wall-clock speed, selection, and charts are outside the model.

Randomness uses a 32-bit xorshift generator with shifts 13, 17, and 5. Its unsigned integer state is divided by 2^32 to obtain a draw in [0,1). Seed zero is mapped to `0x9e3779b9` to avoid xorshift's absorbing zero state; therefore those two input seeds intentionally produce the same random sequence. Each tick starts with agents sorted by ID from the previous tick and uses a Fisher–Yates shuffle. The shuffled order is reused for action, barter, aid, and demographic processing. Newborns begin acting next tick.

Replay requires the same model code, complete state, and ordered interventions. JavaScript binary floating-point arithmetic and transcendental functions are used. Bitwise identity across different JavaScript engines is not promised. An intervention can change later random-draw consumption; paired branches share their initial generator state, not necessarily matching draws for corresponding later actions.

Save validation additionally bounds general numeric magnitudes at 1e100 to prevent finite inputs from overflowing derived arithmetic, requires productive land capacity of at least 1e-6, and checks finite ledger sums. These are defensive import bounds, not ordinary model parameter values. A rejected intervention cannot partially change state. At most 1,000 simultaneous droughts are allowed; individual step calls accept up to 100,000 ticks. Tick arithmetic must remain within safe integer precision.

## Terrain and initialization

Elevation combines seeded sinusoidal fields and small independent random perturbations. Low terrain and a winding river are water; high terrain is hill; another smooth field distinguishes forest from plain. Water is impassable and has zero resource capacity. This is procedural geography, not a scripted history.

| Terrain | Base food capacity | Base wood capacity |
| --- | ---: | ---: |
| Plain | 24 | 6 |
| Forest | 10 | 32 |
| Hill | 9 | 11 |
| Water | 0 | 0 |

Each land cell's capacities share a random multiplier in [0.75,1.25). Each resource starts at 65–95% of its capacity; initial soil is 0.85–1. Agents are placed uniformly among land cells, allowing multiple occupants. Initial food is 7–12, wood 1–4, tool quality 0–0.5, health 1, and age an integer 0–139. Initial food and wood skills are independently drawn in [0.65,1.6), sociability in [0,1), and lifespan is an integer 440–679. These initial endowments are assumptions and recorded sources.

## Exact tick order

1. Increment tick and reset current-tick counters.
2. Expire shocks, recover soil, and regenerate environmental stocks.
3. Shuffle the current agents and build spatial buckets.
4. Each shuffled agent executes one selected action. Resource depletion and movement immediately affect later agents in the same tick.
5. If enabled, process local barter using the resulting locations and inventories.
6. If enabled, process local food aid.
7. Age agents; consume food and fuel; update health, spoilage, tool wear, and trust decay; process death or possible birth.
8. Sort survivors and newborns by ID, remove relationships with agents that died, and record metrics.

This is a sequential update model, not a simultaneous equilibrium solver. A randomized order reduces a fixed-ID scheduling advantage but does not remove ordering effects.

## Ecology

Let `S` be soil, `F,W` local food/wood stocks, `KF,KW` capacities, `r` the regrowth-rate parameter, and `D` the product of active drought factors. First:

```text
S ← min(1, S + 0.0015(1 − S))
season(t) = 0.82 + 0.28 sin(2π(t mod 120)/120)
food growth = min(KF − F, KF × 0.045 × S × season(t) × D × r × (1 − F/KF))
wood growth = min(KW − W, KW × 0.018 × (0.4 + 0.6S) × r × (1 − W/KW))
```

Nonnegative growth is added to stock and to the corresponding regeneration source ledger. These rules replenish empty cells; they do not model biological extinction, seeds, nutrients, or energy conservation. Drought directly reduces food regeneration only. Water is a movement barrier, not a separate drinking-water requirement.

Harvesting `q` food reduces soil by `q × degradationRate`; harvesting wood reduces it by `0.4q × degradationRate`. A floor of 0.12 limits extraction damage. Soil affects subsequent regeneration, not the immediate harvest formula. Default degradation rate is 0.0025; default regrowth multiplier is 1.

## Agent actions

Agents have no global map search, language model, beliefs, institutional goals, or scripted historical objective. They evaluate their own inventory and the current/adjacent cells. Skills are persistent heterogeneity, not learned through practice. A transparent utility heuristic was chosen because all action inputs can be inspected and the same engine can run cheaply in browser and Node tests; it is not claimed to be psychologically optimal.

Food and wood harvest potentials are:

```text
qF = min(local food, 2.5 × foodSkill × technology × (1 + 0.6 × tool))
qW = min(local wood, 3.3 × woodSkill × technology × (1 + 0.35 × tool))
scoreF = log(1 + qF/(owned food + 1))
scoreW = 0.45 log(1 + qW/(owned wood + 1))
```

The larger score wins initially; exact ties favor food. Harvest transfers existing stock from the tile to the agent. `foodProduced` and `woodProduced` measure this transfer, not creation of matter. Production-action counters count actions, not units.

An agent considers crafting only with wood ≥4, food ≥3, and tool <0.55. Its score is:

```text
benefit = 8 × 0.6 × foodSkill × technology × (1 − tool)/(food + 1)
cost = 0.45 log((wood + 1)/(wood − 3)) + log((food + 1)/food)
craft score = benefit − cost
```

This is a fixed heuristic for anticipated benefit, not an executed eight-step plan. If selected, crafting consumes 4 wood and 1 food and sets tool quality to 1. The inputs are ledger sinks. Tool quality is a bounded productive capability, not a conserved tradable good.

Movement considers only the four orthogonal neighbors, in left/right/up/down order where present; water is skipped. A route costs:

```text
cost = transportCost × (1 + 2|destination elevation − origin elevation|
                         + 0.5 if destination is hill)
```

The agent requires food ≥ cost + 0.1. With `bestHere` the larger harvest score and `bestThere` the larger harvest score at the candidate destination:

```text
move score = 2(bestThere/(1 + 0.12 × destination population) − bestHere)
             − cost/(food + 1)
```

A move replaces the current choice only if its score is strictly greater. It consumes the route's food cost and uses the whole action, so the agent does not harvest in that tick. If no positive action score exists, the agent rests. The recorded explanation gives actual scores, quantities, and locations used by that action; it does not prove the ultimate cause of a later population change.

## Exchange and social memory

Trade is bilateral barter of food for wood. There is no currency, global market, price noise, credit, tax, enforceable debt, or central price setter. Candidates are in the same cell or one orthogonal cell away; at most the first 24 nearby agents are considered. Candidate ordering and this cap can matter at high density. Each agent can participate in at most two trades per tick. There is no separate barter transport fee; the transport parameter affects agent movement.

The inventory utility is `U = log(food + 1) + 0.45 log(wood + 1)`. Each agent's marginal food-per-wood valuation is `R = 0.45(food + 1)/(wood + 1)`. The higher-R participant buys wood. Trade is considered only if valuations differ by at least 8%, the buyer has at least 2 food, and the seller has at least 0.3 wood. The offered price is `sqrt(Rbuyer × Rseller)` food per wood.

The initial quantity is the minimum of `1.1 + 0.45 × mutual trust`, 45% of seller wood, and the buyer's food budget after reserving 1 food. The algorithm tries up to five quantities, halving after rejection. Both parties must improve the stated utility by more than 0.00001, and accepted wood quantity must be at least 0.02. The price therefore changes quantities, affordability, and acceptance. Accepted exchanges transfer ownership without a source or sink. This designed Pareto-improvement test does not guarantee increased health, lifetime welfare, or world population.

Successful barter raises each participant's trust in the other by 0.08. Trust is clamped to [0,1]. Each agent remembers at most 12 peers, discarding the weakest link (ID breaks ties), and trust decays by 0.001 each tick. Trust affects trade quantity and aid probability, so it changes behavior.

Aid checks donors with at least 9 food. A donor considers the first nearby peer with food <1 and health <0.8. Its gift probability is:

```text
sociability × (0.12 + 0.65 × donor trust in recipient + 0.2 if parent/child)
```

On success the donor transfers `min(1.5, food − 8)` food. Recipient trust increases by 0.15 and donor trust by 0.03. This is a programmed aid rule with relationship feedback; it is not evidence of independently discovered morality, reciprocal obligations, or institutions.

## Demography and consumption

Age increments before consumption. Agents below age 20 require 0.55 food and 0.12 wood fuel; others require 1 food and 0.25 wood. Consumption is limited by inventory. Meeting at least 98% of food need adds 0.035 health; otherwise health changes by `−0.16 × (1 − fraction met)`. Fuel below half need costs another 0.012 health. Health is clamped to [0,1]. Full food can offset the missing-fuel penalty, so fuel absence alone does not necessarily kill an agent.

After consumption, 0.6% of remaining food spoils and tool quality falls by 0.012. Agents die at health zero or their individual lifespan. Their remaining food and wood enter the death-loss sink; there is no inheritance or scavenging.

Birth is a single-parent abstract reproduction rule. After upkeep, a living agent must have age 35–379, health >0.8, food >14, and wood >3. If below the population cap, it reproduces with probability `birthRate`, default 0.018. The parent transfers 6 food and 1 wood to the child; these are not new sources. The child starts with health 1, tool zero, age zero, and the parent's location. Skills inherit parental values plus uniform perturbations ±0.08, clamped to [0.5,1.8]; sociability perturbs by ±0.075 and is clamped to [0,1]. Lifespan is newly drawn. The cap uses beginning-of-demography population plus births, so a death in the same tick does not immediately free a birth slot.

The health, eligibility, local scarcity, and cap thresholds create nonlinear responses. Their existence does not establish chaos, a phase transition, or realistic demographic behavior.

## Accounting and observations

For each good separately:

```text
sum(environment stock) + sum(agent inventory)
  = initial + regenerated − consumed − spoiled − crafted − lost − intervention
```

Harvest, barter, gifts, and birth endowments are internal transfers. Movement food cost enters `consumed`; craft food and wood enter `crafted`. Wood has no spoilage rule. Tool and soil variables are outside the food/wood conservation equation. Population reconciles as initial population + births − deaths. IDs increase monotonically and are never reused.

| Metric | Definition / interpretation boundary |
| --- | --- |
| `food`, `wood` | Total agent-held inventories, excluding environmental stocks |
| `biomass` | Environmental food plus wood; an abstract mixed-unit index |
| `soil`, `health` | Mean land soil / mean living-agent health |
| `price` | Total food traded divided by total wood traded that tick; null without trade |
| `trades`, `tradeVolume` | Number of exchanges / food units exchanged this tick |
| `consumed` | Food eaten plus movement food costs this tick; excludes craft food |
| `starving` | Count with health <0.6; a health proxy, not direct unmet food need |
| `gini` | Gini of `food + 2 × wood`; the fixed weighting is descriptive, not the current market price or a spendable wealth balance |
| `specialization` | Mean absolute difference between lifetime food/wood action counts divided by their sum; zero for agents with no production actions |
| `clusters` | Connected components of occupied orthogonal cells with at least three agents; empty cells break connectivity |

Clusters do not alter decisions, create settlements, own assets, or imply political organization. The work-concentration metric can increase simply because food requirements dominate; it does not independently establish comparative-advantage occupations. Current-tick metrics have corresponding cumulative counters where appropriate. Histories retain 2,000 rows and events retain 400 entries. Only the first two trades, gifts, deaths, and births of a tick are individually logged; migration is summarized every tenth tick. Totals cover all events despite this display sampling. A save preserves continuation state but not an unbounded audit trail.

## Interventions and feedback hypotheses

Supported interventions are temporary drought (factor 0–1 for 1–1,000 following ticks), proportional environmental depletion, switches for barter/migration/aid, technology multiplier 0.5–3, and transport cost 0–3. Multiple droughts multiply. Depletion removes only environmental stock and records it as an intervention sink. Switching technology is an exogenous experimental capability change, not endogenous invention.

Traceable feedback paths include resources → inventories/health → births → extraction → soil → regeneration; tools → harvest → soil damage → future availability; local exchange → inventory valuations/action choice → production and exchange opportunities; and successful interaction → trust → exchange size/aid → future inventories. These links are implemented. Whether their joint outcomes support any particular high-level interpretation requires the controlled measurements in the experiment report, with alternatives and limits.

Not implemented: drinking water, nonrenewable minerals, property in land, permanent buildings, roads, wages, money, explicit firms, collective institutions, warfare, language, education, endogenous technological discovery, sex/pair reproduction, real-world calibration, or inference about human civilization. The delivered model intentionally favors a small set of connected, inspectable rules.