← Natura·Docs/Design
Contents · Systems

Natura Systems -- detailed designs & how they interact

The fleshed-out per-system design + the coupling model. Complements DESIGN.md (the architecture) and ONTOLOGY.md (the content). Written 2026-08-02 while the whole thing is fresh -- the operator's call to bank the design before returning to finish the weather viz. For each system: purpose, domain, scale, STATE it holds, ALGORITHM, fields OUT (what it exposes), fields IN (what it couples to), key PARAMS, what to BUILD ON, and STATUS. Every system is a {name,domain,scale,init,step,fields,events} plugging into the Natura core (natura.js). Deterministic + node-tested, like the Terrain Engine.

Part I -- THE COUPLING MODEL (how the systems interact)

Coupling in Natura is explicit and one-directional per channel: a system EXPOSES fields via fields(); a downstream system READS them from ctx.fields.<producer> (a pre-step snapshot -> order-independent). A "world" is a stack of systems whose fields wire together. The wiring, top of the scale ladder to the bottom, is essentially the water/energy/matter cycle of a planet:

  ORBIT/STELLAR --insolation, day, season-->  TIME  --daylight,season-->  WEATHER, VEGETATION, LIFE
  TECTONICS  --continents, uplift-->  TERRAIN
  TERRAIN  --elevation, slope, flow, biome, coast-->  WEATHER (orographic), OCEAN (rivers), VEGETATION (soil)
  WEATHER  --moisture, rain, temp, wind, cloud, storms-->  TERRAIN (erosion), OCEAN (rivers/floods),
                                                           VEGETATION (growth), FIRE (dryness/wind), BIOME (climate)
  OCEAN/HYDROLOGY  --water level, river discharge, floods-->  VEGETATION (water), LIFE (habitat), TERRAIN (fluvial erosion)
  VEGETATION  --biomass, canopy, food, fuel, litter-->  LIFE-CYCLE (food), ECOSYSTEM (grazing base),
                                                        FIRE (fuel), BIOME (cover), TERRAIN/SOIL (litter -> humus)
  LIFE-CYCLE  --creatures, carcasses, nutrients-->  ECOSYSTEM, SOIL (decay returns matter)
  ECOSYSTEM  --populations, herds, predation, migration-->  VEGETATION (grazing pressure), LIFE (predation)
  FIRE  --burn, ash, smoke-->  VEGETATION (clears it), SOIL (ash -> fertility), WEATHER (smoke/albedo)
  BIOME  --biome type-->  VEGETATION (which plants), LIFE (which creatures)
  MIND (DONE)  --intent (belief+emotion -> flee/seek/forage/explore/rest)--> selects which LIFE/ECOSYSTEM verb a creature runs
  SOCIETY (DONE)  --shared mood + CONTAGION + COLLECTIVE MEMORY + HIERARCHY--> minds conform; a false belief spreads to consensus; the past scars/heartens the present; a salient minority leads the whole

The feedback LOOPS are the point (a living world is loops, not a pipeline):

