JACK one-shot capture can start one period early: ring clear and one-shot enable race the RT callback

[mkovero]

problem

JackEngine::play_and_capture_cancellable (ac-daemon/src/audio/jack_backend.rs, read at origin/main 340f1c55) starts a one-shot measurement from the consumer thread in two steps:

self.rings.clear_meas_uncounted();                          // l.426
self.state.one_shot_active.store(true, Ordering::Release);  // l.427

The RT callback (Process::process, l.194–231) does two things each period, in this order:

1. l.198: reads one_shot_active to decide what to output: the one-shot, or silence.
2. l.228: pushes that same period's input into the measurement ring.

clear_meas_uncounted (rings.rs l.121) calls the consumer's clear(), which drops only the samples buffered at that instant. capture_available (l.196) then pops the oldest n_total samples.

The race. A period can check the flag (step 1) before l.427 and push its input (step 2) after l.426. That period outputs silence, but leaves one full period of pre-stimulus input at the head of the ring. The one-shot starts in the next period. The returned capture is therefore misaligned with the stimulus by exactly one period, and every arrival derived from it (IR peak, onset, calibrate's τ) reads one period late:

• 256 samples on the FF400 rig at period 256
• 1024 at period 1024

Within the capture the offset is fixed and repeatable, and nothing in the returned data flags it.

Window. A period is exposed when the consumer's two statements land while the callback is between l.198 and l.228. The probability per capture is therefore about the callback's run time over the period length: small, but not the nanosecond gap between two adjacent statements. That estimate is derived from the code, not measured.

evidence

• Code reading only. Found by the estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 architect pass (revision 2, risks) and re-read at the lines above before filing.

• Not observed so far on this build. On 2026-09-15, pupu, build 298f77dc, 186 one-shot captures showed no one-period offset:

  • 128 calibrate τ readings, all identical within each device-enumeration epoch;
  • 58 ac plot ir captures, whose loopback brackets were all identical.

  That bounds the rate as uncommon on that host; it does not show the race is unreachable.

• Same signature as τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347, plot_ir's arrival inherits the one-period jump with no corroboration — #347 guards only calibrate #359 and calibrate stores a τ one JACK period short and calls it corroborated — 42 of 97 rig runs, every one labelled "2 readings agree" #363 (a one-period jump). Those were attributed to pipewire-jack, and the jump disappeared when that stack was removed. This race is an in-process mechanism producing the same symptom on any JACK stack.

what it affects

• plot_ir: a single capture's arrival, with no corroboration (plot_ir's arrival inherits the one-period jump with no corroboration — #347 guards only calibrate #359's concern, via a second mechanism).
• calibrate: measure_tau_twice uses two one-shots. A race in exactly one of them gives two readings a period apart, which τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347's rule refuses. That's a correct refusal of a spurious result, not a stored error. A race in both, a stored error, would need two independent hits.
• estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 revision 2's same-capture reference: the reference ring is pushed in lockstep with the measurement ring (l.229–231), so a race is common-mode there and cancels. That holds only if the reference ring is aligned the same way (estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460's invariant b).

acceptance criteria

• The one-shot's first output sample and the first captured sample are aligned by construction. Either the RT callback establishes the capture start in the same period it starts the one-shot, or the consumer drains to a sample index latched by the RT side. Two consumer-side statements racing the callback is not acceptable.
• Test against the rejected implementation, for example a rings.rs-level test driving the producer and consumer interleavings: for every interleaving point, the fixed sequence yields alignment, and the current clear-then-enable sequence, computed inside the test, yields the one-period offset at the exposed points. A test that only runs the happy interleaving cannot fail on this defect.
• The fake backend cannot model a ring race (its on-demand path has no ring). Nothing may claim fake-backend coverage of this.

related

#347, #359, #363 (one-period jumps), #460 (revision 2 risk and invariant b), #283, #437 (capture budget and ring sizing in the same code).

[mkovero]

hardware evidence from #460's AC5 run (pupu, 2026-09-16, build dbf8746e6103)

