Controls batch 16a: the session timeline, carried like a source; the browser's anchored seek and seek report

[tamashi095]

Controls batch 16a: the session timeline. The source crate gains the session's playhead, a timeline consumer and producer that share one written copy of the seek rules with the PCM sources. Every prepared plan, on both hosts, holds one timeline and carries it to a successor exactly as it carries an unchanged source. The browser engine module also exports the anchored source seek and the per-source seek report, through the same core calls as the C ABI. Nothing in render reads the timeline yet (the first reader is #1647). The session seek that moves it lands in batch 16b (#1642, #1643).

Closes #1640
Closes #1641
Closes #1293

What changed

• Spec check and rulings (docs). The five batch 16 specs were checked against 35ac17545 (eab696d). Root rulings B16-R1 to B16-R7 are recorded (ee5322e):
  • R1: seven seek exports join decision 17 C13's approved list.
  • R2: the session seek's publish fence (Seek the timeline and every source in one C ABI call #1642, batch 16b).
  • R3: the timeline's readiness is the non-PCM test (Give every plan a timeline that carries like a source #1641, Adopt a warm successor with a raw-frame prime at the first ready block #1355).
  • R4: Give every plan a timeline that carries like a source #1641 D6 is deferred to Report the timeline seek position to hosts #1704.
  • R5: the SDK chooses the generation (Seek the timeline and every source from the browser module export and the headless SDK #1643).
  • R6: Seek the timeline and every source from the browser module export and the headless SDK #1643 parity row.
  • R7: Export transaction apply and anchored seek from the browser engine module #1293's record is 64 bytes with the C struct's layout.
• Build the timeline consumer and producer in the source crate #1640 (3f53c07).
  • The seek rules are factored once. A private SeekState holds the active generation and the held seek, with one observe step for the Now, At and Hold clocks. A private SeekProducer has check_seek and try_seek. The PCM source and the timeline both use them.
  • PcmSourceProducer and HostChunkProvider gain check_seek, which Seek the timeline and every source in one C ABI call #1642 calls on every producer before it pushes to any.
  • New TimelineConsumer (with begin_block_at, timeline_at, timeline_block, copy_history_from), TimelineProducer, TIMELINE_SAMPLE_LIMIT = 2^53 with SourceSeekError::FrameOutOfRange (source.seek.frame_out_of_range), and TimelineResourceReport.
  • The source seek tests keep their assertions. Eight tests now name the moved fields (consumer.seek.*).
• Give every plan a timeline that carries like a source #1641 (769dbb2).
  • Every host-core plan's source set holds one timeline, with K = ceil(A_max / q) + 1 history entries from the floored input arrivals. The driver advances it at block entry, before the sources, from the source-read sample.
  • SourceControlSet owns the producer, and adopt_persisting moves it at all three control-plane call sites.
  • A successor builds a vacant timeline with its own history. GraphCarryProgram gains timeline: bool. The swap block moves the seek state, the command consumer and the position, and copies the newest history entries, with no allocation. The flag is set when the successor's rate and quantum equal the predecessor's, which both hosts require of every successor (#1290a).
  • The readiness check is written once (SeekState::prime_window_clear, B16-R3) and PcmSourceConsumer::prime_ready now uses it.
  • Test reader: graph::test_only_timeline_at, re-exported by host-core under test-support.
• Export transaction apply and anchored seek from the browser engine module #1293 (2f99a34).
  • miso_engine_web_v1_source_seek_at calls SessionState::seek_at; it never calls prepare_source_seek.
  • miso_engine_web_v1_source_seek_report and _source_seek_report_ptr copy SessionState::seek_report, the same call as miso_engine_v1_source_seek_report, into a 64-byte record with the C struct's layout and the reserved words zero.
  • Both refuse a host with no control half with RESULT_REFUSED_LIFECYCLE. Host-web holds no seek logic.
  • Mirrors: EXPORTS goes 105 -> 108. The ABI layout document gains seekReport, the SDK mirrors are regenerated, and the self-tests catch an omitted export (36 mutations).
  • One mechanical edit outside the spec's paths: check-session-map-shape.py skips the record pointer by name. It takes only the handle, like a source-map count query, but it is not one.
• No production caller yet.
  • TimelineProducer's seek and check_seek, and FrameOutOfRange: Seek the timeline and every source in one C ABI call #1642 (batch 16b).
  • timeline_block: Render moving stored fader automation, seeks and latency #1647.
  • The timeline's prime and readiness: Adopt a warm successor with a raw-frame prime at the first ready block #1355, which is amended to call them beside each carried consumer.
  • graph::test_only_timeline_at: test only.
  • The browser source_seek_at and seek report exports have no SDK caller until Send a session transaction to the browser control plane #1294 and Feed and retire the sources a browser edit adds or removes #1297.
  • The timeline itself does run in production: every plan advances it on every block and carries it.

Evidence

• The full local CI-equivalent set (batch-gates.sh) passes at the 16a head 35a125e. It covers:

  • fmt, the bench policy, and the realtime policy (153 marked regions in 33 files);
  • the host-core feature matrix and loom;
  • workspace clippy (--all-targets --all-features -D warnings) and the workspace tests;
  • the doc job (cargo doc -D warnings);
  • all 15 shell gates, the web build, check-web-audioworklet, check-sdk-headless (564 of 564), the 7 Python gates and the fuzz check.

• An earlier run at 454d656 (before the folds) failed only the doc job, on three private intra-doc links. The fold fixed them.

• Browser qualification passes at 35a125e on Chromium 151.0.7922.34, Firefox 153.0 and WebKit 26.5 (--check-matrix --self-test-mutations). Render-locked allocations are 0 on all three (render and SDK rows).

• audit capi: pcm_digest 4f52089e4a8cf83c, unchanged from main. 0 violations.

• Realtime policy: 153 marked regions in 33 files (+2, Build the timeline consumer and producer in the source crate #1640's timeline regions; floor 151 -> 153).

• Built artifact miso-engine-v1-audio-worklet.simd128.wasm at the 16a head: 4,203,669 bytes, sha256 ad535e83943d2bcaed785a743c5424e0a80cef0d3bf7fd3851b424638196c5b1 (the committed release pin is not re-pinned).

• Export transaction apply and anchored seek from the browser engine module #1293 gate 7 asks for workspace clippy. The implementer ran clippy on two packages only. The batch gates' workspace clippy (--workspace --all-targets --all-features -D warnings) covers it at the 16a head.

Re-pins (each measured; reason: the timeline consumer's fixed bytes, #1641 D7)

The step is 480 B native (command queue 320, history 16 per entry, inline consumer 144) and 448 B on wasm32. The consumer is charged once, in the driver's allocation row. Each new ceiling is the measured value plus 10 %, rounded up to 64 B.

Pin	Before	After	Ceiling
capi source_overhead_bytes (x86-64)	4,174	4,654	4,352 -> 5,120
host-web source_overhead_bytes (x86-64)	2,658	3,138	2,688 -> 3,456
host-web source_total_bytes (x86-64)	3,682	4,162	3,840 -> 4,608
expected.json sourceOverheadBytes (wasm32)	2,474	2,922	2,496 -> 3,264
expected.json sourceTotalBytes (wasm32)	3,498	3,946	3,648 -> 4,352

These stay inside their ceilings with no re-pin: capi source_total_bytes 12,366 -> 12,846, and capi_retained_bytes 167,754 -> 168,378 (ceiling 175,296). The identity source_overhead + carried_source_overhead == fresh holds. Browser boot high-water growth: 19,857,408 bytes, unchanged, within the 20 MiB pin (20,971,520).

Review

• Batch review (opus-high, with three opus-xhigh reviewers running mutations): FAIL, no blocker, four majors, all folded in 90b76cf.
  • M1: timeline_block reported no step where a declared discontinuity steps the source-read clock back.
  • M2: the carry program's timeline flag had no test. A successor that carries no source would have restarted the timeline while the moved producer acked seeks: an ack before a drop.
  • M3: a timeline vacant on both sides refused every lane's carry.
  • M4: Feed and retire the sources a browser edit adds or removes #1297 D3 had the feed worklet's render path call source_seek_at, which runs the service step, and Send a session transaction to the browser control plane #1294 D1 named exports Export transaction apply and anchored seek from the browser engine module #1293 dropped. Both specs are amended: anchored seeks go through the message handler only, and Send a session transaction to the browser control plane #1294 applies through control_request_ptr / control_command.
  • Eleven minors were folded. These include: tests for the rate/quantum guard, a never-adopted timeline, a seek queued at the swap block and the reader's search order; unread report rows removed; two byte guards that had become vacuous; a behavioural test for the seek-report pointer; a name-swap mutation in the ABI self-test; check-session-map-shape.py excluding _ptr exports by rule; install_carry_program refusing a timeline carry with no source set; three tests with no unique catch deleted; private intra-doc links that failed the doc job.
  • M1, M2 and M3 each have a test that is red on the unfixed code.
• Fold verification (opus-high, 14 mutations, all red): FAIL on one major. The M1 fix still missed a step-back where the node block reads before every held entry. Fold 2 (35a125e) adds the missing comparison, with K=2 and K=3 cases and a sweep over K 1..5 and five step-backs, red on the fold-1 reader. The verifier had checked this exact fix in a scratch copy, so there was no second verification round. The same commit folds three minors: re-anchored cites, the control-handler wake (miso.seek-at.v1) in Send a session transaction to the browser control plane #1294/Feed and retire the sources a browser edit adds or removes #1297, and record wording.

Issues to file from this batch's specs

• Report the timeline seek position to hosts #1704 report-the-timeline-seek-position-to-hosts (B16-R4; holds Give every plan a timeline that carries like a source #1641 D6).

Spec bodies to sync after merge

#1640, #1641, #1642 (batch 16 check, B16-R1, B16-R2), #1293 (batch 16 check, decision record), #1643 (batch 16 check, B16-R1, R5, R6), #1355 (B16-R3), #1294 and #1297 (batch 16a review amendments; the miso.seek-at.v1 wake is coordinator wording for their re-brief to confirm), #1704. Decision 17 ruling doc: C13 list (B16-R1).

🤖 Generated with Claude Code

---

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