Scenario Compiler requirements
Defines validation, capability negotiation, scheduling analysis, fidelity preview, and immutable compilation before execution.
Section relationships
Depends on
Used by
- §9Simulation Kernel and Time
- §10Mechanics
- §11Environment
- §12Materials
- §13Devices, Power, Circuits, Thermal, and Firmware
- §14Sensors
- §15Controllers and ML
- §16Experiment Orchestrator
- §17Result Store
- §19Editor and Viewer
- §20Integration Gateway
- §21Extension Host
- §22Performance and Scalability
- §26Public API, Diagnostics, and Versioning
- §32Required Normative Designs
| ID | Name | Priority | Requirement | Verification |
|---|---|---|---|---|
| COMP-001 | Explicit compilation | MVP | Editable project models SHALL be compiled into an immutable execution description before a run starts. | Inspection |
| COMP-002 | Capability negotiation | MVP | The compiler SHALL verify every required feature against the selected solver, device, sensor, controller, and extension capabilities. | Test |
| COMP-003 | Unsupported-feature rejection | MVP | A required unsupported capability SHALL be a compilation error unless an explicit documented approximation is selected. | Test |
| COMP-004 | Approximation acknowledgement | MVP | A selected approximation SHALL be included in the experiment definition and resulting fidelity card. | Test |
| COMP-005 | Dependency graph | MVP | The compiler SHALL construct a directed graph of subsystem inputs, outputs, and scheduling dependencies. | Inspection |
| COMP-006 | Algebraic-loop detection | MVP | The compiler SHALL detect direct-feedthrough cycles and reject them unless an enabled coupling solver explicitly supports the loop. | Test |
| COMP-007 | Rate compatibility | MVP | The compiler SHALL validate sample rates, phases, interpolation policies, and macro-step boundaries. | Test |
| COMP-008 | Port compatibility | MVP | The compiler SHALL validate unit, type, shape, frame, causality, and cardinality compatibility for every connected port. | Test |
| COMP-009 | Deterministic ordering | MVP | Equivalent compiled scenarios SHALL use stable entity and event ordering independent of hash-map or filesystem enumeration. | Test |
| COMP-010 | Initial-state consistency | MVP | The compiler SHALL detect invalid initial poses, joint limits, penetrations beyond policy, and missing required state. | Test |
| COMP-011 | Resource estimate | Beta | The compiler SHOULD estimate memory, storage, sensor bandwidth, and expected execution profile before a batch starts. | Analysis |
| COMP-012 | Compilation diagnostics | MVP | Every compilation error SHALL identify the entity, property, capability, and at least one corrective action. | Test |
| COMP-013 | Compiled artifact identity | MVP | A compiled scenario SHALL have a content identity derived from canonical inputs, compiler version, target capabilities, and options. | Test |
| COMP-014 | Pre-run fidelity preview | MVP | Before a run launches, the compiler SHALL produce a fidelity preview listing selected models and effects, required engineering properties, consuming capabilities, transformations, final property dispositions, inactive engineering properties, inactive or unsupported effects, approximations, validity warnings, and evidence status. | Demonstration |
| COMP-015 | Fidelity profile enforcement | MVP | Each fidelity profile SHALL declare machine-checkable minimum qualification, convergence, uncertainty, and out-of-envelope policies, and the compiler SHALL enforce them or record an explicitly permitted experiment override. | Test |
| COMP-016 | Checkpoint capability closure | MVP | The compiler SHALL derive checkpoint-resume and input-re-execution guarantees from every stateful participant's snapshot, restore, determinism, and external-input capabilities and SHALL reject or explicitly downgrade an unsatisfied request. | Test |
| COMP-017 | Compiled property closure | MVP | For every engineering property required by the selected compiled model-and-effect graph, the compiler SHALL assign exactly one terminal disposition: consumed only when a compatible consuming capability resolves; explicitly approximated only when a documented replacement capability is selected under COMP-003 and COMP-004; or rejected with actionable diagnostics when neither path resolves. | Test |
| COMP-018 | Inactive property disclosure | MVP | Every authored or imported engineering property reachable by the compiled scenario but not required by its selected model-and-effect graph SHALL be classified and exposed as inactive rather than presented as affecting the run. | Test |
| COMP-019 | Engineering transformation record | MVP | Every unit, basis, numeric precision, representation, or model transformation applied to an active engineering value SHALL record its source and target semantics, its rounding and range or subnormal policy when numeric, and whether it is exact or lossy; a material lossy transformation SHALL produce an actionable preflight diagnostic. | Test |
| COMP-020 | Robot readiness report | Beta | The compiler SHALL emit a machine-readable readiness report covering topology, frames, inertial properties, joint limits and drives, collision geometry, device and sensor connections, controller interfaces, unresolved references, and unavailable required capabilities. | Test |
| COMP-021 | Runtime-action capability closure | Beta | The compiler SHALL validate every declared runtime-action type and version, statically referenced definition or target, payload schema, units, frames, resource bounds, required participant capabilities, and safe-boundary class and SHALL reject an unsupported action plan before execution. | Test |
Change rationale (COMP-014, COMP-017, COMP-018, COMP-019): Canonical representation alone is not simulation. These requirements close properties activated explicitly or transitively by the compiled graph, distinguish compatible consumption, acknowledged replacement, and rejection from orthogonal transformations, expose intentionally inactive data, and make the property-level result visible before execution. Requirements v0.7 extends COMP-019 to every active engineering value because a precision conversion can lose information even when it is not attached to one property record.
Change rationale (COMP-020): Existing compiler diagnostics are individually actionable but do not guarantee one complete bring-up assessment. A stable readiness report lets the CLI, UI, and automation consume the same evidence without creating a second validation path.
Change rationale (COMP-021): Runtime mutation is safe and reproducible only when action types, statically knowable targets, semantics, limits, and required capabilities are resolved before a run. This requirement reuses the existing compile-before-execution boundary rather than creating an unvalidated supervisor path.
Generated from the canonical specification. Edit section metadata or prose in docs/requirements.md; the website rebuilds this page and its relationships automatically.