Frame audit: declare the EE frame every checkpoint we serve speaks

[vertix]

Split out of #483, whose "Frame audit" work item #485 does not do. #485 builds the mechanism and deliberately
leaves every shipped deployment unset: "Zero impact when unused — no ee_frame declared → bit-for-bit today's
behaviour. Every shipped deployment is left unset pending the per-checkpoint frame audit." This issue is that
audit, so the item does not vanish when #485 closes #483.

Background

After #485 every embodiment anchors on a frame named default: its model declares it, its driver reports
robot_state.ee_pose in it and accepts Cartesian commands in it. A checkpoint states the frame it speaks as
a Transform3D measured from default, and ChangeEEFrame(T) converts at the boundary — observations forward
(pose * T), commands back (pose * T⁻¹).

Two places declare it, and they are for different jobs:

• Training — cfg.codecs.compose(ee_frame=T) re-expresses the dataset and stamps ee_frame into the
  episode statics, so the checkpoint is trained in T.
• Serving — openpi.server.pipeline(ee_frame=T) prepends ChangeEEFrame(T) outermost, so the wire and the
  server-side codec see poses already in T.

Setting neither is correct for a checkpoint trained in default, and for any checkpoint that speaks joints.
Setting the wrong one is silent: the arm goes to the wrong place, nothing errors, the eval score is just worse.

What needs deciding

For each checkpoint we serve: does it speak default, or a transform from it?

Deployment	Pipeline	Space	ee_frame today	Needs a decision?
phail	ee	EE	unset	Yes — trained on the phail dataset under the flange convention; correct today only because default coincides with the Franka tool frame. #550 moves default to the flange and breaks that coincidence.
sim_stack	ee_flip_grip	EE	unset	Yes — trained on sim recordings; the sim panda's default sits 45 mm from the FR3's along the approach axis (#485, "Known limit").
libero	libero_pipe	EE	unset	Yes, and blocked on #557 — LIBERO's gripper0_grip_site is 38.1 mm and 90° from what bundled_panda_model() calls default, so its episodes mislabel their poses before any checkpoint frame enters the picture.
droid	droid_pipe	joints	unset	No — droid_obs carries joint_position and gripper_position only, action is joint_delta_action. No pose crosses the wire.
droid_jointpos	droid_jointpos_pipe	joints	unset	No — same observation codec, absolute_joints_action.

The bare pipelines with no checkpoint bound (ee, ee_joints, ee_traj, ee_joints_traj, joints_traj,
ee_flip_grip) inherit whatever the operator passes, so they need documentation rather than a value.

An EE-space DROID checkpoint is the case #483 was opened for and the one we do not currently serve. Serving
one means openpi.server.pipeline(ee_frame=models.DROID_EE_FRAME); there is no shipped config for it, so it is
a hand-wire that someone has to remember.

The other half: nothing enforces agreement

ChangeEEFrame.meta publishes ee_frame in the session handshake, so the rig is told what frame it is being
served in. Nothing compares that against what the checkpoint was trained in. #483 requirement 2 asks for
exactly this — "the checkpoint itself declares what frame it speaks; nobody re-states it at serving time" — and
today the serving config re-states it. A serving pipeline that declares the wrong transform, or omits one the
training run set, fails silently.

Deciding whether the checkpoint's stamped ee_frame should reach the server (via ModelSource.meta, which
already carries per-model handshake facts) and be checked against the pipeline's declaration is part of this
work.

Only OpenPI has the knob

positronic/vendors/lerobot/server.py:58 and positronic/vendors/gr00t/server.py:321 build their pipelines
with no ee_frame parameter at all. Any EE-space checkpoint served through either cannot declare a frame.

Work items

• Assign the correct frame to each EE-space deployment above; set it, or record in the config comment why
  unset is right
• Decide whether the checkpoint's trained ee_frame should be carried in ModelSource.meta and checked
  against the serving pipeline's declaration
• Give lerobot and gr00t pipelines the same ee_frame parameter, or state why they do not need one
• Re-audit after Move Franka's default frame to the flange and migrate existing datasets #550 lands — it moves default to the flange, which changes the correct value for every
  EE-space checkpoint trained before it

[vertix]

phail and sim_stack answered: leave ee_frame unset.

Both were collected with positronic/data_collection.py — sim_stack through main_sim (MuJoCo), phail on the real Franka. Neither applies any conversion: the poses recorded are whatever each rig reported as its end effector, which after #485 is that rig's default. A checkpoint trained on those poses speaks default, so it declares no transform.

