estimate_onset's causal bound is unreachable: no producer ever records position.distance_m

[mkovero]

problem

MeasurementReport::ir_stats() (#346, PR #352) passes estimate_onset a causal lower bound — the earliest sample pure flight time admits — only when the report carries both a measured τ and position.distance_m:

// ac-core/src/measurement/report/ir_stats.rs, on PR #352's branch
let min_admissible_index = match (
    &self.interface_latency,
    self.position.as_ref().and_then(|p| p.distance_m),
) {
    (Some(InterfaceLatency::Measured(tau)), Some(distance_m)) => { … Some(…) }
    _ => None,
};

Nothing that runs outside a test ever sets distance_m. Read at 298f77dc (PR #352 tip, main merged in):

• ac-daemon/src/handlers/audio/plot.rs builds PositionSnapshot at lines 224, 548 and 954 — all three from temperature_c alone, ..Default::default() for the rest.
• Every distance_m: Some(…) in ac-core (report/provenance.rs:348, report/ir_stats.rs:673, report_html/mod.rs:443, report_pdf/mod.rs:313,523, report_layout/sections.rs:302) is inside that file's #[cfg(test)] module.
• ac-cli has no distance argument, config key or plumbing for plot ir.

So on real hardware min_admissible_index is always None, and every capture takes estimate_onset's unbounded ONSET_SEARCH_WINDOW_S path. The bounded path — the one #346's AC1/AC3 causality rejection and PR #352's "on the rig geometry is recorded" reasoning rest on — is exercised by unit tests and by nothing else.

evidence from the rig

#378 AC6, pupu, 2026-09-15 (record on PR #352): 48 acoustic and 10 loopback ac plot ir captures, all unbounded. On the electrical loopback, where onset and peak should nearly coincide, the pick landed 358 samples before the peak on every capture — the unbounded window reaching into the band-limited main lobe's leading skirt. A causal bound is exactly what PR #352 says rejects that; it never ran.

why it matters

This is the silent-config shape: a correctness guard that exists, is tested, reads as active in the code and the PR description, and does nothing on any real measurement. No output says the bound was skipped for want of a distance — onset_rule records "no causal bound", but nothing tells an operator that a distance could have been supplied, because it cannot.

It also means no rig session can currently test the bounded estimator at all: AC6 scored the unbounded path because that is the only one reachable.

acceptance criteria

• An operator can record mic distance for a plot ir capture, and it reaches the persisted report's position.distance_m.
• With a measured τ and a recorded distance, a rig capture's onset_rule shows the causal bound enforced — verified on a real capture, not only a fixture.
• When the bound cannot be applied, the operator-facing output says which input was missing (τ, distance, or both), not only that no bound was enforced.
• Test: a plot_ir round trip through the daemon with a supplied distance produces a report whose ir_stats() has min_admissible_index.is_some(). A test that builds PositionSnapshot by hand would pass while the producer still drops the field.

out of scope

• Whether the bound fixes the onset's distance bias on real hardware — the onset threshold is referenced to a pre-impulse statistic, which cannot see the DRR term that dominates its distance bias #378 AC6 shows the unbounded pick fails; whether the bounded one passes is a new rig question once this lands.
• Deprecate the metre: remove every ms → distance conversion, keep flight time #391's removal of ms → m read-outs. This is an input to a causality check, not a distance display.

related

#346, #352, #378 (AC6 record), #351 (τ rule on the other half of the same bound), #283.

[mkovero]

design inputs before this is built — operator wants a real fix for #346, so this is now on the path

The operator has asked for a real fix for #346 (absolute arrival), not a relabel. That puts this issue on the critical path. Three things the design has to settle, collected from the 2026-09-15 rig session. No answers are proposed here.

1. Where the bound's τ comes from — #461 makes a stored τ unreliable.
The bound is centre + (τ + d/c)·fs. On pupu, the same electrical loopback read τ = 17.9896 ms on 2026-09-14 and 17.8229 ms on 2026-09-15: 16 samples apart, every TauConditions field matching, not the build, not a JACK restart (#461). Tape adds about ±14 samples at 96 kHz (±5 cm). A bound built from a stored τ is therefore good to roughly ±30 samples, with a between-session error nothing detects.
An option the evidence supports, for the architect to accept or reject: capture the reference loopback simultaneously in plot_ir (pupu has AN2 → IN2 wired), so the interface round trip is measured in the same client lifetime as the acoustic IR and no stored τ enters the bound. Within one session the loopback arrival was sample-identical across 10 captures and both positions. #345 first raised this ("either the Farina path captures a reference simultaneously…"). #276 settled decision 3 rejected it before the period-jump and #461 data existed.

2. Where the distance comes from, given #391.
#391 deprecated the metre as an output. The bound needs a distance as an input, for a causality check rather than a display. Does an operator-entered distance fit #391, and on which surface (CLI token, ac setup, report provenance)? Also: the bound feeds a distance into the measurement that was partly meant to yield a path. What claim can the resulting onset support once the bound depends on the tape?

3. The search window, from #378 AC6.
Without a bound, the AIC pick landed 492 samples (1 m) and 628 samples (2 m) before the peak, and 358 before the peak on an electrical loopback. That is inside the 10 ms ONSET_SEARCH_WINDOW_S, in the band-limited deconvolution's leading skirt. With a bound, the window's lower edge is the bound. Does ONSET_SEARCH_WINDOW_S still need to exist, and what happens when no distance is given: decline, or peak?

Acceptance for whatever is chosen stays as filed above. The addition that matters: a rig capture with the bound enforced, scored c-free against transfer_stream on the #378 AC6 geometry (1 m / 2 m on-axis). Pre-register the rule on the PASS branch only (FAIL: Δ > max(3·se, cap)), per the defect found in the AC6 rule.

[mkovero]

design decision

Revision 2, 2026-09-15. This comment supersedes revision 1 (21:05) in place, after the operator brought option C into scope (developer comment 21:45) and the rig measured the stored-τ error (rig comment 21:06, #461 tests A and B). Read at origin/main = 340f1c55. No PR exists for #460, so no branch work has to be undone.

What changed from revision 1:

• τ source. The causal bound no longer reads the stored τ (interface_latency). It reads only a τ measured from a loopback reference recorded in the same capture. Revision 1 rejected this as "out of estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460's scope"; the operator overruled that, and the evidence supports the overrule. A stored τ re-picks 1711 + 16k samples on every device enumeration, which is larger than the bound's 55-sample margin.
• No-reference behaviour. Without a reference, the bound is not enforced, and the output names the reference as the missing input. The design does not fall back to stored τ. Stored calibration is used across device restarts that invalidate it — check τ and level per session, refuse when stale #466 owns stored τ.
• New report field reference_latency, with a schema bump to v7. This means new backend work (a trait method, JACK ring alignment, a fake reference leg), a larger manifest, and two new acceptance criteria (AC5 rig, AC6 test).
• Risk 1 rewritten. Its old mitigation rested on a ≤ 30-sample stored-τ error, which A stored τ can be 16 samples wrong the next session with every TauConditions field matching #461 falsified.

What stands from revision 1, unchanged: the per-request distance_m field and its CLI token (option B is still rejected); CausalBound in place of Option<usize>; the at-or-after-peak decline; ONSET_SEARCH_WINDOW_S staying in place, with the unbounded path unchanged; the #391 reading; and the scope note on c-free scoring.

core question
Where does the causal bound's τ come from, and how does it get there? Specifically: how does a loopback reference recorded in the same capture get captured, validated, archived and consumed, so that nobody can mistake it for the acoustic pair's own τ?

option A: per-request distance, same-capture reference from existing config, archived beside the stored τ (recommended)

• Distance. As in revision 1: optional distance_m on plot_ir, plus a marker-suffixed CLI token.
• Reference routing. plot_ir takes its reference from the config keys transfer_stream, test_hardware and test_dut already use: reference_channel / reference_port for capture, reference_output_channel / reference_output_port for playback, resolved by resolve_ref_input / resolve_ref_output.
  • The engine's single output drives the main output port and, when it differs, the reference output port. Both carry the same samples in the same period.
  • The reference input is captured sample-aligned with the measurement input.
• Reference analysis. The reference leg is deconvolved with the same inverse filter, gated like the IR, and validated by the same single-reading gates calibrate applies: pre-impulse SNR, window-edge margin, and xrun.
• Archive. The result goes into a new optional sibling field, report.reference_latency, with states measured or unavailable (reason).
• Consumption. ir_stats builds the bound from reference_latency × position.distance_m only.
• Stored τ. interface_latency is still resolved and archived exactly as today, but nothing in the bound reads it.

tradeoffs:

• Gained. The bound's τ shares a client lifetime, a stream epoch and a process callback with the IR it bounds. The A stored τ can be 16 samples wrong the next session with every TauConditions field matching #461 re-pick, τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347's period jump, and the one-shot start race below are all common-mode and cancel.
• Cost. New backend surface: a trait method, a JACK path with sample-exact anchoring and a budget-sized ring, and a fake reference leg. A schema bump. A mechanical reference_latency: None in every MeasurementReport literal (10 files).
• Not solved. The per-pair converter difference δ (see question 3). It is uncorrected and gated by AC5.

option B: new InterfaceLatency::InCapture variant instead of a sibling field
It saves the 10-file literal churn. Rejected for three reasons:

1. Wrong-pair τ gets used. interface_latency's contract is τ for this capture's own port pair, by exact match (Interface latency (τ) captured during ac calibrate, with scoped validity and history #281, ac plot ir must print and persist its result #283, ZMQ.md). ac-scene's ir_flight_time_ms subtracts Measured.tau_s from the arrival. A variant carrying the reference pair's τ would either get subtracted by a future match arm, which is exactly the per-channel-pair error, or be silently skipped.
2. Old readers break. An unknown state tag makes the whole report undecodable to any reader built before the change. A sibling field is simply ignored.
3. Stored calibration is used across device restarts that invalidate it — check τ and level per session, refuse when stale #466 needs both values. It compares stored τ against in-session τ, so the two must coexist on one report.

option C: fall back to stored τ when no reference is configured
It would keep the bound alive on rigs with no loopback patched. Rejected:

• The error is larger than the margin, with no signal. Measured on pupu: +16, +32, then back to 0 samples across enumerations, all with every TauConditions field matching. That exceeds the 55-sample margin once tape is added (rig comment). A bound built from that value truncates the search window with nothing to show it. It also prints "causal bound enforced", which reads as more trustworthy than the unbounded pick.
• A wrong guard is worse than no guard here. Declining to bound, with the missing input named, is the honest state.
• The door stays open. If Stored calibration is used across device restarts that invalidate it — check τ and level per session, refuse when stale #466 later marks a stored τ as verified in this session, admitting it is one extra match arm in ir_stats. That decision belongs to Stored calibration is used across device restarts that invalidate it — check τ and level per session, refuse when stale #466.

recommendation
Option A. The bound needs τ from the same client lifetime as the IR, and a sibling field is the only placement that keeps "τ of this pair" and "τ of the reference pair" apart for every existing reader.

Answers to the developer's four questions (21:45)

1. Wire and backends.

   • No new request field or config key for the reference. plot_ir uses the existing reference keys.
   • Refusals before emission. A reference that is configured but does not resolve (out of range, or an orphaned sticky port) returns ok: false with no audio, the same as test_dut. This is new: a config whose bad reference was silently ignored by plot_ir before is now refused, per transfer_stream: reference output leg resolves from reference_channel, an INPUT index, so the drive never reaches the loopback #225's rule.
   • Migration warning. ref_output_migration_warning goes into the reply's warnings array, as test_dut does.
   • New AudioEngine method. It plays once and returns (measurement, reference), each exactly samples.len() + tail long. The default implementation bails, naming the backend. CPAL inherits that default, so on CPAL plot_ir runs single-input and records reference_latency: unavailable with a reason naming the backend. It never silently drops a configured reference.
   • JACK invariants. Each of these closes a failure that would otherwise pass unnoticed:
     • (a) Never padded. A short reference is an error. pop_ref_padded must not be used on this path.
     • (b) Sample-aligned by construction. Both buffers start at the same process-callback boundary. capture_stereo's clear-meas-then-clear-refs admits a one-period offset between the rings, which is the τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347 signature, and is not acceptable here.
     • (c) Ring sized to the budget. The reference ring is sized to meas_ring_capacity(sr) for this path, not REF_RING_CAPACITY. That constant is 4 s at 192 kHz, and a larger within-budget request would drop the newest reference samples: the fix: cancel and bound plot_ir work #437 bug class.
     • (d) Registration settled first. The reference port must be adopted by the RT handler before the anchor, because add_ref_input's hand-off lands a period later.
   • Fake backend. The reference leg is the stimulus delayed by its own hook (AC_FAKE_REF_DELAY_SAMPLES) and scaled by its own gain hook (AC_FAKE_REF_GAIN).
     • Delay default. It must differ from the 32-sample measurement delay. That way a bound mistakenly built from the measurement leg's peak, or from a stored τ, lands on a different index and the test goes red.
     • Gain. Gain 0 makes the SNR refusal reachable.
     • Existing tests. They are unaffected: Daemon::spawn() configures no reference_channel.

2. Place in the report, validity gate, no-reference behaviour.

   • Field. report.reference_latency: Option<ReferenceLatency>, tagged on state:
     • measured: tau_s, pre_impulse_snr_db, method, output_port, input_port. The ports are the reference pair, so a reader can see τ came from a different pair than the capture.
     • unavailable: reason.
   • Schema. SCHEMA_VERSION goes 6 → 7; v1–v6 reports decode with the field None.
   • Gate. A reference reading is valid only if its capture had no xrun, its pre-impulse SNR is ≥ TAU_SNR_THRESHOLD_DB, and its peak clears TAU_EDGE_MARGIN_FRAC of the TAU_MIN_HALF_WINDOW_S half-window. These are the existing constants, so there is one definition of what a τ reading is. Implement it by extracting the analysis half of measure_tau into a function both callers use.
   • No τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347 agreement rule. τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347 exists because two client lifetimes can differ by a period. An in-capture reference shares the lifetime of the IR it corrects, so that error is common-mode here, and a second capture would only double the emission.
   • Tail too short. A capture tail shorter than the reference window (2 × 50 ms) gives unavailable with a reason. It does not error the capture.
   • Unavailable reasons. They name what to check and never assert a cause: no reference configured; backend cannot capture a reference; SNR below threshold; peak at the window edge; xrun during capture; tail shorter than the reference window.
   • No reference. No bound. CausalBound records τ as missing and carries the reference's reason. Older reports without the field count as τ missing too.

3. What the reference measures.

   • The decomposition. τ_ref is DAC(ref out) + ADC(ref in) + buffering. The acoustic leg's electrical part is DAC(out) + ADC(in) + the same buffering. The bound therefore carries δ = τ_acoustic,electrical − τ_ref uncorrected.
   • What cancels. Buffering, the period jump and the one-shot start race cancel, because both buffers come from one callback. A stored τ can be 16 samples wrong the next session with every TauConditions field matching #461's 16-sample re-pick happens below JACK, in the FireWire stream, which carries every channel in one isochronous stream. That it is common to all channels is assumed, not measured.
   • What remains. Per-channel converter and preamp differences. Earlier rig data showed per-pair τ differing by 14–60 samples, but through external converters and a master section. On pupu, AN1/IN1 against AN2/IN2 is unmeasured.
   • No correction term here. No δ correction goes into estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460. AC5 measures δ and its stability across an enumeration before estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 closes.
   • If δ is stable and small enough: ship.
   • If δ is stable but too negative: a per-pair δ layer becomes a follow-up issue, and estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 does not close on a late-biased bound.
   • If δ moves across enumerations: the reference cannot substitute on this interface, and estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 goes back to design.
   • Cheaper topology, not required. With reference_output_channel unset and the main output split in hardware to both amplifier and loopback, the DAC is common and δ shrinks to the input difference.

4. What stands from revision 1. The distance token, the missing-input clause, and the at-or-after-peak decline all stand, with two changes:

   • The τ-missing case names the reference and carries its unavailable reason, not the stored calibration.
   • CausalBound's unavailable state holds that reason text, so the rule clause and the CLI can say which check failed.

Amended acceptance criteria (AC1–AC4 inherited unchanged; the notes and additions below are this revision's)

• AC2 note, not a change. "A measured τ" is satisfied by reference_latency: measured. The rig record must also list, for each capture:
  • pinned vs clear, carried over from revision 1;
  • the reference τ next to a calibrate τ from the same enumeration, on the same loopback pair. Expected: identical to the sample. Provenance: derived. The loopback was sample-identical within an enumeration over 49 calibrate runs and 10 AC6 brackets (measured).
• AC3 note. "τ missing" now reads as "no valid same-capture reference", with its reason.
• AC5 (new, rig). On pupu:
  • Setup. The operator cables the acoustic pair's own output and input as a temporary electrical loopback, with phantom off on IN1. The reference loopback stays on AN2 → IN2.
  • Measure. δ = the measurement leg's peak offset minus the reference τ.
  • Protocol. At least 5 plot ir captures in each of two enumerations, with one FF400 power cycle between them.
  • PASS requires both:
    • δ is identical to the sample across all captures and both enumerations. Provenance: derived, from the measured within-enumeration loopback repeatability, applied to a difference of two legs.
    • δ ≥ −20 samples at 96 kHz. Provenance: derived. 55 samples of loudspeaker margin (An IR-derived arrival needs an onset estimator, not argmax |h| #346 table, measured) − 14 tape (derived) − 10 speed of sound (derived) = 31. A further 11 are held back because the 55 is one DUT at one distance (assumed).
  • Otherwise FAIL, with δ recorded with its sign. A FAIL blocks closing estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 (see question 3).
• AC6 (new, test against the rejected implementation). A report with interface_latency: measured, a distance_m, and no reference_latency yields a CausalBound that is unavailable with τ named as missing. It must not be enforced. Build it in ir_stats tests. Also compute, inside the test, the index the stored-τ bound would have produced, and assert that it is not used.

affected modules

• ac-core measurement/report/provenance.rs + report/mod.rs: ReferenceLatency type; MeasurementReport.reference_latency; SCHEMA_VERSION 7 with a changelog line; re-export.
• ac-core measurement/report/ir_stats.rs: the bound reads reference_latency × distance_m; IrStats exposes CausalBound.
• ac-core measurement/sweep/onset.rs + sweep/mod.rs: CausalBound; estimate_onset takes it; the missing-input clause; the at-or-after-peak decline.
• ac-core report literals (fixtures.rs, csv.rs, report_html, report_pdf, report_layout), ac-scene sweep_ir.rs and ac-view tests/it_sweep_ir_geometry.rs: mechanical reference_latency: None only. ac-scene's flight-time read-out keeps using interface_latency and its semantics do not change. No ac-view behaviour changes.
• ac-daemon audio/mod.rs: the new trait method with its bailing default.
• ac-daemon audio/jack_backend.rs + audio/rings.rs: the anchored, unpadded, budget-sized reference capture.
• ac-daemon audio/fake/{mod,hooks,tests}.rs: the reference leg with its own delay and gain hooks.
• ac-daemon handlers/calibrate/{mod.rs,tau/mod.rs,tau/measure.rs}: extract the reference-reading analysis so plot_ir can call it (tau is a private module today).
• ac-daemon handlers/audio/plot.rs: distance_m; reference resolution, routing and capture; reference_latency; PositionSnapshot built from temperature or distance; reply keys and warnings.
• ac-cli: distance token; request field; the onset read-out names the missing input; a reference line in the read-out.
• ZMQ.md: request field, reply keys, reference_latency, schema v7.

file manifest
ac-rs/crates/ac-core/src/measurement/sweep/onset.rs
ac-rs/crates/ac-core/src/measurement/sweep/mod.rs
ac-rs/crates/ac-core/src/measurement/report/ir_stats.rs
ac-rs/crates/ac-core/src/measurement/report/provenance.rs
ac-rs/crates/ac-core/src/measurement/report/mod.rs
ac-rs/crates/ac-core/src/measurement/report/fixtures.rs
ac-rs/crates/ac-core/src/measurement/report/csv.rs
ac-rs/crates/ac-core/src/measurement/report_html/mod.rs
ac-rs/crates/ac-core/src/measurement/report_pdf/mod.rs
ac-rs/crates/ac-core/src/measurement/report_layout/mod.rs
ac-rs/crates/ac-scene/src/sweep_ir.rs
ac-rs/crates/ac-view/tests/it_sweep_ir_geometry.rs
ac-rs/crates/ac-daemon/src/audio/mod.rs
ac-rs/crates/ac-daemon/src/audio/rings.rs
ac-rs/crates/ac-daemon/src/audio/jack_backend.rs
ac-rs/crates/ac-daemon/src/audio/fake/mod.rs
ac-rs/crates/ac-daemon/src/audio/fake/hooks.rs
ac-rs/crates/ac-daemon/src/audio/fake/tests.rs
ac-rs/crates/ac-daemon/src/handlers/calibrate/mod.rs
ac-rs/crates/ac-daemon/src/handlers/calibrate/tau/mod.rs
ac-rs/crates/ac-daemon/src/handlers/calibrate/tau/measure.rs
ac-rs/crates/ac-daemon/src/handlers/audio/plot.rs
ac-rs/crates/ac-daemon/tests/it_protocol/plot_ir.rs
ac-rs/crates/ac-daemon/examples/ir_probe.rs
ac-rs/crates/ac-cli/src/parse/mod.rs
ac-rs/crates/ac-cli/src/parse/plot.rs
ac-rs/crates/ac-cli/src/parse/sweep.rs
ac-rs/crates/ac-cli/src/commands/plot.rs
ac-rs/crates/ac-cli/tests/it_plot_ir.rs
ac-rs/ZMQ.md

interface changes

• ZMQ plot_ir request. Optional "distance_m": <float>: metres, source to receiver, finite and > 0, otherwise ok: false before port resolution. Absent means today's behaviour. There is no reference field in the request; the reference comes from config.
• ZMQ plot_ir refusal (new). A configured but unresolvable reference returns ok: false with no audio: an out-of-range reference_channel or reference_output_channel, or an orphaned sticky port.
• ZMQ plot_ir reply. Additive "ref_in_port" and "ref_out_port", present only when a reference is configured. "warnings" carries the transfer_stream: reference output leg resolves from reference_channel, an INPUT index, so the drive never reaches the loopback #225 migration warning when it applies.
• ZMQ PUB measurement/report.
  • New optional report.reference_latency, tagged on state as described above.
  • schema_version becomes 7.
  • report.position.distance_m is populated when supplied, and position may now be present without temperature_c.
  • interface_latency is unchanged.
• Emission. With a separate reference_output_channel, the ESS also leaves that output at the same clamped level. That is an electrical loopback, inside the single global drive_max_dbfs limit. With it unset, no extra output is driven.
• AudioEngine (crate-internal). One new method: play once and capture measurement plus one reference input, sample-aligned, exact length. Its default bails.
• ac-core public API.
  • ReferenceLatency (+ re-export);
  • MeasurementReport.reference_latency;
  • CausalBound (+ re-export from measurement::sweep), with an enforced state and an unavailable state naming τ / distance / both and holding the τ reason;
  • estimate_onset's last parameter becomes CausalBound;
  • IrStats gains a CausalBound field.
• CLI. ac plot ir gains one marker-suffixed distance token. The spelling goes to UX, under revision 1's constraints: the marker is required, it must not collide with an existing classify suffix, and it must be listed in the parse/mod.rs help.
• Fake test hooks. AC_FAKE_REF_DELAY_SAMPLES and AC_FAKE_REF_GAIN, inert when unset.
• Cargo features: none.

ZMQ protocol impact
Yes. Additive for both consumers, plus one new refusal:

• ac-cli: the only plot_ir sender. It gains the field, prints the reference outcome and the missing-input clause, and decodes v7 reports (its report type is the same ac-core struct).
• ac-view: does not send plot_ir. The ac-scene sweep-IR panel decodes reports through the same struct and ignores reference_latency, so there is no display change. An ac-view built before v7 still decodes v7 reports, because a new optional field is ignored.
• Older ac-cli clients: omit distance_m and get no bound, with the missing input named. Reports they read still decode.
• The new refusal only affects configs that already carry a broken reference.

implementation notes for developer

• provenance.rs
  • Model ReferenceLatency on InterfaceLatency / MeasuredLatency (l.75–112).
  • No measured_at: the value belongs to this capture.
  • The doc comment must say this is τ of the reference pair, and why it is not interface_latency.
• report/mod.rs: add the field after interface_latency (l.116) with #[serde(default, skip_serializing_if = "Option::is_none")], and a v7 line in the changelog above SCHEMA_VERSION (l.73–84).
• ir_stats.rs
  • The whole change is the min_admissible_index match at l.82–99: read reference_latency, not interface_latency. The bound stays centre + (tau_s + d/c)·fs.
  • Rewrite ir_stats_wires_a_causal_bound_from_position_and_interface_latency against reference_latency, and add AC6 beside it.
• onset.rs: unchanged from revision 1. The change surface is the bound / window_start lines (l.166–168) and the limit match (l.252–259). Check the at-or-after-peak decline before the window-length check.
• calibrate/tau/measure.rs
  • Split measure_tau (l.282–342) at play_and_capture. Everything after it becomes a function taking the captured buffer, SweepParams and the actual tail_s.
  • It replaces the 2·half_window > TAU_TAIL_S check with the caller's tail, and returns offset and SNR or a typed refusal.
  • measure_tau becomes play plus that function.
  • Keep LowSnrRefusal typed.
  • Expose the function pub(crate) through tau/mod.rs and calibrate/mod.rs (mod tau; at l.28 is private).
  • The existing measure tests must pass unchanged. That is the check that calibrate did not move.
• audio/mod.rs: add the method next to play_and_capture_cancellable (l.61–73). The doc states the four invariants from question 1.
• jack_backend.rs + rings.rs
  • Base it on play_and_capture_cancellable (l.404–453), and refactor add_ref_input (l.510–565) so the ring capacity is a parameter.
  • Anchoring, orientation only. The RT callback pushes the measurement ring and every reference ring in lockstep (l.228–231). Latching per-ring pushed-sample counters in the period the one-shot starts gives both rings an exact start index, and ringbuf 0.4.8's Consumer::clear() returns the discarded count, so the consumer can track absolute position.
  • Tests. Add rings.rs unit tests modelled on capture_block_leaves_refs_ahead_of_meas (~l.478). A producer pushes lockstep periods, the consumer clears between rings at every possible interleaving point, and the output must be aligned to the sample. Also compute the sequential-clear result inside the test and assert that it is misaligned, so the test can go red.
• fake/mod.rs + hooks.rs
  • Base it on play_and_capture (l.263–296) and the xrun hook.
  • Hooks go beside next_loopback_delay_samples (hooks.rs l.36–44), with the same read-once OnceLock shape.
  • Choose the default reference delay so that a d of a few cm at 48 kHz gives an enforced bound, and a larger d reaches the at-or-after-peak decline. Test both inside it_protocol/plot_ir.rs, with expected indices computed from the hooks and c, not hard-coded.
• plot.rs (daemon) plot_ir (l.782)
  • Parse distance_m with the other budgets (l.787–815).
  • Resolve the reference next to resolve_output / resolve_input (l.822–829), with the test_dut warnings pattern (l.243–245).
  • Start the engine with both output ports (l.859) and call the new method in place of l.907 when a reference is configured.
  • Build reference_latency, and replace the PositionSnapshot build at l.1085–1088.
  • Leave plot / plot_level untouched.
• it_protocol/plot_ir.rs
  • AC4: spawn_with_config with reference_channel and reference_output_channel on fake ports, plus distance_m. Assert report.position.distance_m, reference_latency.state == "measured" with the fake reference delay, and the bound .is_some().
  • Also: distance with no reference names τ missing; the reference present with AC_FAKE_REF_GAIN=0 gives an SNR reason; an unresolvable reference is refused with no audio; distance_m budget rejections.
  • Keep plot_ir_resolves_the_tau_that_calibrate_stored (l.222) as it is. interface_latency did not change.
• commands/plot.rs (CLI)
  • short_onset_rule l.275–283: split the "no causal bound" label per missing input.
  • run_ir l.159–220: add the field, and print the reply's reference ports next to Output: (l.228).
  • Update the decline list at ~l.788.
  • Wording goes to UX.
• it_plot_ir.rs
  • l.285: update the clause.
  • l.302: keep the Deprecate the metre: remove every ms → distance conversion, keep flight time #391 guard's intent, meaning it still fails if an (X m) read-out returns, rather than the literal "distance " substring. Replace it; do not delete it.
• parse/plot.rs / parse/sweep.rs: as revision 1 (token after tail_s, ~l.52; exhaustive PlotIr patterns).
• ir_probe.rs l.234: pass unavailable, with both inputs missing.
• ZMQ.md ### plot_ir: document the request field and budget, the reply keys, the new refusal, and a reference_latency block after the interface_latency block (l.1188–1206). That block must say which pair it describes, that a reader must not subtract it from the arrival as though it were interface_latency, and that it feeds the causal bound only. Update the schema number in the l.1149 example.

scope
tier-1 (unchanged)

risks

• δ between the acoustic pair and the reference pair is uncorrected, and its sign is unknown. A negative δ makes the bound late, which truncates the window past the true onset. Mitigation: AC5 gates closure on δ ≥ −20 samples and on δ being stable across an enumeration. The "pick ON start" flag stays the per-capture signal.
• That A stored τ can be 16 samples wrong the next session with every TauConditions field matching #461's 16-sample step is common to all channels is assumed. If it is per-channel, the reference does not cancel it. Mitigation: AC5 crosses one power cycle, and the AC2 record compares the reference τ against calibrate's τ in the same enumeration.
• JACK ring misalignment would look exactly like τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347. A one-period meas/ref offset is a stable, repeatable, wrong τ. Mitigation: invariant (b); the rings.rs test against the sequential-clear implementation; the AC2 cross-check.
• The fake cannot reproduce a JACK ring race. Its on-demand path has no ring. Mitigation: the rings.rs unit tests exercise the shared drain code directly; nothing claims fake coverage of it.
• A config set up for transfer_stream now also drives reference_output_channel during plot_ir. If that output is wired to anything other than a loopback, the ESS reaches it. Mitigation: the reply names ref_out_port before any output (UX decides how prominently); the transfer_stream: reference output leg resolves from reference_channel, an INPUT index, so the drive never reaches the loopback #225 warning is surfaced. The electrical level is inside drive_max_dbfs.
• Memory. A budget-sized reference ring is 46 MB at 96 kHz, allocated only for the duration of a plot_ir with a reference.
• Harmonic IRs of a short sweep can fall inside the 50 ms reference window. Order 2 sits L·ln 2 before the linear IR. On an electrical loopback they sit far below the linear peak, so argmax holds, and the SNR/edge gates catch a broken leg.
• Temperature. An unset temperature still uses the default c. That is about 10 samples at 2 m and 96 kHz, in either direction (derived), carried over from revision 1.
• AC2 can pass on a pinned pick. Carried over from revision 1: the rig record reports pinned vs clear.
• The existing single-input one-shot has a clear/activate race. A period that lands between clear_meas_uncounted and one_shot_active.store (jack_backend.rs l.426–427) shifts the capture by one period relative to the stimulus. It is rare, and not fixed here. With a reference it is common-mode. Without one, interface_latency flight times can carry it. The ac plot ir must print and persist its result #283 read-out is outside estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460's scope.
• Operator-facing strings change: distance token, reference line, missing-input clause, decline line, reply ports. Routed to needs-ux before implementation.

[mkovero]

risk update for the design above — stored-τ error is larger than the decision assumed

The decision's first risk bounds the causal bound's error at about ±30 samples: stored τ off by 16 (#461) plus tape ±14. Its mitigation says a late error of ≤ 30 samples still sits before the arrival, because transfer_stream put the arrival 55 samples after pure flight at 1 m.

Measured since, on pupu (#461, comment): one reboot moved τ by +32 samples (1711 → 1743), and the 2026-09-14 value was +16. Every value so far is 1711 + 16k, consistent with the 96 kHz FireWire SYT interval (16, from amdtp-stream.c). How many steps are reachable is unmeasured.

What that does to the mitigation, stated as the numbers show:

• A stored τ from an earlier stream epoch can already be off by ≥ 32 samples. With tape at ±14, that is ≥ 46 samples, and the margin on the rig DUT was 55 (An IR-derived arrival needs an onset estimator, not argmax |h| #346 table). One more epoch step exceeds the margin.
• The sign depends on which epoch τ was stored in. A late bound past the true onset truncates the window, and the "pick ON start" flag is then the only signal.

Not proposing a design change here; that is the architect's call. Two things are now measured that were not when the decision was written:

1. The stored-τ error is quantised and grows with the number of stream epochs between calibration and capture.
2. Option C (same-capture reference) is the τ source this error does not touch. The decision already routes it to An IR-derived arrival needs an onset estimator, not argmax |h| #346 "soon".

Whether #460 should wait for, or ship alongside, a τ-freshness check (or option C) is the question to settle before implementation. Label left as is (needs-ux).

[mkovero]

operator decision: the bound takes τ from a same-capture loopback reference — back to design

Operator, 2026-09-15, on the choice between (1) a loopback reference recorded in the same capture and (2) a per-session check on a stored τ: "1. sounds sensible and yes do both". That is a human decision on the open question in the risk update above. It brings option C into #460's scope for the causal bound's τ, rather than deferring it to #346.

Why, measured since the design decision was written (#461, tests A and B, 2026-09-15): τ re-picks on every device enumeration.

• The values were 1711 → 1743 after a host reboot and → 1711 after an interface power cycle, and 1727 on 2026-09-14, all with every TauConditions field matching.
• A stored τ is therefore wrong by an unbounded-so-far multiple of 16 samples after any boot or power cycle. That exceeds the bound's 55-sample margin in combination with tape error.
• A same-capture reference cannot go stale. Within a session the loopback arrival was sample-identical across all 10 AC6 brackets.

Split out, so this issue does not grow: the check for stored calibration (τ used elsewhere, and level calibration reset by an interface power cycle) is #466, the other half of the operator's "do both".

For the architect (moved needs-ux → needs-design). Revise the decision above for option C in scope. The questions the evidence leaves open:

1. Wire and backends. Two-input capture in plot_ir (acoustic + reference) on every backend. What the fake backend models, so tests cannot pass against a fake that lacks the reference path. Which config names the reference input: reference_channel / reference_output_channel already exist for transfer_stream.
2. The τ source's place in the report. A new InterfaceLatency variant, or a sibling field, recording that τ was measured in-capture, plus its SNR and validity gate. What happens when no reference is configured: fall back to stored τ (then Stored calibration is used across device restarts that invalidate it — check τ and level per session, refuse when stale #466 governs), or no bound with the missing input named.
3. What the reference measures. The loopback leg's arrival is the interface round trip on that output/input pair. Whether the acoustic leg's output and input share it closely enough to subtract, given τ is per channel pair (earlier rig finding) and both legs share one stream epoch.
4. Whether the distance token, the missing-input clause and the at-or-after-peak decline from the decision above stand unchanged. They look independent of the τ source.

UX follows once this is settled.