amethyst/nestsClient/plans/2026-05-07-late-join-catalog-flake-investigation.md

late_join_listener_still_decodes_tail catalog-cancelled flake investigation

Status: partially fixed (commit 8cc7cbd42 shipped; commits 00f6cba31 + 207057374 reverted as net-negative). Residual flake is upstream-territory in moq-relay 0.10.x. Action plan moved to 2026-05-07-moq-relay-routing-investigation.md.

The flake also affects four browser-tier scenarios after the Browser I7 work landed: chromium_listener_late_join_still_decodes_tail, chromium_publisher_baseline_kotlin_listener_decodes, chromium_publisher_reconnect_kotlin_listener_recovers, and intermittently chromium_listener_long_broadcast_60s_tone_440. Browser scenarios soft-pass listener-side assertions on 0-frame outcomes; hard floors planned in 2026-05-07-tighten-cross-stack-assertions.md.

HangInteropTest.late_join_listener_still_decodes_tail, packet_loss_1pct_does_not_kill_audio, long_broadcast_60s_tone_round_trips, and amethyst_speaker_to_hang_listener_stereo_440_660 intermittently fail with hang-listen exiting non-zero on a subscribe error during catalog read. Pre-fix flake rate: 5/5 fail in a sweep. After three layered mitigations: ~2-3/5 fail. The remaining flake is in moq-relay 0.10.x's per-broadcast announce → subscribe-pump setup race; the test-side mitigations have hit diminishing returns.

Pre-fix root cause: moq-rs cancel cascade

The previous hang-listen catalog-read shape:

for attempt in 0..3 {
    let catalog_track = broadcast.subscribe_track(...)?;
    let mut catalog = hang::CatalogConsumer::new(catalog_track);
    match tokio::time::timeout(Duration::from_secs(2), catalog.next()).await { ... }
    // catalog_track + catalog drop at iteration boundary
}

is broken on moq-rs 0.10.x. The flow:

1. Attempt 0: subscribe_track creates a TrackConsumer. Wire subscribe id=0 fires.
2. Speaker's setOnNewSubscriber hook is supposed to write the catalog via send(catalogJson) + endGroup(). For some reason this doesn't deliver in time — see "residual root cause" below.
3. 2 s timeout fires. Loop iteration ends. catalog_track drops.
4. moq-rs sees track.unused() resolve (no consumers left), aborts the wire subscribe with Error::Cancel.
5. Error::Cancel maps to wire stream-reset code 0 per moq-lite/src/error.rs:96-105.
6. Attempt 1: subscribe_track(catalog.json) returns a consumer whose internal state is already in the just-cancelled state. .next() resolves immediately with cancelled.
7. Attempt 2+: subscribe_track itself returns Err(cancelled).
8. Loop bails; Error: subscribe catalog. cancelled.

Fix (commit 8cc7cbd42): hold ONE subscription open for the full 10 s budget; inner timeouts on .next() poll for the first group; outer timeout caps the total wait. Code is in hang-interop/hang-listen/src/main.rs.

This eliminates the cancel-cascade failure mode. 2 of 5 sweep runs post-fix go all-green; 3 hit the residual described next.

Residual root cause (unidentified)

Same test, post-fix, fresh repro from sweep run 4:

12:35:45.333625  subscribe started id=0 catalog.json
                 (no further logs from hang-listen for 2.94 s)
12:35:48.267341  subscribe error id=0 err=remote error: code=0
                 Error: catalog read | moq lite error: cancelled

The single, long-lived subscribe is cancelled by the peer (relay or speaker) ~3 s after start. Wallclock alignment:

• Speaker started broadcasting at T=0
• delay(listenerLateJoinDelayMs = 2_000) → T=2 s
• hang-listen connects + subscribes → T=2.05 s
• Speaker's broadcast window ends at T=5 s (helper does delay(speakerSeconds * 1_000 - listenerLateJoinDelayMs) = delay(3_000) AFTER hang-listen starts)
• Listener-observed cancel at speaker-T+~5 s = ~3 s after subscribe

