@its-not-rocket-science/ananke 0.1.0 → 0.1.2

package/README.md

@@ -1,2199 +1,421 @@
-# Ananke
-![CI](../../actions/workflows/ci.yml/badge.svg)
-
-**Ananke** is a deterministic, physics-grounded simulation engine for characters, combat,
-and survivability — from a single duel to a campaign-scale world.
-
-It models entities using **real physical quantities** rather than abstract hit points,
-using **SI units stored as fixed-point integers** for full determinism.
-Same seed + same inputs → identical results, at every scale.
-
-The core promise is narrow and hard: deterministic, physics-grounded simulation for
-characters, combat, and survivability across tactical-to-campaign scales.
-Everything else — world simulation, mythology, emotional contagion, tech diffusion — is
-built on top of that foundation and can be adopted independently.
-
----
-
-## Start here: three adoption paths
-
-Choose the path that matches your immediate need.  Ignore the rest until you need it.
-
-### Path A — "I want a deterministic combat kernel"
-
-**Minimal modules:** `src/units.ts`, `src/sim/kernel.ts`, `src/presets.ts`, `src/weapons.ts`
-
-**30-minute quickstart:** Run `tools/vertical-slice.ts` (`npm run run:vertical-slice`).
-A Knight fights a Brawler across three seeds, producing a physics-grounded combat log.
-Read `docs/host-contract.md` for the stable integration surface, then
-`docs/integration-primer.md` for data-flow diagrams and type glossary.
-
-**Key entry points:** `stepWorld()`, `resolveHit()`, `generateIndividual()`, `mkKnight()`
-
-**What to ignore for now:** Phases 56–67 (campaign-scale systems), all `tools/` except `vertical-slice.ts`
-
----
-
-### Path B — "I want a campaign / world simulation"
-
-**Minimal modules:** Path A + `src/campaign.ts`, `src/polity.ts`, `src/tech-diffusion.ts`
-
-**30-minute quickstart:** Run `npm run run:what-if` to see alternate-history polity scenarios
-(plague, charismatic leader, sudden war) with probability-weighted outcome distributions.
-
-**Key entry points:** `stepPolityDay()`, `stepTechDiffusion()`, `applyEmotionalContagion()`,
-`compressMythsFromHistory()`
-
-**What to ignore for now:** `src/sim/model3d.ts`, `src/bridge/`, `docs/editors/`
-
----
-
-### Path C — "I want physiology / species modelling"
-
-**Minimal modules:** `src/units.ts`, `src/sim/bodyplan.ts`, `src/archetypes.ts`,
-`src/describe.ts`
-
-**30-minute quickstart:** Open `docs/editors/species-forge.html` in a browser.
-Design a body plan, set archetype sliders, and copy the generated TypeScript trio
-(`BodyPlan` + `Archetype` + `NarrativeBias`) into your project.
-
-**Key entry points:** `generateIndividual()`, `applyAgingToAttributes()`,
-`applySleepToAttributes()`, `extractRigSnapshots()`
-
-**What to ignore for now:** `src/polity.ts`, `src/tech-diffusion.ts`, all `tools/`
-
----
-
-### Where Ananke sits in a larger system
-
-Ananke is the physics and biology layer — Layer 2 in the stack below.  Layers above it
-are partially or fully implemented; Layer 7 is long-term vision.
-
-| Layer | Purpose | Status |
-|-------|---------|--------|
-| **7 — The Universe** | Cosmological scale: planets, interstellar travel, multiple worlds | Long-term vision |
-| **6 — The World** | Geopolitical scale: nations, empires, diplomacy, trade, war, tech diffusion | **Complete** (Phases 61, 67) |
-| **5 — The Society** | Cultural scale: cities, factions, myths, legends, mass psychology | **Complete** (Phases 36, 45, 50, 66) |
-| **4 — The Group** | Social scale: parties, armies, organisations, emotional contagion | **Complete** (Phases 22, 48, 51, 65) |
-| **3 — The Individual** | Character scale: generation, narrative shaping, aging, sleep, skill progression | **Complete** (Phases 21, 33–39, 57–58, 62) |
-| **2 — The Simulation** | Physics and biology kernel | **Complete** (Phases 1–60) |
-| **1 — The Interface** | Visual editors, Species Forge, Culture Forge, Simulation Zoo, Generative Cartography, Persistent World Server, "What If?" engine, validation dashboard, Narrative Stress Test | **Complete** (ROADMAP items 7–11, Long-Term Vision all four; companion renderer READMEs in `docs/companion-projects/`) |
-
-The kernel's deterministic, physics-first foundation makes it suited to the full stack.  A
-scenario that would require hand-waving in a narrative RPG — "does the hero survive this
-battle?" — becomes a distribution of outcomes across thousands of seeded runs, each
-physically grounded.
-
----
-
-## Core design principles
-
-### Deterministic by default
-
-- Lockstep-safe simulation
-- No floating-point drift
-- Stable ordering and RNG consumption
-- Same seed + inputs → identical results
-- Entity iteration and pair resolution are stable and ordered
-
-### Physics-first
-
-- Impact energy → injury (not dice roll → damage)
-- Mass, velocity, leverage, penetration physics
-- Encumbrance affects movement and fatigue
-
-### Fixed-point arithmetic
-
-- All simulation values use Q fixed-point integers
-- No runtime floats in simulation path
-- Units centralised in `src/units.ts`
-
-### No arbitrary scales
-
-Individual variation is expressed in absolute physical terms, not 1–20 ranges.
-
-| What varies | Engine representation | Unit |
-|---|---|---|
-| Strength | `peakForce_N` | N (newtons) |
-| Explosive power | `peakPower_W` | W (watts) |
-| Stamina | `continuousPower_W` | W (watts) |
-| Energy reserves | `reserveEnergy_J` | J (joules) |
-| Reaction speed | `reactionTime_s` | s (seconds) |
-| Motor coordination | `controlQuality`, `fineControl` | dimensionless 0–1 |
-| Body size | `stature_m`, `mass_kg` | m, kg |
-
-An "average human" has `peakForce_N = 1840`, `peakPower_W = 1200`, `continuousPower_W = 200`,
-`reserveEnergy_J = 20000`, `reactionTime_s = 0.20`. These are real sport-science values.
-Variation between individuals is generated by `generateIndividual()` using per-archetype
-variance distributions, producing a unique entity with realistic physical spread.
-
-### Biology-agnostic
-
-- Supports humans, robots, aliens, and abstract entities
-- Genericised actuation, structure, and control systems
-- Region-based anatomy adaptable to any morphology (Phase 8)
-
-### Scalable
-
-- Single entity to squad to formation to army
-- Spatial partitioning and density modelling
-- Deterministic large-battle simulation
-
----
-
-## Current implementation status
-
-**Phases 1–60 complete** (including Phase 6 Formation System, 2ext, 3ext, 8B, 8C, 10B, 10C, 11C, 12B, 31–60). Melee combat,
-grappling, stamina and exhaustion, weapon dynamics (including swing momentum carry), ranged
-and projectile combat (including aiming time, moving target penalty, suppression→AI behaviour,
-and ammo type overrides), injury, entity environmental hazards, movement physics, formation
-basics, deterministic AI scaffolding,
-perception/cognition (sensory model, decision latency, surprise mechanics), morale and
-psychological state (fear accumulation, routing, panic variety, leader/banner auras, rally
-mechanic), terrain systems (surface friction, obstacle/cover grids, elevation, slope direction,
-dynamic hazard cells, AI cover-seeking, cover morale bonus, elevation melee advantage), a
-physics-grounded skill system, a universal data-driven body plan system (humanoid, quadruped,
-theropod, sauropod, avian, vermiform, centaur, octopoid — adding a new species requires only a
-BodyPlan data file and an Archetype baseline, no kernel changes), a full injury and medical
-simulation layer (fractures, infection, permanent damage, natural clotting, fatal fluid loss,
-and a `TreatCommand` system with tiered medical equipment and skill-scaled treatment rates),
-environmental physics including blast and fragmentation explosions, fall damage,
-pharmacokinetics with substance interactions (stimulant/haemostatic/anaesthetic/poison
-cross-effects, temperature-dependent metabolism), flash blindness from explosions, ambient
-temperature stress, a technology spectrum system (`TechContext`, `TechEra`,
-`TechCapability`, `validateLoadout`) with powered exoskeleton items, energy weapons,
-reflective and ablative armour, sensor items, and era-gated starter items, a **capability
-sources and effects** system (Clarke's Third Law — magic and advanced technology are the
-same abstraction; only the tags differ), a **deterministic replay and analytics** system
-(`ReplayRecorder`, `replayTo`, `serializeReplay`/`deserializeReplay`, `CollectingTrace`,
-`collectMetrics`, `survivalRate`, `meanTimeToIncapacitation`), a **3D model integration
-layer** (`deriveMassDistribution`, `deriveInertiaTensor`, `deriveAnimationHints`,
-`derivePoseModifiers`, `deriveGrappleConstraint`, `extractRigSnapshots`) for driving
-host renderer rigs from simulation state, a **named archetype and scenario library**
-(`AMATEUR_BOXER`, `PRO_BOXER`, `GRECO_WRESTLER`, `KNIGHT_INFANTRY`, `LARGE_PACIFIC_OCTOPUS`
-with corresponding `mkBoxer`/`mkWrestler`/`mkKnight`/`mkOctopus`/`mkScubaDiver` factory
-functions in `src/presets.ts`) validated against real-world biomechanics data by a
-statistical scenario test suite, a **character description layer** (`describeCharacter`,
-`formatCharacterSheet`, `formatOneLine` in `src/describe.ts`) that translates SI fixed-point
-attributes into human-readable summaries with tier ratings, labelled comparisons, and plain
-English descriptions grounded in real-world benchmarks, a **historical weapons database**
-(`src/weapons.ts`) covering ~70 weapons across six eras (Prehistoric through Contemporary)
-with two combat extensions: flexible/chain weapon **shield bypass** (`shieldBypassQ` reduces
-effective blocking coverage for flails and morning stars) and **magazine tracking**
-(`magCapacity` + `shotInterval_s` give magazine firearms per-shot and reload cooldowns), a
-**combat narrative layer** (`src/narrative.ts`) that converts trace event streams into
-human-readable combat logs with configurable verbosity, physics-grounded verb selection, and
-injury/outcome summaries, a **downtime and recovery simulation** (`src/downtime.ts`) that
-bridges combat-resolution time (20 Hz) and campaign time (hours to weeks) via a compressed
-1 Hz loop with tiered care levels, resource tracking, and recovery projection, an **arena
-simulation framework** (`src/arena.ts`) providing a declarative scenario DSL, batch trial
-runner, expectation system, and six physics-calibrated built-in scenarios for validating
-simulation realism, and a **character progression system** (`src/progression.ts`) that adds
-the temporal axis to entity attributes: XP/milestone-driven skill advancement using geometric
-thresholds, physical training drift bounded by genetic ceiling, physiologically-grounded
-ageing curves, and permanent injury sequelae, and a **campaign and world state layer**
-(`src/campaign.ts`) that persists entity state, location, and inventory between sessions:
-world clock advancement with integrated downtime healing, a location registry with
-travelCost routing, campaign-level item stockpiles, and Map-aware JSON serialisation so
-full campaign state round-trips cleanly, and a **dialogue and negotiation layer**
-(`src/dialogue.ts`) that resolves non-combat social actions — intimidation, persuasion,
-deception, surrender, and trade negotiation — using the same physical and psychological
-attributes as the combat engine: intimidation strength derives from `peakForce_N`, deception
-is defeated by `attentionDepth`, and escalation triggers when a fearless target interprets
-an intimidation attempt as an insult, and a **faction and reputation system**
-(`src/faction.ts`) that tracks faction membership, inter-faction standing, entity reputation,
-and a witness system that propagates reputation deltas from combat events: kills reduce the
-actor's standing with the victim's faction, aid increases it, and the AI decision layer
-suppresses attacks on entities with standing above `STANDING_FRIENDLY_THRESHOLD`, with a
-self-defence override when the attacker has already taken damage, and a **loot and economy
-layer** (`src/economy.ts`) that adds item valuation, equipment degradation, drop resolution,
-and trade mechanics: `computeItemValue` derives cost-unit prices from physical properties
-(mass, reach, armour resist), `applyWear` tracks cumulative use-wear on melee weapons
-(penalty at q(0.30), fumble at q(0.70), breaks at q(1.0)), `resolveDrops` produces
-deterministic loot from dead or incapacitated entities, and `evaluateTradeOffer` evaluates
-trades from the accepting party's perspective, a **momentum transfer and knockback**
-layer (`src/sim/knockback.ts`) that converts impulse-momentum physics into stagger and
-prone transitions, a **hydrostatic shock and cavitation** layer (`src/sim/hydrostatic.ts`)
-that amplifies internal damage for high-velocity projectiles based on per-tissue compliance
-(temporary cavity ×1.0–×3.0 above 600 m/s; cavitation bleed boost in fluid-saturated organs
-above 900 m/s), and a **cone AoE** system (`src/sim/cone.ts`) that adds directional
-geometry to the capability system for breath weapons, flamethrowers, gas dispersal, and
-sonic blasts: `entityInCone` geometry with configurable half-angle and range, `"facing"` and
-`"fixed"` direction modes, sustained emission with per-tick cost deduction and shock interrupt,
-a `weaponImpact` payload variant for custom per-effect damage profiles, and a full
-dragon-vs-knight scenario demonstration, a **staged thermoregulation model**
-(`src/sim/thermoregulation.ts`) that tracks core body temperature using a heat-balance
-equation (metabolic heat vs. conductive loss through armour and skin), deriving performance
-modifiers across seven stages from mild hyperthermia to cardiac-arrest hypothermia — each
-with calibrated powerMul, fineControlPen, and latencyMul penalties, and a **nutrition and
-starvation model** (`src/sim/nutrition.ts`) that adds the longest survivability axis:
-caloric balance tracked via Kleiber's-law BMR, four hunger states (sated → hungry →
-starving → critical) with staged fat catabolism (300 g/day), muscle catabolism (0.5 N/hour
-reduction in peakForce_N), and a six-item food catalogue from ration bars to water flasks,
-a **species and race system** (`src/species.ts`) providing a data-driven species registry
-where `SpeciesDefinition` bundles archetype, body plan, innate traits, capabilities, natural
-weapons, and physiological overrides into one record: 14 species across fantasy humanoids
-(elf, dwarf, halfling, orc, ogre, goblin, troll), sci-fi humanoids (Vulcan, Klingon, Romulan),
-mythological (dragon, centaur, satyr), and fictional (Heechee); `SpeciesPhysiology` adds
-`coldBlooded` (skips thermoregulation), `bmrMultiplier` (Vulcan q(0.72) starves slower;
-orc q(1.15) starves faster), and `naturalInsulation_m2KW` (scales heat loss), and a
-**multiple intelligences layer** (`src/types.ts`, wired through targeting, morale, decide,
-and dialogue) implementing Howard Gardner's nine cognitive domains plus inter-species empathy
-as Q-coded attributes on every archetype and species: `spatial` scales the threat-horizon
-perception radius (human baseline q(0.60) → ×1.0; octopus q(0.90) → ×1.30),
-`logicalMathematical` reduces decision latency (Vulcan q(0.95) → ×0.82; ogre q(0.25) →
-×1.10), `interpersonal` scales the effective leader-aura reception radius, `intrapersonal`
-boosts effective distress tolerance in morale computations, `linguistic` sets the per-entity
-persuasion base probability in dialogue (elf q(0.80) → q(0.44); ogre q(0.25) → q(0.275)),
-and `bodilyKinesthetic` sets a floor on fine-motor precision (`fineControl ≥ bk × q(0.80)`).
-
-**Phase 34** extends `bodilyKinesthetic` and `spatial` into non-combat competence resolvers
-(`src/competence/`): `resolveCrafting(entity, spec, seed)` computes craft quality
-(materialQ × BK × fineControl-bonus × toolBonus ± RNG) and time (baseTime_s × q(0.50) / BK);
-`computeSurgicalPrecision(entity)` returns lerp(q(0.70), q(1.30), BK) for use as
-`TreatmentSchedule.surgicalPrecisionMul` in downtime surgery; `resolveNavigation(entity, spec, seed)`
-gives routeEfficiency = clamp(spatial × mapBonus × terrainQ × visibilityQ, q(0.50), q(1.0)) and
-the resulting timeLost_s.
-
-**Phase 35** adds the `naturalist` intelligence competence resolver (`src/competence/naturalist.ts`):
-`resolveTracking(entity, spec, seed)` computes track confidence from naturalist skill, track age,
-terrain preservation (ideal/rain/urban/deep_water/forest), and species-specific difficulty;
-`resolveForaging(entity, spec, seed)` yields itemsFound per hour by biome (forest/plains/desert/
-swamp/mountain) and season with misidentification risk (P_misidentify = max(0, 0.30 − naturalist × 0.40));
-`resolveTaming(entity, spec, seed)` computes trust_Q = naturalist × interSpecies × effort − fear × 0.50,
-with attack probability when fear exceeds trust.
-
-**Phase 36** adds inter-species intelligence (`src/competence/interspecies.ts`): the `signal` dialogue
-action for cross-species communication (`{ kind: "signal"; targetSpecies; intent: "calm" | "submit" | "ally" | "territory" }`)
-with success probability `empathy_Q × vocab × (1 − fear × 0.60)` and potential aggravation when low
-empathy meets fearful targets; `computeUnfamiliarSpeciesLatencyPenalty(entity, species)` returns
-up to +80 ms decision latency when facing unfamiliar species (those not in `speciesAffinity`).
-
-**Phase 37** extends linguistic and interpersonal intelligence into practical applications:
-`LanguageCapacity` (languageId + fluency_Q) added to `Entity.languages`; `resolveCommandTransmission`
-computes formation reception rate (`linguistic × formationBonus`) and transmission delay;
-`resolveTeaching` computes XP transfer (`hours × BASE_XP_RATE × interpersonalTeacher × interpersonalLearner`)
-with teacher fatigue; `computeDeceptionDetectionProbability` factors interpersonal intuition into
-detecting lies (`attentionDepth × 0.50 + interpersonal × 0.50 − plausibility`).
-
-**Phase 38** implements logical-mathematical and intrapersonal intelligence: `WillpowerState`
-(`current_J/max_J`) added to `Entity.willpower`; `computeMaxWillpower(entity)` calculates capacity
-from intrapersonal intelligence (max 50kJ); `deductWillpower()`, `replenishWillpower()`, and
-`stepConcentrationWillpower()` manage cognitive stamina for sustained concentration (Phase 12B);
-`resolveEngineering(entity, spec, seed)` computes project quality (`qualityMul = logicalMath ×
-complexityMul × timeFactor`) with latent flaw probability (`P_flaw = max(0, complexity − logicalMath) × 0.40`);
-descriptor bands: exceptional/good/adequate/poor/failure.
-
-**Phase 39** adds musical intelligence and acoustic systems: `deriveAcousticSignature(entity)`
-computes noise level from movement velocity, equipment (metal armour +15, heavy weapons +10),
-and stealth skill; `detectAcousticSignature(listener, source, dist_m)` returns detection confidence
-(`sourceNoise / dist_m × listener.musical × SCALE_ACOUSTIC`); `resolveFormationSignal(signaller,
-signal, listener, dist_m)` computes command clarity (`musical(signaller) × musical(listener) ×
-rangeFactor`) for military coordination (drums, horns); `resolvePerformance(performer, spec)`
-generates morale auras (`fearDecayBonus = musical × q(0.020)`) draining willpower per second;
-performance types: march/rally/dirge/celebration/lament.
-
-**Phase 47** adds individual AI personalities beyond policy presets (`src/sim/ai/personality.ts`):
-`PersonalityTraits` — four Q-coded axes: `aggression` (shifts retreat range, overrides hesitation
-above q(0.70)), `caution` (±q(0.20) defence intensity boost), `loyalty` (switches focus target to
-protect a distressed ally), `opportunism` (switches to the most-wounded enemy). Five named presets:
-`berserker`, `coward`, `guardian`, `schemer`, `soldier`. `derivePersonalityFromCognition()` maps
-distressTolerance → aggression, intrapersonal → caution, interpersonal → loyalty,
-logicalMathematical → opportunism. `entity.personality?: PersonalityTraits` is optional and
-backward-compatible (absent = neutral = q(0.50) on all axes, no behaviour change).
-
-**Phase 48** adds multi-party dynamics (`src/party.ts`): `Party` and `PartyMember` types with
-per-member `loyaltyQ`, `stepPartyLoyalty()` (leader interpersonal aura + resource/injury/hunger
-modifiers), `checkDefection()` (probabilistic when loyalty < q(0.20)), `resolvePartyConflict()`
-(combat-power ratio determines outcome), `recordMissionSuccess/Failure()`.
-
-**Phase 49** adds legacy and inheritance (`src/inheritance.ts`): character death does not end the
-campaign — `transferEquipment()` moves loadout items to the heir, `transferRelationships()` partially
-copies the relationship graph (trust/affinity scaled by `relationshipTransferRate_Q`, default q(0.50)),
-`transferInventory()` merges campaign inventories, and `applyInheritance()` orchestrates all three
-steps while updating the campaign registry and location tracking.
-
-**Phase 50** adds mythology and legend (`src/legend.ts`): high-significance chronicle entries crystallise
-into `Legend` objects with a `LegendReputation` (`heroic`, `notorious`, `legendary`, `forgotten`),
-a `fame_Q` (how widely known), and thematic `tags` derived from source events and story arcs.
-`createLegendFromChronicle(chronicle, subjectId, subjectName)` promotes qualifying entries (default
-significance ≥ 60) into a legend; `fame_Q` scales with total significance (7 × 100-pt entries →
-q(1.0)). `getLegendEffect(legend)` returns `LegendEffect` — persuasion, intimidation, fear, and
-morale bonuses that scale with fame. `npcKnowsLegend(legend, npcId, worldSeed, tick)` is a
-deterministic fame roll (same inputs = same result). `applyLegendToDialogueContext(initiatorId,
-targetId, registry, worldSeed, tick)` aggregates effects for NPCs who know the legend. `stepLegendFame`
-decays fame over time (legendary legends have a q(0.50) floor). Full serialisation support.
-
-**Phase 51** adds weather and atmospheric environment (`src/sim/weather.ts`): `WeatherState` bundles
-`WindField`, `PrecipitationType` (`none` / `rain` / `heavy_rain` / `snow` / `blizzard` / `hail`),
-and `fogDensity_Q`. `deriveWeatherModifiers(weather)` returns `WeatherModifiers` — traction,
-vision, and thermal deltas. Per-tick kernel integration: rain/snow reduce `ctx.tractionCoeff`
-(blizzard → q(0.40)), fog and precipitation reduce `SensoryEnvironment.lightMul` and `.smokeMul`,
-precipitation cools `ctx.thermalAmbient_Q` (snow −5 °C, blizzard −12 °C). `computeWindAimError`
-adds crosswind drift to ranged-combat grouping radius (drift = v_wind_perp × range / v_proj).
-`adjustConeRange` modulates breath-weapon range ±20 % for head/tailwind. All effects are additive
-with existing sensory and thermal modifiers; `weather` absent = backward-compatible.
-
-**Phase 52** adds extended sensory modalities (`src/sim/sensory-extended.ts`): `ExtendedSenses` on
-`Entity` enables echolocation (range-checked, darkness-independent, degraded by noiseMul — dead
-targets still detected via physical echo), electroreception (bioelectric field detection, dead
-targets not detected), and olfaction (wind-direction-aware, precipitation-dispersed scent tracking).
-`computeDaylightMul(hourOfDay)` returns a Q multiplier (q(0.10) at midnight → q(1.0) at noon) for
-integration with `SensoryEnvironment.lightMul`. `canDetectExtended` wraps Phase 4 `canDetect` and
-additionally checks each extended modality in quality order: electroreception q(0.80),
-echolocation q(0.70), olfaction q(0.20–0.40).
-
-**Phase 53** adds systemic toxicology for ingested substances (`src/sim/systemic-toxicology.ts`):
-five toxin profiles — `alcohol` (15 min onset, motor impairment + disinhibition, addictive),
-`sedative_plant` (30 min onset, consciousness erosion, addictive), `alkaloid_poison` (20 min,
-internal damage + fear), `heavy_lead` and `radiation_dose` (cumulative irreversible dose
-accumulation via `CumulativeExposureRecord`). Exponential concentration decay via metabolic
-half-life (fixed-point minimum-1/s guarantee ensures clearance). Withdrawal states
-(`WithdrawalState`) are triggered after sustained addictive use, applying fatigue and fear
-penalties for the withdrawal duration. `deriveCumulativeToxicity(entity)` → Q for chronic
-exposure queries. Stepped at 1 Hz alongside nutrition and Phase 32C venom. Backward-compatible:
-absent fields = no change.
-
-**Phase 54** adds wound aging and long-term sequelae (`src/sim/wound-aging.ts`):
-`stepWoundAging(entity, elapsedSeconds)` models four time-scale processes — uninfected-region
-healing (surface 1%/day, internal 0.5%/day, clamped to permanentDamage floor), infection
-worsening (1.5%/day internalDamage, sepsis threshold at q(0.85)), chronic fatigue from
-sustained permanent damage, and phantom pain shock from fractured+permanent regions.
-`recordTraumaEvent` / `deriveFearThresholdMul` implement PTSD-like trauma accumulation
-with natural q(0.002)/day decay; max trauma halves the effective fear threshold (q(0.50)).
-`deriveSepsisRisk(entity)` → Q aggregates infected-region severity for medical triage AI.
-`TraumaState` added to `Entity`. All healing and worsening rates are deterministic from
-elapsed seconds — no RNG required. Backward-compatible: absent `traumaState` = no effect.
-
-**Phase 55** adds collective non-combat activities (`src/collective-activities.ts`):
-three self-contained group systems for downtime and logistics. **Siege engineering**:
-`createCollectiveProject` / `contributeToCollectiveProject` maintain a shared `progress_Q`
-pool; each entity's contribution = `deriveEngineeringCompetence(entity) × hoursWorked /
-requiredWorkHours`, where competence is the average of `logicalMathematical + bodilyKinesthetic`;
-`isProjectComplete` and `completedAtTick` track completion. **Ritual & ceremony**:
-`stepRitual(participants, elapsedSeconds)` produces a `moraleBonus_Q` (cap q(0.30)) and
-`fearReduction_Q` (60 % of morale bonus) by pooling each participant's average `(intrapersonal
-+ musical) / 2` with sqrt(N) group scaling and a linear time ramp over one hour. **Trade
-caravan logistics**: `planCaravanRoute(waypoints, participants, inventory)` derives
-`routeQuality_Q` from the best navigator's `logicalMathematical`, a `negotiationBonus_Q` from
-the best `interpersonal` score, shortens travel time via a speed factor ∈ [q(0.80), q(1.00)],
-and computes `supplySufficiency_Q` from available rations vs. travel-day demand.
-No kernel integration — all three systems are host-application-driven downtime APIs.
-
-**Phase 56** adds entity-to-entity disease transmission (`src/sim/disease.ts`):
-six disease profiles (common_fever, wound_fever, plague_pneumonic, dysentery, marsh_fever,
-wasting_sickness) each with `transmissionRoute`, daily fatigue drain, incubation/symptomatic
-phase timers, a mortality roll via deterministic `eventSeed`, and graduated immunity.
-`exposeToDisease(entity, id)` adds an incubating state (skips immune/already-infected
-entities); `stepDiseaseForEntity(entity, delta_s, worldSeed, tick)` advances phases, drains
-fatigue, rolls mortality on recovery, grants immunity; `computeTransmissionRisk` returns Q
-risk — airborne decays linearly to zero at `airborneRange_Sm`, contact/vector/waterborne are
-flat within 2 m; `spreadDisease(entityMap, pairs, worldSeed, tick)` performs a deterministic
-batch exposure from host-supplied spatial pairs. `DiseaseState` and `ImmunityRecord` added
-to `Entity`. Backward-compatible: absent `activeDiseases` = no effect.
-
-**Phase 57** adds aging and lifespan simulation (`src/sim/aging.ts`):
-species-agnostic attribute curves parameterized by normalized age fraction
-(`ageFrac = ageYears / lifespanYears`). Seven piecewise-linear Q dimensions —
-muscular strength (peaks at ageFrac ≈ 0.28), reaction time (faster at peak,
-slowest in infancy and antiquity), motor control, stature (stable adult, slight
-compression in ancient), fluid cognition (logical/spatial/musical — peaks young),
-crystallized cognition (linguistic/interpersonal/intrapersonal — peaks mid-life,
-wisdom outlasts speed), and distress tolerance (peaks middle age). A 25-year-old
-human and a 187-year-old elf (lifespan 600) share the same ageFrac and therefore
-the same developmental multipliers. `applyAgingToAttributes(base, ageYears)` returns
-a new `IndividualAttributes` without mutating the peak baseline; `stepAging(entity,
-elapsedSeconds)` accumulates `entity.age.ageSeconds` for campaign-scale time tracking.
-
-**Phase 58** adds sleep and circadian rhythm (`src/sim/sleep.ts`): a two-factor
-deprivation model tracking `awakeSeconds` (continuous wake duration) and `sleepDebt_s`
-(cumulative nightly shortfall, capped at 72 h). `circadianAlertness(hourOfDay)` → Q
-piecewise-linear alertness curve (peak 17:00, nadir 03:00). Impairment begins after 17 h
-awake and degrades four attributes linearly to max at 72 h: fluid cognition −45%, reaction
-time +45% slower, stability −25%, distress tolerance −35%. Sleep-phase cycling follows the
-90-minute NREM/REM cycle (light 45 min → deep 25 min → rem 20 min → repeat). Prior-night
-debt persists even after short sleep: effective driver = max(awakeSeconds, sleepDebt_s).
-`applySleepToAttributes(base, state)` returns a new `IndividualAttributes` (immutable,
-same pattern as Phase 57); `stepSleep(entity, elapsedSeconds, isSleeping)` mutates
-`entity.sleep`; `entitySleepDebt_h(entity)` convenience helper.
-
-**Phase 59** adds mounted combat (`src/sim/mount.ts`): five mount profiles (pony, horse,
-warhorse, camel, war_elephant) with physics-based charge energy (`bonusEnergy_J = ½mv²`),
-rider height advantage (aim bonus proportional to seat elevation, q(0.12)/m, max q(0.30)),
-mount-to-rider fear contagion (40% of excess shock beyond fearThreshold), and
-forced-dismount detection (rider over-shock, mount death, mount bolt). `checkMountStep`
-returns a pure `MountStepResult` with no entity mutation. `MountState { mountId, riderId,
-gait }` added to `Entity`.
-
-**Phase 60** adds environmental hazard zones (`src/sim/hazard.ts`): persistent 2-D circular areas
-with linear exposure falloff that inflict per-second effects (fatigue, thermal shift, radiation dose,
-surface damage, disease exposure). Five types: fire, radiation, toxic_gas, acid, extreme_cold.
-`computeHazardExposure(dist_Sm, hazard)` → Q; `deriveHazardEffect(hazard, exposureQ)` → `HazardEffect`;
-`stepHazardZone` ticks duration (permanent zones are untouched); `isHazardExpired` signals removal.
-No entity field needed — hazards are world-level objects the host iterates each tick.
-
-**Phase 63** adds a **narrative stress test** framework (`src/narrative-stress.ts`): given a
-scene described as a sequence of `NarrativeBeat` predicates — each with a tick window in which
-it must become true — `runNarrativeStressTest` runs the simulation across hundreds of seeds
-and measures what fraction of runs spontaneously produce that sequence. The complement is the
-**narrative push**: `0.00` = plausible (no authorial pressure needed); `1.00` = "extreme — plot
-armour" (the story never happens without explicit intervention). Beat predicate helpers
-(`beatEntityDefeated`, `beatEntitySurvives`, `beatTeamDefeated`, `beatEntityShockExceeds`,
-`beatEntityFatigued`) cover the most common story requirements. `formatStressTestReport`
-produces a human-readable breakdown labelled "none — plausible" / "light" / "moderate" /
-"heavy" / "extreme — plot armour". Demo: `npm run run:narrative-stress-test`.
-
-**Artificial Life Validation ("Blade Runner" Test)** (`tools/blade-runner.ts`, `npm run run:blade-runner`) —
-the ultimate integration test: 198 named NPCs, 3 polities, and 365 simulated days wiring every
-major phase simultaneously (disease, polity economics, war, sleep debt, skill progression).
-Validates 4 emergent-behaviour claims: social hierarchy, disease mortality spikes, morale–economy
-correlation, and skill accumulation hierarchy. All 4/4 claims pass on seed 1.
-
-**Species Forge** (`docs/editors/species-forge.html`) — four-tab standalone HTML/JS species designer
-extending the Body Plan Editor. Tab 1: segment body plan with live validation. Tab 2: 24 archetype
-sliders (stature, mass, peak force/power, reaction time, control quality, resilience, perception).
-Tab 3: five Narrative Bias sliders (strength/speed/resilience/agility/size, −1 to +1) with six
-preset profiles (Warrior/Scholar/Rogue/Tank/Feral Beast/Clear). Tab 4: live-generated TypeScript
-trio (`BodyPlan` + `Archetype` + `NarrativeBias`). Four templates: Humanoid, Large Beast, War
-Machine, Mind Swarm. Linked from `docs/editors/index.html`.
-
-**Phase 67 — Technology Diffusion at Polity Scale** (`src/tech-diffusion.ts`) — tech eras
-spread from advanced polities to lagging neighbours via trade routes and cultural contact.
-`computeDiffusionPressure(source, target, pair, warActive)` computes per-day advance probability
-scaling with era gap (×1–3×), route quality, shared locations, and stability threshold.
-`stepTechDiffusion(registry, pairs, worldSeed, tick)` rolls for advances each tick, mutates
-`techEra`, and refreshes military strength; one advance per polity per tick maximum.
-`totalInboundPressure` provides a signed-Q AI query for "how likely is this polity to advance?"
-Long-run convergence test: era-1 polity reaches era-3 within 2 000 daily ticks (~5.5 years).
-34 tests; 100% coverage.
-
-**Phase 66 — Generative Mythology** (`src/mythology.ts`) — narrative compression of the Legend/
-Chronicle log into in-world cultural beliefs.  `compressMythsFromHistory(legendRegistry, entries,
-factionIds)` detects six archetypal patterns (hero, monster, great_plague, divine_wrath, golden_age,
-trickster) from accumulated legends and chronicle events; each myth carries a `MythEffect` (fear
-threshold, diplomacy, morale, tech modifiers) scaled by its `belief_Q`.  `stepMythologyYear`
-decays belief 12%/year to a floor of q(0.10).  `aggregateFactionMythEffect` gives the net cultural
-modifier for polity-day AI use.  39 tests; 100% statement/branch/function/line coverage.
-
-**Phase 65 — Emotional Contagion at Polity Scale** (`src/emotional-contagion.ts`) — fear and hope
-propagate between polities using the Phase 56 disease transmission model with `fear_Q`/`hope_Q` as
-the "pathogen".  Four built-in profiles: `military_rout` (fast-spreading panic), `plague_panic`
-(slow-decaying dread), `victory_rally` (hope wave from a battle win), `charismatic_address`
-(leader-amplified; Phase 39 `leaderPerformance_Q` scales initial intensity).
-`applyEmotionalContagion(registry, pairs, waves, profiles, worldSeed, tick)` drives spread +
-moraleQ updates each polity day-tick.  `netEmotionalPressure` gives a signed Q for AI queries.
-46 tests; 100% statement/function/line coverage.
-
-**"What If?" / Alternate History Engine** (`tools/what-if.ts`, `npm run run:what-if`, Phase 64) —
-polity-scale alternate-history simulator that runs a `WhatIfScenario` across N seeds and reports
-probability-weighted outcome distributions. Three built-in scenarios: plague devastating a capital
-(−92.5% population; density-floor mechanics), a charismatic leader's morale surge (+22% military
-at day 90), and a sudden war between equal polities (−100% aggressor stability; −40% treasury for
-both; war persists all 180 days). Demonstrates geopolitical consequence modelling built on Phase 61.
-
-**Emergent Behaviour Validation Suite** (`tools/emergent-validation.ts`, `npm run run:emergent-validation`) —
-four historical combat scenarios validated across 100 seeds each: 10v10 open-ground skirmish
-(Ardant du Picq), environmental friction in rain + fog (Keegan), Lanchester's numerical
-superiority law (5 vs. 10), and siege attrition via disease (Raudzens). All 4/4 scenarios pass.
-
-**Performance & Scalability Benchmarks** (`tools/benchmark.ts`, `npm run run:benchmark`) —
-reproducible throughput figures across four entity-count scenarios (10 / 100 / 500 / 1 000).
-Includes AI-decision-budget breakdown, spatial-index comparison vs. naïve O(n²), and a tuning
-guide. Full report in `docs/performance.md`.
-
-**Dataset Contribution Pipeline** (`docs/dataset-contribution.md`) — step-by-step guide for
-adding empirical datasets and `DirectValidationScenario` entries to the validation runner.
-Includes CSV format spec, four code templates, tolerance-selection table, and a live example
-(`datasets/example-sprint-speed.csv` — human peak anaerobic power, ✓ PASS at 9.5% error).
-
-**Public Validation Dashboard** (`docs/dashboard/`, `npm run run:validation-dashboard`) —
-self-contained HTML dashboard showing all 43 validation scenarios with pass/fail status,
-simulated vs. empirical bars with ±tolerance bands, and filter controls. JSON data is
-regenerated automatically on push via `.github/workflows/validation-dashboard.yml`.
-Serve locally with `python -m http.server` inside `docs/dashboard/`.
-
-**Visual Editors for Non-Developers** (`docs/editors/`) — two standalone HTML/JS tools
-requiring no build step or TypeScript knowledge. **Body Plan Editor**: define species segments
-with mass-share sliders, locomotion/manipulation/CNS roles, and live validation; generates a
-`BodyPlan` TypeScript literal. **Validation Scenario Builder**: configure entities, simulation
-parameters, weather, and empirical reference data; generates a `DirectValidationScenario`
-block. Both tools serve via GitHub Pages or `python -m http.server`.
-
-**2904 tests.** All coverage thresholds met (statements 93.75%+, branches 84.69%+, functions 92%+, lines 93.75%+).
-
-See `ROADMAP.md` for the full development plan.
-
----
-
-## Validation against real-world data
-
-> **Emergent validation report:** [`docs/emergent-validation-report.md`](docs/emergent-validation-report.md)
-> — four historical combat scenarios, 100 seeds each, all passing.  This is the flagship trust
-> artifact: it validates *distributions of outcomes* across multi-system interactions, not just
-> individual formula outputs.  CI runs a 20-seed fast subset on every push.
-
-Ananke's physics-based approach is systematically validated against external real-world datasets and literature sources. The validation framework (`tools/validation.ts`) compares simulation outputs with empirical measurements across multiple sub‑systems, ensuring the simulation's predictions remain grounded in reality.
-
-**Key validated sub‑systems:**
-- Movement energy cost (AddBiomechanics walking metabolic dataset)
-- Projectile drag (BVR Air Combat dataset)
-- Jump height and sprint speed (sports‑science literature)
-- Fracture thresholds (Yamada 1970, McElhaney 1970)
-- Thoracic and pelvic impact tolerance (AFRL Biodynamics Data Bank)
-- Damage energy constants (NATO STANAG 4526)
-- Sleep deprivation cognitive impairment (Van Dongen et al. 2003 meta‑analysis)
-- Disease mortality rates (historical epidemiology)
-- Calibration scenarios: armed vs. unarmed, untreated knife wound, first‑aid saves lives, fracture recovery, untreated infection, plate armour effectiveness
-
-Each validation scenario runs a deterministic simulation that replicates the experimental conditions of the external dataset, then compares the simulated mean against the empirical mean with a ±20 % tolerance. A constant‑suggestion system provides actionable recommendations for tuning constants when deviations exceed tolerance.
-
-**Validation inventory:** A comprehensive catalogue of all validated and potential future datasets is maintained in [`docs/external-dataset-validation-inventory.md`](docs/external-dataset-validation-inventory.md). The inventory includes 19 currently validated sources and identifies 11 high‑value external datasets for future validation work across muscle mechanics, ground‑reaction forces, blast physics, cognitive state, and melee combat.
-
-**Run validation:** `npm run run:validation <subsystem>` generates a validation report for a specific sub‑system.
-
-## Physics realism summary (post-Phase 30)
-
-Ananke now models the complete survivability stack. Five independent threat vectors can kill
-an entity, each operating on a different time scale and requiring different intervention:
-
-| Threat | Time scale | Mechanism | Primary phases |
-|--------|-----------|-----------|----------------|
-| Injury / blood loss | Seconds | Fluid loss → shock → death | 1, 9 |
-| Infection | Hours–days | Internal damage accumulation | 9 |
-| Thermal stress | Minutes–hours | Core temperature extremes | 29 |
-| Dehydration | Hours–days | Hydration balance collapse | 30 |
-| Starvation | Days–weeks | Caloric deficit → catabolism | 30 |
-
-### Physical phenomena modelled
-
-**Newtonian mechanics**
-- Kinetic energy → injury via impact physics, penetration, and leverage (Phases 1–3)
-- Impulse-momentum → knockback velocity and stagger/prone transitions (Phase 26)
-- Angular momentum → miss recovery time and weapon bind probability (Phase 2)
-
-**Wound physiology**
-- Per-region surface / internal / structural damage; penetration bias by tissue type
-- Bleeding rate proportional to internal damage; natural clotting proportional to tissue integrity
-- Fluid loss → haemodynamic shock → consciousness erosion → death (`fluidLoss ≥ 0.80` fatal)
-- Fracture (structural ≥ 0.70), permanent damage (≥ 0.90), infection onset after 100 ticks of bleeding
-
-**High-velocity ballistics** (Phase 27)
-- Temporary cavity multiplier ×1.0–×3.0 above 600 m/s; scales by tissue compliance
-- Cavitation bleed boost in fluid-saturated organs (torso, liver, spleen, lung, legs) above 900 m/s
-
-**Thermodynamics** (Phase 29)
-- Core temperature balance: metabolic heat (1.06–5.50 W/kg by activity) vs. conductive loss through skin + armour insulation
-- Thermal resistance: `R = 0.09 + Σ(armour.insulation_m2KW)` °C/W; thermal mass = `3500 × mass_real` J/°C
-- Seven-stage temperature model: critical hyperthermia → heat stroke → heat exhaustion → normal → mild → moderate → severe hypothermia → cardiac arrest
-
-**Metabolism** (Phase 30)
-- Basal metabolic rate: `80 × (mass_kg / 75)^0.75` W (Kleiber's law)
-- Active metabolic rate: `BMR + peakPower_W × activityFrac × 0.15`
-- Four hunger states: sated (< 12 h deficit), hungry (12–24 h), starving (24–72 h), critical (≥ 72 h)
-- Fat catabolism: 300 g/day during starvation; muscle catabolism: 0.5 N/hour reduction in `peakForce_N` during critical state
-
-**Pharmacokinetics** (Phase 10)
-- One-compartment absorption/elimination model per active substance
-- Cross-substance interactions: stimulant, haemostatic, anaesthetic, poison
-
-**Neuromuscular and cognitive**
-- Reaction time → attack/defence timing; decision latency → AI replanning interval
-- Fine motor control impairment from arm damage; manipulation penalty from fractures
-- Fatigue accumulation (joules) → exhaustion threshold → prone collapse
-
-**Environmental**
-- Fire, corrosive, electrical, radiation, suffocation — tick-based accumulation with channel-specific armour
-- Blast wave (quadratic falloff) and fragmentation (stochastic count, random region)
-- Ambient temperature stress (Phase 10); terrain friction, elevation, cover, hazard cells (Phase 6)
-
-**Psychology**
-- Fear accumulation from near-miss fire, ally deaths, calibre size (Phase 5)
-- Routing, panic varieties (surrender / freeze / flee), leader auras, rally mechanics
-- Suppression from near-miss ranged fire → AI cover-seeking
-
-### Time scales covered
-
-| Scale | System |
-|-------|--------|
-| 50 ms / tick (20 Hz) | Combat resolution, movement, stamina |
-| Seconds | Bleeding, pharmacokinetics, thermal tick |
-| Minutes | Clotting, hypothermia onset |
-| Hours | Infection onset, hunger onset, thermal equilibrium |
-| Days | Hunger state transitions, mass loss from starvation |
-| Weeks | Wound healing, infection mortality |
-| Months / years | Training drift, ageing decline, injury sequelae (Phase 21) |
-
----
-
-## Quick start
-
-```typescript
-import { stepWorld, TICK_HZ } from "./src/sim/kernel.js";
-import { STARTER_WEAPONS } from "./src/equipment.js";
-import { HUMAN_BASE } from "./src/archetypes.js";
-import { generateIndividual } from "./src/generate.js";
-import { q, SCALE } from "./src/units.js";
-import { v3 } from "./src/sim/vec3.js";
-import { defaultIntent } from "./src/sim/intent.js";
-import { defaultAction } from "./src/sim/action.js";
-import { defaultCondition } from "./src/sim/condition.js";
-import { defaultInjury } from "./src/sim/injury.js";
-
-// Two fighters, procedurally generated from the human archetype.
-// Each will have unique physical attributes drawn from realistic distributions.
-const attrsA = generateIndividual(1, HUMAN_BASE);
-const attrsB = generateIndividual(2, HUMAN_BASE);
-
-const world = {
-  tick: 0,
-  seed: 12345,
-  entities: [
-    {
-      id: 1, teamId: 1,
-      attributes: attrsA,
-      energy: { reserveEnergy_J: attrsA.performance.reserveEnergy_J, fatigue: q(0) },
-      loadout: { items: [STARTER_WEAPONS[0]] },
-      traits: [],
-      position_m: v3(0, 0, 0),
-      velocity_mps: v3(0, 0, 0),
-      intent: defaultIntent(), action: defaultAction(),
-      condition: defaultCondition(), injury: defaultInjury(),
-      grapple: { holdingTargetId: 0, heldByIds: [], gripQ: q(0) },
-    },
-    {
-      id: 2, teamId: 2,
-      attributes: attrsB,
-      energy: { reserveEnergy_J: attrsB.performance.reserveEnergy_J, fatigue: q(0) },
-      loadout: { items: [] },
-      traits: [],
-      position_m: v3(Math.trunc(0.8 * SCALE.m), 0, 0),
-      velocity_mps: v3(0, 0, 0),
-      intent: defaultIntent(), action: defaultAction(),
-      condition: defaultCondition(), injury: defaultInjury(),
-      grapple: { holdingTargetId: 0, heldByIds: [], gripQ: q(0) },
-    },
-  ],
-};
-
-const cmds = new Map([
-  [1, [{ kind: "attack", targetId: 2, weaponId: "wpn_club", intensity: q(1.0), mode: "strike" }]],
-]);
-
-for (let i = 0; i < 5 * TICK_HZ; i++) {
-  stepWorld(world, cmds, { tractionCoeff: q(0.9) });
-}
-
-const target = world.entities.find(e => e.id === 2)!;
-console.log("Torso surface damage:", target.injury.byRegion.torso.surfaceDamage / SCALE.Q);
-console.log("Consciousness:",        target.injury.consciousness / SCALE.Q);
-console.log("Dead:",                 target.injury.dead);
-```
-
----
-
-## Fixed-point unit system
-
-All simulation values are scaled integers. Never use `Math.random()` or floating-point
-arithmetic in simulation code.
-
-| Unit | SCALE constant | Meaning |
-|---|---|---|
-| metres | `SCALE.m = 10000` | 1 m = 10 000 units |
-| seconds | `SCALE.s = 10000` | 1 s = 10 000 units |
-| kilograms | `SCALE.kg = 1000` | 1 kg = 1 000 units |
-| newtons | `SCALE.N = 1000` | 1 N = 1 000 units |
-| joules | `SCALE.J = 1000` | 1 J = 1 000 units |
-| watts | `SCALE.W = 1000` | 1 W = 1 000 units |
-| dimensionless | `SCALE.Q = 10000` | 1.0 = 10 000 units |
-
-Convert to fixed-point: `q(0.5)` → `5000`, `to.m(1.8)` → `18000`.
-Read back: `value / SCALE.m` → metres, `value / SCALE.Q` → dimensionless fraction.
-
----
-
-## Entity model
-
-Every entity is built from four attribute groups, all in SI units.
-
-### Morphology
-
-| Field | Unit | Meaning |
-|---|---|---|
-| `stature_m` | m | Height |
-| `mass_kg` | kg | Total mass |
-| `actuatorMass_kg` | kg | Muscle or actuator mass |
-| `actuatorScale` | Q | Actuator strength multiplier |
-| `structureScale` | Q | Structural toughness multiplier |
-| `reachScale` | Q | Limb reach multiplier |
-
-### Performance
-
-| Field | Unit | Meaning |
-|---|---|---|
-| `peakForce_N` | N | Maximum output force |
-| `peakPower_W` | W | Maximum instantaneous power |
-| `continuousPower_W` | W | Sustainable aerobic power |
-| `reserveEnergy_J` | J | Total metabolic reserve (stamina pool) |
-| `conversionEfficiency` | Q | Fraction of metabolic energy delivered as mechanical work |
-
-### Control
-
-| Field | Unit | Meaning |
-|---|---|---|
-| `controlQuality` | Q | Overall motor coordination (0–1) |
-| `reactionTime_s` | s | Neuromuscular response latency |
-| `stability` | Q | Balance and postural stability (0–1) |
-| `fineControl` | Q | Precision of fine movements (0–1) |
-
-### Resilience
-
-| Field | Unit | Meaning |
-|---|---|---|
-| `surfaceIntegrity` | Q | Resistance to surface-layer damage |
-| `bulkIntegrity` | Q | Resistance to bulk soft-tissue damage |
-| `structureIntegrity` | Q | Resistance to skeletal or structural damage |
-| `distressTolerance` | Q | Pain and distress tolerance (0–1) |
-| `shockTolerance` | Q | Resistance to haemodynamic shock (0–1) |
-| `concussionTolerance` | Q | CNS impact tolerance (0–1) |
-| `heatTolerance` | Q | Thermal hazard resistance (0–1) |
-| `coldTolerance` | Q | Cold hazard resistance (0–1) |
-| `fatigueRate` | Q | Fatigue accumulation rate multiplier |
-| `recoveryRate` | Q | Recovery rate multiplier |
-| `magicResist` | Q | Resistance to capability effects (magic/technology); q(1.0) = fully immune (optional) |
-
-### Perception (Phase 4)
-
-| Field | Unit | Meaning |
-|---|---|---|
-| `visionRange_m` | m | Maximum reliable visual detection range |
-| `visionArcDeg` | degrees | Horizontal field of view (120° human, 360° robot) |
-| `halfArcCosQ` | Q | cos(visionArcDeg/2) pre-computed for fast sim-path arc checks |
-| `hearingRange_m` | m | Omnidirectional acoustic detection range |
-| `decisionLatency_s` | s | Minimum time between plan revisions (500ms human, 50ms robot) |
-| `attentionDepth` | integer | Maximum simultaneously tracked threats |
-| `threatHorizon_m` | m | Range at which threats are integrated into decisions |
-
-### Individual variation
-
-`generateIndividual(seed, archetype)` produces a unique entity by applying triangular
-distributions to each attribute, parameterised by the archetype's variance fields.
-
-A human with seed 1 might have `peakForce_N = 1640` (below average) but
-`reserveEnergy_J = 26000` (high stamina). These values are physically meaningful and feed
-directly into combat, movement, and fatigue calculations with no intermediate conversion.
-
-Archetypes in `src/archetypes.ts`: `HUMAN_BASE`, `SERVICE_ROBOT`, `AMATEUR_BOXER`,
-`PRO_BOXER`, `GRECO_WRESTLER`, `KNIGHT_INFANTRY`, `LARGE_PACIFIC_OCTOPUS`. Additional
-archetypes (quadruped, alien, etc.) are data additions, not code changes.
-
----
-
-## Anatomy and injury
-
-Per-region injury tracking — fully data-driven via `BodyPlan` (Phase 8). Default is humanoid
-(head, torso, left arm, right arm, left leg, right leg). Other plans: quadruped, theropod,
-sauropod, avian, vermiform, centaur, octopoid — see `src/sim/bodyplan.ts`.
-
-Each region tracks:
-
-- `surfaceDamage` — skin, scales, outer covering
-- `internalDamage` — organ, soft-tissue, deep injury
-- `structuralDamage` — bone, frame, load-bearing structure
-- `bleedingRate` — active blood loss rate
-- `fractured` — set when `structuralDamage ≥ 0.70`; persistent impairment until surgically repaired (Phase 9)
-- `permanentDamage` — floor below which surgery cannot reduce `structuralDamage` (set at ≥ 0.90) (Phase 9)
-- `bleedDuration_ticks` — ticks with active bleeding; infection onsets after 100 ticks if `internalDamage > 0.10` (Phase 9)
-- `infectedTick` — tick at which infection began (`-1` = none); infected regions gain `+q(0.0003)` internal damage per tick (Phase 9)
-
-Global injury state:
-
-- `shock` — haemodynamic and neurological shock (0–1)
-- `fluidLoss` — cumulative blood or fluid loss (0–1); fatal at 0.80 (Phase 9)
-- `consciousness` — 1.0 = fully conscious, 0 = unconscious
-- `dead` — irreversible cessation
-
----
-
-## Functional impairment
-
-Damage produces functional penalties that feed automatically into movement, combat, and
-stamina calculations:
-
-| Damage location | Effect |
-|---|---|
-| Leg structural | Sprint speed and acceleration reduction |
-| Leg fracture | Up to −30% mobility (Phase 9) |
-| Arm damage | Manipulation quality and parry effectiveness reduction |
-| Arm fracture | Up to −25% manipulation (Phase 9) |
-| Head damage | Coordination and consciousness degradation |
-| Torso damage | Breathing impairment and shock vulnerability |
-| Shock (global) | All performance multipliers degraded |
-
----
-
-## Combat resolution
-
-### Hit resolution
-
-1. Attacker rolls against `controlQuality` and `reactionTime_s`
-2. Defender rolls against their defence mode (block, parry, dodge) and intensity
-3. Geometry influence (facing angle) modifies contest
-4. On hit: location selected by weighted region roll, hit quality computed
-5. Shield interposition checked against region coverage
-6. Armour checked per region and channel
-7. Residual energy applied to injury
-
-### Impact physics
-
-Impact energy derived from:
-
-- Weapon effective mass (kg)
-- Relative velocity (m/s) from attacker's `peakPower_W` and `continuousPower_W`
-- Leverage: parry leverage from weapon moment arm (N·m)
-- Two-handed grip: 1.12× energy bonus when both arms are free
-
-Converted to surface, internal, and structural injury proportional to penetration profile.
-Bleeding rate increases proportionally to internal damage severity.
-
-### Weapon dynamics
-
-- **Reach dominance**: shorter weapon is penalised in both attack and parry against a longer one
-- **Miss recovery**: missed strikes add extra cooldown ticks proportional to weapon angular momentum (mass × reach)
-- **Weapon bind**: successful parry with heavy weapons can lock both weapons; requires a strength contest (`breakBind`) to escape
-- **Grappling**: strength+mass+technique contest; positions (standing/pinned/prone), throws, chokes, joint locks
-- **Swing momentum carry**: `swingMomentumQ` decays 5%/tick; a clean hit sets it to `intensity × q(0.80)`; adds up to +12% energy on the next strike; reset to 0 on miss, block, or parry
-
-### Stamina
-
-Actions cost energy (joules). When reserve falls below 15% of baseline, functional penalties
-ramp in. At zero reserve the entity collapses prone and loses all active defence.
-
-### Medical treatment (Phase 9)
-
-Treatment is issued via `TreatCommand` and resolved by `resolveTreat()` in the kernel.
-The treater must be within 2 m of the target. Outcome scales with equipment tier and the
-treater's `medical` skill (`treatmentRateMul`).
-
-**Equipment tiers** (ascending capability): `bandage`, `surgicalKit`, `autodoc`, `nanomedicine`.
-
-| Action | Min tier | Effect |
-|---|---|---|
-| `tourniquet` | bandage | Zeroes `bleedingRate` for one region immediately |
-| `bandage` | bandage | Reduces `bleedingRate` by `q(0.005) × effectMul` per tick |
-| `surgery` | surgicalKit | Reduces `structuralDamage`; clears fracture; clears infection (≥ surgicalKit) |
-| `fluidReplacement` | autodoc | Reduces `fluidLoss`; slightly reduces shock |
-
-**Natural clotting**: `bleedingRate` decays automatically each tick at a rate proportional
-to `(1 − structuralDamage) × q(0.0002)`. Severe structural damage slows natural clotting.
-
-**Injury progression** each tick:
-- Bleeding accumulates `fluidLoss` at `bleedingRate / TICK_HZ`
-- Fluid loss drives shock; shock erodes consciousness
-- `fluidLoss ≥ 0.80` → immediate death
-- Infection (if present) adds `+q(0.0003)` internal damage per tick
-
-### Ranged combat
-
-Physics-based projectile system parallel to melee. Issued via `shoot` command.
-
-**Energy at range** — linear drag approximation: `energy_J = launchEnergy_J × max(0, 1 − range_m × dragCoeff_perM)`. No energy means no hit.
-
-**Accuracy** — angular dispersion converts to grouping radius at range (`dispersionQ × range_m`). Compared against body half-width (~20% of stature). Miss if error exceeds half-width; near-miss if within 3× half-width.
-
-**Dispersion modifiers**: `controlQuality`, `fineControl`, fatigue, and aiming intensity all scale the base weapon dispersion.
-
-**Aiming time** — issuing consecutive `shoot` commands against the same target while stationary accumulates `aimTicks` (max 20, capped at 50% dispersion reduction). Resets on target switch, movement above 0.5 m/s, or after firing.
-
-**Moving target penalty** — target velocity adds a lead error (`velocity × 0.2 s reaction time`) to the grouping radius before the hit roll. A sprinting target at 30 m is dramatically harder to hit than a stationary one.
-
-**Suppression** — near-misses set `suppressedTicks` on the target, applying a −10% `coordinationMul` penalty until the counter drains. Entities with `suppressedTicks ≥ 3` and low `distressTolerance` will go prone via AI; all suppressed entities seek cover at a higher threshold (q(0.50) vs q(0.30)).
-
-**Ammo types** — a `RangedWeapon` may carry an `ammo: AmmoType[]` array. A `shoot` command with `ammoId` selects a round that overrides mass, drag, damage profile, and/or launch energy multiplier for that shot. `STARTER_AMMO` provides `ammo_ap` (penetrating), `ammo_hv` (×1.20 launch energy), and `ammo_hollow` (high bleed factor).
-
-**Projectile categories:**
-
-| Category | Launch energy | Examples |
-|---|---|---|
-| Thrown | Derived from thrower `peakPower_W` (÷10) | Sling |
-| Bow | Fixed weapon property (J) | Short bow, long bow, crossbow |
-| Firearm | Fixed weapon property (J) | Pistol, musket |
-
-Hits reuse the existing injury pipeline (`applyImpactToInjury`) via a weapon proxy. Armour and shields interpose by the same rules as melee.
-
----
-
-## Armour
-
-Per-region coverage with per-channel protection:
-
-| Channel | Protects against |
-|---|---|
-| Kinetic | Blunt and penetrating impacts |
-| Thermal | Fire, extreme heat |
-| Chemical | Corrosive aerosols |
-| Electrical | Electrical discharge |
-| Radiation | Ionising radiation |
-| Suffocation | Airborne hazard (sealed suits) |
-| ControlDisruption | EMP, neural disruption |
-
-Armour properties: `resist_J` (kinetic threshold), `coverageByRegion` (probability of
-interposition), `protectedDamageMul` (residual damage fraction), `channelResistMul`
-(per-channel resistance modifier), `mobilityMul`, `fatigueMul`.
-
----
-
-## Environmental hazards
-
-Conditions accumulate on entities per tick and drive injury via the same per-channel,
-per-region pipeline as combat:
-
-| Condition | Effect |
-|---|---|
-| `onFire` | Surface damage + shock accumulation |
-| `corrosiveExposure` | Surface and internal damage |
-| `electricalOverload` | Internal damage + stun |
-| `radiation` | Internal damage + shock |
-| `suffocation` | Shock and consciousness erosion |
-
-Armour provides protection against all channels. Traits (`radiationHardened`, `sealed`,
-`nonConductive`, etc.) provide immunity or resistance.
-
-### Blast and fragmentation (Phase 10)
-
-`applyExplosion(world, origin, spec, tick, trace)` applies a `BlastSpec` point-source explosion
-to all living entities within the blast radius. Uses quadratic falloff (`1 − dist²/radius²`).
-
-- **Blast wave**: delivered to torso as `BLAST_WEAPON` (high internal damage)
-- **Fragments**: stochastic count per entity; each fragment hits a random region as `FRAG_WEAPON`
-  (high penetration bias, high bleed factor)
-- Emits `BlastHit` trace event per affected entity
-
-### Fall damage (Phase 10)
-
-`applyFallDamage(world, entityId, height_m, tick, trace)` applies fall physics.
-KE = mass × g × height; 85% absorbed by muscles (15% transmitted). Any fall ≥ 1 m forces prone.
-Damage distributed: locomotion-primary regions 70%, others 30% (body-plan-aware).
-Humanoid fallback: legs 35% each, arms 10% each, torso/head 5% each.
-
-### Pharmacokinetics (Phase 10)
-
-One-compartment model per active substance (`entity.substances`). Each tick:
-absorption rate × pendingDose absorbed into concentration; elimination rate × concentration removed.
-Effects activate when concentration exceeds `effectThreshold`:
-
-| Effect type | Per-tick effect |
-|---|---|
-| `stimulant` | Reduces `fearQ` and slows fatigue accumulation |
-| `anaesthetic` | Erodes `consciousness` |
-| `poison` | Internal damage to torso + mild shock |
-| `haemostatic` | Reduces `bleedingRate` across all regions |
-
-`STARTER_SUBSTANCES` provides four ready-made entries: `stimulant`, `anaesthetic`, `poison`, `haemostatic`.
-
-### Ambient temperature (Phase 10)
-
-`KernelContext.ambientTemperature_Q` — comfort range `[q(0.35), q(0.65)]`.
-- Heat (above q(0.65)): shock + torso surface damage; scaled by `heatTolerance`
-- Cold (below q(0.35)): shock + fatigue accumulation; scaled by `coldTolerance`
-
-### Technology spectrum (Phase 11)
-
-`TechContext` gates which items are usable in a scenario without locking them to a specific era.
-
-```typescript
-import { TechEra, defaultTechContext, isCapabilityAvailable } from "./src/sim/tech.js";
-import { validateLoadout, STARTER_EXOSKELETONS } from "./src/equipment.js";
-
-const ctx = defaultTechContext(TechEra.NearFuture);
-// ctx.available includes PoweredExoskeleton but not EnergyWeapons
-
-const exo = STARTER_EXOSKELETONS.find(e => e.id === "exo_combat")!;
-const loadout = { items: [exo] };
-const errors = validateLoadout(loadout, ctx); // [] — valid
-```
-
-**`Exoskeleton` item kind** — integrated with kernel:
-- `speedMultiplier: Q` — factored into `stepMovement` baseMul
-- `forceMultiplier: Q` — applied to strike `energy_J` in `resolveAttack`
-- `powerDrain_W: number` — added to metabolic demand in `stepEnergy`
-
-**Starter items**: `exo_combat` (+25% speed, +40% force, 200 W drain),
-`exo_heavy` (+10% speed, +80% force, 400 W drain), `arm_plate` (800 J resist, requires `MetallicArmour`),
-`rng_plasma_rifle` (2000 J, requires `EnergyWeapons`).
-
-Era capabilities are cumulative: Prehistoric has none; DeepSpace has all eight.
-
-**Magic and para-science types** (Phase 12B) — four additional `TechCapability` values gate
-Clarke's Third Law capability effects: `ArcaneMagic`, `DivineMagic`, `Psionics`, `Nanotech`.
-These are not assigned to any era by `ERA_DEFAULTS`; host applications opt in explicitly.
-
-**Medical technology gate**: `TIER_TECH_REQ` in `medical.ts` maps medical tiers to required
-capabilities. When `ctx.techCtx` is set, `resolveTreat()` blocks treatment if the treater's
-tier requires a capability absent from the scenario. Currently: `nanomedicine` tier requires
-`NanomedicalRepair`. Tiers without a listed requirement work in any era.
-
----
-
-## Capability Sources and Effects (Phase 12)
-
-**Clarke's Third Law**: a fireball and a plasma grenade, a healing spell and a nanobot swarm,
-a mana pool and a fusion reactor — all resolve through identical engine primitives. The engine
-cannot distinguish magic from technology. Only the `tags` field differs.
-
-### CapabilitySource
-
-Attached to `entity.capabilitySources?: CapabilitySource[]`. Each source is an energy reservoir
-(always in joules) with one of five regen models:
-
-| RegenModel type | Behaviour |
-|---|---|
-| `rest` | Regens only when entity is stationary and not in combat |
-| `constant` | Regens every tick regardless of activity |
-| `ambient` | Regens proportional to `ambientGrid` cell value at entity's position |
-| `event` | Fires on tick intervals or kill triggers |
-| `boundless` | Never depletes; cost deduction skipped entirely |
-
-### ActivateCommand
-
-```typescript
-{ kind: "activate", sourceId: string, effectId: string, targetId?: number, targetPos?: Vec3 }
-```
-
-### EffectPayload variants
-
-| Payload kind | Effect | Engine primitive |
-|---|---|---|
-| `impact` | Kinetic, thermal, internal, or penetrating damage | `applyImpactToInjury` |
-| `treatment` | Healing at specified tier and rate multiplier | `resolveTreat` |
-| `armourLayer` | Temporary per-channel armour overlay | `condition.temporaryArmour` |
-| `velocity` | Direct velocity delta (telekinesis, jump jet) | velocity integration |
-| `substance` | Pharmacokinetic substance injection | `stepSubstances` |
-| `structuralRepair` | Structural damage write-back (respects `permanentDamage`) | injury state |
-| `fieldEffect` | Places suppression zone in `world.activeFieldEffects` | `stepFieldEffects` |
-
-### Phase 12B extensions
-
-- **Per-capability cooldowns**: `cooldown_ticks?: number` on `CapabilityEffect`; tracked in
-  `action.capabilityCooldowns` (Map, key = `"sourceId:effectId"`); decremented at tick start.
-- **TechCapability gating**: `requiredCapability?: TechCapability` on `CapabilityEffect`;
-  checked against `ctx.techCtx` when set. Includes magic gates: `ArcaneMagic`, `DivineMagic`,
-  `Psionics`, `Nanotech`.
-- **Magic resistance**: `magicResist?: Q` on `Resilience`; seeded roll per non-self target in
-  `applyCapabilityEffect`; q(1.0) = always resist; self-cast bypasses entirely.
-- **Kill-triggered regen**: `{ on: "kill", amount_J }` in `EventRegen.triggers`; dispatched at
-  entity death; all living non-dead observers receive the reward (including the killer).
-- **Terrain-entry triggers**: `{ on: "terrain", tag, amount_J }` fires exactly once per
-  cell-boundary crossing; `action.lastCellKey` tracks the previous cell; supply
-  `KernelContext.terrainTagGrid` (Map of cell key → tag array) and optional `cellSize_m`.
-- **Concentration auras**: `castTime_ticks = -1` marks an ongoing per-tick effect;
-  `entity.activeConcentration` holds the active aura; `cost_J` is deducted every tick;
-  concentration breaks when reserve falls below `cost_J` or shock reaches q(0.30), emitting
-  `CastInterrupted`.
-- **Linked sources**: `CapabilitySource.linkedFallbackId` names a secondary source to draw
-  from when the primary is depleted; fallback can be `boundless` for unlimited overflow.
-- **Effect chains**: `FieldEffectSpec.chainPayload?: EffectPayload | EffectPayload[]` — payload
-  applied to every living entity within the field's radius each tick while the field is active;
-  fires before expiry so the final tick still delivers the payload.
-
----
-
-## 3D model integration (Phase 14)
-
-`src/model3d.ts` provides pure data-extraction functions for driving 3D character rigs from
-simulation state. No kernel changes, no state mutations. Call once per tick after `stepWorld`.
-
-```typescript
-import { extractRigSnapshots } from "./src/model3d.js";
-
-const snapshots = extractRigSnapshots(world);
-for (const snap of snapshots) {
-  // snap.mass     — MassDistribution: per-segment mass and estimated CoG in real metres
-  // snap.inertia  — InertiaTensor: yaw/pitch/roll moment of inertia (kg·m²)
-  // snap.animation — AnimationHints: locomotion blend weights, guarding, attacking, prone, dead
-  // snap.pose     — PoseModifier[]: per-region injury deformation blend weights
-  // snap.grapple  — GrapplePoseConstraint: relative pose lock for grappling pairs
-  hostRenderer.updateRig(snap.entityId, snap);
-}
-```
-
-**Mass and inertia** are derived from `entity.bodyPlan` segment masses via canonical keyword
-matching (`head`, `torso`, `forearm`, `thigh`, `shin`, `wing`, etc.); fallback to a solid-sphere
-approximation when no body plan is present.
-
-**Animation hints** — locomotion weights (`idle`/`walk`/`run`/`sprint`/`crawl`) are mutually
-exclusive; exactly one is `SCALE.Q` when mobile. Overlays include `guardingQ`, `attackingQ`,
-`shockQ`, `fearQ`, and boolean flags `prone`, `unconscious`, `dead`.
-
-**Pose modifiers** — one entry per `injury.byRegion` key. `impairmentQ = max(structuralQ, surfaceQ)`.
-Map each `segmentId` to a skeleton bone and drive blend-shape or constraint weights.
-
-**Grapple constraints** — `isHolder`/`isHeld` flags, `holdingEntityId`, `heldByIds`, `position`
-(`standing`/`prone`/`pinned`), and `gripQ`. Use to lock relative pose between grappling entities.
-
-**Integration note:** These functions provide data snapshots only.  Mapping Ananke's abstract
-segment IDs to a specific engine's skeleton, handling tick-rate mismatch (20 Hz → 60+ Hz), and
-wiring animation hints into a state machine are the host's responsibility.  See
-`docs/bridge-api.md` for the full API reference and `docs/ecosystem.md` for Unity/Godot adapter
-sketches.  A minimal runnable reference plugin (ROADMAP item 6) is the next priority for
-lowering this integration barrier.
-
----
-
-## API stability contract
-
-> Full reference: [`STABLE_API.md`](./STABLE_API.md) — Versioning policy: [`CHANGELOG.md`](./CHANGELOG.md)
-
-Ananke distinguishes three tiers of API stability so adopters know what to pin and what to
-expect to change.
-
-| Tier | What | Promise |
-|------|------|---------|
-| **Stable host API** | `stepWorld()`, `generateIndividual()`, `resolveHit()`, `Entity` shape (core fields), `q()` / `qMul()` / `clampQ()`, `ReplayRecorder` / `replayTo()`, `serializeReplay()` / `deserializeReplay()`, `extractRigSnapshots()` | No breaking changes without a major version bump and migration guide |
-| **Experimental extension API** | `stepPolityDay()`, `stepTechDiffusion()`, `applyEmotionalContagion()`, `compressMythsFromHistory()`, `stepNarrativeStress()`, `arena.ts` scenario DSL | Good-faith stability; may shift between minor versions with changelog |
-| **Internal kernel structures** | `src/sim/push.ts`, `src/sim/kernel.ts` internals, `src/rng.ts`, `eventSeed()` | No stability promise; do not import directly |
-
-All replay, serialization, and campaign round-trip guarantees apply only to the Stable tier.
-Experimental APIs are safe to use but may require migration on minor version updates.
-
----
-
-## Determinism rules
-
-To maintain lockstep safety:
-
-- Never use `Math.random()`
-- Avoid floating point in simulation path
-- Iterate in stable, deterministic order
-- Consume RNG in fixed sequence per event type
-- Use deterministic event batching
-- Avoid unordered map iteration for gameplay logic
-- All seeds derived from `(worldSeed, tick, entityId, eventType)` — no global state
-
----
-
-## AI and Perception
-
-Deterministic AI modules (Phase 4):
-
-- `sensory.ts` — `canDetect()`: vision arc, hearing range, environmental multipliers
-- `perception.ts` — `perceiveLocal()`: sensory-filtered enemy and ally detection
-- `targeting.ts` — `pickTarget()`, `updateFocus()`: horizon-limited, focus stickiness
-- `decide.ts` — `decideCommandsForEntity()`: behaviour presets with decision latency
-- `presets.ts` — `AI_PRESETS`: lineInfantry, skirmisher
-- `system.ts` — `buildAICommands()`: full AI pass over world
-
-**Decision latency**: entities re-plan at most once every `decisionLatency_s` seconds
-(10 ticks for humans, 1 tick for robots). Between plans, previous intent persists.
-
-**Surprise mechanics**: `canDetect(defender, attacker, env)` returns detection quality Q.
-If attacker is outside defender's FoV (< q(0.8)), defensive intensity is scaled
-proportionally. Full surprise (q(0)) eliminates defensive reaction entirely.
-
----
-
-## Skills (Phase 7)
-
-Skills represent learned technique — adjustments to physical outcomes, not abstract point totals.
-They are provided by the host application and consumed by the engine. The engine never writes
-back to skill values; progression is the host's responsibility.
-
-### Skill map
-
-Each entity carries an optional `skills?: SkillMap` (`Map<SkillId, SkillLevel>`).
-When a skill is absent, `getSkill()` returns neutral defaults (no effect on simulation output),
-making all existing entities fully backward-compatible.
-
-```typescript
-import { buildSkillMap } from "./src/sim/skills.js";
-
-entity.skills = buildSkillMap({
-  meleeCombat:  { hitTimingOffset_s: -to.s(0.2), energyTransferMul: q(1.35) },
-  meleeDefence: { energyTransferMul: q(1.5) },
-  athleticism:  { fatigueRateMul: q(0.75) },
-});
-```
-
-### Skill domains
-
-| SkillId | Physical effect |
-|---|---|
-| `meleeCombat` | `hitTimingOffset_s` reduces attack cooldown; `energyTransferMul` scales strike energy |
-| `meleeDefence` | `energyTransferMul` scales effective parry/block quality |
-| `grappling` | `energyTransferMul` scales grapple contest score |
-| `rangedCombat` | `dispersionMul` tightens grouping radius (more accurate fire) |
-| `throwingWeapons` | `energyTransferMul` scales thrown weapon launch energy |
-| `shieldCraft` | `energyTransferMul` boosts defence skill when blocking with a shield |
-| `medical` | `treatmentRateMul` reduces fluid loss from bleeding each tick |
-| `athleticism` | `fatigueRateMul` reduces fatigue accumulation per energy tick |
-| `tactics` | `hitTimingOffset_s` reduces AI decision latency |
-| `stealth` | `dispersionMul` reduces the subject's acoustic signature (harder to hear) |
-
-### Composing skill levels
-
-`combineSkillLevels(a, b)` multiplies Q fields and adds time offsets, letting the host express
-synergy bonuses or composite experience modifiers before building the SkillMap:
-
-```typescript
-import { combineSkillLevels, defaultSkillLevel } from "./src/sim/skills.js";
-
-// Melee expert with an athleticism timing synergy (−0.25 s total)
-const combined = combineSkillLevels(
-  { ...defaultSkillLevel(), hitTimingOffset_s: -to.s(0.20), energyTransferMul: q(1.40) },
-  { ...defaultSkillLevel(), hitTimingOffset_s: -to.s(0.05) },
-);
-entity.skills = buildSkillMap({ meleeCombat: combined });
-```
-
----
-
-## Replay and analytics (Phase 13)
-
-### Deterministic replay
-
-Every simulation is reproducible from initial state + command log. `ReplayRecorder` snapshots
-the world before the first tick and records command maps per tick. `replayTo` reconstructs
-any past tick by restoring the snapshot and re-applying frames.
-
-```typescript
-import { ReplayRecorder, replayTo, serializeReplay, deserializeReplay } from "./src/replay.js";
-
-const recorder = new ReplayRecorder(world);
-for (let i = 0; i < 100; i++) {
-  recorder.record(world.tick, cmds);
-  stepWorld(world, cmds, ctx);
-}
-
-// Seek to any past tick
-const worldAt50 = replayTo(recorder.toReplay(), 50, ctx);
-
-// Persist and restore across sessions
-const json = serializeReplay(recorder.toReplay());
-const restored = deserializeReplay(json);
-const worldAt50Again = replayTo(restored, 50, ctx);
-```
-
-`serializeReplay`/`deserializeReplay` handle `Map` fields (`entity.armourState`,
-`action.capabilityCooldowns`) that `JSON.stringify` would otherwise drop.
-
-### Combat analytics
-
-`CollectingTrace` implements `TraceSink` and accumulates all trace events for offline
-analysis. Pass it to `stepWorld` via `ctx.trace`, then extract metrics.
-
-```typescript
-import { CollectingTrace, collectMetrics, survivalRate, meanTimeToIncapacitation }
-  from "./src/metrics.js";
-
-const tracer = new CollectingTrace();
-for (let i = 0; i < 200; i++) stepWorld(world, cmds, { ...ctx, trace: tracer });
-
-const m = collectMetrics(tracer.events);
-console.log("Damage dealt by entity 1:", m.damageDealt.get(1));   // joules
-console.log("Hits landed by entity 1:", m.hitsLanded.get(1));
-console.log("Survival rate:", survivalRate(tracer.events, [1, 2, 3, 4]));
-console.log("Mean TTI (ticks):", meanTimeToIncapacitation(tracer.events, [1, 2, 3, 4], 200));
-```
-
-`collectMetrics` covers melee `Attack` events and ranged `ProjectileHit` events in a single
-pass over any flat `TraceEvent[]` — ordering and tick mixing are fine.
-
-### Visual debug layer (Phase 13)
-
-`extractMotionVectors`, `extractHitTraces`, and `extractConditionSamples` in `src/debug.ts`
-transform world state and trace events into renderer-friendly snapshots:
-
-```typescript
-import { extractMotionVectors, extractHitTraces, extractConditionSamples } from "./src/debug.js";
-import { CollectingTrace } from "./src/metrics.js";
-
-const tracer = new CollectingTrace();
-stepWorld(world, commands, { ...ctx, trace: tracer });
-
-// Motion overlay — one entry per entity with position, velocity, and facing
-const arrows = extractMotionVectors(world);
-
-// Hit display — melee and projectile hits with region and energy
-const { meleeHits, projectileHits } = extractHitTraces(tracer.events);
-
-// Condition heatmap — fear, shock, consciousness, fluid loss per entity
-const heatmap = extractConditionSamples(world);
-
-// Sample any past tick via replay
-const past = replayTo(recorder.toReplay(), 42, ctx);
-const pastHeatmap = extractConditionSamples(past);
-```
-
----
-
-## Character description layer (Phase 16)
-
-`src/describe.ts` translates raw SI fixed-point attributes into human-readable summaries.
-No simulation dependencies — safe to import from any host application.
-
-```typescript
-import { describeCharacter, formatCharacterSheet, formatOneLine } from "./src/describe.js";
-import { generateIndividual } from "./src/generate.js";
-import { PRO_BOXER } from "./src/archetypes.js";
-
-const attrs = generateIndividual(7, PRO_BOXER);
-const desc  = describeCharacter(attrs);
-
-console.log(formatOneLine(desc));
-// → "Tall (1.83 m), 86.4 kg; strength excellent (4982 N), reaction quick (180 ms), resilience tough."
-
-console.log(formatCharacterSheet(desc));
-// Body
-//   Stature:      1.83 m — tall
-//   Mass:         86.4 kg — average build
-//
-// Performance
-//   Strength:     4982 N      [excellent]    elite level — professional fighter strength
-//   Power:        2214 W      [excellent]    elite explosive output
-//   Endurance:    398 W       [strong]       strong sustained performance
-//   Stamina:      40 kJ       [strong]       good combat energy reserves
-// ...
-```
-
-### Tier system
-
-Every attribute is rated 1–6 using breakpoints grounded in sports-science literature:
-
-| Tier | Label | Meaning |
-|------|-------|---------|
-| 1 | feeble / sluggish / fragile | Well below human baseline |
-| 2 | weak / slow / low | Below-average adult |
-| 3 | average | Baseline healthy adult (HUMAN_BASE anchor) |
-| 4 | strong / precise / resilient | Trained athlete or competitive fighter |
-| 5 | excellent / fast / tough | Elite / professional level |
-| 6 | exceptional / instant / ironclad | Superhuman, mechanical, or distributed biology |
-
-Reaction time and decision latency use an **inverted** scale (lower value = higher tier).
-`SERVICE_ROBOT` (80 ms reaction, 50 ms decision) → tier 6 "instant" / "machine-like" in both.
-`LARGE_PACIFIC_OCTOPUS` (no enclosed skull) → tier 6 "ironclad" concussion resistance.
-
-### API
-
-```typescript
-describeCharacter(attrs: IndividualAttributes): CharacterDescription
-// Returns a structured object with tier, label, comparison string, and formatted value
-// for every attribute. Vision and hearing are formatted strings (e.g. "200 m, 120° arc").
-
-formatCharacterSheet(desc: CharacterDescription): string
-// Multi-line columnar output suitable for a character screen or debug log.
-
-formatOneLine(desc: CharacterDescription): string
-// Single sentence, no newlines — suitable for tooltips or list views.
-```
-
----
-
-## Combat narrative layer (Phase 18)
-
-`src/narrative.ts` converts raw `TraceEvent` streams into human-readable text. Like
-`src/describe.ts`, it has no simulation dependencies — safe to import from UI code or CLI tools.
-
-```typescript
-import { narrateEvent, buildCombatLog, describeInjuries, describeCombatOutcome }
-  from "./src/narrative.js";
-import { CollectingTrace } from "./src/metrics.js";
-import { ALL_HISTORICAL_MELEE } from "./src/weapons.js";
-
-const tracer = new CollectingTrace();
-for (let i = 0; i < 10 * TICK_HZ; i++) stepWorld(world, cmds, { ...ctx, trace: tracer });
-
-// Build weapon profile lookup for verb selection
-const profiles = new Map(ALL_HISTORICAL_MELEE.map(w => [w.id, w.damage]));
-
-const cfg = {
-  verbosity: "normal" as const,
-  nameMap: new Map([[1, "Sir Roland"], [2, "the orc"]]),
-  weaponProfiles: profiles,
-};
-
-// Per-event narration
-for (const ev of tracer.events) {
-  const line = narrateEvent(ev, cfg);
-  if (line) console.log(line);
-}
-// → "Sir Roland stabs the orc in the torso"
-// → "the orc attacks Sir Roland — parried"
-// → "Sir Roland powerfully stabs the orc in the head"
-// → "the orc is knocked unconscious"
-
-// Batch log
-const log = buildCombatLog(tracer.events, cfg);
-
-// Injury summary
-const orc = world.entities.find(e => e.id === 2)!;
-console.log(describeInjuries(orc.injury));
-// → "Unconscious; Significant blood loss; head fractured"
-
-// Outcome
-const summary = describeCombatOutcome(
-  world.entities.map(e => ({ id: e.id, teamId: e.teamId, injury: e.injury })),
-  200,
-);
-console.log(summary);
-// → "Team 1 wins — Team 2 defeated (200 ticks)"
-```
-
-### Verbosity levels
-
-| Level | What is included |
-|-------|-----------------|
-| `terse` | Landed hits, KO, death, morale route/rally, fractures, blasts — nothing else |
-| `normal` | Adds blocked/parried/shield notes, misses, grapple start/break, weapon bind, treatment |
-| `verbose` | Adds grapple maintenance ticks, capability events |
-
-### Verb selection
-
-Verb is chosen from the weapon's `WeaponDamageProfile` (supplied via `weaponProfiles` config):
-
-| Profile dominant field | Verb |
-|------------------------|------|
-| `penetrationBias ≥ q(0.65)` | stab(s) |
-| `structuralFrac ≥ q(0.50)` | bludgeon(s) |
-| `surfaceFrac ≥ q(0.50)` | slash(es) |
-| Default | strike(s) |
-
-Ranged: `penetrationBias ≥ q(0.80)` → snipe(s); `surfaceFrac ≥ q(0.55)` → blast(s); default → shoot(s).
-
-Energy qualifiers: `< 10J` → "barely grazes"; `≥ 200J` → "powerfully"; `≥ 500J` → "devastatingly".
-
-Set an entity's name to `"you"` in `nameMap` for second-person verb conjugation
-("you strike" rather than "you strikes").
-
----
-
-## Downtime & Recovery simulation (Phase 19)
-
-`src/downtime.ts` bridges the gap between 20 Hz combat and hours-to-weeks campaign time.
-It runs a compressed 1 Hz loop applying the same healing physics as the kernel, suitable
-for computing wound outcomes, resource consumption, and recovery timelines between sessions.
-
-```typescript
-import { stepDowntime, MEDICAL_RESOURCES } from "./src/downtime.js";
-
-const reports = stepDowntime(world, 3600, {
-  treatments: new Map([
-    [1, { careLevel: "first_aid" }],
-    [2, { careLevel: "field_medicine", onsetDelay_s: 120 }],
-  ]),
-  rest: true,
-});
-
-for (const r of reports) {
-  console.log(`Entity ${r.entityId}: died=${r.died}, bleedingStopped=${r.bleedingStopped}`);
-  console.log(`  Fluid loss: ${r.injuryAtStart.fluidLoss} → ${r.injuryAtEnd.fluidLoss}`);
-  console.log(`  Resources used: ${r.totalCostUnits} cost units`);
-  console.log(`  Combat ready in: ${r.combatReadyAt_s}s`);
-}
-```
-
-**Care levels:** `"none"` | `"first_aid"` | `"field_medicine"` | `"hospital"` | `"autodoc"` | `"nanomedicine"`
-
-**Resource catalogue** (`MEDICAL_RESOURCES`): 7 items from field bandage (1 unit) to nanomed dose (2000 units). All items have `costUnits` and `massGrams` for encumbrance and economy integration.
-
-**Calibration:** `q(0.06)` bleedingRate → fatal in ~267 simulated seconds without treatment. First aid stops bleeding in under 60 seconds. Untreated infection fatal within 21 simulated days.
-
----
-
-## Arena simulation framework (Phase 20)
-
-`src/arena.ts` provides a declarative scenario DSL for batch-running combat trials with statistical expectations. Use it to validate simulation realism, balance archetypes, and author calibration tests.
-
-```typescript
-import { runArena, expectWinRate, expectSurvivalRate, formatArenaReport }
-  from "./src/arena.js";
-import { mkKnight, mkBoxer } from "./src/presets.js";
-
-const scenario = {
-  name: "Knight vs Boxer",
-  combatants: [
-    { id: 1, teamId: 1, factory: () => mkKnight(1, 1, 0, 0) },
-    { id: 2, teamId: 2, factory: () => mkBoxer(2, 2, 1, 0) },
-  ],
-  maxTicks: 400,
-  expectations: [
-    expectWinRate(1, 0.70),           // knight wins ≥ 70% of trials
-    expectSurvivalRate(1, 1, 0.90),   // knight survives ≥ 90%
-  ],
-};
-
-const result = runArena(scenario, 50);
-console.log(formatArenaReport(result));
-```
-
-**Six built-in calibration scenarios** validate core physics:
-`CALIBRATION_ARMED_VS_UNARMED`, `CALIBRATION_UNTREATED_KNIFE_WOUND`,
-`CALIBRATION_FIRST_AID_SAVES_LIVES`, `CALIBRATION_FRACTURE_RECOVERY`,
-`CALIBRATION_INFECTION_UNTREATED`, `CALIBRATION_PLATE_ARMOUR`.
-
-**Recovery integration:** supply `scenario.recovery` to run `stepDowntime` post-combat and get `recoveryStats` (mean days to combat-ready, p90 resource cost, etc.).
-
----
-
-## Character progression (Phase 21)
-
-`src/progression.ts` adds the temporal axis: how entities improve through training and experience, decline through ageing, and carry permanent marks from injury. No simulation dependencies — safe to use in save-game serialisation and UI layers.
-
-```typescript
-import {
-  createProgressionState, awardXP, advanceSkill,
-  applyTrainingSession, stepAgeing, applyAgeingDelta,
-  deriveSequelae, serialiseProgression,
-} from "./src/progression.js";
-import { buildSkillMap } from "./src/sim/skills.js";
-import { to, q } from "./src/units.js";
-
-// XP and milestones
-const prog = createProgressionState();
-const milestones = awardXP(prog, "meleeCombat", 1, world.tick);  // +1 XP per combat
-for (const m of milestones) {
-  entity.skills = advanceSkill(entity.skills ?? buildSkillMap({}), m.domain, m.delta);
-}
-
-// Physical training (peakForce_N ceiling 3500 N)
-const plan   = { sessions: [], frequency_d: 3/7, ceiling: to.N(3500) };
-const sess   = { attribute: "peakForce_N", intensity_Q: q(0.50), duration_s: 3600 };
-entity.attributes.performance.peakForce_N =
-  applyTrainingSession(entity.attributes.performance.peakForce_N, plan, sess, 3);
-
-// Annual ageing
-const delta = stepAgeing(entity.attributes, entity.ageYears ?? 30);
-applyAgeingDelta(entity.attributes, delta);
-
-// Injury sequelae after a bad fracture
-const seqs = deriveSequelae(entity.injury.byRegion["leftLeg"]!, entity.bodyPlan!);
-for (const s of seqs) prog.sequelae.push({ region: "leftLeg", ...s });
-
-// Persist
-const json = serialiseProgression(prog);  // Map-aware JSON
-```
-
-**Milestone thresholds** grow geometrically (`BASE_XP=20`, `GROWTH_FACTOR=1.80`): milestone 0 at 20 XP, milestone 1 at 36, milestone 2 at 65, milestone 3 at 117… Calibrated so 100 combats (1 XP each) reduce `meleeCombat` reaction time by ~80 ms.
-
-**Training calibration:** 12-week strength programme (3×/week, moderate intensity) raises `peakForce_N` by 150–300 N. Overtraining penalty applies above 5 sessions/week.
-
-**Ageing:** 1 %/year performance decline after 35; +2 ms decision latency per year after 45. Integrating from age 20 to 70 always stays above zero (physically plausible minimum).
-
-**Sequelae types:** `fracture_malunion` (−15 % peak force), `nerve_damage` (−10 % fine control), `scar_tissue` (surface bleed threshold −5 %).
-
----
-
-## Campaign & World State (Phase 22)
-
-`src/campaign.ts` is the persistence layer for multi-session campaigns. It tracks world time,
-entity state, location, and item stockpiles between encounters, and delegates wound recovery
-to `stepDowntime`.
-
-```typescript
-import {
-  createCampaign, addLocation, travel,
-  creditInventory, debitInventory, getInventoryCount,
-  stepCampaignTime, mergeEntityState,
-  serialiseCampaign, deserialiseCampaign,
-} from "./src/campaign.js";
-
-// Create a campaign with starting entities
-const campaign = createCampaign("my-campaign", [fighter1, fighter2], "2025-01-01T00:00:00Z");
-
-// Register locations with travel costs (seconds)
-addLocation(campaign, { id: "town", name: "Town", elevation_m: 50, travelCost: new Map() });
-addLocation(campaign, { id: "dungeon", name: "Dungeon", elevation_m: 20,
-  travelCost: new Map([["town", 1800]]) });  // 30 min from dungeon to town
-
-// Move an entity — advances worldTime_s by travel cost
-const travelTime = travel(campaign, fighter1.id, "dungeon");  // 1800
-
-// After an encounter, merge updated entity states back into the registry
-mergeEntityState(campaign, [fighter1, fighter2]);
-
-// Advance time with wound recovery (delegates to stepDowntime)
-const reports = stepCampaignTime(campaign, 3600, {
-  downtimeConfig: {
-    treatments: new Map([[fighter1.id, { careLevel: "first_aid" }]]),
-    rest: true,
-  },
-});
-
-// Campaign inventory (arrows, bandages, rations, etc.)
-creditInventory(campaign, fighter1.id, "arrow", 30);
-debitInventory(campaign, fighter1.id, "arrow", 5);   // returns false if insufficient
-getInventoryCount(campaign, fighter1.id, "arrow");   // 25
-
-// Persist across sessions (Map-aware JSON)
-const json = serialiseCampaign(campaign);
-const restored = deserialiseCampaign(json);
-```
-
-**`CampaignState` fields:**
-- `id`, `epoch` — campaign identity and ISO start timestamp
-- `worldTime_s` — absolute simulated seconds since epoch (monotonically increasing)
-- `entities: Map<number, Entity>` — master registry; deep-cloned on write
-- `locations: Map<string, Location>` — registered locations with travel routing
-- `entityLocations: Map<number, string>` — current locationId per entity
-- `entityInventories: Map<number, Map<string, number>>` — campaign item stockpiles (separate from `entity.loadout`)
-- `log: Array<{ worldTime_s, text }>` — timestamped event log
-
-**Healing integration:** `stepCampaignTime` builds a minimal `WorldState`, calls `stepDowntime`,
-then writes the healed `InjuryState` back into the entity registry. The optional
-`downtimeConfig` matches `stepDowntime`'s `DowntimeConfig` exactly; if omitted, all entities
-rest with `careLevel: "none"` (natural clotting only).
-
-**Serialisation:** `serialiseCampaign`/`deserialiseCampaign` handle all nested `Map` fields
-using the `__ananke_map__` marker pattern — entities, locations, entityLocations,
-entityInventories, entity skills, armourState, and location travelCost all survive round-trip.
-
----
-
-## Dialogue & Negotiation (Phase 23)
-
-`src/dialogue.ts` resolves non-combat social encounters. No Charisma stat — intimidation
-strength comes from `peakForce_N`, persuasion from cognitive depth, deception is beaten by
-sharp minds. Fully deterministic when given a seed.
-
-```typescript
-import {
-  resolveDialogue, applyDialogueOutcome, narrateDialogue, dialogueProbability,
-  type DialogueContext,
-} from "./src/dialogue.js";
-
-const ctx: DialogueContext = {
-  initiator:  knight,
-  target:     bandit,
-  worldSeed:  world.seed,
-  tick:       world.tick,
-};
-
-// Check probability before rolling
-const P = dialogueProbability({ kind: "intimidate", intensity_Q: q(0.80) }, ctx);
-// → q(0.72) for a 2800N knight vs. a mid-fear bandit
-
-// Roll the outcome
-const outcome = resolveDialogue({ kind: "intimidate", intensity_Q: q(0.80) }, ctx);
-// → { result: "success", fearDelta: q(0.15) }  or  { result: "failure", cooldown_s: 30 }
-// → { result: "escalate" }  if target.fearQ < q(0.20) and failed
-
-// Write deltas back to entities
-applyDialogueOutcome(outcome, bandit);
-
-// Natural language description
-const line = narrateDialogue(
-  { kind: "intimidate", intensity_Q: q(0.80) }, outcome,
-  { verbosity: "verbose", nameMap: new Map([[1, "Sir Roland"], [2, "the bandit"]]) },
-  { initiatorId: 1, targetId: 2 },
-);
-// → "Sir Roland attempted intimidation on the bandit — the target was cowed by the show of force."
-```
-
-### Action types
-
-| Action | Resolution | Escalates? |
-|--------|-----------|------------|
-| `intimidate` | `q(peakForce_N/4000) + fearQ − distressTolerance`; leader trait −q(0.15) | Yes, if fearQ < q(0.20) |
-| `persuade` | base q(0.40) + learningBonus(attentionDepth) + factionBonus − failurePenalty | No |
-| `deceive` | `plausibility_Q × (1 − attentionDepth/10)` | No |
-| `surrender` | Deterministic: accepted if `target.fearQ > q(0.40)` | No |
-| `negotiate` | Deterministic: accepted if trade utility is positive for target | No |
-
-**`dialogueProbability(action, ctx)`** — exported helper that returns the success probability
-without rolling RNG. Useful for UI previews, AI decision-making, and testing.
-
-**Verbosity levels** match the narrative layer: `terse` (label: result), `normal` (one sentence),
-`verbose` (entity names + full outcome description). Entity names resolved from `cfg.nameMap`.
-
----
-
-## Faction & Reputation (Phase 24)
-
-`src/faction.ts` tracks political standing, witnesses hostile events, and modulates AI
-behaviour based on inter-faction relationships. Fully deterministic — no RNG, standing
-changes are pure arithmetic.
-
-```typescript
-import {
-  createFactionState, adjustStanding, getStanding,
-  extractWitnessEvents, applyReputationDelta,
-  type FactionState,
-} from "./src/faction.js";
-```
-
-- **`adjustStanding(state, factionId, delta)`** — clamp standing to [−SCALE.Q, SCALE.Q]
-- **`getStanding(state, factionId)`** — 0 for unknown factions
-- **`extractWitnessEvents(world, env)`** — returns assault events seen by bystanders
-- **`applyReputationDelta`** — propagate witness events into faction standing
-
-AI target-selection uses `STANDING_HOSTILE_THRESHOLD = q(−0.40)` to activate attack
-mode; the `factionGuard` preset additionally suppresses attack below standing `q(0.60)`.
-
----
-
-## Loot & Economy (Phase 25)
-
-`src/economy.ts` provides item valuation, equipment wear, loot drop resolution, and
-trade evaluation. No kernel dependency — pure data management.
-
-```typescript
-import {
-  computeItemValue, armourConditionQ, applyWear,
-  resolveDrops, evaluateTradeOffer, totalInventoryValue,
-  type ItemInventory, type TradeOffer, type DropTable,
-} from "./src/economy.js";
-```
-
-- **`computeItemValue(item, wear_Q?)`** — derives `baseValue`, `condition_Q`, `sellFraction`
-  for any weapon, armour, or medical resource
-- **`applyWear(weapon, intensity_Q, seed?)`** — accumulates `WEAR_BASE = q(0.001)` per strike;
-  penalty at `q(0.30)`, fumble at `q(0.70)`, breaks at `q(1.0)`
-- **`resolveDrops(entity, seed, extra?, config?)`** — dead → all equipped items drop;
-  probabilistic extras rolled deterministically from seed
-- **`evaluateTradeOffer(offer, inventory)`** — `netValue` + `feasible` from accepting party's view
-
----
-
-## Momentum Transfer & Knockback (Phase 26)
-
-`src/sim/knockback.ts` adds the impulse-momentum half of Newtonian mechanics: every
-impact now imparts a velocity delta to the target. Calibrated to real physics — a
-5.56 mm rifle round produces negligible knockback (≈ 0.05 m/s on 75 kg), while a
-large-creature kick can knock humans prone.
-
-```typescript
-import {
-  computeKnockback, applyKnockback,
-  STAGGER_THRESHOLD_mps, PRONE_THRESHOLD_mps, STAGGER_TICKS,
-} from "./src/sim/knockback.js";
-
-const result = computeKnockback(energy_J, massEff_kg, target);
-// → { impulse_Ns, knockback_v, staggered, prone }
-
-applyKnockback(target, result, { dx, dy });
-// → mutates velocity_mps, condition.prone, action.staggerTicks
-```
-
-**Physics**: `impulse = sqrt(2 × E × m_eff)` [N·s]; `Δv = impulse / m_target` [m/s].
-Stability coefficient reduces effective knockback before threshold checks:
-`effective_v = Δv × (1 − stabilityQ)`.
-
-| Threshold | Value | Effect |
-|-----------|-------|--------|
-| `STAGGER_THRESHOLD_mps` | 0.5 m/s | 3-tick stagger window |
-| `PRONE_THRESHOLD_mps` | 2.0 m/s | `condition.prone = true` |
-
-The kernel integrates knockback automatically for every melee and ranged hit — no
-changes to call sites required.
-
----
-
-## Hydrostatic Shock & Cavitation (Phase 27)
-
-`src/sim/hydrostatic.ts` models the wound-amplification physics of high-velocity
-projectiles. Above 600 m/s a temporary stretch wave radiates outward through
-inelastic tissue; above 900 m/s momentary vacuum cavitation further boosts
-haemorrhage in fluid-saturated organs.
-
-```typescript
-import {
-  computeTemporaryCavityMul, computeCavitationBleed,
-  HYDROSTATIC_THRESHOLD_mps, CAVITATION_THRESHOLD_mps,
-} from "./src/sim/hydrostatic.js";
-
-// Multiplier applied to internalDamage (q(1.0) = no effect, q(3.0) = max)
-const cavMul = computeTemporaryCavityMul(v_impact_mps, "liver");  // → q(3.0) at 960 m/s
-
-// Cavitation bleed boost for fluid-saturated tissue (torso, liver, lung, spleen, legs)
-const newBleed = computeCavitationBleed(v_impact_mps, currentBleed, "torso");
-```
-
-**Tissue compliance** governs how much the stretch wave amplifies damage:
-
-| Region | Compliance | Behaviour |
-|--------|-----------|-----------|
-| bone / skull | q(0.05) | Brittle; maximum cavity damage |
-| brain / liver / spleen | q(0.10) | Very inelastic; high amplification |
-| lung | q(0.30) | Partially air-filled; intermediate |
-| torso | q(0.40) | Mixed; moderate amplification |
-| muscle / limbs | q(0.60) | Elastic; minimum amplification |
-
-The kernel computes `v_impact_mps` from pre-armour projectile energy and mass in
-`resolveShoot`, passes it through `ImpactEvent`, and applies both functions
-automatically in the finalImpacts loop — no changes to call sites required.
-
----
-
-## Cone AoE: Breath Weapons, Fire, Gas (Phase 28)
-
-`src/sim/cone.ts` adds directional cone geometry to the capability system, enabling
-breath weapons, flamethrowers, gas dispensers, and sonic disorientation blasts.
-
-```typescript
-import { entityInCone, buildEntityFacingCone } from "./src/sim/cone.js";
-import type { CapabilityEffect, CapabilitySource } from "./src/sim/capability.js";
-import { q, SCALE } from "./src/units.js";
-import { DamageChannel } from "./src/channels.js";
-
-// Dragon fire breath — 20 ticks sustained, 30° half-angle cone, 10m range
-const DRAGON_FIRE: CapabilityEffect = {
-  id:               "fire_breath",
-  cost_J:           800,           // deducted each sustained tick
-  castTime_ticks:   5,
-  sustainedTicks:   20,            // fires 20 consecutive ticks
-  coneHalfAngle_rad: Math.PI / 6,  // 30° half-angle = 60° total cone
-  coneDir:          "facing",      // follows entity's facingDirQ
-  range_m:          10 * SCALE.m,
-  payload: {
-    kind:     "weaponImpact",
-    energy_J:  800,
-    profile: {
-      surfaceFrac:     q(0.60),  // fire burns surface heavily
-      internalFrac:    q(0.30),  // convective heat reaches internal tissue
-      structuralFrac:  q(0.10),
-      bleedFactor:     q(0.05),
-      penetrationBias: q(0.05),
-    },
-  },
-};
-// Total reserve cost for one breath: 800J × 20 ticks = 16 000 J
-```
-
-**Cone direction modes**:
-- `coneDir: "facing"` — cone follows the actor's `facingDirQ` (updated by movement commands)
-- `coneDir: "fixed"` with `coneDirFixed: { dx, dy }` — fixed world-space direction (gas cloud, mounted turret)
-
-**Sustained emission** respects the same concentration-break rules as `castTime_ticks = -1`
-auras: shock ≥ q(0.30) cancels emission immediately. Each tick deducts `cost_J`; if the
-source reserve falls below `cost_J` the emission stops early.
-
-**`weaponImpact` payload** allows any damage profile without being constrained to a
-`DamageChannel`. Unlike `impact` (which maps to a synthetic weapon via `DamageChannel`),
-`weaponImpact` takes a `WeaponDamageProfile` directly — enabling fire's
-surface-heavy/internal-pass-through split or acid's structural bias.
-
----
-
-## Environmental Stress: Thermoregulation (Phase 29)
-
-`src/sim/thermoregulation.ts` models core body temperature as a continuous heat-balance
-system. Unlike abstract "cold resistance" stats, temperature is tracked in real °C (encoded
-as Q) and driven by genuine thermophysics.
-
-```typescript
-import { stepCoreTemp, deriveTempModifiers, cToQ, CORE_TEMP_NORMAL_Q } from "./src/sim/thermoregulation.js";
-import type { KernelContext } from "./src/sim/context.js";
-
-// Ambient temperature −10°C arctic environment
-const ctx: KernelContext = {
-  thermalAmbient_Q: cToQ(-10),  // cToQ converts Celsius to engine Q encoding
-  tractionCoeff: q(0.9),
-};
-
-// stepWorld automatically calls stepCoreTemp for every living entity each tick.
-// After simulation, query an entity's thermal state:
-const mods = deriveTempModifiers((entity.condition as any).coreTemp_Q ?? CORE_TEMP_NORMAL_Q);
-// → { powerMul: q(0.80), fineControlPen: q(0.15), latencyMul: q(1.2), dead: false }
-// → moderate hypothermia: −20% power, +20% reaction time
-```
-
-**Temperature stage thresholds** (Q encoding; `q(0.5)` = 37 °C; full range 10–64 °C):
-
-| Stage | Core temp | `powerMul` | `fineControlPen` | `latencyMul` |
-|-------|-----------|-----------|-----------------|-------------|
-| Critical hyperthermia | > 40.1 °C | q(0.60) | q(0.30) | q(3.0) — dead |
-| Heat stroke | 39.4–40.1 °C | q(0.60) | q(0.20) | q(2.0) |
-| Heat exhaustion | 38.6–39.4 °C | q(0.85) | q(0.10) | q(1.0) |
-| Mild hyperthermia | 37.8–38.6 °C | q(0.95) | q(0) | q(1.0) |
-| Normal | 37.0–37.8 °C | q(1.0) | q(0) | q(1.0) |
-| Mild hypothermia | 36.2–37.0 °C | q(0.95) | q(0.05) | q(1.0) |
-| Moderate hypothermia | 34.6–36.2 °C | q(0.80) | q(0.15) | q(1.2) |
-| Severe hypothermia | 33.0–34.6 °C | q(0.50) | q(0.20) | q(3.0) |
-| Critical hypothermia | < 33.0 °C | q(0.50) | q(0.30) | q(4.0) — dead |
-
-**Armour insulation** is modelled via `insulation_m2KW?: number` on `Armour` items.
-Higher insulation slows both heating and cooling. Typical values: plate armour 0.02, wool 0.15, fur 0.25.
-
-**Downtime integration**: `DowntimeConfig.thermalAmbient_Q` enables temperature tracking
-through multi-hour recovery simulations. `EntityRecoveryReport.finalCoreTemp_Q` reports the
-final state.
-
----
-
-## Nutrition & Starvation (Phase 30)
-
-`src/sim/nutrition.ts` adds the longest survivability axis: caloric balance from hours to
-weeks. Hunger states impose escalating combat penalties and eventually cause mass loss —
-fat catabolism first, then muscle tissue.
-
-```typescript
-import {
-  computeBMR, stepNutrition, consumeFood, deriveHungerModifiers,
-  FOOD_ITEMS, type HungerState,
-} from "./src/sim/nutrition.js";
-
-// BMR for a 75 kg entity: 80 W (Kleiber's law)
-const bmr = computeBMR(entity.attributes.morphology.mass_kg);  // → 80
-
-// stepWorld calls stepNutrition automatically at 1 Hz for every living entity.
-// Feed an entity from their food inventory:
-(entity as any).foodInventory = new Map([["ration_bar", 3], ["water_flask", 2]]);
-const ate = consumeFood(entity, "ration_bar", world.tick);  // → true; caloricBalance += 2 000 000 J
-
-// Query current state:
-const hunger: HungerState = (entity.condition as any).hungerState ?? "sated";
-const mods = deriveHungerModifiers(hunger);
-// → { staminaMul: q(1.0), forceMul: q(1.0), latencyMul: q(1.0), moraleDecay: q(0) }  // sated
-// → { staminaMul: q(0.50), forceMul: q(0.80), latencyMul: q(1.50), moraleDecay: q(0.030) }  // critical
-```
-
-**Hunger state thresholds** (deficit relative to BMR):
-
-| State | Onset | `staminaMul` | `forceMul` | `latencyMul` | `moraleDecay` |
-|-------|-------|-------------|-----------|-------------|--------------|
-| `sated` | deficit < 12 h × BMR | q(1.0) | q(1.0) | q(1.0) | q(0) |
-| `hungry` | 12–24 h × BMR | q(0.90) | q(1.0) | q(1.0) | q(0) |
-| `starving` | 24–72 h × BMR | q(0.75) | q(0.90) | q(1.0) | q(0.030)/tick |
-| `critical` | ≥ 72 h × BMR | q(0.50) | q(0.80) | q(1.50) | q(0.030)/tick |
-
-**Food catalogue** (`FOOD_ITEMS`):
-
-| Item | Energy | Mass | Hydration |
-|------|--------|------|-----------|
-| `ration_bar` | 2 000 000 J | 500 g | — |
-| `dried_meat` | 1 500 000 J | 300 g | — |
-| `hardtack` | 800 000 J | 200 g | — |
-| `fresh_bread` | 700 000 J | 250 g | — |
-| `berry_handful` | 150 000 J | 50 g | — |
-| `water_flask` | 0 J | 500 g | 500 000 hydJ |
-
-**Mass loss** (accumulated as float; applies only during starvation/critical):
-- Fat catabolism: 300 g/day (`mass_kg -= 300/86400 × delta_s`)
-- Muscle catabolism: 0.5 N/hour (`peakForce_N -= 0.5 × SCALE.N / 3600 × delta_s`, critical only)
-
-**Entity food inventory**: attach `(entity as any).foodInventory = new Map<string, number>()`
-before calling `consumeFood`. Absent inventory = unlimited supply.
-
----
-
-## Project layout
-
-```
-src/
-  units.ts          Fixed-point SI unit system and arithmetic helpers
-  types.ts          Core attribute interfaces (Morphology, Performance, Control, Resilience, Perception)
-  channels.ts       DamageChannel enum and bitmask helpers
-  traits.ts         Entity trait definitions and attribute multiplier application
-  archetypes.ts     Reference archetype baselines (HUMAN_BASE, SERVICE_ROBOT, AMATEUR_BOXER, PRO_BOXER, GRECO_WRESTLER, KNIGHT_INFANTRY, LARGE_PACIFIC_OCTOPUS)
-  equipment.ts      Weapon, Armour, Shield, RangedWeapon, Loadout types and starter item catalogue (includes wpn_boxing_gloves)
-  generate.ts       Procedural individual generation from archetype with variance distributions; NarrativeBias parameter (Phase 62)
-  polity.ts         Phase 61: Polity & World-State System — createPolity/Registry, trade, war, diplomacy, tech advancement, population-scale disease spread; integrates with Faction/Economy/Tech/Disease/Campaign
-  presets.ts        Entity factory functions for named real-world archetypes (mkBoxer, mkWrestler, mkKnight, mkOctopus, mkScubaDiver)
-  derive.ts         Movement caps and energy/fatigue derived from attributes and loadout
-  replay.ts         ReplayRecorder, replayTo, serializeReplay/deserializeReplay — deterministic replay
-  metrics.ts        CollectingTrace, collectMetrics, survivalRate, meanTimeToIncapacitation — analytics
-  debug.ts          extractMotionVectors, extractHitTraces, extractConditionSamples — visual debug layer
-  model3d.ts        deriveMassDistribution, deriveInertiaTensor, deriveAnimationHints, derivePoseModifiers, deriveGrappleConstraint, extractRigSnapshots — 3D rig integration
-  describe.ts       describeCharacter, formatCharacterSheet, formatOneLine — SI→human-readable translation layer (no sim dependencies)
-  weapons.ts        Historical weapons database — ~70 weapons across 6 eras (Prehistoric → Contemporary); shieldBypassQ for flexible weapons; magCapacity + shotInterval_s for magazine firearms
-  narrative.ts      narrateEvent, buildCombatLog, describeInjuries, describeCombatOutcome — combat narrative layer (no sim dependencies)
-  downtime.ts       stepDowntime(), MEDICAL_RESOURCES — 1 Hz wound recovery bridge (hours-to-weeks scale)
-  arena.ts          runArena(), expectWinRate/SurvivalRate/MeanDuration/Recovery/ResourceCost, formatArenaReport, 6 calibration scenarios
-  progression.ts    createProgressionState(), awardXP(), advanceSkill(), applyTrainingSession(), stepAgeing(), applyAgeingDelta(), deriveSequelae()
-  campaign.ts       createCampaign(), addLocation(), travel(), mergeEntityState(), stepCampaignTime(), debitInventory/creditInventory/getInventoryCount(), serialiseCampaign/deserialiseCampaign()
-  dialogue.ts       resolveDialogue(), applyDialogueOutcome(), narrateDialogue(), dialogueProbability() — social encounter resolution (intimidate/persuade/deceive/surrender/negotiate)
-  faction.ts        createFactionState(), adjustStanding(), extractWitnessEvents(), applyReputationDelta() — faction tracking and reputation system
-  economy.ts        computeItemValue(), applyWear(), resolveDrops(), evaluateTradeOffer() — item valuation, wear, loot drops, trade evaluation
-  narrative-stress.ts  runNarrativeStressTest(), formatStressTestReport(), beatEntityDefeated/Survives/TeamDefeated/ShockExceeds/Fatigued() — narrative push analyser (Phase 63)
-
-  sim/
-    kernel.ts           stepWorld(), applyFallDamage(), applyExplosion() — main simulation entry points
-    entity.ts           Entity type (all mutable simulation state)
-    world.ts            WorldState type
-    kinds.ts            CommandKind, TraceKind, MoveMode, DefenceMode enums (includes MoraleRally)
-    body.ts             BodyRegion type, region weights, hit-to-region mapping
-    injury.ts           InjuryState, per-region damage, bleeding rate helpers
-    medical.ts          MedicalTier, MedicalAction, tier rank/multiplier tables
-    condition.ts        ConditionState (fire, radiation, suffocation, stun, prone, etc.)
-    impairment.ts       deriveFunctionalState() — damage to mobility and manipulation penalties
-    combat.ts           resolveHit(), parryLeverageQ(), shield helpers
-    grapple.ts          Grapple resolution: score, positions, throw/choke/joint-lock
-    weapon_dynamics.ts  Reach dominance, two-handed bonus, miss recovery, weapon bind/break
-    ranged.ts           Ranged physics: energy at range, dispersion, grouping radius, costs
-    explosion.ts        BlastSpec, blastEnergyFracQ, fragmentsExpected, fragmentKineticEnergy
-    substance.ts        Substance, ActiveSubstance, STARTER_SUBSTANCES — pharmacokinetics model
-    tech.ts             TechEra, TechCapability, TechContext, defaultTechContext, isCapabilityAvailable
-    capability.ts       CapabilitySource, CapabilityEffect, RegenModel, EffectPayload, FieldEffect — Clarke's Third Law abstraction
-    knockback.ts        computeKnockback(), applyKnockback() — impulse-momentum transfer; stagger/prone checks
-    hydrostatic.ts      computeTemporaryCavityMul(), computeCavitationBleed() — high-velocity wound physics
-    cone.ts             entityInCone(), buildEntityFacingCone(), ConeSpec — directional cone AoE geometry (breath weapons, flamethrowers, gas)
-    thermoregulation.ts stepCoreTemp(), deriveTempModifiers(), cToQ() — 9-stage core-temp model (mild hyperthermia → cardiac-arrest hypothermia)
-    nutrition.ts        computeBMR(), stepNutrition(), consumeFood(), deriveHungerModifiers(), FOOD_ITEMS — caloric balance, hunger states, fat/muscle catabolism
-    events.ts           ImpactEvent type, deterministic sort
-    seeds.ts            Deterministic per-event seed derivation
-    formation.ts        pickNearestEnemyInReach()
-    frontage.ts         applyFrontageCap() — limits engagers per target
-    occlusion.ts        isMeleeLaneOccludedByFriendly()
-    density.ts          computeDensityField() — crowd slowdown
-    push.ts             stepPushAndRepulsion() — entity separation
-    spatial.ts          Grid spatial index and neighbour queries
-    indexing.ts         buildWorldIndex() — O(1) id-to-entity lookup
-    vec3.ts             Fixed-point 3D vector maths
-    team.ts             isEnemy() helper
-    intent.ts           IntentState defaults
-    action.ts           ActionState defaults
-    trace.ts            TraceSink interface and nullTrace
-    tuning.ts           SimulationTuning presets (arcade, tactical, sim)
-    testing.ts          mkHumanoidEntity(), mkWorld() test helpers
-
-    bodyplan.ts         BodyPlan, BodySegment, 8 body plan constants, resolveHitSegment, getExposureWeight
-    sensory.ts          canDetect(), SensoryEnvironment — vision arc + hearing + env modifiers
-    skills.ts           SkillId, SkillLevel, SkillMap, buildSkillMap, getSkill, combineSkillLevels
-
-    ai/
-      types.ts      AIPolicy interface
-      presets.ts    AI_PRESETS (lineInfantry, skirmisher)
-      perception.ts perceiveLocal() — sensory-filtered enemy and ally detection
-      targeting.ts  pickTarget(), updateFocus() — horizon-limited target selection
-      decide.ts     decideCommandsForEntity() — with decision latency cooldown
-      system.ts     buildAICommands() — full AI pass over world
-
-    formation-unit.ts   computeShieldWallCoverage, deriveRankSplit, stepFormationCasualtyFill, computeFormationMomentum, deriveFormationCohesion, deriveFormationAllyFearDecay — Phase 6 formation system
-
-test/              Vitest test suite (one file per feature area)
-tools/             Developer utilities and runnable demos
-  blade-runner.ts         Artificial Life Validation — 365-day city-scale emergent-behaviour test
-  emergent-validation.ts  Emergent Behaviour Validation Suite — 4 historical combat scenarios × 100 seeds
-  benchmark.ts            Performance & Scalability Benchmarks — 10/100/500/1 000 entity throughput
-  what-if.ts              "What If?" Alternate History Engine — polity divergence × 100 seeds (Phase 64)
-  generate-zoo.ts         Simulation Zoo generator — 5 pre-computed scenarios embedded in docs/zoo/index.html
-  generate-map.ts         Generative Cartography — 180-day polity simulation → docs/map/index.html SVG viewer
-  world-server.ts         Persistent World Server — HTTP server with live polling client at docs/world-client/
-docs/
-  onboarding.md         New-engineer two-week onboarding guide
-  contributing.md       Contribution guide: conventions, PR checklist, module skeleton
-  versioning.md         Versioning contract: commit-hash pinning, breaking-change tiers, upgrade cadence
-  ecosystem.md          Ecosystem index: body-plan templates, renderer bridge boilerplate, companion repo suggestions
-  integration-primer.md Deep technical onboarding (architecture, data-flow, gotchas)
-  bridge-api.md         Renderer bridge API reference
-  use-case-validation.md Integration Milestone 1 — use-case fit validation
-  narrative-stress-test.md Narrative Stress Test guide: API, Deus Ex score, cinematic benchmark table
-  editors/
-    index.html          Editor hub — links to all visual design tools
-    species-forge.html  Species Forge — body plan + archetype + narrative bias editor
-    culture-forge.html  Culture Forge — cultural values, taboos, myth predispositions, diplomacy modifiers editor
-  zoo/
-    index.html          Simulation Zoo — 5 pre-computed combat/disease scenarios with health visualiser
-  map/
-    index.html          Generative Cartography — 180-day polity map with timeline slider
-  world-client/
-    index.html          Persistent World Client — live-polling browser UI for world-server.ts
-  companion-projects/
-    ananke-godot-reference/README.md    Godot 4 physics-driven character plugin starter
-    ananke-unity-reference/README.md    Unity 6 physics-driven character plugin starter
-    ananke-threejs-bridge/README.md     In-browser Three.js renderer bridge starter
-    ananke-language-forge/README.md     LLM-backed dynamic dialogue generation starter
-    ananke-world-ui/README.md           SvelteKit world management UI starter
-    ananke-fantasy-species/README.md    Fantasy / sci-fi species pack starter
-    ananke-historical-battles/README.md Historical battle validation suite starter
-    ananke-archive/README.md           Searchable public simulation database starter
-```
-
----
-
-## Companion ecosystem
-
-Seven companion projects are designed to build on top of Ananke.  Each has a starter README
-in `docs/companion-projects/` describing the architecture, key Ananke entry points, and a
-suggested first milestone.
-
-| Repository | Purpose |
-|---|---|
-| `ananke-godot-reference` | Godot 4 plugin driving a humanoid rig from `extractRigSnapshots` over WebSocket |
-| `ananke-unity-reference` | Unity 6 plugin using the HTTP polling sidecar; HumanBodyBones mapping |
-| `ananke-threejs-bridge` | In-browser Three.js renderer — no sidecar, WebAssembly kernel long-term target |
-| `ananke-language-forge` | LLM-backed dynamic dialogue generation reading `linguisticIntelligence_Q` and Phase 66 myth events |
-| `ananke-world-ui` | SvelteKit world management UI — supersedes `docs/editors/` when feature-complete |
-| `ananke-fantasy-species` | Fantasy / sci-fi species pack with allometric-scaled body plans and archetype templates |
-| `ananke-historical-battles` | Historical battle validation suite comparing outcomes against primary sources |
-| `ananke-archive` | Searchable public database of simulation runs, parameter spaces, and raw trace data |
-
-### Companion ecosystem infrastructure (ROADMAP CE-1 to CE-4)
-
-The following Ananke-side changes are the highest-leverage items for enabling companion projects:
-
-**CE-1 — npm publish + subpath exports map.**  Remove `"private": true` from `package.json`,
-add a `"exports"` map so consumers can import `ananke/units`, `ananke/sim/kernel`, etc.
-without bundling the whole library.  See ROADMAP for proposed exports JSON.
-
-**CE-2 — `createWorld()` convenience factory.**  A single call that builds a `World` with
-sensible defaults (5 humans, no terrain, tactical tuning).  Eliminates 20 lines of setup
-boilerplate for companion projects that need a quick simulation harness.
-
-**CE-3 — JSON scenario schema + `loadScenario()`.**  Lets companion projects (especially
-`ananke-historical-battles` and `ananke-fantasy-species`) ship scenario definitions as JSON
-files rather than TypeScript, reducing the barrier to non-developer contribution.
-
-**CE-4 — `src/index.ts` stable-API barrel.**  A single import surface (`import { ... } from "ananke"`)
-covering everything in `STABLE_API.md`.  Companion projects should depend on this barrel, not
-on internal module paths that may change.
-
----
-
-## Performance baselines
-
-Performance is a published contract, not just a tool that exists.
-
-| Scenario | Entities | Median tick | Throughput | 20 Hz budget |
-|----------|----------|-------------|------------|--------------|
-| Melee skirmish | 10 | 0.19 ms | 5 300 ticks/s | 4% |
-| Mixed ranged/melee | 100 | 4.68 ms | 214 ticks/s | 9% |
-| Formation combat | 500 | 31 ms | 32 ticks/s | 62% |
-| Weather + disease | 1 000 | 64 ms | 16 ticks/s | 129% (exceeds real-time) |
-
-Measured on Node 22, Apple M-series reference hardware.  Full methodology, AI-budget
-breakdown, spatial-index comparison, memory footprint, and tuning guidance are in
-`docs/performance.md`.  Run with `npm run run:benchmark`.
-
-**Key constraint:** at 20 Hz real-time rate, 500 entities fits comfortably within budget;
-1 000 entities requires a tick-rate reduction or spatial partitioning.  `stepWorld` (kernel
-physics) consumes ≥ 95% of tick budget at all entity counts; AI is negligible (< 1%).
-
-Benchmark regression is enforced in CI via `npm run benchmark-check` — throughput regressions
-are caught before release (ROADMAP item 15, complete).
-
----
-
-## Validation
-
-Ananke's validation strategy has two layers:
-
-**Isolated subsystem validation** — 19+ subsystems (sprint speed, bleeding rate, sleep
-deprivation, thermoregulation, etc.) tested individually against empirical datasets with
-±20 % tolerance on the simulated mean.  Run with `npm run run:validation`.
-
-**Emergent behaviour validation** — Four historical combat scenarios (English longbowmen at
-Agincourt, Roman testudo vs. Gaul charge, small-unit skirmish attrition, epidemic spread)
-each run across 100 seeds.  The distribution of outcomes is compared against historical
-casualty data.  Run with `npm run run:emergent-validation`.
-
-Results from both suites are committed to `docs/` and linked from releases.  See ROADMAP
-item PH-8 for the plan to make these first-class trust artifacts.
-
----
-
-## Next steps — Platform Hardening
-
-The simulation is architecturally complete.  The highest-leverage remaining work is making
-the existing depth trustworthy and legible to adopters:
-
-| Item | What | Status |
-|------|------|--------|
-| PH-1 | API tiering — Stable / Advanced / Internal tiers in exports and docs | Planned |
-| PH-2 | Versioning policy unification — one unambiguous adopter contract | Planned |
-| PH-3 | Minimal host integration contract document | Planned |
-| PH-4 | Save / replay / bridge contract tests — golden compatibility fixtures | Planned |
-| PH-5 | Bridge as first-class supported surface — `docs/bridge-contract.md` | Planned |
-| PH-6 | Entity / WorldState core vs. extensions split — JSDoc annotations | Planned |
-| PH-7 | Benchmark operational guide — tick-rate and entity-cap recommendations | Planned |
-| PH-8 | Emergent validation as flagship trust artifact — versioned, CI-enforced | Planned |
-
-See ROADMAP `## Platform Hardening` for full scope of each item.
+# Ananke — Programmer's Guide
+
+![CI](../../actions/workflows/ci.yml/badge.svg)
+
+> **Package:** `@its-not-rocket-science/ananke`
+> **Full project overview:** [`docs/project-overview.md`](docs/project-overview.md)
+
+---
+
+## What is Ananke?
+
+Ananke is a **deterministic, physics-grounded simulation engine** for characters, combat,
+and survivability.  It models entities using real physical quantities — mass in kg, force
+in newtons, energy in joules — rather than abstract hit points or dice rolls.
+
+Same seed + same inputs → identical results, every time.  No floating-point drift.
+Suitable for lockstep multiplayer, reproducible research, and offline AI training.
+
+---
+
+## Installation
+
+```bash
+npm install @its-not-rocket-science/ananke
+```
+
+Requires Node ≥ 18.  ESM-only.  TypeScript declarations included — no `@types/` package
+needed.  Zero runtime dependencies.
+
+> **Versioning:** pin to a specific version in production.  The `0.x` series may include
+> minor-version breaking changes to Tier 2 (experimental) APIs; Tier 1 (Stable) APIs follow
+> full semver.  See [`STABLE_API.md`](STABLE_API.md) for the tier breakdown and
+> [`docs/versioning.md`](docs/versioning.md) for the upgrade policy.
+
+---
+
+## Core concepts
+
+### Fixed-point arithmetic
+
+All simulation values use `Q` — a fixed-point integer where `SCALE.Q = 16384` represents
+`1.0`.  Never use raw `number` for simulation values; always use `q()` to construct them.
+
+```typescript
+import { q, SCALE } from "@its-not-rocket-science/ananke";
+
+const half   = q(0.50);   // 8192  — 50%
+const full   = q(1.00);   // 16384 — 100%
+const eighty = q(0.80);   // 13107 — 80%
+
+// SI unit scales
+SCALE.m;    // 1000  — 1 metre in fixed-point units
+SCALE.kg;   // 1000  — 1 kilogram
+SCALE.mps;  // 1000  — 1 m/s
+SCALE.J;    // 1     — 1 joule (energy is stored at 1:1)
+```
+
+You will see values like `position_m: { x: 3000, y: 0, z: 0 }` — that is 3 metres on the
+x-axis (`3000 / SCALE.m = 3`).  The `_m`, `_kg`, `_J`, `_s` suffixes on field names tell
+you the unit.
+
+### The Entity
+
+An `Entity` is any simulated object.  Required fields at creation:
+
+```typescript
+import type { Entity } from "@its-not-rocket-science/ananke";
+```
+
+| Field | Type | Meaning |
+|---|---|---|
+| `id` | `number` | Unique integer; used as RNG salt |
+| `teamId` | `number` | Entities attack those on different teams |
+| `position_m` | `Vec3` | World-space position in fixed-point metres |
+| `attributes` | `IndividualAttributes` | Physical stats (force, power, mass…) |
+| `energy` | `{ current_J, max_J }` | Stamina pool in joules |
+| `injury` | `InjuryState` | Per-region damage accumulation |
+| `condition` | `ConditionSnapshot` | Shock, fear, fatigue |
+| `loadout` | `{ items: Item[] }` | Equipped weapons and armour |
+
+Use a factory instead of constructing these manually — see **Quick starts** below.
+
+### The simulation loop
+
+```typescript
+import { mkWorld, stepWorld } from "@its-not-rocket-science/ananke";
+
+const world = mkWorld(seed, entities);     // create world with deterministic seed
+
+for (let tick = 0; tick < 2000; tick++) {
+  const commands = buildCommands(world);   // your AI / player input
+  stepWorld(world, commands, ctx);         // mutates world in-place
+}
+```
+
+`stepWorld` is the only function that mutates state.  Everything else is pure computation.
+Call it at 20 Hz for real-time simulation; 1 Hz or lower for campaign-scale time.
+
+---
+
+## Quick start A — Melee combat
+
+Two fighters, one fight, three seeds:
+
+```typescript
+import {
+  mkWorld, stepWorld, generateIndividual, q,
+  SCALE, STARTER_WEAPONS, STARTER_ARMOUR,
+  buildAICommands, buildWorldIndex, buildSpatialIndex,
+  AI_PRESETS,
+} from "@its-not-rocket-science/ananke";
+import type { Q } from "@its-not-rocket-science/ananke";
+
+const LONGSWORD = STARTER_WEAPONS[2]!;
+const LEATHER   = STARTER_ARMOUR[0]!;
+
+function makeEntity(id: number, teamId: number, x_m: number) {
+  const e = generateIndividual("KNIGHT_INFANTRY", id, teamId);
+  e.position_m = { x: x_m * SCALE.m, y: 0, z: 0 };
+  e.loadout    = { items: [LONGSWORD, LEATHER] };
+  return e;
+}
+
+const policy = AI_PRESETS["lineInfantry"]!;
+
+for (const seed of [1, 42, 99]) {
+  const a = makeEntity(1, 1, -2);
+  const b = makeEntity(2, 2, +2);
+  const world = mkWorld(seed, [a, b]);
+  const ctx   = { tractionCoeff: q(0.85) as Q };
+
+  let tick = 0;
+  while (tick < 2000 && !a.injury.dead && !b.injury.dead) {
+    tick++;
+    const idx  = buildWorldIndex(world);
+    const spat = buildSpatialIndex(world, 40_000);
+    const cmds = buildAICommands(world, idx, spat, () => policy);
+    stepWorld(world, cmds, ctx);
+  }
+
+  const winner = a.injury.dead ? "B" : b.injury.dead ? "A" : "draw";
+  console.log(`seed=${seed}  winner=${winner}  ticks=${tick}`);
+}
+```
+
+### Reading injury state
+
+```typescript
+for (const [region, inj] of Object.entries(entity.injury.regions)) {
+  const pct = (inj.surfaceDamage / SCALE.Q * 100).toFixed(0);
+  if (inj.surfaceDamage > 0)
+    console.log(`  ${region}: ${pct}% surface damage${inj.infected ? " [infected]" : ""}`);
+}
+console.log(`  dead:  ${entity.injury.dead}`);
+console.log(`  shock: ${(entity.condition.shockQ / SCALE.Q * 100).toFixed(0)}%`);
+```
+
+### Using the narrative layer
+
+```typescript
+import {
+  CollectingTrace, renderChronicle,
+} from "@its-not-rocket-science/ananke";
+
+const trace = new CollectingTrace();
+stepWorld(world, commands, { ...ctx, trace });
+
+const log = renderChronicle(trace.events, world.entities, { verbosity: "normal" });
+console.log(log);
+// → "Knight strikes Brawler in the torso for 340 J. Brawler staggers."
+```
+
+---
+
+## Quick start B — Campaign and world simulation
+
+Advance two polities through 90 days with tech diffusion and emotional contagion:
+
+```typescript
+import {
+  createPolityRegistry, stepPolityDay,
+  applyEmotionalContagion, stepTechDiffusion,
+  createEmotionalWave, FEAR_WAVE, q, SCALE,
+} from "@its-not-rocket-science/ananke";
+
+const WORLD_SEED = 1;
+
+const registry = createPolityRegistry([
+  { id: 1, name: "Ironhold", population: 50_000, techEra: 2, moraleQ: q(0.70) /* ... */ },
+  { id: 2, name: "Ashfeld",  population: 30_000, techEra: 1, moraleQ: q(0.55) /* ... */ },
+]);
+
+const pairs = [{ polityA: 1, polityB: 2, routeQuality_Q: q(0.60), atWar: false /* ... */ }];
+
+for (let day = 1; day <= 90; day++) {
+  stepPolityDay(registry, WORLD_SEED, day);
+  stepTechDiffusion(registry, pairs, WORLD_SEED, day);
+  applyEmotionalContagion(registry, [createEmotionalWave(FEAR_WAVE, 1)], pairs);
+}
+
+for (const p of registry.polities) {
+  console.log(`${p.name}: pop=${p.population}  era=${p.techEra}  morale=${(p.moraleQ / SCALE.Q).toFixed(2)}`);
+}
+```
+
+---
+
+## Quick start C — Species and character generation
+
+Generate individuals from a body-plan archetype, apply aging, and describe them:
+
+```typescript
+import {
+  generateIndividual, applyAgingToAttributes,
+  describeCharacter, formatCharacterSheet,
+} from "@its-not-rocket-science/ananke";
+
+// Generate a 45-year-old knight
+const base = generateIndividual("KNIGHT_INFANTRY", 1, 1);
+const aged = applyAgingToAttributes(base.attributes, 45);
+
+console.log(formatCharacterSheet({ ...base, attributes: aged }));
+// → Strength: 1840 N  [above average]
+//   Reaction: 0.21 s  [average]
+//   ...
+
+// Fantasy species
+const elf = generateIndividual("ELF_ARCHER", 2, 2);
+console.log(describeCharacter(elf));
+```
+
+Available built-in archetypes: `KNIGHT_INFANTRY`, `PRO_BOXER`, `GRECO_WRESTLER`,
+`AMATEUR_BOXER`, `LARGE_PACIFIC_OCTOPUS`, and all species defined in
+[`src/species.ts`](src/species.ts) — humans, elves, dwarves, orcs, dragons,
+Vulcans, Klingons, and more.
+
+---
+
+## The command system
+
+`stepWorld` takes a `CommandMap` — a `Map<entityId, EntityCommand>`.  You build it
+manually, from your AI layer, or from the built-in AI system:
+
+```typescript
+import type { EntityCommand } from "@its-not-rocket-science/ananke";
+
+// Attack
+const commands = new Map<number, EntityCommand>([
+  [entityId, { kind: "attack", targetId: opponentId, weapon: LONGSWORD }],
+]);
+
+// Move to a position
+commands.set(entityId, {
+  kind:        "move",
+  destination: { x: 5 * SCALE.m, y: 0, z: 0 },
+});
+
+// Treat a wounded ally
+commands.set(medicId, {
+  kind:     "treat",
+  targetId: woundedId,
+  schedule: { care: "field_surgery", equipmentTier: 2 },
+});
+```
+
+Valid `kind` values: `"attack"`, `"move"`, `"grapple"`, `"treat"`, `"use_capability"`,
+`"signal"`, `"idle"`.
+
+---
+
+## Determinism
+
+Ananke guarantees that `mkWorld(seed, entities)` followed by identical commands produces
+identical `WorldState` at every tick, regardless of platform, JS engine, or execution time.
+
+**Rules to preserve determinism in your host:**
+
+1. Never use `Math.random()` — use `makeRng(eventSeed(...))` from the package instead
+2. Iterate `world.entities` in insertion order (it is a stable array, not a Map)
+3. Keep entity `id` values stable across ticks — IDs are used as RNG salts
+4. Do not rely on wall-clock time inside the simulation loop
+
+```typescript
+import { makeRng, eventSeed } from "@its-not-rocket-science/ananke";
+
+// Deterministic RNG inside your AI or event code:
+const rng  = makeRng(eventSeed(world.seed, world.tick, entityId, 0, 42));
+const roll = rng();  // float in [0, 1) — deterministic from inputs
+```
+
+---
+
+## Replay and serialisation
+
+```typescript
+import {
+  ReplayRecorder, serializeReplay, deserializeReplay, replayTo,
+} from "@its-not-rocket-science/ananke";
+
+// Record
+const recorder = new ReplayRecorder();
+for (let tick = 0; tick < N; tick++) {
+  const cmds = buildCommands(world);
+  recorder.record(tick, cmds);
+  stepWorld(world, cmds, ctx);
+}
+const json = serializeReplay(recorder.replay);  // stable JSON string
+
+// Replay to any tick
+const replay = deserializeReplay(json);
+const state  = replayTo(replay, initialWorld, targetTick, ctx);
+```
+
+---
+
+## 3D renderer bridge
+
+Extract per-segment pose data for driving a humanoid rig at renderer frame rate:
+
+```typescript
+import {
+  extractRigSnapshots, deriveAnimationHints, BridgeEngine,
+} from "@its-not-rocket-science/ananke";
+
+// Per-tick: get bone transforms
+const snapshots = extractRigSnapshots(world.entities, bodyPlan);
+// snapshots[entityId] → RigSnapshot { segments: Map<segmentId, { position_m, rotation }> }
+
+// Per-tick: get animation state machine hints
+const hints = deriveAnimationHints(entity);
+// hints → { idle, walk, run, attacking, prone, unconscious, dead, shockQ, fearQ, ... }
+
+// Or use BridgeEngine for double-buffered interpolation at renderer frame rate:
+const bridge = new BridgeEngine(config);
+bridge.writeSimFrame(world.tick, world.entities);
+const interp = bridge.readInterpolated(rendererTimestamp);
+```
+
+See [`docs/bridge-contract.md`](docs/bridge-contract.md) for the full double-buffer
+protocol and `AnimationHints` field-by-field contract.
+
+---
+
+## API stability tiers
+
+| Tier | Guarantee | Examples |
+|------|-----------|---------|
+| **Tier 1 — Stable** | Breaking changes require major semver bump + migration guide | `stepWorld`, `generateIndividual`, `Entity`, `q`, `SCALE`, bridge module |
+| **Tier 2 — Experimental** | May change in minor versions; CHANGELOG will note it | Campaign, polity, dialogue, faction, quest subsystems |
+| **Tier 3 — Internal** | No stability guarantee; may change at any time | `makeRng`, `eventSeed`, kernel tuning constants, `mkHumanoidEntity` |
+
+Full tier table: [`STABLE_API.md`](STABLE_API.md)
+
+---
+
+## TypeScript
+
+The package ships full `.d.ts` declarations.  Key types to know:
+
+```typescript
+import type {
+  Entity,               // the simulated object
+  WorldState,           // world.entities + world.tick + world.seed
+  KernelContext,        // tractionCoeff, weather, etc. — passed to stepWorld
+  EntityCommand,        // what an entity does this tick
+  IndividualAttributes, // physical stats (SI units)
+  InjuryState,          // per-region damage
+  ConditionSnapshot,    // shock, fear, fatigue
+  Q,                    // fixed-point number alias (just `number` at runtime)
+  Vec3,                 // { x, y, z } in fixed-point metres
+} from "@its-not-rocket-science/ananke";
+```
+
+`Q` is a nominal alias for `number` — it carries no runtime overhead, but the `q()`
+constructor and `SCALE` constants make the intent clear in every formula.
+
+---
+
+## Performance guidance
+
+| Scenario | Recommended tick rate | Practical entity cap |
+|---|---|---|
+| Duel / 1v1 | 20 Hz | Unlimited |
+| Skirmish (squads) | 20 Hz | ~300 |
+| Battle (formations) | 10 Hz | ~500 |
+| Siege / campaign | 1 Hz | ~1 000 |
+| World simulation | 0.01 Hz (once/day) | ~10 000 |
+
+Enable `buildSpatialIndex` when entities exceed ~50 and distances matter.  Disable
+expensive subsystems (disease O(n²) spread, thermoregulation) at high entity counts
+unless required.
+
+Full benchmark methodology and operational guide: [`docs/performance.md`](docs/performance.md)
+
+---
+
+## Validation and trust
+
+Ananke's outputs are validated against historical and experimental sources:
+
+- **Isolated sub-system validation** — compares physical constants against sport-science
+  and biomechanics datasets: `npm run run:validation`
+- **Emergent validation** — four historical combat scenarios (du Picq, Keegan, Lanchester,
+  Raudzens) across 100 seeds each: `npm run run:emergent-validation`
+- **Pinned baseline** — committed result summaries that CI guards against regression:
+  [`docs/emergent-validation-report.md`](docs/emergent-validation-report.md)
+
+---
+
+## Further reading
+
+| Document | What's in it |
+|---|---|
+| [`docs/host-contract.md`](docs/host-contract.md) | Stable integration surface — everything needed to embed Ananke without reading `src/` |
+| [`docs/integration-primer.md`](docs/integration-primer.md) | Data-flow diagrams, type glossary, gotchas |
+| [`docs/bridge-contract.md`](docs/bridge-contract.md) | 3D renderer bridge protocol (AnimationHints, GrapplePoseConstraint) |
+| [`STABLE_API.md`](STABLE_API.md) | Full tier table for every export |
+| [`docs/versioning.md`](docs/versioning.md) | Semver policy, breaking-change tiers, upgrade cadence |
+| [`docs/performance.md`](docs/performance.md) | Benchmark results, operational guide, entity caps |
+| [`docs/emergent-validation-report.md`](docs/emergent-validation-report.md) | Historical scenario validation report |
+| [`docs/project-overview.md`](docs/project-overview.md) | Full project overview — implementation status, entity model reference, design principles, architecture |