feat(arena): add deterministic headless RL environments

src/actors/controller.ts

@@ -396,6 +396,24 @@ export class ActorController {
     return { ...this.current, identity: copyIdentity(this.current.identity) };
   }
 
+  /** Restore a trusted JSON snapshot for deterministic environment checkpointing. */
+  restore(snapshot: ActorControllerSnapshot): void {
+    const numeric = Object.entries(snapshot)
+      .filter(([, value]) => typeof value === "number")
+      .every(([, value]) => Number.isFinite(value));
+    if (
+      !numeric || !validKind(snapshot.kind) ||
+      (snapshot.mode !== "ground" && snapshot.mode !== "flight") ||
+      (snapshot.altitudeBoundContact !== "none" &&
+        snapshot.altitudeBoundContact !== "minimum" && snapshot.altitudeBoundContact !== "maximum") ||
+      !Number.isSafeInteger(snapshot.elapsedSteps) || snapshot.elapsedSteps < 0
+    ) throw new RangeError("actor snapshot is incompatible or invalid");
+    Object.assign(this.current, snapshot, { identity: checkedIdentity(snapshot.identity) });
+    this.applyHorizontalBounds();
+    if (this.current.mode === "flight" && this.current.kind === "crow") this.applyAltitudeBounds();
+    this.accumulator = 0;
+  }
+
   /** Replace profile/identity without changing kind, pose or position. */
   setIdentity(identity: ActorIdentity): void {
     this.current.identity = checkedIdentity(identity);