PR #470 landed a one-shot arming path (ref_one_shot_period) that arms the stimulus and both capture rings inside a single JACK callback, plus two tests: ref_one_shot_aligns_stimulus_and_both_captures_whatever_period_arms_it, and clear_then_enable_puts_the_stimulus_one_period_late_when_it_races_the_callback, which reconstructs the rejected sequential-clear implementation and pins its off-by-one-period behaviour.

Tonight that path ran on real hardware at JACK period 256, 96 kHz, across ten captures and one FF400 power cycle:

	meas leg arrival	reference τ	δ
5 captures, enumeration 1	+1711	1711	0
5 captures, enumeration 2	+1711	1711	0

δ is the difference between the two legs of the same capture, so a one-period misalignment between them would read ±256 samples. It read 0, ten times out of ten, either side of a re-enumeration.

This does not close #467. It is evidence that the merged reference-capture path arms both rings in the same period on hardware, at one period size, on one interface. Whether the original clear-then-enable pattern still exists on other capture paths is not something tonight's run tested, and I am not claiming it from a measurement that only exercised the reference leg.

Full record: PR #470 rig comments, and $AC_HOME/rig-verify-queue.md under #460.

[mkovero]

tracked under EPIC #475 — τ trust

Role here: alignment, not trust — included because its failure is indistinguishable from a one-period τ error at the output. #460's one-shot arming avoids it on the reference path, and δ = 0 across 10 captures at period 256 is evidence that path is aligned on hardware; whether the original pattern survives elsewhere is untested.

The epic groups this with #346, #347, #350, #351, #359, #363, #461, #466 and #467 because they share one mechanism — latency moves in discrete quanta (one JACK period per client start; 16 samples per FireWire enumeration) that TauConditions cannot see — and one signature: a number that is stable, repeatable, physically plausible and wrong.

Backlink only. No routing, scope or priority change to this issue.

[mkovero]

spec

type: bug

problem statement
When the JACK backend starts a plain one-shot capture (play_and_capture_cancellable), the daemon does two separate things: it clears the measurement ring, then it enables the one-shot. The RT callback can run between those two steps. When it does, the returned capture starts one JACK period before the stimulus. Every arrival derived from that capture then reads exactly one period late: IR peak, onset, plot_ir, and each τ reading inside calibrate. Nothing in the returned data shows the offset. It looks the same as the one-period jumps in #347, #359 and #363, but it can happen on any JACK stack. PR #470 closed this race for the reference-capture path only, by arming the stimulus and both rings inside one callback; the rig showed δ = 0 over 10 captures at period 256. On origin/main 1bf486c4, the plain one-shot path still clears and then enables as two separate steps (jack_backend.rs around l.561–562). So the defect is still open for every capture that does not go through the reference path. The only evidence for it so far is the code itself: 186 captures on pupu (build 298f77dc) showed no offset. That makes the race rare on that host; it does not show the race is unreachable.

acceptance criteria