So the cancel coincides with the speaker tearing down. The catalog data never arrived during the 3 s subscribe window, despite the speaker presumably having the hook installed AND the inbound SUBSCRIBE arriving normally.

Ruled out

• Hook installation race. MoqLiteNestsSpeaker.setOnNewSubscriber is called BEFORE the speaker transitions to Broadcasting state (MoqLiteNestsSpeaker.kt:176-182). Listener subscribes 2 s later — hook is definitively installed.
• Stale inboundSubs. @BeforeTest calls resetShared() which restarts the moq-relay subprocess. Speaker session is fresh per test (new pumpScope + fresh MoqLiteSession). No cross-test state leak.
• Hook captured-but-null. registerInboundSubscription reads onNewSubscriberHook inside the gate AFTER the sub is added. By T=2 s the hook is non-null.
• inboundSubs.isEmpty() race in send(). Hook is launched AFTER inboundSubs += sub inside the same gate. The hook's send() re-acquires the gate; sees inboundSubs non-empty.
• MAX_STREAMS_UNI exhaustion at speaker. Catalog uni stream is one stream per subscriber; cap is 10000.
• Idle timeout. Quinn's default (per moq-native) is 30 s, not 3.
• Audio publisher's onTerminalFailure firing. Only triggered by MAX_CONSECUTIVE_SEND_ERRORS thrown errors, not the no-subscribers return false path that the audio publisher takes during the 2 s warmup.

Plausible remaining hypotheses

1. Relay-side per-track state race. The relay's downstream subscriber (forwarding to hang-listen) is created when hang-listen's SUBSCRIBE arrives. The relay's upstream subscriber (subscribed-on-speaker) might be created on-demand and might race with the speaker's hook firing. If the relay's upstream consumer isn't fully alive by the time the speaker's uni stream arrives at the relay, the relay drops the uni without forwarding.
2. Catalog uni stream priority/scheduling. The audio publisher (running silent — inboundSubs.isEmpty() → return false) could somehow contend with the catalog publisher's uni-stream open via the shared transport.openUniStream(), even though they're separate publishers with separate gates. Less likely.
3. moq-rs CLIENT-side subscribe_track returning a stale consumer. Even on the first call, if the broadcast's track- producer pool has ANY residual entry from an earlier test (despite resetShared()), the consumer might be born already-cancelled. The 2/5 pass rate suggests there's a timing component.
4. Track.unused() racing with the long subscribe. The hang crate's CatalogConsumer::new(track) may temporarily drop an internal handle, causing a brief unused() flicker that aborts the upstream subscription before the speaker's data arrives.

What would confirm a hypothesis

1. Speaker-side log instrumentation. Add Log.d("NestTx") { "catalog hook fired for subId=$id" } inside the setOnNewSubscriber lambda; "catalog send returned $result for subId=$id" after each send(); "catalog endGroup completed for subId=$id". Run the failing test under --info Gradle output to see if the hook fires + writes succeed on the SPEAKER side. If yes → the data is being written but the listener isn't receiving it (relay-side issue).
2. Relay-side log instrumentation. Boot moq-relay with RUST_LOG=moq_relay=debug,moq_lite=debug and capture per-test stderr to a file. Look for "subscribe started" / "serving group" / "subscribe cancelled" timing on the relay side. Cross-reference with hang-listen's view.
3. Listener-side QUIC-level capture. Wrap hang-listen's UDP socket via udp-loss-shim modified to packet-log instead of drop. See exactly which streams open + close.

Mitigations attempted (in order)