That holds on one condition: each is served on the rig it was trained on. The FR3's default and the sim panda's sit 45 mm apart along the approach axis (#485, "Known limit"), so serving sim_stack on the real arm — or phail in sim — is off by that much, and unset stops being the right answer. #550 removes the divergence by moving both to the flange, and re-opens the question for every checkpoint trained before it.

Remaining open: libero, which is blocked on #557.

Also worth knowing before setting any of these for real: the server's own recording_dir taps at the wire boundary (rec.tap('raw'), positronic/offboard/server.py), which is after the rig-side half runs. A pipeline-level ee_frame therefore changes what server-side inference recordings contain — correctly labelled, since the episode carries ee_frame too, but different from today. Rig-side harness recordings are unaffected.

[vertix]

lerobot and gr00t answered: no gap. Both serve only phail checkpoints, trained on phail data, which sits in the rig's default (see the comment above). There is no frame to declare, so the missing ee_frame parameter costs nothing today. It becomes real the first time either serves an EE-space checkpoint trained in another frame.

Direction for carrying the frame: derive, not check.

Two shapes are possible once a checkpoint records the frame it was trained in:

• Check — the serving config keeps stating the frame; the server compares it against the checkpoint's and refuses to start on a mismatch. Two configs still, but disagreement is loud rather than silent.
• Derive — the serving config states nothing. The server reads the frame off the checkpoint and installs the conversion itself.

Derive is what #483 requirement 2 asks for: "the checkpoint itself declares what frame it speaks. Nobody re-states it at serving time; there is no second config to forget."

It does not remove every serving-side decision. Where the conversion runs — rig-side, before the wire, or server-side — is a property of the deployment, not of the checkpoint: it decides who does the math and what the wire carries. So a pipeline would still say convert here, just not convert by this much.

Two hops are missing before either shape is possible, and they are the actual work:

1. Training does not record the frame anywhere durable. The dataset knows it — ChangeEEFrame's training encoder stamps ee_frame into every episode's statics — but nothing in the openpi, lerobot or gr00t training paths copies it into the checkpoint directory.
2. The handshake hook exists but does not carry it. ModelSource.meta(model_id) is the documented home for static per-model facts; OpenpiSource publishes type, config name, checkpoint path and experiment name. The trained frame belongs in that dict.

Old checkpoints record no frame, so whatever lands needs a defined answer for "the checkpoint does not say" — today's behaviour, i.e. no conversion.

[vertix]

Retracting the comment above: neither check nor derive is possible.

Both assumed a checkpoint can carry the frame it was trained in. It cannot:

• Third-party checkpoints are most of what we serve — pi05_droid, pi05_droid_jointpos and pi05_libero all come from published gs:// dirs. Nothing will ever put a frame in them.
• For our own, we do not own the training script that writes the checkpoint, so there is no hook to stamp one.

So #483 requirement 2 — "the checkpoint itself declares what frame it speaks. Nobody re-states it at serving time; there is no second config to forget" — is not achievable as written, and the ModelSource.meta work item above is void. The frame is knowledge about a checkpoint that lives outside it, and always will.

What is achievable. The frame belongs with the thing that already names the checkpoint: the deployment entry. In positronic/vendors/openpi/server.py that is the COMMANDS block, where each deployment sets source.checkpoints_dir — checkpoint identity and frame in one override, so they cannot drift the way two independent configs can. That is already where a frame would be set today; nothing needs building.

The residual exposure is different from what this issue first described, and smaller: nothing verifies that a stated frame matches how the checkpoint was actually trained. For a third-party checkpoint that is irreducible — the answer comes from a paper or a README, not from any artifact we hold.

What can still be closed off is forgetting rather than disagreeing. openpi.server.pipeline defaults ee_frame=None, so a new EE-space deployment that says nothing silently gets no conversion. Dropping the default would force every deployment to state its frame — None for a checkpoint that speaks default, a transform otherwise — making the omission impossible instead of silent. That is a config change across the ~10 COMMANDS entries, and is the concrete option this issue should carry.

[omnilink-tech]

I built a small frame-contract proof against the Panda URDF that this repository ships.

The proof pins the source file by SHA-256 and records these fixed transforms:

• link7 -> hand: [0, 0, 0.107], yaw -45 deg
• hand -> end_effector: [0, 0, 0.0584], no rotation
• the declared default frame is end_effector, so default -> tool is identity

It evaluates three joint configurations. The declared transform composes to the same world TCP with 0 m maximum translation error and 1.21e-6 deg maximum rotation error.

I also used the offset measured in #557 as a negative control: [0, 0, 0.0381], yaw -90 deg. That run fails with 38.1 mm and 90.0 deg world-TCP error, as expected.

The public proof is on this branch. It includes the contract fixture, verifier, and focused tests. The normal command exits 0, and --negative-control exits 1. The focused tests, Ruff, and BasedPyright pass.

I also imported a path-normalized proof copy into OmniSim's CPU MuJoCo path. It finalized and stepped with 0 errors. For that load only, I added the hand inertia from the same Apache-2.0 panda.xml; the frame transforms stayed unchanged. I did not treat the source IK/viewer asset as a collision-physics model.

PR #583 already makes each OpenPI deployment state its frame. I have not opened another PR because #550 and #557 still require a convention choice.

Question: should this fixture keep hand as a named flange proxy, or should the accepted contract identify it as the Panda flange before #550 moves default?