Simulation Fields
This page documents the simulator’s field/environment-dynamics layer and the generic external environment boundary.
Field Layer
Telltale now treats field dynamics as one layer inside a broader environment model. The field layer is responsible for evolving shared fields, latent environment state, or node-local physical state when protocol-visible effects occur. It does not by itself decide topology, medium contention, mobility, or admission.
The simulator-facing Rust abstraction is FieldModel in rust/simulator/src/field.rs.
A FieldModel supplies a stable layer name, an EffectHandler via build_handler(), and default per-role initial states via derive_initial_states(roles).
The built-in scenario schema uses the serde-tagged FieldSpec catalog through Scenario.field.
Current built-in families are mean_field, hamiltonian, and continuum_field.
Adapter Integration
Use FieldAdapter::from_scenario(...) when built-in scenario field parameters should drive handler construction and default state derivation.
Use FieldAdapter::new(...) or FieldAdapter::from_boxed_model(...) when a host integration wants the harness to own a custom FieldModel.
The harness provides derive_initial_states(&Scenario) for the built-in schema and derive_initial_states_for_field_model(&dyn FieldModel, roles) for arbitrary implementations.
Simulator field handlers implement deterministic EffectHandler::step updates over fixed-point state.
The runner stores field state in coroutine registers starting at register 2.
Initial State Derivation
derive_initial_states(&Scenario) builds default per-role state vectors from the built-in field when present.
mean_field broadcasts one concentration vector to every role.
hamiltonian maps each role index to [position, momentum].
continuum_field assigns one scalar field value per role.
If a HostAdapter returns explicit initial states, the simulator never consults the built-in field catalog.
Environment Boundary
External projects should extend the simulator through the domain-neutral environment hooks in rust/simulator/src/environment.rs.
The shared execution core accepts five external model traits: TopologyModel for graph structure and reachability, MediumModel for link-level delay/loss/collision behavior, MobilityModel for node position updates, NodeCapabilityModel for per-node resource or radio constraints, and LinkAdmissionModel for connection-level admission decisions.
These hooks all receive the same EnvironmentSnapshot each round.
That snapshot exposes current tick, logical step, participating roles, field-backed node state, node poses, node capabilities, and potential links.
The shared execution core emits one canonical EnvironmentTrace of EnvironmentArtifact records for mobility updates, capability snapshots, reachability decisions, admission outcomes, and medium outcomes.
Extension Configuration
Scenario.extensions is the generic config hook for domain-owned environment configuration.
It is a namespaced map of arbitrary TOML values so external projects can carry their own config without adding vertical-specific fields to core Scenario.
Vertical-specific logic belongs in downstream crates, not in the core simulator schema.
Lean Mirror
Lean mirrors the executable field boundary under lean/Runtime/Simulation/Field.lean.
That module includes a Lean-native FieldModel, FieldHandler, built-in FieldParams catalog, and default initial-state derivation for the shipped field families.
It remains an executable parity layer rather than a mirror of Rust trait objects or serde-based scenario parsing.
Coverage
The main parity and extension lanes are:
rust/simulator/tests/field_handler_parity.rsrust/simulator/tests/environment_models.rsrust/simulator/tests/lean_reference_parity.rslean/Runtime/Tests/SimulatorParity.lean
environment_models.rs exists specifically to prove that topology, medium, mobility, capability, and admission hooks work through an external adapter without built-in domain knowledge.