AutoForge/docs/simulation.md

97 lines
5.1 KiB
Markdown

# Synthetic simulation definitions and state
## Definition boundary
Vehicle-profile JSON remains the strict schema-v1 metadata contract. Endpoint
addresses, implemented services, initial DTC state, static signals, response
latency and deterministic faults live in a separate source-controlled
`SimulationDefinition`, not in profile JSON.
The `SyntheticDiagnosticExamples` catalog contains two inventories:
- `autoforge.synthetic.test-truck` revision 1: a synthetic engine controller,
transmission controller and cabin/body controller.
- `autoforge.synthetic.orchard-cart` revision 1: an alternate inventory with a
custom experimental sensor-bridge role.
IDs, names, identities and declared configuration are intentionally synthetic.
The truck has no-response configured for the transmission probe to demonstrate
that expected inventory is not the same as actual discovery. The body module
returns an explicit unsupported negative response to virtual DTC clear. The
engine has one initial virtual DTC and supports virtual clear.
`SimulationDefinition.ValidateAgainst` requires the exact profile identifier
and revision, one unique mapping for every profile module and matching role,
name and supplied hardware/software/firmware/calibration identity. Endpoint
addresses and module IDs are unique. Service identifiers must be known protocol
v1 synthetic services; signal IDs, units, JSON values, DTC values and fault
entries are validated. Profile capability/provenance declarations do not
enable or prove a virtual service.
Definitions may advertise `probe` without `read.identity`. Discovery then
retains the validated probe and its advertised services, marks identity as not
attempted with an explicit reason, and does not synthesize identity from the
matching profile entry. Expected endpoints, positive probes and identities
verified against the selected profile are counted separately. Advertised
read/clear services do not enable UI actions until runtime identity is verified.
## Session state
Opening a new Simulation session creates independent DTC state for each virtual
module from its configured initial values. A successful `clear.dtcs` response
acknowledges the request but is not itself proof of a state change. The
Application clear-and-verify use case issues a fresh `read.dtcs` request and
reports success only for a valid empty readback. A nonempty readback remains
visible and fails verification; timeout, cancellation, closed session,
no-response or malformed/negative readback is explicit uncertainty, never
verified success. An already-empty module can still verify successfully even
when the acknowledgement count is zero. These semantics concern virtual
in-memory state only; no physical write occurs.
An accepted clear changes only that module in that session. Opening a second
session starts with the definition's original initial values.
Reset explicitly closes the old session and opens a new one against the same
exact profile revision/provider/configuration, thereby restoring initial state
and starting a new trace. Closing releases the old transport and its trace/state.
No profile metadata or another session is mutated.
Normal Application/UI consumers see state only through encoded diagnostic
requests and typed responses. An internal simulation oracle is granted only to
the IntegrationTests assembly so tests can independently assert clear/reset/
isolation behavior; it is not a public provider or application service.
## Static signals
Signals are configured JSON values with a source module, identifier, unit and
quality. In this example, engine speed is the fixed synthetic value 850 rpm,
engine supply voltage is fixed at 12.6 V, transmission state is the string
`parked-static`, and the body module reports a static synthetic door count.
Replies carry the logical request tick and origin `SYNTHETIC_STATIC`.
These are reproducible fixture values, not dynamic model output, current sensor
data, a vehicle capture, compatibility evidence or operational advice. Unknown
values remain unknown; there is no generated motion, fuel, road-load or
scenario physics.
## Reproducible faults and lifecycle
`VirtualModuleDefinition` accepts a validated fault map keyed by a defined
synthetic service, plus non-negative logical response latency. Fault modes are:
- `NoResponse`: no response payload arrives.
- Latency above the protocol deadline: explicit `Timeout`, no response payload.
- `MalformedResponse`: response bytes are retained but protocol decoding fails.
- `WrongCorrelation`: response does not match request correlation.
- `WrongIdentity`: identity reply names an unexpected module.
- `HoldUntilCancelled`: pending transport work completes only on request
cancellation or session close.
Fault maps are data, not random scheduling. The default truck definition
reproducibly demonstrates a missing transmission probe response; tests construct
other explicit vectors and assert their exact outcomes and trace records.
There is no physical/replay provider in this implementation. The Simulation
provider will reject unknown or incompatible profile revisions and target
selection does not automatically open an operational session. No simulation
state is persisted beyond the current process/session.