• On the JACK plain one-shot path, the first captured sample and the first stimulus output sample are aligned by construction. This means one of two things: the RT side fixes the capture start in the same period that starts the stimulus, or the consumer drains up to a sample index the RT side latched. Two consumer-side steps that race the callback do not meet this criterion.
• A test drives the producer/consumer interleavings at every interleaving point. The fixed sequence gives zero offset at every point. Inside the same test, the current clear-then-enable sequence is rebuilt and shows an offset of exactly one period at the points it exposes. This proves the test can go red on this defect. A test that only runs the happy interleaving does not meet this criterion. — provenance: derived (one-period offset follows from the callback order described in the issue body; feat: bound the onset search with a same-capture reference (#460) #470's clear_then_enable_… test already pins it for the reference path)
• Offset under test is zero samples for every period size the test uses, at least 256 and 1024. — provenance: derived (the period sizes come from the rig configurations named in the issue, not from a measured failure)
• The feat: bound the onset search with a same-capture reference (#460) #470 reference-capture path still passes ref_one_shot_aligns_stimulus_and_both_captures_whatever_period_arms_it unchanged. If both paths now share one arming mechanism, that test covers the shared mechanism.
• No test, doc or PR text claims the fake backend covers this race. Its on-demand path has no ring.
• The PR states what the fix does not fix: one-period jumps that come from the audio stack or a client restart (τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347, plot_ir's arrival inherits the one-period jump with no corroboration — #347 guards only calibrate #359, calibrate stores a τ one JACK period short and calls it corroborated — 42 of 97 rig runs, every one labelled "2 readings agree" #363, EPIC EPIC: make τ trustworthy — every consumer of an absolute latency can be one quantum wrong, undetectably #475) are a separate mechanism. A later one-period τ step on the rig does not show this fix failed.

out of scope

• The latency quanta themselves (one period per client start, 16 samples per FireWire enumeration). Tracked under EPIC EPIC: make τ trustworthy — every consumer of an absolute latency can be one quantum wrong, undetectably #475 and its members.
• τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347's two-reading agreement rule in calibrate. That rule already refuses a single race hit, and it stays as it is.
• Rig evidence as a gate. A rare race cannot be shown absent by a finite run of captures, so the tests above are the acceptance. A rig run is welcome as a regression check, but it cannot prove the fix.
• The CPAL backend. cpal_backend.rs (around l.380–386) has a similar clear-then-enable sequence, but input and output run in separate callbacks there, so "same period" does not mean the same thing. The architect decides whether that needs its own issue. This issue does not cover it.
• Any change to wire protocol, CLI or view output.

files likely affected

• ac-rs/crates/ac-daemon/src/audio/jack_backend.rs: plain one-shot arming in play_and_capture_cancellable, and the RT process callback
• ac-rs/crates/ac-daemon/src/audio/rings.rs: ring clear/drain semantics, and the natural home for the interleaving test
• ac-rs/crates/ac-daemon/src/audio/cpal_backend.rs: only if the architect puts it in scope

needs architect review
yes. Three reasons:

• Two arming mechanisms are on the table: extending feat: bound the onset search with a same-capture reference (#460) #470's single-callback arming, or a latched sample index.
• The choice interacts with estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460's invariant b (reference ring aligned the same way as the measurement ring).
• The CPAL backend's analogous sequence needs a scope decision.

This is RT-callback concurrency in the daemon's audio core.

estimated complexity
medium: 2–8h

---

labels: category bug. I removed measurement-accuracy because triage keeps exactly one category label; the τ/onset impact is recorded above. Scope tier-1: the diff is in ac-daemon, but the values it corrupts are onset and τ, and their correctness is governed by measurement/sweep.rs's cited onset rule (same reasoning as #351). No needs-ux: no field, label or text changes. Only a rare spurious offset goes away.

[mkovero]

design decision

core question
How should the JACK plain one-shot (play_and_capture_cancellable) fix the start of its capture? The options are #470's single-callback message arming, or a sample index latched by the RT side on the shared measurement ring.

option A — one arming mechanism, reference optional
Generalise #470's hand-off so that the plain one-shot uses it too, with no reference leg:

• The consumer builds a per-request measurement ring of exactly capture_len samples and pushes one start message.
• The callback pops the message at the top of a period. In that same period it starts the stimulus and pushes that period's input as the capture's first samples.
• The consumer waits for capture_len samples on its own ring and pops exactly that many.

The plain path stops using the shared CaptureRings measurement ring, and stops using one_shot_buf / one_shot_pos / one_shot_active. The code stays in jack_backend.rs.
tradeoffs:

• Gains: alignment by construction, and one mechanism instead of two. That mechanism is already rig-evidenced (δ = 0 ×10 at period 256, estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 AC5).
• Gains: cancel/timeout reuse the abort/ack handshake that already exists.
• Costs: one heap ring of capture_len samples per call. The reference path already allocates two.
• Costs: the shared ring keeps filling during the one-shot, so it has to be cleared afterwards.

option B — latched index on the shared ring
The callback keeps a running count of samples pushed to the measurement ring. In the period where it first renders the one-shot, it latches that count. The consumer tracks everything it has removed (pops and clears), then discards up to the latched index before it pops n_total.
tradeoffs:

• Gains: no per-call allocation, and the shared ring keeps its current role.
• Costs: a second arming mechanism alongside feat: bound the onset search with a same-capture reference (#460) #470, so estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 invariant b would then depend on two mechanisms agreeing.
• Costs: new cross-thread counters. Accounting is fragile under ring overflow, because push_slice drops samples silently and the push count stops matching the ring's contents.
• Costs: the cancel path would still flip the old flag.

recommendation
Option A. #470 already arms a one-shot inside one callback and has rig evidence that it works. A second mechanism for the same job would reopen the question #460 invariant b settled. With one mechanism, ref_one_shot_aligns_… covers both paths (triage AC4).

CPAL scope decision: split out as #480, not covered here. CPAL runs input and output in separate callbacks, so "same period" has no meaning there. The input/output offset is not fixed by construction on CPAL even without the race, so this mechanism cannot transfer.

affected modules

• ac-daemon / audio/jack_backend.rs:
  • the one-shot hand-off types and the per-period function become reference-optional;
  • play_and_capture_cancellable is rewritten onto the hand-off;
  • the plain-path SharedState one-shot fields are removed;
  • new interleaving test.

file manifest
ac-rs/crates/ac-daemon/src/audio/jack_backend.rs

interface changes
none. The AudioEngine trait signatures and behaviour contract are unchanged. All changes are private to jack_backend.rs.

ZMQ protocol impact
no. ac-cli and ac-view see the same fields; the only visible effect is that a rare spurious one-period arrival offset goes away.

implementation notes for developer
Everything below is in jack_backend.rs on origin/main 1bf486c4.

1. Hand-off types (l.108–130).

   • Add a generic queue payload OneShotStart { stimulus, capture_len, meas, reference: Option<(usize, HeapProd<f32>)> }.
   • Add a generic slot type OneShot with the same optional reference.
   • Keep RefOneShotStart as a struct, with From<RefOneShotStart> for OneShotStart. The reference path builds it and pushes .into().
   • Make RefOneShot a type alias of OneShot.

   Constraint (triage AC4): the test module's source must compile unchanged. That means:

   • the RefOneShotStart { stimulus, ref_index, capture_len, meas, reference } literal (test helper arm_ref_one_shot, l.961) still compiles;
   • Option<RefOneShot> still names the slot type;
   • ref_one_shot_period(&mut Option<RefOneShot>, Option<RefOneShotStart>, &mut [f32], &[f32], Option<&[f32]>) -> bool keeps its signature.

   ref_one_shot_period becomes a thin #[cfg(test)] wrapper over the generic one_shot_period, so the existing tests exercise the shared core. Do not edit the three existing ref_one_shot_* / clear_then_enable_* tests.

2. Per-period function (l.234–268).

   • one_shot_period pushes to reference only when the slot has one and ref_in is Some. The existing short-reference behaviour (l.260–262, invariant a) stays.
   • Also fix the doc comment at l.220–233. The fill_one_shot doc lines currently sit above ref_one_shot_period, so move them back onto fill_one_shot (l.270).

3. Callback (l.305–351).

   • Extract the abort check, the conditional pop, the ref-port lookup and the one_shot_period call into one function that process() calls. Suggested inputs: slot, &mut HeapCons<OneShotStart>, abort flag, out, meas_in, and a FnOnce(usize) -> Option<&[f32]> port lookup. No allocation.
   • The new test drives this function, not a reconstruction of it.
   • Delete the one_shot_active branch (l.333–340). What remains is: slot owns output, else silence, else tone.

4. Consumer (l.539–588).

   • Rewrite play_and_capture_cancellable to follow play_and_capture_with_reference (l.625–699) minus the port adoption: per-request ring, silence store, abort flag reset, try_push, then wait on occupied_len() >= capture_len.
   • On cancel or timeout, run the same abort/ack handshake (l.671–685) and hold stimulus and the consumer half until the ack arrives. Nothing may be freed on the RT thread.
   • Pop exactly capture_len, and bail on a short pop. Never pad.
   • Factor the shared wait/abort/pop into one private helper that both paths call, so the two paths cannot drift apart.
   • After the one-shot returns (Ok or Err), call self.rings.clear_meas_uncounted(). The shared ring filled during the one-shot, and today's plain path left it drained. Without the clear, the next capture_block would count a whole stimulus as a discarded_samples splice (see rings.rs clear_meas_uncounted doc).
   • Apply the same post-clear to the reference path through the shared helper. It has the same latent inflation.

5. Remove the dead state. Remove one_shot_buf, one_shot_pos and one_shot_active from SharedState (l.81–88, l.169–171). Update the comments that name them.

   • Renaming ref_one_shot_abort, ref_one_shot_prod and ref_one_shot_cons to one_shot_* is required: after this change they carry both paths, and a ref_ name would misdescribe the plain path.
   • The names the tests use (RefOneShot, RefOneShotStart, ref_one_shot_period) stay, per item 1.

6. meas_ring_capacity doc (l.25–51). Its rationale is sized around plot_ir reading this ring. Add one sentence saying the plain one-shot no longer reads the ring (JACK one-shot capture can start one period early: ring clear and one-shot enable race the RT callback #467). Do not change the capacity in this PR. Sizing belongs to fix: cancel and bound plot_ir work #437/ac plot ir must print and persist its result #283, and the ring still absorbs pushes during a one-shot.

7. New test (triage AC2/AC3) in the jack_backend.rs test module, next to clear_then_enable_….

   Deviation from triage: triage suggested rings.rs for the test. It goes in jack_backend.rs instead, because the fix no longer touches CaptureRings, and the private period function lives here.

   Shape:

   • For PERIOD in {256, 1024}, and for arming in each of the first few periods, place the consumer's single try_push at every point around the extracted callback function (before it, and after it within the same period).
   • Assert that the first stimulus sample in the popped capture sits at exactly the loopback delay: offset 0.
   • In the same test, rebuild the rejected clear-then-enable sequence at the same PERIODs. Its two statements go at every ordered pair of points around "flag read at top" and "input push at bottom".
   • Assert that the exposed pairs (clear before the push, enable after the flag read, same period) give exactly PERIOD, and that every other pair gives 0.
   • Model the loopback as a delay line whose delay is not a multiple of PERIOD (e.g. 37 samples). The existing test's one-period loopback cannot tell latency apart from a one-period offset.

   The 256/1024 sizes and the 0 / PERIOD values are triage's criteria, inherited unchanged. The 37-sample delay is a fixture choice, not a criterion.

8. Fake backend (AC5). Nothing changes in fake/. No test name, doc comment or PR text may mention fake coverage of this race.

9. PR body (AC6). State what the fix will not fix:

   • one-period steps from a client restart or the audio stack (τ must be measured more than once: a single reading can be one period wrong with nothing to detect it #347, plot_ir's arrival inherits the one-period jump with no corroboration — #347 guards only calibrate #359, calibrate stores a τ one JACK period short and calls it corroborated — 42 of 97 rig runs, every one labelled "2 readings agree" #363, EPIC EPIC: make τ trustworthy — every consumer of an absolute latency can be one quantum wrong, undetectably #475);
   • CPAL (CPAL one-shot capture: clear-then-enable races separate input/output callbacks (split from #467) #480).

   A later one-period τ step on the rig is not evidence that this fix failed.

scope
tier-1. Unchanged from triage.

risks

• Freeing on the RT thread. When remaining hits 0, the slot drops the HeapProd and Arc<stimulus> inside the callback. That is safe only because the consumer still holds the other halves. Mitigation: the shared helper keeps stimulus and the consumer ring alive until after the pop or the abort ack, as the reference path already does. Keep the comment that says why.
• Per-call allocation of capture_len samples. At the protocol budget and a high rate, this is large (the shared ring is already that size). Mitigation: the allocation happens on the consumer thread and matches what estimate_onset's causal bound is unreachable: no producer ever records position.distance_m #460 already does, twice over, per reference capture. If memory becomes a problem, that belongs to fix: cancel and bound plot_ir work #437, not here.
• Silent state drift between the two paths. Mitigation: one helper, and one callback function under test.
• Queue capacity 2 with a stale start after an abort. Unchanged from feat: bound the onset search with a same-capture reference (#460) #470. The abort handshake drains the queue before the next push.
• Rig reading. A finite run cannot prove this rare race is gone (triage out-of-scope). A rig regression run is optional and is not a gate.