Physics Author-Trainer Launcher¶

Status: target launcher contract; cli.pipeline.mimic, mimic.run, pipeline/physics/mimic/ and old mimic YAML/tests are still present pending migration and must not be used for formal runs. Experiment authority: Physics Studio Author-Fidelity Plan.

Entry point¶

正式入口只有：

python cli/pipeline/physics.py \
  --config <method-config.yaml> \
  --case-json <case.json> \
  --result <result.pt> \
  --output-dir <new-run-dir> \
  --mode train

在 root backends 仍含 generic trainer 时，该命令只可用于 interface_sanity_only，不得启动 formal job。Author-trainer fidelity gates 通过后才切换 formal launcher。

Job contract¶

一个 job 固定：

one method identity/fidelity class；
one case；
one seed；
one author config digest；
one GPU UUID；
one independent output/cache/Torch-extension path。

Root launcher 只管理 process lifecycle、GPU assignment、manifest 和 exit status，不实现 trainer/network/PPO。Thin backend 只调用冻结的 author entrypoint/coordinator，并提供可序列化 canonical/config descriptors 与窄 env factory；author Task/VecEnv factory 在作者预期时点创建当前 simulator process 唯一的 IsaacEnv。

RePHO root backend 只调用冻结的作者 official coordinator。Forward/backward topology、启动顺序、文件交换和 repair schedule 由该作者链决定；每个实际 simulator worker 创建自己的 IsaacEnv，不能跨进程传 live env。

Manifest¶

Formal gate 先冻结只读 fidelity_gate.json，记录 method identity、已通过的 author execution/parity/pilot gates 和批准的 code/config digests。每个 job 在运行前写 immutable scheduled_job.json：

fidelity_gate.json 必须通过 machine schema，status 必须由 validator 写成 passed，并包含 formal manifest digest、author-fidelity manifest digest、exact reviewed patch digest 以及每个 required gate 的 true。任一 TODO/unknown/missing、source/config/ checkpoint mismatch、actual diff mismatch 或 required gate false 都不能生成 passed gate。

{
  "run_kind": "studio_author_trainer",
  "protocol": "studio",
  "fidelity_class": "author_algorithm_preserving",
  "method": "coda",
  "case": "case_id",
  "seed": 42,
  "fidelity_gate": {"path": "fidelity_gate.json", "digest": ""},
  "command": ["python", "cli/pipeline/physics.py"],
  "input_digests": {},
  "config_digests": {},
  "code_digests": {},
  "gpu_uuid": "",
  "conda_export_digest": "",
  "output_dir": ""
}

Formal job 只有在引用的 fidelity_gate.json 已批准后才能排期。 eligible_for_formal 不出现在 scheduled input 中；它只能由统一 validator 根据完整 provenance/runtime chain 推导，launcher 与 aggregator 都重算，不能由 run 自报。进程结束后另写一次性的 attempt_status.json，包含 exit/status/wall time、actual transitions、checkpoint/output digests 和 failure details；失败 job 仍保持 formal eligibility，但按协议计 Fail。

Digest 依赖固定为单向：

author-fidelity manifest + reviewed patch
  → formal manifest
  → fidelity gate
  → scheduled job
  → run records + outputs
  → attempt status

每层只 hash 上游。attempt_status.json 可以 hash run records/outputs，run records 不能 hash attempt_status.json。

历史 generic output 使用 run_kind=interface_sanity_only、 trainer_kind=generic_studio、eligible_for_formal=false。

Monitoring¶

每 15 分钟检查 process、author outer/global step、TensorBoard mtime 和 GPU；
每个 method/case 预先冻结 hard timeout；
crash、NaN、stall 或 timeout 记录后停止，不自动 retry；
重跑必须新建 manifest entry 和 output directory；
launcher 不复用“最近 checkpoint”或成功 run。

Outputs¶

<case>/<method>/<seed>/
  train/
    checkpoints/<author-native files>
    tensorboard/<author-native event files>
    <author-native resumable state>
    run_record.json
  eval/
    humanoid.xml
    common_rollout.npz
    evaluation.json
    run_record.json
    replay.mp4
  fidelity_gate.json
  scheduled_job.json
  attempt_status.json

run_record.json.checkpoint_set 保存每个 selected checkpoint 的 role/path/digest；RePHO 至少包含 forward/backward。禁止复制成统一 final.pt，禁止 native rollout、renderer sidecar 或 method-specific object asset 进入 eval output。

Completion¶

Launcher 只有 process-level completed/failed；common evaluator 对已排期 method run 只有 Success/Fail。Crash/timeout/missing rollout 映射为 Fail 并保留在 formal 分母。 Available、自动跳过和只收集成功 output 都不允许。