Cross-SCALE coupling flows DOWN as boundary conditions (stellar insolation sets planetary climate sets regional weather sets a leaf's frost) and UP as aggregation (per-storm erosion accumulates to a landform over eons; individual lives aggregate to a population). A system reads the scale above for its context and writes the scale below's inputs.

The COUPLING RECIPE (the proven default pattern, banked from the Sept/Aug fold-ins). To couple, do NOT edit a system's core: each step, feed one system's fields() output into another's input via ctx.fields.<producer> -- a scenario lever driven by a live field. Nature-side and EXISTA pieces alike were built this way: weather->hydro moisture->watershed recharge (Where the Water Waits), a coupled field-year (weather->soil->vegetation->ecosystem), The Long Game (watershed allocation across settlements). A NEW system should EXPOSE the fields others will want and READ the fields it needs by config (rechargeFrom, elevationFrom, surfaceFrom, weather), so worlds wire without touching code. The library carries the full capability; a WORK may pick a simplified subset -- never simplify the library.

A second coupling FLAVOUR -- CROSS-SCALE GROUNDING (banked 2026-09-13, city<->traffic). Beyond "drive a scenario lever from a live field," a MACROSCOPIC system can replace an ASSUMED constitutive law with the EMERGENT one from a finer-scale model. city.js assumed a BPR volume-delay power law (1 + alpha*x^beta); traffic.js (the microscopic IDM) now computes its ANALYTIC fundamental diagram -- the equilibrium speed-density relation its car-following PARAMETERS imply, s0 + v*T = gap*sqrt(1-(v/v0)^delta), solved by bisection with NO ring run -- and exposes it as a volume-delay table vdCost. city, opt-in via congestFrom:'traffic', reads that table as its congestion curve, so the macro delay is grounded in real car-following instead of a fitted exponent. The pattern: the fine model exposes a PARAMETER-DERIVED characteristic curve (static, so compute once), the coarse model consumes it as a constitutive law. Keep it opt-in (default path byte-identical) and prove the curve is actually READ (same seed, only the law swapped -> the outcome must change) not silently ignored.

Part II -- THE SYSTEM CATALOG

0. CORE (infra) -- DONE (natura.js, 22 assertions)

The clock (day->eon cadences), the system interface, the registry, the World runner, and the coupling snapshot. Not a "system" but the substrate all systems plug into. Determinism: clock + seed are inputs.

1. WEATHER (physical / weather scale) -- DONE, viz WIP (weather.js, 10 assertions)

2. TERRAIN (physical / planetary-regional) -- WRAP the Terrain Engine -- DONE (terrain.js, 7 assertions)

3. TIME / SEASONS (physical / all scales) -- DONE, subsumed by CELESTIAL (celestial.js)

4. OCEAN / HYDROLOGY (physical / landscape) -- DONE (ocean.js, 6 assertions)

5. VEGETATION (life / ecological) -- the visible "greening under rain" -- DONE (vegetation.js, 8 assertions)

6. LIFE-CYCLE (life / local) -- a creature's life as a state machine -- DONE (lifecycle.js, 9 assertions)

7. ECOSYSTEM / POPULATION (life+society / regional) -- "the battle of two moose" -- DONE (ecosystem.js, 11 assertions)

8. BIOME DYNAMICS (regional) -- biomes that spread and shrink -- DONE (biome.js, 6 assertions)

9. FIRE (physical+life / local) -- a gorgeous coupled system -- DONE (fire.js, 8 assertions; incl. EMBER-SPOTTING 2026-09-13: a hot cell in strong wind lofts embers downwind past its neighbours -> fire JUMPS a firebreak, catching only in dry fuel. From Downwind / the Sept audit.)

10. TECTONICS / PLANET (planetary / deep time) -- bigger, grander worlds -- DONE (tectonics.js, 6 assertions)

11. ORBITS / STELLAR (cosmic / deep time) -- "the slow cooling of a sun over billions of years"

12. MICRO (any domain / micro scale) -- "the branching of rime on a leaf in a storm" -- FROST DONE (frost.js, 7 assertions)

13. MIND (mind / individual) -- "the map is not the territory" -- DONE (mind.js, 20 assertions)

14. SOCIETY (society / collective) -- "consensus without truth" + "the country that remembers itself" + "a committed minority leads" -- DONE (society.js, 20 assertions)

Part II.b -- EXISTA: the model past nature (the human + made world)

The ontology covers ALL things, not a field of animals (operator, 2026-08-07: "exista, not natura ... the same machinery pointed at a market instead of a meadow"). These systems point the same emergence machinery at the human/made world -- each a DEEP coupled model (not a scalar), every emergence verified by RUNNING. Four were built in one evening (economy by hand; artifact/technology/city in parallel by orchestrated apprentices, then each re-verified here). This is the answer to "stop redoing the same five nature motifs, go broad AND deep."

15. ECONOMY (society / market) -- "the invisible hand" -- DONE (economy.js, 14 assertions; incl. an activity coupling lever)

Seven coupled mechanisms: production by comparative advantage at the going prices; Cobb-Douglas demand; EXACT market-clearing prices (p = money-chasing-good / quantity, so money is conserved to the cent, no auctioneer); monetary circulation with saving; learning-by-doing; capital (wealth funds better production, r>g); idiosyncratic luck (a Kesten process). EMERGENCE (run): prices CONVERGE + track SCARCITY; TRADE beats autarky (gains from trade); SPECIALISATION sorts agents by comparative advantage; WEALTH concentrates into a heavy tail from an equal start; supply + demand shocks ripple through prices; money conserved throughout. VIZ: the-invisible-hand.html (live).

16. ARTIFACT (artifice / material) -- the lifecycle of made things -- DONE (artifact.js, 20 assertions)

Manufacture -> wear + fatigue -> stochastic FAILURE on a real BATHTUB hazard (infant + constant + Weibull wear-out) -> maintenance with diminishing returns + a repair-vs-replace crossover -> material conservation with recycle-entropy. EMERGENCE (run): the bathtub curve; maintenance extends life with diminishing returns; a steady-state fleet; usable mass decays over recycle cycles while total matter is conserved to ~1e-6.

17. TECHNOLOGY (mind+society / knowledge) -- how a people invents + forgets -- DONE (technology.js, 25 assertions)

Invention by RECOMBINATION against a hidden tech-tree with prerequisites; diffusion with fidelity<1; obsolescence; LOSS (a dark age when a tech's few holders turn over before transmitting). EMERGENCE (run): cumulative innovation ACCELERATES (combinatorial); a superior tech sweeps (S-curve); knowledge is LOST in small/fragmented/high-turnover populations that a large connected one keeps; DIVERSITY raises the discovery frontier (a monoculture reinvents).

18. CITY (society / built-environment) -- an emergent city -- DONE (city.js, 20 assertions)

Bid-rent land use (residential/commercial/industrial sort into rings); accessibility over a CONGESTED road network; development + density; AGGLOMERATION; aging/BLIGHT + renewal; population + jobs locate by utility. EMERGENCE (run): a monocentric CORE emerges from a flat plain; a road induces development + congestion; monocentric -> POLYCENTRIC as the core congests; blight-and-renewal cycles.

19. SOIL (physical<->life / the matter cycle) -- pedogenesis, the skin between rock and life -- DONE (soil.js, 28 assertions)

Weathering of bedrock (physical freeze-thaw + chemical dissolution, gated by climate + slope) into mineral soil + HORIZONS; the organic cycle (litter -> decomposition -> humus -> mineralisation -> distinct nutrients N + P, each with uptake + leaching); soil moisture + texture; EROSION (slope + water strip topsoil) + DEPOSITION (build valley floors); and the two-way vegetation feedback (soil gates growth; growth + death build soil). EMERGENCE (run): a soil CATENA (soil deepens + enriches downslope); fertile valley floors vs bare steep slopes; organic matter + nutrients accumulate where life has grown + died (the land records its biology); MASS BALANCE (conserved minus leaching); stripping the vegetation (fire/clearing) accelerates soil + nutrient LOSS on the now-bare ground (humus 6.18 -> 0.00 bare vs 6.18 -> 6.48 vegetated). The matter cycle closed: LIFE -> death -> soil -> LIFE.

20. EPIDEMIC (society / contagion) -- "the shape of a season" -- DONE (epidemic.js, 23 assertions), viz DONE

A pathogen moving through a POPULATION on a CONTACT NETWORK -- not well-mixed. Each person S->E->I->R (+D): susceptible, exposed/incubating, infectious, recovered-and-immune, or dead. Transmission passes ONLY along the network edges (per-contact chance beta per infectious day); the graph is heavy-tailed (lognormal sociability, hubSigma) so a few SUPERSPREADERS emerge and carry the outbreak past what the mean contact-rate predicts. Incubation, infectious period, fatality (ifr), and optional immunity WANING (R->S) are all real per-person mechanisms. Levers a viz/scenario reaches: distancing (global beta multiplier), quarantine (fraction of new cases that self-isolate), and vaccinate(st, frac, targeted) (S->R, random or superspreader-targeted). EMERGENCE (all RUN-verified, epidemic-test.js): mass conserved; an OUTBREAK above R0=1 and a FIZZLE below; the CURVE turns over at an interior peak; the peak is where Reff falls through 1 (susceptible ~ 1/R0) and it OVERSHOOTS herd immunity; the HERD THRESHOLD (vaccinate > 1-1/R0 -> no ignition); TARGETING superspreaders crushes the peak far more than random at equal cost; final size grows with beta; DISTANCING flattens + delays the peak; WANING -> an ENDEMIC steady state instead of burnout; deaths ~ ifr x attack; QUARANTINE (isolating cases) reduces + past a threshold crushes the outbreak; SUPERSPREADING/overdispersion -- read off the causal tree the sim records, the top fifth of spreaders cause most infections and most infected people infect NOBODY (the 80/20 of outbreaks). R0 is the network-corrected T x <k^2-k>/<k> (excess degree), which is exactly why superspreaders matter. NOT society.js's MOOD contagion -- a real disease with immunity + mortality. The network-corrected R0 formula overestimates for a heavy tail; hubSigma=0.6 is the calibration where analytic R0 tracks the empirical turning point (1/sAtPeak) -- measured, not assumed.

21. COUPLED EXISTA WORLDS -- the human-world systems wired to drive each other -- Lives and Livelihoods DONE

The first time two EXISTA systems run in one World and drive each other (The Long Noon couples the NATURE stack; this couples the HUMAN one). lives-and-livelihoods.html: EPIDEMIC + ECONOMY. The coupling channel is economy.js's new activity lever (scales production AND consumption together, so money conserves + prices hold -- only REAL output moves; economy-test #9). Each step the viz reads the epidemic and sets economy.activity = (healthy workforce fraction) x (1 - lockdown cost) and sets epidemic.distancing from a policy: so REAL OUTPUT craters as infections peak (the sick + dead leave the workforce -- doing nothing is NOT free), and a distancing POLICY trades deaths for economic loss (no lever helps both). A THIRD channel is ENDOGENOUS FEAR: a fear scalar rises with prevalence + fresh deaths and makes people distance VOLUNTARILY (cutting transmission AND activity) with no order given, so even "no action" flattens the curve a little AND carries a large recession -- and that recession is mostly VOLUNTARY, not mandated (the real empirical finding: at policy 0 deaths 24->~20 but econ loss ~3.2k->~7.6k); policy layers on TOP of that fear baseline. EMERGENCE (RUN-verified by probe-sweep BEFORE building the viz): output troughs to ~47% at the peak; more distancing -> fewer deaths + more econ loss; TOTAL HARM is U-shaped and its minimum SHIFTS with the value-of-life (low -> do little, high -> distance hard, a full lockdown almost never optimal). The viz plots the (econ-loss, deaths) tradeoff FRONTIER, a point per auto-reseeded season coloured by policy, + a value-of-life slider whose iso-harm line marks the least-harm policy. PATTERN for coupling within the framework: drive one system's SCENARIO LEVER from another's fields() each step -- no system-code change beyond adding ONE clean defaulted input lever (here activity), so both systems' own test suites stay green.

THE GRAND COUPLING (commonwealth.js + nothing-happens-alone.html, commonwealth-test.js) -- the capstone the separate windows pointed at: TEN systems in ONE running World along a causal spine, natural world into human world. The real EXISTA agent-systems where they connect naturally (economy.js, epidemic.js, speculation.js) + SIX thin purpose-built BRIDGE systems (climate, land [veg over slow soil], harvest, population, knowledge, mood) that share variables by design, + a coupler system that runs FIRST each tick, reads last tick's fields, and writes the three levers (economy.activity, epidemic.distancing, speculation.V) -- INCLUDING sparking a latent plague when crowding x malnutrition push R past 1, so epidemics ARISE from conditions rather than being scripted. One tick = one WEEK (the agent-systems scale by dt-in-days -- epidemic burns a realistic multi-week wave; the bridges key off the clock so seasons + slow soil-building stay timescale-correct). EMERGENCE (RUN-verified, response-time measured): a stable BREATHING baseline (the ~9-year wet/dry epochs make it cycle on their own -- good decades, then famine, then plague, then recovery); a drought CASCADES downstream IN LAG ORDER (biomass 0.02y < hunger 0.17y < economy 0.21y < unrest 0.38y) with a grain-price mania and, often, an emergent plague off the famine; plagues ignite unbidden over drought-battered decades. The viz shows the causal WEB (8 nodes as gauges, edges carrying travelling flux-pulses that redden with hardship) over 7 scrolling RIBBONS (the same story as time, so one drought reads as a staggered diagonal of dips) + drought/plague/good-years perturbations + a health-drone soundtrack. The LESSON of the whole EXISTA arc: a system built to be COUPLED must be judged coupled; strung together, the separate models stop being dials and become a universe where a cause becomes, with lag, a distant effect -- "a drought in the sky ends, in time, as a riot in the street". THE MALTHUSIAN ESCAPE (added after): the world was locked in eternal cycles, so a KNOWLEDGE bridge gives it the ARC of real history -- practical know-how (logistic, COMPOUNDING invention driven by prosperity+population, ERODED by famine/plague) raises the yield of fixed farmland, so the trap holds for ~a century, then know-how compounds and population BREAKS the old ceiling (RUN-verified: know 0.14 at y50 -> plateau 4.07, pop 108 -> 301), a catastrophe can claw it back (a dark age). TOOL-CHOICE lesson: technology.js was the WRONG tool (its bounded tech-tree saturates in a few years -- the wrong scale for a centuries-long productivity climb); a purpose-built bridge is right, same as using climate/land bridges over weather.js/vegetation.js. The viz gained a KNOWLEDGE node (the feedback loop drawn -- economy funds it, know-how flows UP into harvest, the web's one 'good' upward edge) + a slow-S-curve know-how ribbon + takeoff/ dark-age chronicle lines. The piece now models the WHOLE arc of a civilization: the ancient trap AND the escape from it.

40. SETTLEMENTS -- THE SHARED WELL (society / regional) -- "draw hard now, or last" -- DONE (settlements.js, settlements-test.js, 12 assertions). [naming: the INTERACTIVE stewardship game is a separate piece, "The Long Game"; this is the headless natura SCENARIO that proves the coupling.]

The SPATIAL, watershed-grounded cousin of the GRAND COUPLING (commonwealth.js is the same forces as a NON-spatial time series; this plays them out ON THE MAP). A valley of villages on the uplands above watershed.js's river, each DRAWING from the SPATIAL aquifer (writing a draw field watershed subtracts from the table -- a new opt-in extraction input on watershed), FARMING beside it (a fallow/fertility soil-stand-in; soil.js is the deep version), growing/shrinking by the water + food it wins, and passing a CONTAGION along the valley network. Per-village policy: a village stewards its WATER and its LAND on two independent knobs (0 greedy .. 1 paced), so a valley MIXES wise and greedy neighbours on one aquifer. FIVE emergences, each RUN-verified and each ISOLATED so one tragedy cannot masquerade as another (measured, never reasoned): (1) WATER TRAGEDY -- greedy pumping draws the shared table down, wells fail, population collapses (pop 254 @ wOK 0.25 vs paced 919 @ 0.71); (2) SPATIAL EXTERNALITY -- an upstream over-pumper lowers the DOWNSTREAM table through the aquifer's lateral flow (well depth 0.0033 alone -> 0.0080 with a greedy neighbour), the commons made spatial; (3) FALLOW -- over-cropping mines the soil, fallowing keeps it fertile; (4) VALLEY EPIDEMIC -- a plague sweeps the malnourished valley 7x worse than a healthy one (peak 0.124 vs 0.017), because degraded water+soil (not head-count) drive transmission; (5) FLOODS -- the wet-season river overtops the BOTTOMLAND villages (exposure falls off with distance from a river cell, so the uplands are spared), drowning some but laying SILT that heals the soil -- so a riverside field stays fertile (0.91) under the very cropping that mines an upland field to dust (0.00). The river GIVES as it takes. STIFFNESS LESSON (found by RUNNING): a logistic pop update p*(1-p/K) ANNIHILATES a village the instant K collapses (the term explodes negative) -- so growth is logistic only when there is room, and DECLINE is a bounded relaxation toward K. HONESTY LESSON (same pass): I also built a MIGRATION mechanism (refugees flow to a neighbour with room) and CUT it -- it washed out (every village is pinned to its local K, so relocated people just regrow at the source and cannot be absorbed at a full destination) and behaved murkily; a mechanism that adds code but produces no clean, intuitive, measurable effect is noise dressed as depth, not depth. Better one excellent mechanism than one excellent + one fake. The scenario proves watershed's new draw coupling end to end.

22. SPECULATION (society / financial market) -- "the madness of crowds" -- DONE (speculation.js, 9 assertions), viz DONE

The ASSET market, the shadow of economy.js (the REAL market). One asset of fixed fundamental value V; price is set by a market maker from the demand of two agent types whose POPULATIONS shift by fitness: FUNDAMENTALISTS (expect reversion to V -> stabilising) and CHARTISTS / trend-followers (extrapolate the last move -> destabilising). Agents switch toward the recently-profitable style (a logit on remembered profit). EMERGENCE (all RUN-verified, speculation-test.js): fundamentalists ALONE keep price near value; add chartists + switching and ENDOGENOUS BUBBLES + CRASHES appear with NO external shock (a rise pays the trend-chasers -> recruits more -> steepens -> until a stumble flips everyone back); MEAN-REVERSION to value over the long run; FAT-TAILED returns (kurtosis > 3); VOLATILITY CLUSTERING (|return| autocorrelated); the chartist share swings caution<->mania; more trend-following -> bigger bubbles. Calibration (MEASURED by probe-sweep, not assumed): the loop gain mu*g must sit JUST UNDER 1 (g=3, mu=0.3) so bubbles GROW then REVERT instead of exploding to the price cap -- the edge-of-chaos regime.

23. CRYOSPHERE (physical / geological) -- "the ice ages" -- DONE (cryosphere.js, 12 assertions)

24. CHEMISTRY (physical / material) -- "the chemical layer" (ONTOLOGY-FOLD-IN #1, the biggest hole) -- DONE (chemistry.js, 9 assertions)

25. NICHE CONSTRUCTION (life / ecological) -- "life that remakes its world" (ONTOLOGY-FOLD-IN #2) -- DONE (niche.js, 8 assertions)

26. WATER CYCLE (physical / landscape) -- "one substance, all its states" (ONTOLOGY-FOLD-IN #5) -- DONE (hydro.js, 9 assertions)

27. SENSING (life / ecological) -- "what a creature can detect, and its limits" (ONTOLOGY-FOLD-IN #3) -- DONE (sensing.js, 14 assertions)

28. MUTUALISM / COEVOLUTION (life / ecological) -- "the cooperative +/+ edge, the mirror of predation" -- DONE (mutualism.js, 19 assertions), viz DONE

29. WATERSHED / GROUNDWATER (physical / landscape) -- "the drainage the land carves, and the water table beneath" -- DONE (watershed.js, 12 assertions)

30. STIGMERGY / SELF-ORGANIZED TRAILS (life / ecological) -- "the path no ant planned" -- DONE (stigmergy.js, 7 assertions)

31. SYNCHRONIZATION (physical/life) -- "a rhythm no one called" (the Kuramoto model) -- DONE (sync.js, 10 assertions)

32. THE COMMONS (society / resource) -- "the tragedy, or the governance that saves it" -- DONE (commons.js, 6 assertions)

33. OPTICS / CAUSTICS (physical / optical) -- "the net of light on the seafloor" -- DONE (caustics.js, 6 assertions)

34. STRUCTURE (artifice / material, EXISTA) -- "load, stability, and failure" -- DONE (structure.js, 9 assertions)

35. TRAFFIC (society / flow) -- "no one hit the brakes" (the Intelligent Driver Model) -- DONE (traffic.js, 6 assertions)

36. VORTEX-BLOB FLUID (physical / micro) -- "it carries itself" (a Lagrangian fluid substrate) -- DONE (vortex.js, 5 assertions)

37. CRYSTALLIZATION (physical / material) -- "how slowly it cooled" (nucleation + grain growth) -- DONE (crystal.js, 5 assertions)

38. ATMOSPHERIC REFRACTION / MIRAGE (physical / optical) -- "the ship that became a castle" -- DONE (refraction.js, 5 assertions)

39. GRANULAR MEDIA (physical / material) -- "the narrow of the glass" (sand that flows but isn't a fluid) -- DONE (granular.js, 5 assertions)

40. WINTERING (life / physiology) -- "what the hill keeps" (how a life gets through the lean season) -- DONE (wintering.js, 45 assertions)

Part III -- cross-cutting