ScheduledSceneEnv public API — private FrozenEnv 상태 접근 없이 절대 timestamp 스케줄러 사용

TL;DR

API: ScheduledSceneEnv(candidate_path, candidate_complete_sha256) — reset, advance_to(timestamp_ms, camera=None, rgb=True, depth=False, segmentation=False), submit_joint_target({joint_targets(7), gripper_target}).
위임: advance_to는 FrozenEnv.advance_to_observation에 unchanged 위임. arm은 현재 시각, gripper는 now + delay_ms deadline에 큐잉. 물리를 직접 진행하지 않음.
검증: 실제 compiled candidate 5ms 공개 시퀀스 = 기존 FrozenEnv 스케줄러, 지연 gripper deadline 통과, mj_step wrapping으로 95 step (≤100) 확인.
Pin: 상속된 IntegratedSceneEnv bytes SHA-256 9b7a2c79… 고정.

mj_step count (한도 100)

joint target 차원

5 ms

테스트 시퀀스 간격

> 2^53

same-timestamp 정수 경계 테스트

1 배경 / 목적

절대 timestamp 기반 action replay(action-state 타이밍, gripper delay 검증)를 하려면 read/control/next-read 시각에 맞춰 물리를 진행하는 스케줄러가 필요하다. 이미 FrozenEnv에 스케줄러가 있었지만 caller가 private env._runtime.frozen을 직접 읽어야 해서 재현 가능한 공개 진입점이 없었다.

기존 한계: private 상태 접근에 의존하는 호출 코드는 scheduler 구현이 바뀌면 조용히 깨지고, 검증 계약(입력 범위·순서)이 caller마다 달라짐.

2 작업 내용

with ScheduledSceneEnv(candidate_path, candidate_complete_sha256) as env: env.reset(initial_state) env.advance_to(read_start_ms) env.advance_to(control_start_ms) env.submit_joint_target({"joint_targets": q_target, "gripper_target": grip_target}) result = env.advance_to(next_read_start_ms)

advance_to: 유한한 정수 ms만 허용(FrozenEnv 정수 보존 검증 그대로), pre-reset·역행 요청 거부, 동일 timestamp는 물리 진행 없이 허용. observation과 timing provenance 반환.
submit_joint_target: 정확히 7개의 유한 joint_targets + 범위 내 유한 gripper_target. shape/finite/control-range 검증을 큐 변경 이전에 완료. 물리를 진행하지 않고 command/timing/lag provenance만 반환.
의도적 비허용: future state, implicit reset, raw Cartesian action, controller/timestep/delay/candidate override.
candidate 경로와 complete SHA 계약을 유지하며 candidate를 채택하거나 scene/controller/physics/FrozenEnv 큐 구현을 변경하지 않음.

3 결과 (수치)

검증 (`tests/test_scheduled_scene_env.py`)	결과
실제 compiled-candidate no-render, 5 ms 공개 시퀀스 vs 기존 FrozenEnv 스케줄러	동일
지연 gripper deadline (`now + delay_ms`) 통과	확인
`mj_step` wrap으로 실제 scheduler 시퀀스 step 수	95 (≤ 100)
pre-reset / closed 호출, malformed·non-finite·boolean·역행·range-invalid·future-state 형태 action	모두 거부
> 2^53 same-timestamp 정수 경계	통과

경계: API usability만 확인했다. timing, physics, visual, Real-to-Sim scientific acceptance는 이 결과로 주장할 수 없다.

4 Takeaway

의미

action replay 코드가 private 상태 없이 검증된 단일 진입점을 쓰게 되어 호출 계약(입력 검증·순서·timing provenance)이 고정되었다. 상속 클래스 bytes를 SHA로 pin해 scheduler 구현이 바뀌면 감지된다.

5 Next Steps

미해결 한계

raw Cartesian action을 받지 않으므로 source IK bridge(260915 카드)와의 결합은 caller가 joint target으로 변환해야 함. scheduler 자체의 timing 정확도(control step 69–77 ms 대비 재현성)는 미검증.

다음 작업

(제안) 공개 API 위에서 recorded joint target을 replay하고, 기존 controller_physics_convergence 카드에서 FAIL이던 contact 이벤트 timing 10 ms gate를 재측정.