@its-not-rocket-science/ananke 0.1.0

package/STABLE_API.md

@@ -0,0 +1,266 @@
+# Ananke — Stable API Reference
+
+This document defines the three stability tiers for Ananke's public API surface.
+See [`docs/versioning.md`](docs/versioning.md) for the full versioning policy, upgrade
+cadence, and commit-hash pinning guide.
+
+---
+
+## Versioning policy (summary)
+
+Ananke uses **semantic versioning (semver)** as its public contract.  Tier 1 exports
+will not break without a major version bump and migration guide.  See
+[`docs/versioning.md`](docs/versioning.md) for the complete policy.
+
+Every export in `src/index.ts` is annotated with its tier via inline comments.
+The tables below list key symbols by tier.
+
+---
+
+## Tier 1 — Stable host API
+
+These exports are safe to depend on.  They will not change in a breaking way without a major
+version bump and a migration guide in `CHANGELOG.md`.
+
+### Fixed-point arithmetic (`src/units.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `type Q` | Dimensionless fixed-point scalar; `SCALE.Q == 1.0` |
+| `type I32` | int32-safe number |
+| `SCALE` | Unit scale constants: `SCALE.Q`, `SCALE.kg`, `SCALE.m`, `SCALE.mps`, `SCALE.J`, `SCALE.N`, `SCALE.W`, `SCALE.s` |
+| `q(x)` | Convert a float to fixed-point Q |
+| `qMul(a, b)` | Fixed-point multiply |
+| `qDiv(a, b)` | Fixed-point divide |
+| `clampQ(x, lo, hi)` | Clamp a Q value |
+| `mulDiv(a, b, div)` | Integer multiply-then-divide with overflow safety |
+| `to` | Conversion helpers: `to.kg(x)`, `to.m(x)`, `to.mps(x)`, `to.J(x)`, `to.N(x)`, `to.W(x)`, `to.s(x)` |
+| `from` | Reverse converters: `from.kg(x)`, etc. |
+| `sqrtQ(x)` | Fixed-point square root |
+
+### Core simulation (`src/sim/kernel.ts`, `src/sim/world.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `stepWorld(world, cmds, ctx)` | Advance the world by one tick |
+| `applyImpactToInjury(world, aId, bId, energy_J, channel)` | Apply kinetic impact |
+| `applyFallDamage(entity, height_m)` | Apply fall damage to an entity |
+| `applyExplosion(world, x, y, energy_J, radius_m, ctx)` | Blast AoE |
+| `applyPayload(world, targetId, payload, ctx)` | Apply a capability payload |
+| `applyCapabilityEffect(world, actorId, targetId, effect, ctx)` | Apply a capability effect |
+| `WorldState` | World container type (`entities`, `spatialIndex`, `clock`) |
+| `KernelContext` | Tick context (`worldSeed`, `techCtx`, `weather`) |
+| `CommandMap` | Map of entity ID → command |
+
+### Entity and attributes (`src/sim/entity.ts`, `src/types.ts`, `src/archetypes.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `Entity` | Core entity shape.  **Stable fields:** `id`, `pos`, `mass_kg`, `attributes`, `injuries`, `fatigue`, `fluid`, `consciousness`, `shock`, `fear`, `team`, `dead`.  Optional extension fields (mount, age, sleep, etc.) may gain new members in minor versions |
+| `IndividualAttributes` | Physical attribute block (`peakForce_N`, `peakPower_W`, `continuousPower_W`, `reserveEnergy_J`, `reactionTime_s`, `controlQuality`, `stability`, `fineControl`, `stature_m`, `mass_kg`, …) |
+| `Archetype` | Archetype baseline with variance fields |
+| `BodyPlan` | Species body plan descriptor |
+| `NarrativeBias` | Story-shaping bias for `generateIndividual` |
+
+### Entity generation (`src/generate.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `generateIndividual(seed, archetype, bias?)` | Generate a physically plausible entity from an archetype |
+
+### Presets and weapons (`src/presets.ts`, `src/weapons.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `mkKnight`, `mkBoxer`, `mkWrestler`, `mkOctopus`, `mkScubaDiver` | Named entity factories |
+| `AMATEUR_BOXER`, `PRO_BOXER`, `GRECO_WRESTLER`, `KNIGHT_INFANTRY`, `LARGE_PACIFIC_OCTOPUS` | Validated archetypes |
+| `WEAPONS` | Historical weapons database (~70 weapons, six eras) |
+
+### Replay and serialization (`src/replay.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `ReplayRecorder` | Attach to a world to record all ticks |
+| `replayTo(replay, tick, ctx)` | Replay to a target tick deterministically |
+| `serializeReplay(replay)` | JSON-stringify a replay |
+| `deserializeReplay(json)` | Restore a replay from JSON |
+| `Replay`, `ReplayFrame` | Replay types |
+
+### 3D integration and renderer bridge (`src/model3d.ts`, `src/bridge/`)
+
+See [`docs/bridge-contract.md`](docs/bridge-contract.md) for the field-by-field contract
+including `AnimationHints`, `GrapplePoseConstraint`, and `InterpolatedState`.
+
+| Export | Description |
+|--------|-------------|
+| `extractRigSnapshots(world)` | Per-entity rig data snapshot for renderer use |
+| `deriveAnimationHints(entity)` | Animation state hints |
+| `derivePoseModifiers(entity)` | Per-region impairment pose weights |
+| `deriveGrappleConstraint(entity)` | Grapple pose constraint for paired entities |
+| `deriveMassDistribution(entity)` | Mass distribution for physics rigs |
+| `deriveInertiaTensor(entity)` | Inertia tensor for physics rigs |
+| `AnimationHints`, `PoseModifier`, `GrapplePoseConstraint`, `MassDistribution`, `InertiaTensor` | Types |
+| `BridgeEngine` | Double-buffered renderer bridge engine |
+| `BridgeConfig`, `BodyPlanMapping`, `InterpolatedState` | Bridge configuration and output types |
+
+### Description layer (`src/describe.ts`)
+
+| Export | Description |
+|--------|-------------|
+| `describeCharacter(attrs)` | Translate fixed-point attributes into rated descriptions |
+| `formatCharacterSheet(desc)` | Multi-line formatted character sheet |
+| `formatOneLine(desc)` | One-line summary |
+| `CharacterDescription`, `AttributeRating` | Types |
+
+---
+
+## Tier 2 — Experimental extension API
+
+These exports are usable and tested but may change across minor versions.
+A `CHANGELOG.md` entry will document any breaking change.
+
+| Module | Key exports |
+|--------|------------|
+| `src/polity.ts` | `createPolity`, `createPolityRegistry`, `stepPolityDay`, `declareWar`, `areAtWar`, `Polity`, `PolityRegistry`, `PolityPair` |
+| `src/tech-diffusion.ts` | `computeDiffusionPressure`, `stepTechDiffusion`, `totalInboundPressure`, `techEraName` |
+| `src/emotional-contagion.ts` | `applyEmotionalContagion`, `stepEmotionalWaves`, `computeEmotionalSpread`, `triggerMilitaryRout`, `triggerVictoryRally`, `netEmotionalPressure` |
+| `src/mythology.ts` | `compressMythsFromHistory`, `stepMythologyYear`, `aggregateFactionMythEffect`, `scaledMythEffect` |
+| `src/narrative-stress.ts` | `runNarrativeStressTest`, `scoreNarrativePush` |
+| `src/campaign.ts` | `Campaign`, `stepCampaignDay`, `advanceCampaignClock`, `serializeCampaign`, `deserializeCampaign` |
+| `src/arena.ts` | Arena scenario DSL, `runArenaTrial`, `runArenaScenario` |
+| `src/sim/aging.ts` | `applyAgingToAttributes`, `stepAging`, `deriveAgeMultipliers`, `getAgePhase` |
+| `src/sim/sleep.ts` | `applySleepToAttributes`, `stepSleep`, `deriveSleepDeprivationMuls`, `circadianAlertness` |
+| `src/sim/disease.ts` | `exposeToDisease`, `stepDiseaseForEntity`, `spreadDisease`, `computeTransmissionRisk` |
+| `src/sim/mount.ts` | `checkMountStep`, `computeChargeBonus`, `deriveRiderHeightBonus` |
+| `src/sim/hazard.ts` | `deriveHazardEffect`, `computeHazardExposure`, `stepHazardZone` |
+| `src/dialogue.ts` | `resolveIntimidation`, `resolvePersuasion`, `resolveDeception`, `resolveTradeNegotiation` |
+| `src/faction.ts` | `FactionRegistry`, `updateStanding`, `getFactionStanding` |
+| `src/economy.ts` | `computeItemValue`, `applyWear`, `resolveDrops`, `evaluateTradeOffer` |
+| `src/progression.ts` | `applyXP`, `applyTrainingDrift`, `computeMilestones` |
+
+---
+
+## Tier 3 — Internal kernel structures
+
+These are implementation details.  Do not import them directly; they may change at any time.
+
+| Module | Why internal |
+|--------|-------------|
+| `src/rng.ts` | `makeRng`, `eventSeed`, `hashString` — RNG contract is internal; seed structure may change |
+| `src/sim/push.ts` | Pair-based resolution internals |
+| `src/sim/kernel.ts` (non-exported functions) | Step sub-phases, internal accumulators |
+| `src/sim/seeds.ts` | Seed derivation utilities |
+| `src/sim/ai/` | AI decision internals; host applications should use `buildAICommands()` via `src/sim/ai/system.ts` |
+
+> `buildAICommands()` from `src/sim/ai/system.ts` is Experimental (Tier 2).
+> The individual sub-modules (`decide.ts`, `perception.ts`, `targeting.ts`) are Tier 3.
+
+---
+
+## What constitutes a "breaking change"
+
+| Tier 1 (breaking, requires major bump) | Tier 2 (documented in changelog) |
+|---------------------------------------|----------------------------------|
+| Removing or renaming a stable export | Removing or renaming an experimental export |
+| Changing the signature of a stable function | Changing observable behaviour without a matching test update |
+| Removing required fields from stable types | Changing field names in experimental types |
+| Changing `stepWorld`'s observable output for identical inputs | Changing RNG consumption order in internal modules |
+| Breaking `serializeReplay`/`deserializeReplay` round-trip | Changing undocumented default values |
+
+Adding new **optional** fields to `Entity` or `IndividualAttributes` is never a breaking change.
+Adding new exports is never a breaking change at any tier.
+
+---
+
+## Entity and WorldState Field Tiers
+
+Every field on `Entity` and `WorldState` carries a JSDoc annotation that identifies which
+subsystem owns it and whether it is required by the kernel.  There are three tiers:
+
+### `@core` — Required by `stepWorld` every tick
+
+These fields must always be present.  Removing or renaming them is a Tier 1 breaking change.
+
+**`Entity` core fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Unique entity identifier; stable across ticks |
+| `teamId` | `number` | Combat team / allegiance for attack resolution and AI targeting |
+| `attributes` | `IndividualAttributes` | Physical and cognitive capabilities |
+| `energy` | `EnergyState` | Energy reserve and fatigue accumulator |
+| `loadout` | `Loadout` | Equipped items: weapons, armour, held objects |
+| `traits` | `TraitId[]` | Permanent trait flags |
+| `position_m` | `Vec3` | World-space position (fixed-point, `SCALE.m` = 1 m) |
+| `velocity_mps` | `Vec3` | Velocity (fixed-point, `SCALE.mps` = 1 m/s) |
+| `intent` | `IntentState` | Movement and defence intent derived from the previous tick's commands |
+| `action` | `ActionState` | Attack cooldowns, swing momentum, weapon-bind state |
+| `condition` | `ConditionState` | Fear, morale, sensory modifiers, fatigue, thermal state |
+| `injury` | `InjuryState` | Per-region damage, shock, consciousness, fluid loss, death flag |
+| `grapple` | `GrappleState` | Active grapple relationships, grip strength, positional lock |
+
+**`WorldState` core fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tick` | `number` | Current tick count; incremented by `stepWorld` |
+| `seed` | `number` | Deterministic RNG seed |
+| `entities` | `Entity[]` | All live and dead entities |
+
+### `@subsystem(name)` — Optional state consumed by a specific module
+
+These fields are optional `?` properties.  Omitting a subsystem field disables that module's
+behaviour for the entity; the kernel continues to run correctly without it.  Adding new
+subsystem fields is never a breaking change.
+
+**`Entity` subsystem fields:**
+
+| Field | Module | Description |
+|-------|--------|-------------|
+| `willpower?` | `willpower` | Cognitive stamina reserve for concentration abilities |
+| `skills?` | `skills` | Per-skill proficiency map for skill-contest resolution |
+| `bodyPlan?` | `anatomy` | Body plan defining injury segments and mass distribution |
+| `substances?` | `pharmacology` | Active pharmacological substances in the bloodstream |
+| `foodInventory?` | `nutrition` | Consumable food items and counts |
+| `molting?` | `anatomy` | Arthropod molting state (softening segments, repair cycles) |
+| `ai?` | `ai` | AI decision state (target selection, threat map) |
+| `capabilitySources?` | `capability` | Attached capability sources (mana pools, divine reserves) |
+| `armourState?` | `armour` | Mutable resist state for ablative armour items |
+| `pendingActivation?` | `capability` | In-flight capability cast |
+| `activeConcentration?` | `capability` | Active concentration aura |
+| `faction?` | `faction` | Faction membership identifier |
+| `party?` | `party` | Adventuring party membership identifier |
+| `reputations?` | `faction` | Entity-level faction-standing overrides |
+| `physiology?` | `thermoregulation` | Species-level physiological overrides |
+| `activeVenoms?` | `toxicology` | Active venom/toxin injections |
+| `limbStates?` | `anatomy` | Per-limb state for multi-limb entities |
+| `personality?` | `ai` | AI personality traits (aggression, caution, loyalty) |
+| `extendedSenses?` | `sensory` | Extended sensory modalities (echolocation, olfaction) |
+| `activeIngestedToxins?` | `toxicology` | Active ingested toxins (alcohol, sedatives, heavy metals) |
+| `cumulativeExposure?` | `toxicology` | Cumulative lifetime dose records |
+| `withdrawal?` | `toxicology` | Active withdrawal states |
+| `traumaState?` | `wound-aging` | PTSD-like trauma state from severe shock events |
+| `activeDiseases?` | `disease` | Active systemic disease states |
+| `immunity?` | `disease` | Post-recovery immunity records |
+| `age?` | `aging` | Elapsed life-seconds for aging calculations |
+| `sleep?` | `sleep` | Sleep-phase state and debt accumulator |
+| `mount?` | `mount` | Rider/mount pair state for mounted combat |
+| `compiledAnatomy?` | `anatomy` | Internal anatomy cache — do not set manually |
+| `anatomyHelpers?` | `anatomy` | Internal anatomy helper cache — do not set manually |
+
+**`WorldState` subsystem fields:**
+
+| Field | Module | Description |
+|-------|--------|-------------|
+| `activeFieldEffects?` | `capability` | Active suppression zones and field-effect modifiers |
+| `__sensoryEnv?` | `sensory` | Ambient lighting and visibility environment |
+| `__factionRegistry?` | `faction` | Global faction-standing registry |
+| `__partyRegistry?` | `party` | Global party registry |
+| `__relationshipGraph?` | `relationships` | Inter-entity relationship graph |
+| `__nutritionAccum?` | `nutrition` | Cross-tick nutrition accumulator |
+
+### `@extension` — Host-owned data
+
+No built-in fields carry this tag.  Hosts may add their own optional `?` fields to pass
+renderer metadata, network session IDs, or other application-specific data alongside entities.
+TypeScript's structural typing allows this without modifying `Entity`'s definition.

package/dist/src/anatomy/anatomy-compiler.d.ts

@@ -0,0 +1,14 @@
+import type { BodySegment } from "../sim/bodyplan.js";
+import type { AnatomyCapabilities, AnatomyContracts, AnatomyIndexes, AnatomySegmentAugmentation, CompiledAnatomyModel, SegmentId } from "./anatomy-contracts.js";
+import { type ExtendedBodyPlanDefinition, type ValidationIssue } from "./anatomy-schema.js";
+export interface CompileAnatomyResult {
+    readonly ok: boolean;
+    readonly model?: CompiledAnatomyModel;
+    readonly issues: readonly ValidationIssue[];
+}
+export declare function compileAnatomyDefinition(input: unknown): CompileAnatomyResult;
+export declare function compileAnatomyDefinitionOrThrow(input: unknown): CompiledAnatomyModel;
+export declare function buildIndexes(plan: ExtendedBodyPlanDefinition): AnatomyIndexes;
+export declare function buildSegmentData(plan: ExtendedBodyPlanDefinition, segmentsById: ReadonlyMap<SegmentId, BodySegment>): ReadonlyMap<SegmentId, AnatomySegmentAugmentation>;
+export declare function deriveContracts(plan: ExtendedBodyPlanDefinition, segmentData: ReadonlyMap<SegmentId, AnatomySegmentAugmentation>, indexes: AnatomyIndexes): AnatomyContracts;
+export declare function deriveCapabilities(plan: ExtendedBodyPlanDefinition, segmentData: ReadonlyMap<SegmentId, AnatomySegmentAugmentation>, contracts: AnatomyContracts): AnatomyCapabilities;

package/dist/src/anatomy/anatomy-compiler.js

@@ -0,0 +1,277 @@
+import { validateExtendedBodyPlan, } from "./anatomy-schema.js";
+export function compileAnatomyDefinition(input) {
+    const validated = validateExtendedBodyPlan(input);
+    if (!validated.ok || !validated.value) {
+        return { ok: false, issues: validated.issues };
+    }
+    const plan = validated.value;
+    const indexes = buildIndexes(plan);
+    const segmentData = buildSegmentData(plan, indexes.segmentsById);
+    const contracts = deriveContracts(plan, segmentData, indexes);
+    const capabilities = deriveCapabilities(plan, segmentData, contracts);
+    const model = {
+        plan,
+        segmentData,
+        indexes,
+        contracts,
+        capabilities,
+        targetProfiles: toProfileMap(plan.targetProfiles),
+        coverageProfiles: toCoverageMap(plan.coverageProfiles),
+    };
+    return { ok: true, model, issues: [] };
+}
+export function compileAnatomyDefinitionOrThrow(input) {
+    const result = compileAnatomyDefinition(input);
+    if (!result.ok || !result.model) {
+        const message = result.issues.map(issue => `${issue.path}: ${issue.message}`).join("\n");
+        throw new Error(`Invalid anatomy definition\n${message}`);
+    }
+    return result.model;
+}
+export function buildIndexes(plan) {
+    const segmentsById = new Map();
+    const childrenMutable = new Map();
+    const roots = [];
+    for (const segment of plan.segments) {
+        segmentsById.set(segment.id, segment);
+        childrenMutable.set(segment.id, []);
+    }
+    for (const segment of plan.segments) {
+        if (segment.parent === null)
+            roots.push(segment.id);
+        else
+            childrenMutable.get(segment.parent)?.push(segment.id);
+    }
+    const subtreeMutable = new Map();
+    const visit = (id) => {
+        const children = childrenMutable.get(id) ?? [];
+        const nested = children.flatMap(child => visit(child));
+        const subtree = [id, ...nested];
+        subtreeMutable.set(id, subtree);
+        return subtree;
+    };
+    for (const root of roots)
+        visit(root);
+    for (const id of segmentsById.keys())
+        if (!subtreeMutable.has(id))
+            visit(id);
+    const tags = new Map();
+    const functions = new Map();
+    for (const segment of plan.segments) {
+        const inferredTags = inferLegacySegmentTags(segment);
+        for (const tag of inferredTags)
+            pushIndex(tags, tag, segment.id);
+        for (const fnId of inferLegacyFunctionIds(segment)) {
+            pushIndex(functions, fnId, segment.id);
+        }
+        const explicit = plan.segmentData?.[segment.id];
+        for (const tag of explicit?.tags ?? []) {
+            pushIndex(tags, tag, segment.id);
+        }
+        for (const fn of explicit?.functions ?? []) {
+            pushIndex(functions, fn.id, segment.id);
+        }
+        for (const organ of explicit?.organs ?? []) {
+            for (const tag of organ.tags ?? []) {
+                pushIndex(tags, tag, segment.id);
+            }
+            for (const fnId of organ.functionIds ?? []) {
+                pushIndex(functions, fnId, segment.id);
+            }
+            if (organ.vital) {
+                pushIndex(functions, "vital", segment.id);
+            }
+        }
+    }
+    return {
+        segmentsById,
+        childrenById: freezeIndex(childrenMutable),
+        subtreeById: freezeIndex(subtreeMutable),
+        segmentsByTag: freezeIndex(tags),
+        segmentsByFunction: freezeIndex(functions),
+        roots,
+    };
+}
+export function buildSegmentData(plan, segmentsById) {
+    const out = new Map();
+    for (const [segmentId, segment] of segmentsById) {
+        const def = plan.segmentData?.[segmentId];
+        const inferredFunctions = inferLegacyFunctions(segment);
+        const mergedFunctions = mergeFunctions(inferredFunctions, def?.functions ?? []);
+        const mergedTags = unique([
+            ...inferLegacySegmentTags(segment),
+            ...(def?.tags ?? []),
+            ...mergedFunctions.flatMap(fn => fn.tags ?? []),
+            ...(def?.organs?.flatMap(organ => organ.tags ?? []) ?? []),
+        ]);
+        out.set(segmentId, {
+            tags: mergedTags,
+            tissues: [...(def?.tissues ?? [])],
+            organs: [...(def?.organs ?? [])],
+            functions: mergedFunctions,
+        });
+    }
+    return out;
+}
+export function deriveContracts(plan, segmentData, indexes) {
+    const ids = new Set();
+    const hasFunctions = [...segmentData.values()].some(seg => seg.functions.length > 0);
+    const hasVitalOrgans = [...segmentData.values()].some(seg => seg.organs.some(organ => organ.vital));
+    const hasManipulation = [...segmentData.values()].some(seg => seg.functions.some(fn => fn.id === "manipulation"));
+    const hasLocomotion = [...segmentData.values()].some(seg => seg.functions.some(fn => fn.id === "mobility"));
+    const hasWeaponMounts = [...segmentData.values()].some(seg => seg.functions.some(fn => fn.id === "weaponMount"));
+    const hasCoverage = (plan.coverageProfiles?.length ?? 0) > 0;
+    const hasHumanoidAliases = plan.contracts?.humanoidTargeting !== undefined;
+    const hasBilateral = plan.symmetry === "bilateral" || inferBilateral(indexes);
+    if (hasFunctions)
+        ids.add("functionalDamage");
+    if (hasVitalOrgans)
+        ids.add("vitalOrganWounding");
+    if (hasManipulation)
+        ids.add("manipulation");
+    if (hasLocomotion)
+        ids.add("locomotion");
+    if (hasCoverage)
+        ids.add("shieldCoverage");
+    if (hasWeaponMounts)
+        ids.add("weaponMounts");
+    if (hasBilateral)
+        ids.add("bilateralSides");
+    if (hasLocomotion && hasBilateral)
+        ids.add("stancePosture");
+    if (hasVitalOrgans)
+        ids.add("organMedicalModel");
+    if (hasHumanoidAliases)
+        ids.add("humanoidTargeting");
+    return {
+        ids,
+        humanoidTargeting: plan.contracts?.humanoidTargeting,
+    };
+}
+export function deriveCapabilities(plan, segmentData, contracts) {
+    const hasCentralNervousSystem = [...segmentData.values()].some(seg => seg.functions.some(fn => fn.id === "cns")) || plan.cnsLayout.type === "centralized";
+    const hasManipulators = contracts.ids.has("manipulation");
+    const hasLocomotion = contracts.ids.has("locomotion");
+    const hasLateralSides = contracts.ids.has("bilateralSides");
+    const hasVitalOrgans = contracts.ids.has("vitalOrganWounding");
+    const supportsPostureModel = contracts.ids.has("stancePosture");
+    const supportsFineManipulation = [...segmentData.values()].some(seg => seg.functions.some(fn => fn.id === "manipulation" && (fn.role === "primary" || fn.weight === undefined || fn.weight >= 0.9)));
+    const supportsShieldCoverage = contracts.ids.has("shieldCoverage");
+    const supportsWeaponMounts = contracts.ids.has("weaponMounts");
+    const targetingModel = (plan.targetProfiles?.length ?? 0) > 0
+        ? "profiles"
+        : contracts.ids.has("humanoidTargeting")
+            ? "aliases"
+            : "segments";
+    return {
+        hasCentralNervousSystem,
+        hasManipulators,
+        hasLocomotion,
+        hasLateralSides,
+        hasVitalOrgans,
+        supportsPostureModel,
+        supportsFineManipulation,
+        supportsShieldCoverage,
+        supportsWeaponMounts,
+        impairmentModel: contracts.ids.has("functionalDamage") ? "functional" : plan.segments.length > 0 ? "segment" : "none",
+        targetingModel,
+    };
+}
+function inferLegacyFunctions(segment) {
+    const out = [];
+    if (segment.locomotionRole && segment.locomotionRole !== "none") {
+        out.push({
+            id: "mobility",
+            role: mapLegacyRole(segment.locomotionRole),
+            weight: segment.locomotionRole === "primary" ? 1.0 : 0.6,
+            tags: ["locomotor"],
+        });
+    }
+    if (segment.manipulationRole && segment.manipulationRole !== "none") {
+        out.push({
+            id: "manipulation",
+            role: mapLegacyRole(segment.manipulationRole),
+            weight: segment.manipulationRole === "primary" ? 1.0 : 0.6,
+            tags: ["manipulator"],
+        });
+    }
+    if (segment.cnsRole && segment.cnsRole !== "none") {
+        out.push({
+            id: "cns",
+            role: segment.cnsRole === "central" ? "primary" : "secondary",
+            weight: segment.cnsRole === "central" ? 1.0 : 0.6,
+            tags: ["cns"],
+        });
+    }
+    return out;
+}
+function inferLegacyFunctionIds(segment) {
+    return inferLegacyFunctions(segment).map(fn => fn.id);
+}
+function inferLegacySegmentTags(segment) {
+    const tags = new Set();
+    const id = segment.id.toLowerCase();
+    if (id.includes("left"))
+        tags.add("left");
+    if (id.includes("right"))
+        tags.add("right");
+    if (id.includes("head"))
+        tags.add("head");
+    if (id.includes("torso") || id.includes("chest") || id.includes("abdomen"))
+        tags.add("torso");
+    if (id.includes("arm") || id.includes("hand") || id.includes("forelimb") || id.includes("tentacle")) {
+        tags.add("manipulator");
+    }
+    if (id.includes("leg") || id.includes("foot") || id.includes("hindlimb") || id.includes("hoof")) {
+        tags.add("locomotor");
+    }
+    if (id.includes("wing"))
+        tags.add("wing");
+    if (id.includes("tail"))
+        tags.add("tail");
+    return [...tags];
+}
+function inferBilateral(indexes) {
+    const leftCount = (indexes.segmentsByTag.get("left") ?? []).length;
+    const rightCount = (indexes.segmentsByTag.get("right") ?? []).length;
+    return leftCount > 0 && leftCount === rightCount;
+}
+function mergeFunctions(inferred, explicit) {
+    const byId = new Map();
+    for (const fn of inferred)
+        byId.set(fn.id, { ...fn, tags: [...(fn.tags ?? [])] });
+    for (const fn of explicit) {
+        const prior = byId.get(fn.id);
+        byId.set(fn.id, {
+            id: fn.id,
+            role: fn.role ?? prior?.role ?? "none",
+            weight: fn.weight ?? prior?.weight ?? 0,
+            tags: unique([...(prior?.tags ?? []), ...(fn.tags ?? [])]),
+        });
+    }
+    return [...byId.values()];
+}
+function mapLegacyRole(role) {
+    if (role === "none")
+        return "none";
+    return role;
+}
+function toProfileMap(profiles) {
+    return new Map((profiles ?? []).map(profile => [profile.id, profile]));
+}
+function toCoverageMap(profiles) {
+    return new Map((profiles ?? []).map(profile => [profile.id, profile]));
+}
+function pushIndex(index, key, value) {
+    const prior = index.get(key);
+    if (prior)
+        prior.push(value);
+    else
+        index.set(key, [value]);
+}
+function freezeIndex(index) {
+    return new Map([...index.entries()].map(([key, value]) => [key, [...value]]));
+}
+function unique(values) {
+    return [...new Set(values)];
+}

package/dist/src/anatomy/anatomy-contracts.d.ts

@@ -0,0 +1,94 @@
+import type { BodySegment } from "../sim/bodyplan.js";
+import { ExtendedBodyPlanDefinition } from "./anatomy-schema.js";
+export type SegmentId = BodySegment["id"];
+export type AnatomyFunctionId = "mobility" | "manipulation" | "cns" | "vision" | "respiration" | "circulation" | "digestion" | "sensor" | "balance" | "weaponMount" | "vital";
+export interface TissueLayerDefinition {
+    id: string;
+    kind: "skin" | "fat" | "muscle" | "bone" | "shell" | "membrane" | "organ" | "other";
+    integrity?: number;
+    tags?: readonly string[];
+}
+export interface OrganDefinition {
+    id: string;
+    kind: string;
+    functionIds?: readonly AnatomyFunctionId[];
+    vital?: boolean;
+    paired?: boolean;
+    tags?: readonly string[];
+}
+export interface SegmentFunctionDefinition {
+    id: AnatomyFunctionId | string;
+    role?: "primary" | "secondary" | "support" | "none";
+    weight?: number;
+    tags?: readonly string[];
+}
+export interface SegmentTargetAliasBlock {
+    head?: readonly SegmentId[];
+    torso?: readonly SegmentId[];
+    leftArm?: readonly SegmentId[];
+    rightArm?: readonly SegmentId[];
+    leftLeg?: readonly SegmentId[];
+    rightLeg?: readonly SegmentId[];
+}
+export interface SegmentCoverageProfile {
+    id: string;
+    tags?: readonly string[];
+    selectors: readonly SegmentSelector[];
+}
+export interface SegmentTargetProfile {
+    id: string;
+    selectors: readonly WeightedSegmentSelector[];
+}
+export interface WeightedSegmentSelector extends SegmentSelector {
+    weight: number;
+}
+export interface SegmentSelector {
+    ids?: readonly SegmentId[];
+    tags?: readonly string[];
+    functionIds?: readonly string[];
+    subtreeOf?: SegmentId;
+    anyOf?: readonly SegmentSelector[];
+    allOf?: readonly SegmentSelector[];
+    exclude?: SegmentSelector;
+}
+export type AnatomyContractId = "functionalDamage" | "vitalOrganWounding" | "bilateralSides" | "manipulation" | "locomotion" | "stancePosture" | "shieldCoverage" | "humanoidTargeting" | "organMedicalModel" | "weaponMounts";
+export interface AnatomyContracts {
+    readonly ids: ReadonlySet<AnatomyContractId>;
+    readonly humanoidTargeting?: SegmentTargetAliasBlock | undefined;
+}
+export interface AnatomyCapabilities {
+    readonly hasCentralNervousSystem: boolean;
+    readonly hasManipulators: boolean;
+    readonly hasLocomotion: boolean;
+    readonly hasLateralSides: boolean;
+    readonly hasVitalOrgans: boolean;
+    readonly supportsPostureModel: boolean;
+    readonly supportsFineManipulation: boolean;
+    readonly supportsShieldCoverage: boolean;
+    readonly supportsWeaponMounts: boolean;
+    readonly impairmentModel: "functional" | "segment" | "none";
+    readonly targetingModel: "profiles" | "aliases" | "segments";
+}
+export interface AnatomyIndexes {
+    readonly segmentsById: ReadonlyMap<SegmentId, BodySegment>;
+    readonly childrenById: ReadonlyMap<SegmentId, readonly SegmentId[]>;
+    readonly subtreeById: ReadonlyMap<SegmentId, readonly SegmentId[]>;
+    readonly segmentsByTag: ReadonlyMap<string, readonly SegmentId[]>;
+    readonly segmentsByFunction: ReadonlyMap<string, readonly SegmentId[]>;
+    readonly roots: readonly SegmentId[];
+}
+export interface AnatomySegmentAugmentation {
+    readonly tags: readonly string[];
+    readonly tissues: readonly TissueLayerDefinition[];
+    readonly organs: readonly OrganDefinition[];
+    readonly functions: readonly SegmentFunctionDefinition[];
+}
+export interface CompiledAnatomyModel {
+    readonly plan: ExtendedBodyPlanDefinition;
+    readonly segmentData: ReadonlyMap<SegmentId, AnatomySegmentAugmentation>;
+    readonly indexes: AnatomyIndexes;
+    readonly capabilities: AnatomyCapabilities;
+    readonly contracts: AnatomyContracts;
+    readonly targetProfiles: ReadonlyMap<string, SegmentTargetProfile>;
+    readonly coverageProfiles: ReadonlyMap<string, SegmentCoverageProfile>;
+}

package/dist/src/anatomy/anatomy-contracts.js

@@ -0,0 +1 @@
+export {};