1. Per-method resetShared() (706ccda67) — kills the relay subprocess between test methods. Closes a moq-rs accumulated- state class but the catalog-cancel pattern persists.
2. hang-listen single long-lived subscribe (8cc7cbd42) — replaces the create-drop-recreate retry shape with one subscribe held for the full 10 s read budget. Eliminates the moq-rs Error::Cancel cascade. 5/5 fail → ~2-3/5 pass.
3. Speaker warmup bump 150 ms → 600 ms (00f6cba31) — gave the relay more time to register the speaker's broadcast in its origin before the listener subscribed. NET NEGATIVE, reverted in 1ddf4967c — same failure pattern AND ate into the listener's catalog-read window (5 s broadcast minus 600 ms warmup leaves ~4.4 s instead of 4.85 s).
4. hang-listen 250 ms post-origin.announced() sleep (207057374) — gave the relay time to fully prime its per-broadcast upstream-subscribe pump. NET NEGATIVE, reverted in 9b8b5692b — combined with #3 produced 0/5 sweep pass (worse than single-subscribe-fix-alone's 2/5) because the cumulative ~850 ms of pre-subscribe delay shrank the catalog-read window into the speaker tear-down region.

Lesson: the failure window for the broken-routing case is ~3 seconds (until the speaker tears down at end of broadcast). ANY pre-subscribe delay shrinks the available retry budget on the listener side. Mitigations should NOT add delays.

Smoking gun (from speaker stderr trace)

For broadcasts that fail (10d4b6f2…, c75e2648…, f1be27ef…), the speaker-side Log.d("NestTx") trace shows ONE event for the broadcast suffix:

12:53:32.293 ANNOUNCE inbound prefix='' → emitted Active suffix='f1be27ef…'

…and then NOTHING for the entire 10 s catalog-read window. No SUBSCRIBE inbound, no openGroupStream. The audio publisher keeps logging send returning false — no inboundSubs at 50 fps until hang-listen times out. Meanwhile hang-listen's moq-rs client is logging subscribe started id=0 catalog.json and waiting.

Interpretation: the relay accepts the listener's wire SUBSCRIBE on the downstream connection, BUT does not open an upstream SUBSCRIBE bidi to the speaker. The two sides are disconnected; nothing the test code can fix from above.

For broadcasts that succeed (688e130b…, 6e577e5f…), the same trace shows:

12:58:10.334  ANNOUNCE inbound prefix='' → emitted Active suffix='6e577e5f…'
12:58:11.246  SUBSCRIBE inbound id=0 broadcast='6e577e5f…' track='catalog.json'
12:58:11.246  SUBSCRIBE registered id=0 …
12:58:11.247  openGroupStream subId=0 seq=0
…

The relay successfully forwards the upstream SUBSCRIBE. It's a binary "the relay does or does not forward" — there's no partial state.

Conclusion

The flake is moq-relay 0.10.x's relay-side per-broadcast forward-subscribe routing, not anything the test or speaker can mitigate from outside. Some component of the relay's Origin::announced() → broadcast.subscribe_track(...) → upstream subscribe pump is set up asynchronously and intermittently fails to wire up the upstream subscribe.

Possible next steps if this matters more:

1. Boot the relay with RUST_LOG=moq_relay=trace,moq_lite=trace under the test harness (currently RUST_LOG=info); capture per- test relay stderr to a tempfile; check whether the relay logs the upstream subscribe attempt for the failing broadcast suffix.
2. File an upstream issue at kixelated/moq with this reproducer (HangInteropTest 5x sweep, ~40-60% flake under load) citing the smoking-gun trace pair above.
3. Stop pinning to moq-relay 0.10.25 and try the next minor release — maybe the race has been fixed upstream since.

Currently rejected: bumping speakerSeconds to 8 s and changing the test's threshold. That masks a real bug; the failure mode is worth surfacing.

Files referenced

• nestsClient/tests/hang-interop/hang-listen/src/main.rs:160-220 (post-fix catalog read shape)
• nestsClient/src/commonMain/kotlin/com/vitorpamplona/nestsclient/MoqLiteNestsSpeaker.kt:170-181 (setOnNewSubscriber hook installation)
• nestsClient/src/commonMain/kotlin/com/vitorpamplona/nestsclient/moq/lite/MoqLiteSession.kt:1167-1192 (registerInboundSubscription + hook-launch path)
• nestsClient/src/jvmTest/kotlin/com/vitorpamplona/nestsclient/interop/native/HangInteropTest.kt:170-180 (late_join_listener_still_decodes_tail scenario)
• Pre/post sweep results: 0/5 → 2/5 over 10 total sweep runs.