MuJoCo checkpoints

MujocoDriver declares a readonly world.native_checkpoint field. The resource read and snapshot capture the same world document under the bridge's native lock. The checkpoint participates in the normal state hash; there is no hidden cache or hash exclusion. Restoring a checkpoint also restores the logical tick, and the endpoint verifies the actual post-restore state before reporting completion.

The mujoco_integration_v1 profile requires the native get/set/state-size APIs and named component masks. It preserves the complete mjSTATE_INTEGRATION vector, including integration inputs such as actuator activation and warm-start state. Profile, engine version, dimensions, signature, vector size and the public time/qpos/qvel/ctrl values are checked before the setter. The bridge never calls mj_forward during restore: forward computation can invoke control callbacks and overwrite warm-start inputs. The currently served public fields do not require derived contacts or sensor arrays to be recomputed. A subsequent ordinary step performs the engine's normal pipeline.

The mujoco_basic_v1 profile is an explicit fallback for incomplete native APIs and stand-ins. It restores the advertised time/qpos/qvel/ctrl fields, actuator activation, configured seed metadata and logical tick. It does not claim complete native integration state or exact continuation. Native time is retained without integer-millisecond rounding. The seed must equal the bridge's configured metadata; MuJoCo reset is not advertised as an RNG-seeding operation.

Checkpoint documents contain at most 32768 native values and 1 MiB of JSON. Values must be finite numbers, dimensions and counters must be integers rather than booleans, and extra/missing fields are refused. The bridge owns one model/data configuration; replacing it or changing its represented dimensions/timestep invalidates a checkpoint. The descriptor is not a compiled-model-content fingerprint. External code must not mutate the owned model, native data, callbacks or plugin configuration during the endpoint's lifetime.

The mjSTATE_EQ_ACTIVE segment has a narrower domain: each equality activation must be exactly numeric 0 or 1. The bridge derives that segment's offset and length from the native component mask and validates it before mj_setState. Fractional, negative, nonboolean byte values, oversized numbers and JSON booleans are refused. This prevents the native setter's numeric-to-byte conversion from receiving an invalid activation value; post-restore readback would be too late for that boundary. MuJoCo documents mjtByte as its boolean byte type; the versioned state setter performs the conversion.

The presence of a state API does not establish callback, plugin or external RNG completeness, deterministic physics across engine versions/architectures, or fidelity to hardware. The family therefore derives no exact/seeded determinism from API presence. A package may provide a separately justified fidelity declaration. Derived contact/sensor resources, external callback state, model editing, persistent cross-endpoint restoration and arbitrary asynchronous native APIs are outside this profile.

Snapshot/restore and world mutations share endpoint ownership. A caller deadline does not release a native worker's lock. Stop latching remains responsive, while unresolved native work cannot confirm that the simulation is safely paused or permit safety reset. Restore admission retains stop history through validation and rollback. An unexpected non-None setter completion fences future mutations and positive safety acknowledgements for that endpoint. A failed setter is not a pre-effect rejection: the endpoint must prove rollback or report an unknown outcome.

Existing MuJoCo packages need freshly generated reference.json and REFERENCE.md, because the new checkpoint field and conservative derived determinism change their public contract. Keep original attribution and human review fields unchanged, and rerun the package gate rather than reusing its historical digest.

The native-state semantics are described in MuJoCo's integration-state documentation. The versioned forward implementation contains the control callback and warm-start writes. These sources describe engine behavior; a successful controlled or isolated engine test does not establish every package's runtime configuration.