EPIC: make τ trustworthy — every consumer of an absolute latency can be one quantum wrong, undetectably

[mkovero]

why these are one epic

Nine open issues share one physical mechanism and one failure signature, and fixing them singly is how #363 happened: #347's guard shipped, looked correct, and manufactured confidence.

The mechanism. Latency on this stack moves in discrete quanta, and the quantum is invisible to the key meant to detect change:

• One JACK period, per client start. jack_iodelay on an unchanged leg: 4262.064 → 5286.064 frames. The fractional part survives untouched, identifying it as an integer number of periods added in software rather than anything analogue (τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347, rig 2026-08-18).
• One SYT interval — 16 samples at 96 kHz — per FireWire device enumeration: 1711 → 1743 after a host reboot, back to 1711 after a power cycle, 1727 the previous day (A stored τ can be 16 samples wrong the next session with every TauConditions field matching #461, pupu 2026-09-15/16).

TauConditions keys on device, backend, sample rate, period size and the port pair. Two readings a quantum apart share all six, so #281's refuse-on-mismatch design has nothing to refuse on.

The signature. Every issue below produces a number that is stable, repeatable, physically plausible, and wrong. None looks like a bug in the output. That is what makes them one problem rather than nine.

The scale. One period at 1024 / 96 kHz is 10.67 ms — 3.66 m of apparent path, larger than most geometry it would be used to measure. At period 256 it is 0.91 m. One SYT step is 5.7 cm.

measurements this epic rests on

fact	provenance	source
Round trip jumps exactly one period between client starts, per client, no config change	measured	#347, 2026-08-18
42 of 97 calibrate runs stored a value one period short — every one printed 2 readings agree	measured	#363, 2026-08-22, 96 kHz / 1024
24 plot_ir captures at a fixed mic position split into two clusters 1023 samples apart, each stable to ±1.5 samples	measured	#359, 2026-08-22
τ re-picks by a multiple of 16 samples per device enumeration, every condition field matching	measured	#461, pupu 2026-09-15/16
calibrate (argmax) and ir_stats (onset) no longer cancel: −0.093 m on a zero-path fake	measured	#351
A power cycle changes analog gain staging while ALSA readback reports the baseline (+6 dB, and +3 dB again on 2026-09-16)	measured	#466, docs/rigs/pupu.md

A constraint on all of it: the PipeWire mechanism behind #363 and #359 was removed from the rig on 2026-08-23, and no rig in reach reproduces the sticky one-period state today — 65 runs / 130 client lifetimes afterwards showed a single value, and pupu read 1711 on every reading on 2026-09-16. Operator, 2026-08-24: "it is very much to be expected that latency can jump… testing / awareness needs to be global enough to take this into account."

So guards written here must be verifiable without the fault present — by construction, or by synthetic injection — or the issue must say plainly that its acceptance is deferred until hardware exhibits it again. A green unit test on a FakeEngine proves nothing about a sticky state.

what is already solved, so it is not re-litigated

• ac calibrate cannot measure a τ larger than 13.1 ms, and does not say so #340 (closed 2026-09-16) — the τ window could not hold a large arrival and returned a pinned peak. Now a 100 ms window at n_harmonics = 1, with EdgeRefusal naming peak position, window length and half-width. calibrate measured 17.8229 ms on pupu, above the old 13.1 ms ceiling.
• estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 (merged a9281ac5) — the onset search's causal bound no longer reads a stored τ at all; it reads a reference leg captured in the same run. This is the first thing in the repo to follow τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347's own general remedy: a scheme that composes two separately-measured absolutes inherits the problem; one that measures a difference within a single client does not. Verified on pupu: bound enforced 5/5 at 2 m, and δ between the acoustic and reference pairs measured 0 samples across 10 captures spanning an FF400 power cycle.
• plot_ir's same-capture reference fails calibrate's 24 dB gate at default sweep parameters #471 (merged f7506dcd) — the reference leg's SNR gate is derived from its own stimulus, so that path stops refusing correct cables.

members

issue	what it covers	routing
#346	The arrival rule itself — argmax |h| reads late on a multi-way DUT; #460 made its causal bound reachable for the first time	ready-to-implement
#347	The two-reading corroboration mechanism for calibrate (correct mechanism; its independence assumption is what fails)	ready-to-implement
#350	TAU_MIN_HALF_WINDOW_S / TAU_EDGE_MARGIN_FRAC are assumed, not derived against a real noise floor	requires-rig
#351	calibrate picks with argmax, ir_stats with onset — they no longer cancel in arrival − τ	needs-design
#359	plot_ir's arrival inherits the jump with no corroboration; #347 guards only calibrate	needs-design
#363	agreement_count measures how long the state persisted, not whether the value is right	needs-design
#461	Stored τ re-picks per enumeration, undetectably	requires-rig
#466	Stored calibration (τ and level) used across events its key cannot see; state unknown rather than stale	—
#467	The capture path itself can start one period early (ring clear/enable race)	—

sequencing

#363 ─→ #347        (what "corroborated" may claim, before the mechanism is changed)
#363 ─→ #359        (same answer, applied to plot_ir's arrival)
#351 ─→ #346        (two consumers sharing a rule, before tuning either)
#461 ─→ #466        (the measured staleness, then the general per-session check)
#350                (independent; needs a rig session, not a decision)
#467                (independent; alignment, not trust — included because its
                     failure is indistinguishable from a one-period τ error)

