Engine Refactor: Trait-Based Species Architecture with Allometric Scaling

[biosynthart]

Engine Refactor: Trait-Based Species Architecture with Allometric Scaling

Summary

Replaces per-species hardcoded constants in the engine with a trait-based derivation layer. Every species is now defined as a functional trait vector; all engine parameters (metabolism, speed, sensory
range, flow rates, guard thresholds) are derived from body mass and traits using allometric scaling laws.

New Modules

• ecosim/traits.py — TraitVector dataclass + allometric derivation functions (derive_metabolic_rate, derive_speed, derive_flow_rates, etc.). All numeric constants the tick loop uses flow through
  DerivedParams.
• ecosim/trait_compiler.py — Compiles trait vectors at world init into: (1) per-species DerivedParams, (2) sparse interaction matrix, (3) resource tag registry, (4) decomposer registry. Per-tick cost
  is O(1) dict lookups only.
• ecosim/interactions.py — Parameterized interaction templates (Herbivory, Predation, Pollination, Decomposition) replace per-species-pair code. Templates encode ecological rules (mass-ratio windows,
  diet compatibility); compiler evaluates all pairs upfront.

Engine Changes

• 7-phase hybrid automaton (was 2-phase): Flow → Interactions → Guards → Voxel FX → Water → Motor → Spawn/Kill
• Functional role dispatch: engine routes on diet_type (autotroph/decomposer/consumer), never on entity class. No per-species special cases remain in the tick loop.
• Universal constants extracted: all species-specific values removed from engine; remaining named constants are world-level physics (drinking rates, stress thresholds, plant physiology).

Backward Compatibility

Worlds without species_definitions in JSON fall back to LegacyParams, preserving original per-entity metadata behavior. Existing worlds work unchanged.

World Format

New optional species_definitions.json defines species as trait vectors:

  { "species_id": "monarch", "body_mass_kg": 0.0005, "thermoregulation": "ectotherm",                                                                                                                    
    "diet_type": "nectarivore", "reproductive_strategy": "r_selected", ... }                                                                                                                             

Testing

66 unit tests covering: allometric derivation functions (mass scaling, ectotherm/endotherm), interaction template matching (herbivory/predation/pollination/decomposition), trait compiler integration,
and JSON parsing. All pass.