# Research bundle schema v1 An export is an immutable directory: ```text policy.onnx deterministic actor, with trained observation normalization contract.json observation/action ordering, affine transforms, simulation PD settings reference.json one raw observation and its expected unclipped policy action evaluation.json fixed-protocol rollout evidence bound to the checkpoint/source hashes experiment.json original experiment agent.json runner architecture/configuration provenance.json source/assets/runtime versions and hashes manifest.json SHA-256 of every payload file, checkpoint hash, ONNX parity results ``` The bundle contains no robot meshes, checkpoint pickle, board executable or motor transport. It is portable for **CPU ONNX inference**, not a self-contained simulation environment. Replay still needs the recorded task code, asset checkout and compatible mjlab environment. ## Consumer contract `PolicyRuntime(Path(bundle)).predict(observation)` accepts a finite float32 `[1, observation_size]` array. Observation terms must be concatenated in the exact `start:stop` order. Read each term's function identity in `contract.json`; implementation semantics are in the recorded sources. For current flat tasks, terms are base linear/angular velocity from the configured IMU sensors, projected gravity, joint position relative to default, joint velocity relative to default, previous clipped raw action, and `(vx, vy, yaw_rate)` commands. Sensor frame/site and filtering matter; a base estimator cannot be substituted without validating parity. Joint observation ordering is explicitly separate from action ordering. Units are SI; angles in radians. Normalization is inside ONNX. Do **not** normalize twice. On reset, previous action is zero. During inference: ```text raw_action = policy(observation) clipped_action = clip(raw_action, -raw_clip, raw_clip) joint_target_rad = offset + scale * clipped_action ``` The consumer returns all three arrays and does not send them anywhere. Host PD/control frequency must match the recorded policy/physics timestep semantics. Simulation gain and torque data are metadata, not a certified motor configuration. Joint-limit clamping is not silently added to inference because it would change training semantics; a physical safety controller must be separately designed, validated and may refuse the policy. ## Export checks and limits Export requires a completed local run and matching evaluation report. It tests ONNX checker validity and action parity at 16 actual rollout observations (`atol=1e-5`, `rtol=1e-4`), then writes file hashes. `verify-bundle --inference` checks integrity and one saved reference. This detects common swapped-joint/normalizer/version mistakes, but is not a complete behavioral proof. The current exporter requires MLP, one joint-position action group, no per-joint action clip, one position actuator per joint and batch size one. It does not generate a robot driver. A report can show poor tracking and many falls and still be packaged for research. All bundles are `hardware_approved: false`. There is no release-quality gate or hardware approval command. Before physical deployment, implement and validate bus index mapping, estimator/calibration, IMU frame, latency, torque/position bounds, thermal limits, watchdog, controlled startup/shutdown, E-stop and supervised sim-to-real tests. Require explicit operator authorization for actual motion.