definition of done

• No consumer of τ composes two separately-measured absolutes without either corroboration independent of the failure mode or an explicit uncorroborated state in the output and in the stored record.
• The word corroborated (and agreement_count) either earns its meaning or is replaced — calibrate stores a τ one JACK period short and calls it corroborated — 42 of 97 rig runs, every one labelled "2 readings agree" #363's 42/97 evidence is the bar it must clear.
• plot_ir's arrival carries the same protection as calibrate's τ, or states that it does not.
• calibrate and ir_stats share a picking rule, or their non-cancellation is measured and recorded rather than left to cancel by luck.
• Stored calibration reports unknown rather than a stale value across events the condition key cannot see.
• Each guard has a test that can fail without a rig that reproduces the fault, or the issue records why it cannot.

deliberately not included

No "settled decisions" section. #276 carried one, and two of its decisions had to be struck through when hardware contradicted them — decision 3 survived in the body for a month after a rig comment had already falsified it, under a heading saying not to relitigate. This epic carries measurements with provenance and nothing that outranks a later measurement.

Out of scope: room-acoustic parameters; the internals of #346's estimator; the metre, settled by #391.

[mkovero]

#363 is merged — ee58e616. Two members it gated are now unblocked.

calibrate no longer claims corroboration it cannot support. corroborated ×N, uncorroborated — single reading and N readings agree are gone; the output states evidence instead — how many lifecycles, how far apart, to what resolution they matched, what the graph declared, and the peak SNR:

  Delay:  4.4167 ms   424 samples   (measured, 96000 Hz, period 64)
          2 lifetimes 1.204 s apart, identical to the sample
          graph declared 244 samples (both lifetimes)
          peak SNR 41.2 dB pre-impulse, threshold 24.0 dB

A second, structurally different account is recorded alongside: JACK's declared path latency per lifecycle. Two lifecycles declaring different exact frame counts for one unchanged graph refuse with the new disagree_declared_latency state — no tolerance, and no threshold anywhere on measured − declared.

What it deliberately does not do, stated in the state's own ZMQ.md row so it is not re-derived: it does not detect the failure #363 documents. A shift the graph never declares stays invisible. Honest reporting was the answer, not a detector nobody can verify — no reachable rig reproduces the sticky one-period state any more.

what this settles for the sequenced members

• τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347 — the question "what may a τ line claim" is answered in merged code. Its mechanism (two lifecycles, refuse on a period-multiple disagreement) is correct and kept; what remains is its independence assumption, which calibrate stores a τ one JACK period short and calls it corroborated — 42 of 97 rig runs, every one labelled "2 readings agree" #363's 97-run evidence falsified. Whatever replaces it now has a vocabulary to inherit: state the separation, never the verdict.
• plot_ir's arrival inherits the one-period jump with no corroboration — #347 guards only calibrate #359 — the same answer applies to plot_ir's arrival, which still has no corroboration at all. The wire fields and the rendering convention now exist; only the producer side is missing.

newly open, from this work

Declared-latency false-positive check — queued in $AC_HOME/rig-verify-queue.md as "#363 / PR #476". Whether declared_latency_frames() can report two different counts across two lifecycles of one healthy, unchanged graph — i.e. whether the new refusal blocks calibration on a good rig. ≥30 back-to-back plus ≥30 spread-soak runs; falsified by any differing pair. The remedy is already decided and is not a tolerance: downgrade the gate to a reported field.

Epic status: 2 of 11 members closed (#363 here, #340 earlier today), 8 open, plus the rig check above.

[mkovero]

#461's FF400 power-cycle rig check is deferred to #529 (operator, 2026-09-17), so #499 can merge without waiting for a site visit.