Controls batch 15c: seeks anchored on the source-read clock, prime check and replay, seek contract docs, source-read clock, seqlock loom model (#1316, #1320, #1317, #1396, #1702)

[tamashi095]

Controls batch 15c: the source and latency chain's second half. Every seek is anchored on the plan's source-read clock, and a host can read where each seek landed. A plan carries a source-read offset that a successor inherits and a declared discontinuity resets. A source consumer can check and replay its next blocks for a prime. The C header documents the seek contract and the ABI growth rule. The engine's one seqlock is modelled under loom. This PR sits on batch 15b and merges after it.

Closes #1316
Closes #1320
Closes #1317
Closes #1396
Closes #1702

What changed

• Anchor every seek on the plan's source-read clock #1316 begin_block_at's anchor is the source-read sample (equal to the render clock in this version). Render publishes one seek report per ring: the generation in effect, the source-read sample and source frame of its first block, and the cumulative underrun and held frames. It goes through the engine's one single-writer seqlock (new crates/engine/src/realtime/seqlock.rs, B15-R1; watermark.rs moved onto it; record size unchanged). C ABI: miso_engine_v1_source_seek_report, struct miso_engine_v1_seek_report (64 bytes; the struct cannot share the function's name in C), FEATURE_SOURCE_SEEK_REPORT = 1 << 9 (batch 15b's Reset latency floors at a host-declared discontinuity #1323 took bit 8 first), mask 0x3ff, frozen symbol list 19. The browser export is Export transaction apply and anchored seek from the browser engine module #1293 D6 in batch 16, with a parity row against the C struct, independent of Run the browser control plane in a Worker and keep the AudioWorklet render-only #1332 (root ruling); the browser cannot seek through the core before Export transaction apply and anchored seek from the browser engine module #1293 either.
• Let a source consumer check and replay its next blocks for a prime #1320 spsc::Consumer::peek (a shared read that changes nothing; unit and loom tests). source: prime_ready (a read-only readiness walk) and prime_block_at (plays exactly the blocks the consumer would have played and observes no command), a prime flag shared by the handle and the consumer, and the prime_required_bytes report row (24 B per ring on 64-bit, 12 B on wasm32).
• Document the seek contract and the C ABI growth rule in the header #1317 Eleven seek paragraphs in the C header on the source-read clock, the "ABI growth" comment (B15-R3), the qualification record, and abi_smoke.c now tests each defined feature bit instead of the exact mask. Every sentence was checked against the code.
• Give a plan a source-read clock that leads its render clock #1396 A plan carries a source-read offset: the source section reads at render sample + offset (checked; overflow is TimeOverflow). The inventory records it; an ordinary successor inherits it and a discontinuity successor resets it (runs_behind_natural_timing gains the offset term). After each block render publishes the active plan's render and source-read clocks (two Release stores into a preallocated record, 32 B native, 24 B wasm32). No reader needs the two as a consistent pair (checked in review: the planned callers Adopt a warm successor with a raw-frame prime at the first ready block #1355, Fall back to the transition when a warm successor is not ready by its deadline #1358, Check the warm-successor deadline in miso_engine_v1_service and report its outcome #1360 and Check the warm-successor deadline in the browser Worker's service loop and report its outcome #1361 each read one); the doc says a reader that needs both must use the seqlock.
• Model the engine seqlock under loom #1702 seqlock.rs runs through the engine's sync shim, and a loom model (one writer, one reader) proves a read never returns a torn record. CI runs it in the realtime race-model job. Under cfg(loom) only, a read takes 2 attempts instead of 64 so loom can finish; shipped builds keep 64. Red with the reader's Acquire fence, the second sequence compare or the writer's Release fence removed (loom finds torn records [1, 2] / [0, 1]). No ordering changed. Known limit: a cargo test filter that matches no test passes, so a rename that drops the seqlock_loom prefix would run nothing (the SPSC leg has the same exposure).
• No production caller yet (Let a source consumer check and replay its next blocks for a prime #1320, Give a plan a source-read clock that leads its render clock #1396). No production path calls the prime check and replay, or sets a nonzero source-read offset, until Adopt a warm successor with a raw-frame prime at the first ready block #1355, which wires both on both hosts. Their tests are the evidence: Let a source consumer check and replay its next blocks for a prime #1320's eleven readiness tests, the replay-equals-ordinary-blocks, no-command, shared-flag and zero-allocation gates; Give a plan a source-read clock that leads its render clock #1396's seek-on-the-source-read-clock, inheritance, reset and clock-publication gates. Adopt a warm successor with a raw-frame prime at the first ready block #1355's spec records that it must amend the header's "equal to the render clock in this version" sentence when the offset becomes nonzero.

Evidence

• The full local CI-equivalent set (batch-gates.sh) passes at 8e73689 (the tree of ae580b0): fmt, bench and realtime policy (151 marked regions in 33 files), host-core feature matrix and loom, workspace clippy, the workspace tests, the doc job (cargo doc -D warnings), all 15 shell gates, the web build, check-sdk-headless (564 of 564), the 7 Python gates and the fuzz check. check-web-audioworklet failed there only because INDIRECT_SITES pins enter_block's mangled name, and Give a plan a source-read clock that leads its render clock #1396's impl PlanClocks moved it from Ms6 to Ms7; the site count stays 4 and the trap owners and panic entries are unchanged. The pin edit (c48cc38, owner-approved, made by root) renames the key; check-web-audioworklet passes at c48cc38. Later commits change comments and docs only (doc job and realtime policy re-run green).
• Browser qualification passes at c48cc38 on Chromium 151.0.7922.34, Firefox 153.0 and WebKit 26.5 (--check-matrix --self-test-mutations); render-locked allocations are 0. Two earlier Firefox failures ("spectrum collection audio resume timed out") came from the local harness, not from 15c: its PulseAudio socket path was 119 bytes, over the 108-byte Unix limit, so the null sink never opened and Firefox's resume() waited for an audio server that did not exist (bisection: the result depended on time, not on the commit; with the socket up, 15c's head and its parents pass 2 of 2). The harness now uses a short path and stops if the socket is missing.
• audit capi: 0 allocations, deallocations, locks and syscalls; pcm_digest 4f52089e4a8cf83c (unchanged from batch 15b).
• Realtime policy: 151 marked regions in 33 files (the one new region is seqlock.rs's publish).
• Loom: spsc_loom 15 of 15 (with the new peek model); seqlock_loom passes (4.3 s test time).

Re-pins (each from a measurement)

• None. New report rows: seek_report_bytes (64 B per ring on 64-bit, 56 B on wasm32), prime_required_bytes (24 B / 12 B) and the clock record (32 B / 24 B); every host-web and C ABI ceiling holds (tightest: browser sourceOverheadBytes 2,474 of 2,496).

Review

• Batch review (opus-high): PASS, no blocker or major. Five minors: four folded in 544da3b (policy-comment attribution, a doc that contradicted a literal mask pin, a clock-pair snapshot note, rewraps); the fifth (the seqlock had only an x86 stress test) became Model the engine seqlock under loom #1702, which root put inside this PR.
• Root's question (are the two clocks read as a pair?): no reader needs them as a consistent pair; every planned caller reads one.
• Model the engine seqlock under loom #1702 and fold verification: PASS; five mutants (each removed or weakened fence or ordering) all turn the loom model red. Three cosmetic minors folded in f0f10f8.

Issues to file from this batch's specs

• Model the engine seqlock under loom #1702 model-the-engine-seqlock-under-loom (lands and closes in this PR).

Spec bodies to sync after merge

#1316, #1320, #1317, #1396, #1293 (D6 amendment), #1355 (note), #1702.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}