profiles.JointCalibration persists REPORTED ticks while its docstring says raw — every profile written before the elbow re-zero is silently wrong by ~1071 ticks

[OriNachum]

The bug

arm101/hardware/profiles.py:JointCalibration persists per-joint encoder tick limits to disk. Its docstring says:

Raw STS3215 encoder tick limits for a single joint.

They are not raw. They are read straight from read_position, which returns reported ticks — (raw - Ofs) mod 4096, a view through the servo's current homing offset.

Why it matters right now, on our arm

elbow_flex has been re-zeroed (Ofs 85 -> 1073, PR #40/#41, hardware-confirmed). So any calibration profile captured before that re-zero is now wrong by ~1071 ticks for that joint — and nothing anywhere says so. The file loads clean, the numbers look plausible, and they name different physical angles than they did when they were written.

This is the same class of bug the arm limits spec exists to eliminate (#43), sitting in a second place with a longer fuse.

The fix

Persist raw ticks. Raw ticks are invariant under a re-zero — the offset changes, the encoder does not. That eliminates the failure mode rather than detecting it. arm101/hardware/ticks.py (landed in wave 0 of the #43 build) is the conversion boundary to route through.

An existing profile on disk cannot be migrated blind, because the offset it was captured under is not recorded. Two honest options, to be decided when the fix is built:

1. Refuse a profile with no recorded calibration and require re-capture. Loud, safe.
2. Add the offset to the persisted format going forward, and treat pre-format profiles as unknown-frame.

Silently reinterpreting old numbers as raw is not an option — the elbow's would be wrong by ~1071 ticks.

How it was found

Task t1 of the #43 build, while establishing the one-conversion-boundary rule. It is pinned as a known-outstanding site in _PERSISTED_TICK_SITES (tests/test_tick_frames.py), which has a discovery guard — a new tick table that is not classified fails the test — and a backlog that can shrink but never grow. So this cannot be forgotten, only fixed.

Related: #43, #35

[OriNachum]

2026-07-13 — still live, and the blast radius is now bigger than when this was filed

arm limits (PR #48) shipped, and hardware confirms the raw-vs-reported hazard this issue names
is not hypothetical:

• elbow_flex is re-zeroed on the bench right now — its live offset is 1073, not the
  factory 85. Every REPORTED tick recorded for it before that re-zero is off by ~1071.
• Three more joints turn out to wrap the seam and are re-zero candidates (shoulder_pan
  arc 3330, gripper arc 2587 — both measured this session, see elbow_flex and wrist_roll encoders wrap — a [min, max] range cannot describe them, and gentle_move cannot converge across the seam #35). If any of them is ever
  re-zeroed, every REPORTED tick persisted for them silently becomes wrong too.

The fix direction chosen for the limits work is the one this issue should follow:
persist RAW ticks. Raw is invariant under a re-zero; reported is a view through whatever
offset happens to be in the register right now. That eliminates the staleness problem rather
than trying to detect it — no calibration identity needed. See arm101/hardware/ticks.py
(the single reported<->raw boundary) and arm101/hardware/soft_limit_store.py (which already
persists RAW) for the pattern to copy.

Related: #43 (parent), #51, #52.