longTauGnssCoupling: coast-cap + graded-taper (primitives + scheduler + engine)

[bobvan]

Summary

Bounds the adaptive coast interval by the DO's stochastic wander, not just the deterministic drift budget τ=√(2·T/D). Targets the tau~64–256 s long-tau TDEV hump (2026-05-29 overnight: PiFace 6.4 ns @ 64 s, MadHat 3.6 ns @ 256 s) where a quiet DO (D≈0) pinned τ at max_interval and coasted blind while its random-walk wander accumulated — exactly where the GNSS reference is at its best.

Squash of the reviewed stack (per Bob, fewer merges): #80 primitives (Charlie-approved) + #84 scheduler wiring + #85 engine wiring. Those three are closed in favor of this PR.

Primitives (discipline.py, pure)

• coast_cap_from_tdev — invert a power-law freerun TDEV; ~138 s for an 85 ps OCXO, <1 s for a 1.17 ns TCXO; slope≤0 → +inf (no cap).
• coast_cap_from_p22 — largest τ with k·√(P22(τ))≤budget, P22 from a caller closure; variance-space compare with a boundary epsilon.
• normalized_distance_to_lock — √(P22)/σ_total → [0,1] (0=locked, 1=far); the single derived signal every policy reads.
• graded_interval — geometric taper replacing the binary 1 if converging else interval latch + its 1→120 s cliff; continuous + monotone (can't chatter).

Scheduler (compute_adaptive_interval)

All baseline paths flow through a coast-cap + taper tail. coast_tdev ctor arg → TDEV cap; p22_at_tau (per-call) → P22 cap; distance_to_lock (per-call) → taper. The quiet-DO branch (the exact over-coast) now gets capped.

Engine (--coast-cap, default off)

• do_state.derive_coast_tdev_from_char — log-log fit of the DO freerun TDEV curve → (tdev_ref, slope, 1.0).
• DOFreqEst.project_p22_coast — predict-only P[2,2] table, one O(max_tau) projection/epoch.
• --coast-cap → coast_tdev from char into the scheduler ctor + per-epoch p22_at_tau closure; --coast-cap-k-sigma confidence factor.

Scope / dependencies

• Wires the coast-cap (tdev + p22). The graded taper hook is implemented + tested but the engine doesn't pass distance_to_lock yet — deferred to disciplineModeFsm (which defines the convergence metric + thresholds). Main DOFreqEst path only; CM_TDC unchanged.
• The p22 cap is honest only with Q-from-char (qFromCharPerActuator, separate PR qFromCharPerActuator: derive Q[3,3] (sigma_do_freq) from char ADEV #83) — merge that first; an inflated Q over-grows P22 and caps the coast spuriously short.
• After qFromCharPerActuator: derive Q[3,3] (sigma_do_freq) from char ADEV #83 merges, expect a trivial import math dup-conflict in do_state.py (both add it) — resolve by keeping one line.

Test plan

• 48 tests (coast-cap unit + scheduler integration + TDEV-fit + project_p22_coast). Default-off / byte-identical when --coast-cap absent. Full suite 1428 passed; both flags in --help.
• closedLoopServoSim A/B (Charlie) on honest Q[3,3] (qFromCharPerActuator: derive Q[3,3] (sigma_do_freq) from char ADEV #83): --coast-cap on vs off — hump drops, >60 s coast no longer diverges.
• Lab A/B on PiFace/clkPoC3 after the sim validates (Main coordinates).

🤖 Generated with Claude Code