Epic: Extend BYOM from motor inference to full phase-level pluggability

[biosynthart]

Goal

Extend the existing BYOM (Bring Your Own Model) architecture so that any simulation phase can be replaced or augmented by a learned model. Currently only Phase 6 (motor inference) is pluggable. The target is all 7 phases:

Phase 1  Flow          ──► Physics OR LearnedFlowAdapter
Phase 2  Interactions  ──► Templates OR LearnedInteraction
Phase 3  Guards        ──► Thresholds OR BehaviorAdapter (#20)
Phase 4  Voxel FX      ──► Handlers OR VoxelAdapter (#79)
Phase 5  Water/Soil    ──► Handlers OR WorldAdapter
Phase 6  Motor         ──► MotorAdapter (already implemented)
Phase 7  Spawn/Kill    ──► EffectBus (always physics for now)

Design Principles

1. Physics is ground truth. Models augment or approximate — they don't replace physics as the source of training data. The engine always runs in "pure physics" mode for data generation.
2. Each phase is independently swappable. Swap diffusion without touching flow, guards, or interactions. Experiments stay isolated and composable.
3. BYOM protocol consistency. All learned adapters follow the same pattern as MotorAdapter: declare a context spec, receive flat float vectors, return predictions. No engine internals leak into model code.

Sub-Issues (in order)

#	Issue	Phase	Status
#77	Telemetry emitter + batch runner	Foundation	Open
#78	Surrogate model + sensitivity analysis	Understanding	Open
#79	Learned diffusion (voxel adapter)	First replacement	Open
#20	Behavior-level adapter	Guard augmentation	Open
#21	Narrative-level adapter	Macro intelligence	Open

Success Criteria

• Telemetry infrastructure captures config + aggregates + events with <5% overhead (Telemetry emitter: config snapshot + time-series aggregates + event batching #77)
• Sensitivity analysis identifies effective dimensionality of the ~48 tunable params (Surrogate model + sensitivity analysis over sim_config parameter space #78)
• At least one phase (diffusion) has a working learned adapter that matches physics accuracy (Learned diffusion: replace or gate voxel nutrient diffusion with a model #79)
• Behavior and narrative adapters implemented per existing protocols in model_adapter.py (Behavior-level adapter #20, Narrative-level adapter #21)
• Documentation updated: each adapter level has a training data spec + example model

Docs

Full plan: docs/ECOSIM_PARAMETER_TELEMETRY_SPACE.md

[biosynthart]

⏸️ Shelved — hybrid BYOM epic (phase-level pluggability) deferred until after the distributed engine scalability work. All child issues (#77, #78, #79, #20, #21) are shelved in parallel.