Section 15Simulation Runtime
Controller Host and ML requirements
Defines trusted and isolated controller execution, controller timing and lifecycle, control-facing kinematics, planning and local dynamics artifacts, and native ML environment interfaces.
Section relationships
| ID | Name | Priority | Requirement | Verification |
|---|---|---|---|---|
| CTRL-001 | Trusted native Rust controller | MVP | The portable product SHALL execute first-party or explicitly trusted, content-hashed Rust controller artifacts through a documented in-process contract. | Demonstration |
| CTRL-002 | Controller lifecycle | MVP | A controller SHALL support configure, initialize, reset, observe, act, snapshot where declared, restore where declared, and shutdown. | Test |
| CTRL-003 | Timestamped observation | MVP | Controller observations SHALL identify the virtual time and source timing of their data. | Test |
| CTRL-004 | Timestamped action | MVP | Controller actions SHALL identify their intended application time or use a documented next-activation policy. | Test |
| CTRL-005 | Controller rate | MVP | A controller SHALL declare its activation rate and phase. | Inspection |
| CTRL-006 | Controller state | MVP | Stateful controllers SHALL declare whether their state participates in checkpoint and restore. | Test |
| CTRL-007 | Native controller failure | MVP | A native controller panic or invalid output SHALL terminate or degrade the run according to an explicit experiment policy. | Test |
| CTRL-008 | Action bounds | MVP | Controller outputs SHALL be validated against port type, unit, shape, finite-value, and configured bounds before application. | Test |
| CTRL-009 | Multiple controllers | Beta | BeforeMetal SHALL support multiple independently scheduled controllers with explicit ownership or arbitration of command ports. | Test |
| CTRL-010 | Safety limiter | MVP | An experiment SHALL be able to apply a deterministic command-limiting layer between controller output and actuator input. | Test |
| CTRL-011 | Wasm controller | Beta | The portable product SHALL support a sandboxed Wasm controller profile with declared resource and host capabilities. | Demonstration |
| CTRL-012 | Process controller protocol | Beta | BeforeMetal SHALL expose a versioned external process protocol for initialization, reset, observations, actions, step coordination, termination, and errors. | Test |
| CTRL-013 | Python controller adapter | External | BeforeMetal SHALL provide or permit an optional Python SDK over the process controller protocol. | Demonstration |
| CTRL-014 | ROS 2 controller adapter | External | BeforeMetal SHALL permit a ROS 2 bridge to exchange clock, state, sensor, command, transform, and diagnostic data. | Demonstration |
| CTRL-015 | ONNX inference boundary | External | BeforeMetal SHALL validate ONNX model inputs, outputs, types, shapes, layouts, and supported operators before execution; in-process execution SHALL use only a pure-Rust implementation, while ONNX Runtime and vendor execution providers SHALL run in an optional sidecar. | Demonstration |
| CTRL-016 | Controller resource measurement | Beta | BeforeMetal SHALL measure controller execution time, deadline misses, and supported memory or process resource data. | Test |
| CTRL-017 | Native controller trust gate | MVP | Project-supplied native controller code SHALL remain unbuilt and unexecuted until the user explicitly trusts its identity for the project or workspace. | Test |
| CTRL-018 | Isolated controller deadline | Beta | A Wasm or process controller SHALL have a configured response deadline and timeout policy enforceable without relying on cooperative in-process preemption. | Test |
| CTRL-019 | External activation identity | Beta | Every external controller observation and action SHALL carry world, episode, and activation identities in addition to simulation time. | Test |
| CTRL-020 | External action acceptance | Beta | A process controller SHALL accept at most one action per activation and SHALL enforce configured duplicate, stale, future, late, timeout, and invalid-action policies. | Test |
| CTRL-021 | External disconnect and backpressure | Beta | A process controller SHALL declare disconnect, reconnect, input-queue, output-queue, and backpressure behavior before activation. | Test |
| CTRL-022 | Forward-kinematics query | Beta | BeforeMetal SHALL expose a backend-neutral query for named body and frame poses, spatial velocities, and supported Jacobians with explicit joint ordering, coordinates, units, frames, virtual time, and source state identity. | Test |
| CTRL-023 | Inverse-kinematics query | Beta | BeforeMetal SHALL expose a backend-neutral inverse-kinematics query with named frames, start state, target constraints, joint limits, tolerances, solution status, and actionable infeasibility diagnostics. | Test |
| CTRL-024 | Planning-scene snapshot | Beta | A planning participant SHALL receive an immutable, timestamped snapshot identifying robot state, collision geometry, allowed-collision policy, static and supported dynamic obstacles, frames, and source compiled scenario. | Test |
| CTRL-025 | Canonical motion trajectory | Beta | A motion trajectory SHALL declare named joints or frames, units, timestamps or timing law, interpolation and continuity semantics, limits, provenance, and feasibility status independently of any planner's native representation. | Inspection |
| CTRL-026 | Motion-planner protocol | Beta | BeforeMetal SHALL expose a versioned planner protocol that accepts a planning-scene snapshot, start and goal conditions, constraints, seed, and resource budget and returns status, candidate trajectories, planner identity and settings, termination reason, and diagnostics. | Test |
| CTRL-027 | Plan execution gate | Beta | A candidate motion trajectory SHALL not command the simulation until it has been explicitly selected and checked against the current compiled scenario, state identity, joint and actuator limits, timing constraints, and supported collision policy. | Test |
| CTRL-028 | Controller-restart action | Beta | A runtime action SHALL be able to restart a supported controller at a safe boundary under an explicit policy for controller state, pending observations and actions, held outputs, random streams, initialization, and restart failure. | Test |
| CTRL-029 | State and control derivatives | Beta | At least one portable General Robotics Beta profile SHALL expose continuous-dynamics or discrete-transition state and control Jacobians at a named operating point with ordered coordinates, units, frames, source identities, timestep or integrator semantics, derivative method, perturbation and tolerance settings, active mode, residuals, conditioning, and declared handling of one-sided, undefined, or unavailable derivatives. | Analysis |
| CTRL-030 | Canonical linearization artifact | Beta | BeforeMetal SHALL produce a versioned, content-identified linearization artifact binding its source compiled scenario, operating point, continuous- or discrete-time semantics, ordered state, control, and output coordinates, matrices, affine or equilibrium residual, sampling or integration settings, derivative identity, active mode, and declared local validity bounds. | Test |
| CTRL-031 | Nonsmooth derivative boundary | Beta | A derivative or linearization request at contact onset, saturation, mode transition, hybrid event, or another condition outside the selected capability's declared smoothness envelope SHALL return a structured unavailable or one-sided diagnostic rather than an unqualified matrix. | Test |
| ML-001 | Native environment transition API | MVP | The native API SHALL provide reset(seed, options) -> (observation, info) and step(action) -> (observation, reward, terminated, truncated, info) transitions with typed schemas. | Test |
| ML-002 | Observation schema | MVP | An ML observation SHALL declare names, types, shapes, units, frames, bounds, and sample timing. | Inspection |
| ML-003 | Action schema | MVP | An ML action SHALL declare names, types, shapes, units, target ports, bounds, and application timing. | Inspection |
| ML-004 | Seeded reset | MVP | Resetting the same compiled scenario with the same seed and options SHALL reproduce all declared stochastic initialization. | Test |
| ML-005 | Domain randomization | Beta | An experiment SHALL support seeded randomization of declared robot, device, sensor, material, and environment parameters. | Test |
| ML-006 | Randomization record | Beta | Every sampled parameter SHALL be recorded in the episode or run manifest. | Test |
| ML-007 | Termination distinction | MVP | The native API SHALL distinguish task termination from administrative truncation. | Test |
| ML-008 | Reward decomposition | Beta | A task SHALL expose named reward or score components rather than only one opaque scalar. | Test |
| ML-009 | Batched environments | Beta | BeforeMetal SHALL support multiple independent headless worlds through a batched control interface. | Analysis |
| ML-010 | Gymnasium wrapper | External | BeforeMetal SHALL provide or permit an optional Gymnasium-compatible wrapper over the native environment API. | Demonstration |
| ML-011 | Multi-agent wrapper | Future | BeforeMetal MAY provide a multi-agent API with per-agent observations, actions, rewards, and lifecycle. | Demonstration |
| ML-012 | Training-framework boundary | MVP | BeforeMetal SHALL not require or implement a specific ML training framework in the portable core. | Inspection |
| ML-013 | Batched transition semantics | Beta | A batched environment API SHALL provide stable environment identities and ordering, per-environment reset, and explicit partial-failure behavior. | Test |
| ML-014 | Policy asset manifest | Beta | An inference policy asset SHALL record content hash, input and output tensors, normalization, backend identity, operator coverage, numerical mode, and applicable controller configuration. | Inspection |
| ML-015 | Episode dataset export | Beta | BeforeMetal SHALL export synchronized observations, actions, rewards, termination state, causal timestamps, realized parameters, and selected truth through a versioned dataset schema. | Test |
| ML-016 | Inference timing model | Beta | Online policy evaluation SHALL support measured or configured inference latency and deadline behavior in simulation time. | Analysis |
Change rationale (CTRL-022–CTRL-027): General robotics Beta needs portable analysis and motion-planning boundaries, but not a hard dependency on MoveIt, Drake, or another planner. These requirements keep kinematics, planning scenes, trajectories, planner invocation, and pre-execution validation explicit, frame-aware, inspectable, and backend-neutral.
Change rationale (CTRL-028–CTRL-031): Runtime controller restart needs explicit state and queue semantics rather than silent hot swapping. Control-facing derivatives and linearization are local artifacts, not promises across contact onset, saturation, hybrid transitions, or other nonsmooth behavior; the separate boundary requirement prevents unsupported operating modes from returning misleading matrices.
Generated from the canonical specification. Edit section metadata or prose in docs/requirements.md; the website rebuilds this page and its relationships automatically.