τ must be measured more than once: a single reading can be one period wrong with nothing to detect it

[mkovero]

spec

type: bug

depends on: #340 (same layer, different mechanism — that one is the window ceiling, this one survives fixing it)

problem statement

Round-trip latency for a fixed path on this stack varies by exactly one period between client starts, with no configuration change of any kind. Measured on the rig 2026-08-18 (work/rig/rig-243-343-results.md, PR #345), jack_iodelay on an unchanged leg:

4262.064 frames
5286.064      ← +1024.000
5286.063
5286.064

The fractional part survives the jump untouched, which identifies it as an integer number of periods added in software rather than anything analogue. It is per client, not per graph: at one point jack_iodelay measured its own clients at +1024 while ac-daemon's workers, minutes apart on the same machine, sat at the unshifted value.

Why this layer cannot see it

TauConditions (shared/calibration.rs:128-138) keys on device, backend, sample rate, period size, output port and input port. Two τ readings a period apart share all six. Nothing changed about the configuration, so there is no mismatch for the refuse-on-mismatch logic to catch, and #340's fix does not help: a measure_tau that refuses a pinned peak and admits a 50 ms round trip will still happily store a value that is 10.67 ms wrong at 96 kHz.

#281's premise — "τ is a property of (device, backend, sample rate, period size, port pair)" — is not quite true here. It is also a property of which client measured it, and when.

Within-run consistency proves nothing. Each state is internally stable to 0.001 frames. A measure_tau that sampled its own peak a hundred times in one worker would get the same answer every time and still be a period out.

acceptance criteria

• τ is measured more than once, in separate client lifetimes, and the calibration refuses rather than storing when the readings disagree. One reading is not a measurement of this quantity.
• The period quantum is used as the prior it is: a disagreement of exactly period_size samples is reported as this — a graph-buffering shift — and not as noise or as hardware drift. A disagreement that is not a multiple of the period is a different fault and should say so.
• The stored entry records how many readings agreed, so a reader can tell a corroborated τ from a single-shot one. An entry from before this lands must not be indistinguishable from one after.
• Test: two synthetic readings one period_size apart are refused, with the period named in the message. A test that only checks "readings differ" would pass on noise and miss the point.
• Whatever ac calibrate prints says which route produced τ and whether it was corroborated, per Interface latency (τ) captured during ac calibrate, with scoped validity and history #281's existing requirement that a reader a year later can tell.

stretch

• If a majority of readings agree and one is a period out, that is recoverable rather than fatal — but only with the disagreement recorded. Do not silently take the mode.

out of scope

• Fixing PipeWire. The instrument has to be correct on the stack it runs on.
• transfer_stream, which is immune and shows why: both legs live in one client for one session, so an added period is common-mode and cancels. It held 378 samples across three sessions and 378/378/379/379/379 across five more while this was happening. Any τ scheme that composes two separately-measured absolutes inherits the problem; one that measures a difference within a single client does not — worth weighing before more is built on the absolute.

files likely affected

• ac-rs/crates/ac-daemon/src/handlers/calibrate.rs — measure_tau
• ac-rs/crates/ac-core/src/shared/calibration.rs — the stored entry, if corroboration count joins it

needs architect review yes — it questions whether τ should be an absolute at all, which is #281's shape.

estimated complexity medium

Found while running #243. Related: #276 (settled decision 3 rests on the same false premise), #340.

[mkovero]

design decision

Revised 2026-09-16. The 2026-08-18 decision (option A: two readings, each in its own client lifecycle) shipped as #348 and still holds. It is kept unedited in the collapsed block at the end. What changed: the question is no longer how to build the guard. It is whether this issue still has code to write. #363 showed the guard's independence assumption fails, and #476 settled what the guard is allowed to claim. #475 lists #347 as ready-to-implement and says "before the mechanism is changed". This revision decides that no mechanism change belongs to #347, and gives the reasons. No PR is open against this issue, so no branch work is invalidated.

core question
All five acceptance criteria are on main (#348, #476), and the rig check on the exact-zero tolerance (2026-09-15, 49 runs / 98 lifecycles) did not falsify it. Does #347 still owe a change to how τ is measured, one that makes the two readings independent of a state that persists for seconds? Or is that work owned elsewhere, so that #347 should close?

acceptance criteria, checked against origin/main (ee58e616)

• Measured more than once, in separate client lifetimes; refuse on disagreement. measure_tau_twice (handlers/calibrate/tau/mod.rs). Disagreements return TauOutcome::Disagree, and stored_entry returns None for them. Met.
• A period-multiple disagreement is named as one; anything else is a different fault. compare_tau_readings / TauDisagreement::periods (ac-core/src/shared/calibration/tau.rs). The states are disagree_period_shift and disagree_other. Met.
• The stored entry records how many readings agreed; pre-τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347 entries stay distinguishable. TauEntry::agreement_count has #[serde(default)] → 0, and 0 renders as 1 reading, nothing compared (render_tau_history_leg_missing_agreement_count_reads_as_one_reading). fix: state τ's evidence instead of claiming corroboration (#363) #476 adds reading_separation_s and declared_latency_frames. Met.
• Test: two readings one period apart are refused, with the period named. Unit test tau_result_period_shift_disagreement_refuses_and_names_the_period (asserts tau_periods == 1 and "1 period" in the message). End-to-end test calibrate_reports_disagree_period_shift_end_to_end. Met.
• Output says which route produced τ and what backs it. Live output shows (measured, …), stored output shows measured <timestamp>, per Interface latency (τ) captured during ac calibrate, with scoped validity and history #281's "measured this run / loaded from cal" split. Since fix: state τ's evidence instead of claiming corroboration (#363) #476, what backs the value is written out as evidence (2 lifetimes 1.204 s apart, identical to the sample) rather than the word corroborated. Met.
• Tolerance (delta_samples == 0, provenance: assumed at the time). The rig run on 2026-09-15 on pupu (comment above) produced no false refusals at 48 kHz or 96 kHz. It stays assumed for any interface other than the FF400, and that limit is recorded there.

option A — close as delivered; the independence gap belongs to the consumers of τ
No code. Close #347. The remaining defect is that readings about 1 s apart are correlated by a state that persists for seconds. This mechanism cannot fix that: #363's design found no buildable detector for a shift the graph never declares. The one remedy the repo has proven is the one this issue's own out-of-scope note names: measure a difference inside one client, instead of combining two separately measured absolutes. #460 applied it to the onset bound. The places that still combine absolutes are the consumers of τ, and each has an open issue: #359 (plot_ir arrival) and #466 (stored calibration reused across sessions).
tradeoffs: ships nothing new, and keeps the gap owned by issues that can fix it structurally. It costs #475 one member that its table currently lists as open work.

option B — make the readings independent over time: N lifecycles spread over seconds
Spread three or more lifecycles over a longer wall-clock interval inside measure_tau_twice.
tradeoffs: no spacing can be derived, because how long the state persists was never measured and cannot be measured now (the PipeWire mechanism was removed on 2026-08-23; no rig in reach reproduces it). Any interval would be a guess, and nothing without the fault present could make it fail. That breaks #475's rule that a guard must be verifiable without the fault present, and it breaks the memory rule "ask what makes a check fail". It also makes every calibrate run slower.

rejected — probe at a second period size
The idea: in a second lifecycle, change the JACK buffer size, so that a one-period ambiguity moves. This is rejected. jack_set_buffer_size changes the whole graph, including other clients and the operator's jackd, and TauConditions keys on the period size, so the two readings would no longer describe the same stored entry.

rejected — the stretch goal (majority recovery)
Declined, not deferred. A shift that persists for seconds hits all readings in one run together, so a majority vote is exactly the correlated sampling #363 measured. It would store a value in the one case where the readings already disagree. The 08-18 decision already kept it out of scope. This revision declines it outright so nobody reopens #347 to build it.

recommendation
Option A. Every criterion this issue states is met on main. The defect that remains is correlation between readings, and inside one client lifecycle pair it cannot be detected or verified. The architecture already has a working answer to it, the within-client differential used by #460, and that answer is applied where τ is consumed, which is #359 and #466, not in calibrate.

affected modules

• none

file manifest
none. This decision closes the issue and authorises no code change. Any change to τ's mechanism needs a new issue with its own acceptance criteria.

interface changes
none

ZMQ protocol impact
no. The additive cal_done / tau_history fields from #348 and #476 are already documented in ac-rs/ZMQ.md. ac-cli renders them; ac-view and ac-scene read no tau_* field.

implementation notes for developer
Nothing to implement. For whoever picks up #359 or #466: measure_tau_twice is not the place to add independence. The model is #460's same-capture reference leg, which puts both legs in one client for one capture so that an added period cancels. On pupu, 10 captures spanning an FF400 power cycle measured δ = 0 samples.

scope
tier-1, unchanged. No code follows from this decision, so the label has no work attached to it.

risks

• EPIC: make τ trustworthy — every consumer of an absolute latency can be one quantum wrong, undetectably #475's table still lists τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347 as ready-to-implement: that table is prose, and the tracker holds the real state. Closing the issue is the record, so the table is not edited from here.
• Reading "closed" as "fixed": the bug the issue title describes, a single reading one period wrong with nothing to detect it, is fixed. A value that persists across both readings is not detected, and calibrate stores a τ one JACK period short and calls it corroborated — 42 of 97 rig runs, every one labelled "2 readings agree" #363 and ZMQ.md's disagree_declared_latency row say so. A rig tester should not expect calibrate to refuse a sticky shift the graph never declared.
• Tolerance on other interfaces: exact-zero is verified only on the FF400 (jackd -S, period 256). If a Babyface run refuses healthy readings, that is a new issue against this rule, which the 2026-09-15 rig record names as the next check.

original decision, 2026-08-18 (implemented as #348, still in force)

design decision

core question
How does ac calibrate get a second, independently-lifecycled τ reading in one run, and what rule decides agree / period-shift / other-disagreement?

option A — in-run double lifecycle (recommended)
After the loopback check, run measure_tau twice, each inside its own fresh eng.start() / measure_tau() / eng.stop() cycle (decoupled from the voltage-cal eng already used for steps 1–2). JackEngine::start() calls Client::new("ac-daemon", ...) fresh every time (jack_backend.rs:274) and stop() drops _async_client (:348-353) — so close+reopen is a genuinely new JACK client registration, which is exactly the boundary the bug lives on. Compare the two tau_s results with a pure function in ac-core; store only on agreement (or a recoverable-majority case, if the stretch goal is picked up later).
tradeoffs: self-contained — one ac calibrate call yields a corroborated τ or an explicit refusal, no operator ritual, no dependency on a possibly-stale prior entry. Costs ~2× the τ sweep time (~0.35 s each) per run with loopback detected.

option B — cross-run corroboration against tau_history
Compare each new single reading against the newest stored entry with identical TauConditions; only mark corroborated once two runs, possibly minutes or days apart, agree.
tradeoffs: zero extra runtime per call, and closer in spirit to the issue's own "minutes apart" reproduction. But the first ac calibrate for any device/port config has nothing to corroborate against, so it must either store an explicitly-uncorroborated single reading (reintroducing the exact silent-single-reading risk the issue is about) or refuse to store at all until the operator manually re-runs — which is the "one reading is not a measurement" failure mode restated as a process requirement instead of fixed in code.

recommendation
Option A, because it makes the corroboration guarantee unconditional on operator behavior — the acceptance criteria ask for "the calibration refuses rather than storing when readings disagree," and option B can't do that on a first run without either violating it or refusing to ever produce a usable τ for a new config.

affected modules

• ac-core/shared/calibration.rs — TauEntry gains a corroboration field; new pure comparison type/fn alongside tau_diff_fields/TauRefusal.
• ac-daemon/handlers/calibrate.rs — τ measurement becomes two dedicated engine lifecycles + comparator call; cal_done wire frame gains fields and new tau_state values.
• ac-cli/commands/calibrate.rs — print_tau_leg (live) and render_tau_history_leg (stored) both render the new field/states.
• ac-rs/ZMQ.md — cal_done schema doc update.
• ac-view — none; grepped, no tau_state/cal_done reference anywhere in ac-view/src.

interface changes
cal_done wire frame: additive tau_agreement_count: u32 (or equivalent name), and tau_state gains values beyond today's {measured, error, not_measured_no_loopback} — at minimum a period-shift-disagreement state and a generic-disagreement state, each carrying its own tau_error message. TauEntry (persisted, in cal.json and over the wire in tau_history) gains the same corroboration field, #[serde(default)] so pre-existing entries deserialize to 0 — never indistinguishable from a freshly-corroborated one. No CLI flags, no public fn signature changes outside these two files.

ZMQ protocol impact
Yes. ac-cli must render the new tau_state values and the agreement count (exact call sites named below). ac-view is unaffected — confirmed no reference to tau_state/cal_done in its source.

implementation notes for developer

• measure_tau() (calibrate.rs:72-97) stays single-shot per lifecycle, unchanged. Add an orchestration layer around it that calls it twice, each wrapped in its own make_engine(fake) → eng.start(...) → measure_tau(...) → eng.stop(), using the same out_port/in_port both times.
• Put the agree/period-shift/disagree decision as a pure fn in ac-core/shared/calibration.rs, next to tau_diff_fields — model it on TauRefusal::message()'s pattern of naming the delta rather than just saying "mismatch."
• TauEntry::agreement_count: u32 (or your chosen name), #[serde(default)]. Never write 1 — a lone reading is no longer a storable outcome at all; corroborated entries always store ≥2.
• Classification rule, derived directly from the issue's own data (+1024.000 exact, fractional part unchanged): work in whole samples — delta_samples = round((tau2 - tau1) * sample_rate). delta_samples == 0 → agree. delta_samples != 0 && period_size.is_some() && delta_samples % period_size == 0 → period-shift disagreement, name the period in the message (same style as tau_for_refuses_on_period_size_change_and_names_the_delta, which is the test shape to copy for the new "refuses on period-shift disagreement, names the period" acceptance test). Anything else → generic disagreement. — provenance: derived
• Agreement tolerance: no cross-lifecycle jitter data exists yet (rig data so far only shows within-lifecycle stability, 0.001 frame). Starting rule above uses exact-integer-sample agreement (delta_samples == 0); this may need a small tolerance band if real hardware shows sub-sample jitter across fresh lifecycles with no real shift. — provenance: assumed — flag for rig verification before hardening.
• Wire additions go in the same cal_done json! block (calibrate.rs:307-317) and the tau_history push (:294-301).
• CLI render call sites: print_tau_leg (calibrate.rs:204, live session) and render_tau_history_leg (:310, stored history) — both need the new field/state, modeled on the existing "(measured, {conditions})" suffix.

risks

• Window ceiling (ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340) still open: if true τ exceeds the ~13.1 ms window, measure_tau pins to the edge and returns a stable, repeatable, wrong number — both dedicated lifecycles will pin to the same edge and agree, laundering a wrong τ as "corroborated." Mitigation: this issue is already marked as depending on ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340; do not ship τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347 ahead of it, and add a test that a pinned-edge reading is not indistinguishable from a real agreement once ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340 defines what a pinned read looks like.
• Extra runtime: ~0.7 s added to every loopback-detected ac calibrate run. Acceptable — it replaces a reading that was flatly wrong some fraction of the time with no way to tell which fraction.
• Stretch goal (majority-vote recovery) is explicitly out of scope for this design — do not implement as part of ready-to-implement; it needs its own acceptance criteria if picked up later.

[mkovero]

what this output must communicate

1. τ in ms, this run — but only when it has survived the two-lifecycle check. A τ that has not is not a smaller signal, it is a different message: refused.
2. Whether the shown τ is corroborated (2+ independent readings agreed) or, on refusal, exactly how the readings disagreed — period-shift (software, name the period) vs anything else (different fault class, per issue body).

Current print_tau_leg/render_tau_history_leg show a single tau_s with no corroboration state at all — that's the gap #347 closes. Nothing in the existing render is spurious; it's incomplete, not noisy.

what to remove

Nothing removed. This is additive: one new clause on the agreement path, two new states on the refusal path, one new field in history.

proposed output

live cal_done, agreement (normal path):

  Delay:  1.1931 ms   (measured, 2 readings agree, 48000 Hz, period 128)

live cal_done, period-shift disagreement (this issue's case, rig data):

  Delay:  not measured (2 readings disagree by exactly 1 period)
          4262.064 samples → 5286.064 samples  (Δ 1024 samples = 10.6667 ms at 96000 Hz)

live cal_done, generic disagreement (not a period multiple — different fault):

  Delay:  not measured (2 readings disagree, not a period multiple)
          4262.064 samples → 4290.500 samples  (Δ 28.436 samples = 0.2962 ms at 96000 Hz)

stored history (ac calibrate show), corroborated entry:

    Delay:  1.1931 ms   (measured 2024-06-15T12:00:00Z, 2 months ago, corroborated ×2)
            jack, dev 0, 48000 Hz, period 128
            system:playback_3 → system:capture_1

stored history, pre-#347 entry (agreement_count absent, deserializes to 0):

    Delay:  1.1931 ms   (measured 2020-01-01T00:00:00Z, 5 years ago, uncorroborated — single reading)
            jack, dev 0, 48000 Hz, period 128
            system:playback_3 → system:capture_1

Continuation lines indent 10 spaces (" " + "{:<8}" = the existing label column width), matching the alignment discipline render_tau_history_leg already uses for its condition/port lines.

field justifications

• 2 readings agree / corroborated ×2: the entire content of this issue — a τ shown without this clause is indistinguishable from the single-shot reading that was wrong 1 period out. Must be on the same line as the value, not a separate field a reader can miss.
• 4262.064 samples → 5286.064 samples: shown verbatim, not compressed to a delta. The fractional part staying identical across the jump is the exact diagnostic clue the issue body uses to prove this is software, not analogue drift (tolerance-for-the-minute — the evidence, not just the conclusion, is the signal here).
• Δ 1024 samples = 10.6667 ms at 96000 Hz: both domains needed. Samples is the causal unit (period-quantized, integer); ms is what an operator holds in their head. Neither alone lets a reader verify "exactly one period" without doing the arithmetic themselves.
• by exactly 1 period / not a period multiple: acceptance criteria require the period named in the message, and the two disagreement causes to read as different faults, not both as generic "mismatch." A reader must not have to open cal.json to tell them apart.
• uncorroborated — single reading (vs blank) on old entries: acceptance criteria say an old entry "must not be indistinguishable from" a new one. Silence would be indistinguishable; this is not.

before / after

before:
  Delay:  1.1931 ms   (measured, 48000 Hz, period 128)

after:
  Delay:  1.1931 ms   (measured, 2 readings agree, 48000 Hz, period 128)

removed: nothing
added:   corroboration clause on the agreement path; two new refusal renders
         (period-shift, generic) with both raw readings and the delta in
         samples and ms; corroboration/uncorroborated marker in stored history
changed: nothing reformatted — insertion only, existing alignment held

open questions

• ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340 (window ceiling) risk noted by architect: two lifecycles pinned to the same window edge will agree and render as corroborated ×2 with a wrong τ. This design cannot distinguish that case from a real agreement — the CLI has no signal to render that ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340 hasn't defined yet. Not blocking this issue (already sequenced behind ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340), but the eventual pinned-edge state will need its own render pass once ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340 lands; flagging so it isn't assumed covered by this one.
• Everything else here fits the existing cal_done/tau_history schema additively — no wire-schema ambiguity, so no needs-discussion.

Proposal is concrete and complete (every field justified, literal renders shown) — removing needs-ux.

[mkovero]

Reopening under requires-rig: the code half merged as #348, but the acceptance rule it ships — τ readings must agree to exactly zero samples (delta_samples == 0, no tolerance band) — is still architect-tagged provenance: assumed — flag for rig verification before hardening, with no measurement closing it. QA withheld on this in all three review passes and it merged unchanged.

The only evidence today is the fake backend disagreeing with itself on demand (AC_FAKE_TAU_DELAY_SAMPLES_OVERRIDE, added by #348), which proves the refusal path fires, not that the tolerance is right.

Measurement that settles it: ≥10 ac calibrate runs on the rig, both within one client lifetime and across daemon restarts, at 48 and 96 kHz. Falsified if delta_samples is nonzero on runs with no configuration change — #345 already measured a one-period shift between client lifetimes, which is exactly the case an exact-zero rule refuses.