feat(arena): add deterministic headless RL environments

src/transport/vehicleController.ts

@@ -257,6 +257,24 @@ export class VehicleController {
     return { ...this.current };
   }
 
+  /** Restore a trusted JSON snapshot for deterministic environment checkpointing. */
+  restore(snapshot: VehicleControllerSnapshot): void {
+    const numeric = Object.entries(snapshot)
+      .filter(([, value]) => typeof value === "number")
+      .every(([, value]) => Number.isFinite(value));
+    if (
+      !numeric || snapshot.routeId !== this.path.route.id ||
+      snapshot.direction !== this.options.direction ||
+      (snapshot.mode !== "manual" && snapshot.mode !== "assisted") ||
+      snapshot.distanceM < 0 || snapshot.distanceM > this.path.lengthM ||
+      Math.abs(snapshot.lateralOffsetM) > this.options.guardrailOffsetM ||
+      snapshot.speedMps < 0 || snapshot.speedMps > this.options.maximumSpeedMps ||
+      !Number.isSafeInteger(snapshot.elapsedSteps) || snapshot.elapsedSteps < 0
+    ) throw new RangeError("vehicle snapshot is incompatible or invalid");
+    Object.assign(this.current, snapshot);
+    this.accumulator = 0;
+  }
+
   /** Restore the configured spawn state and clear pending fractional time. */
   reset(): void {
     this.accumulator = 0;