Controls batch 16b: seek the session in one step on both hosts, behind a publish fence

[tamashi095]

Controls batch 16b: the session seek. One call moves the session's timeline and every source to one timeline sample, under one new generation, all or nothing, on both hosts. A publish fence makes every consumer take the seek in the same render block even while the session thread pushes during a render. The C ABI exports miso_engine_v1_session_seek and _session_seek_at. The browser engine module exports the same two calls. The headless SDK gains OfflineEngine.seek. This PR sits on batch 16a and merges after it.

Closes #1642
Closes #1643

What changed

• Seek the timeline and every source in one C ABI call #1642 tranche 1 (51ec4fd): the publish fence and the session seek in the core.

  • The publish fence (root ruling B16-R2). There is one PublishedGeneration word per session (an Arc<AtomicU64>). PlanStateInventory keeps it across every plan of the session: successors, discontinuity successors and withdrawn-candidate successors. Every source producer, the timeline producer and each plan's source-set driver share it.
  • The driver loads the word once per block entry (Acquire). SeekState::take_published, the one peek/pop path, pops a command only when its generation is at or below the word.
  • Every seek push publishes max(word, g) with a Release fetch_max. The session seek publishes once, after its last push.
  • The PCM acquire peeks each block before it pops it, so a block whose seek is held back stays queued. Nothing acked is dropped.
  • Behaviour note: a per-source seek pushed while a block renders now applies at the next block, not possibly the current one. Only a concurrent host can see this.
  • SourceControlSet::seek_session:
    • It refuses generation 0, and a generation at or below the word (source.generation.stale).
    • It checks every producer with check_seek before it pushes to any.
    • It pushes the timeline first, then the sources in ID order. Each source goes to min(timeline_sample, its frames); the timeline frame is not clamped (limit 2^53).
    • A push that fails after the checks is InternalInvariant.
  • SessionState::session_seek runs the service step, then seeks the newest committed session (the candidate's producers while a swap waits).
  • The word costs 24 B, charged in PlanStateInventory.

• Seek the timeline and every source in one C ABI call #1642 tranche 2 (a5beb8b): the C ABI.

  • miso_engine_v1_session_seek and _session_seek_at share one body.
  • MISO_ENGINE_V1_FEATURE_SESSION_SEEK is 1 << 10, so the mask is 2047. The frozen symbol list goes 19 -> 21.
  • Header: the session seek paragraph after "Anchored seek.", the thread table and the "Control service" list. The text says a host may pick one above the largest generation it has used.
  • The qualification record carries the same text.
  • Four private intra-doc links became plain code spans.

• Root ruling B16-R8 (5567f74): RealtimePlanOwner::active_plan_mut, the capi gates' reader of the active plan's timeline, is behind a new engine/test-support feature. capi's dev-dependency turns it on. The workspace debug-test and doctest steps of qualification.yml name it, so check-test-support-ci.py passes (13 packages). The release build does not see it. The edit under crates/engine/src/realtime/ was accepted on its one attempt.

• Seek the timeline and every source from the browser module export and the headless SDK #1643 (e9a203c): the browser and headless SDK.

  • miso_engine_web_v1_session_seek and _session_seek_at call SessionState::session_seek only: no seek logic in host-web, and no prepare_source_seek. A host with no control half refuses with RESULT_REFUSED_LIFECYCLE.
  • OfflineEngine.seek(frame, { generation? }) calls WasmBoundary.sessionSeek once (after B16-R9 the core declares the discontinuity itself). The default generation is one above the largest this engine object has used through seek, seekSource or submitSource (B16-R5).
  • Mirrors: EXPORTS goes 108 -> 110, and the SDK mirrors are regenerated.
  • host-web's test-support also names control-plane/test-support and engine/test-support, for the timeline reader.

• No production caller yet. miso_engine_web_v1_session_seek_at waits for Seek the timeline and every source from the browser SDK and the PCM feed #1644, the browser SDK seek. The headless seek() is the first SDK caller of miso_engine_web_v1_session_seek.

• Root ruling B16-R9, folded in 07b8084.

  • A plain session seek is a declared discontinuity. SessionState::session_seek checks every producer, then declares the discontinuity through the core's one declaration path, then pushes, in one call on both hosts. A refused seek declares nothing. A refused declaration pushes nothing and returns the declaration's own error. A push that fails after the check is InternalInvariant.
  • An anchored session seek keeps continuity and declares nothing. It is the loop and exact-start form; a declaration would reset floors and effect tails before the anchor while the old pass still plays.
  • No host and no SDK calls declare_discontinuity before a session seek. The SDK and the audit lost their separate calls, and B15-R7's order is retired (Reset latency floors at a host-declared discontinuity #1323, Seek the timeline and every source from the browser module export and the headless SDK #1643, Seek the timeline and every source from the browser SDK and the PCM feed #1644).
  • declare_discontinuity keeps its duty for a stop, and before a seek of every source made with per-source seeks.
  • Gates, each red when its rule is removed: a refused plain seek publishes nothing; an accepted plain seek publishes one discontinuity successor and its seek applies; an anchored seek publishes no successor. They run on the C ABI (session_seek_declares, also while a candidate waits), in a parity row at 48 and 96 kHz, and in the headless SDK eval. The floor is raised on the Keep every node's latency from dropping during playback #1285 path, through a new structural frame remove_t3_limiter (structural-frames.json regenerated).

• Review fold M2 (07b8084).

  • The unfenced mode is gone. The session's word is a required argument of every ring, timeline and set preparation, and prepare_graph_source_set is removed.
  • The only unpublished push is the source crate's SessionSeek (PublishedGeneration::session_seek). It owns the zero and stale rules, refuses a producer of another session, and publishes once, only if it pushed.
  • A set, carry or swap across two words is refused (SourceGraphSourceSetError::SessionWord; a pointer compare on the render path).
  • PcmSourceRing::prepare(config) stays for standalone tests. It gives the ring a private word, so the ring is fenced as a session of one.

• Review fold M1. Stale tests where the word is above every live producer (host-core), and where a removed source keeps a session seek stale (capi). Each is red without the stale rule.

• Current host difference (root ruling B16-R10, Ask for a control queue slot only when a declared discontinuity publishes #1707). On the browser, a plain session seek or a standalone declare_discontinuity refuses with RESULT_BACKPRESSURE when the control table queue is full, even when nothing would publish. The C ABI has no such queue and returns OK. Ask for a control queue slot only when a declared discontinuity publishes #1707 fixes it in the core for both calls, with a parity row.

Evidence

• Gate 1b (crates/host-core/tests/session_seek.rs):

  • A session thread pushes 10,000 plain and anchored session seeks with rising generations, at random moments up to 40 µs into a block, while a render thread renders.
  • Every seek lands in one block, on the timeline and on both sources, at Simd8 and Simd4.
  • Render-thread allocations, reallocations and frees are 0.
  • With the fence removed, it went red in both runs (the short source one block ahead).

• C ABI gates 1-7 (runtime::tests::session_seek): both forms move everything at one block; a stale generation changes nothing; one full slot refuses every consumer; a seek before the swap reaches the carried source, the added source and the timeline; a per-source seek leaves the timeline alone; the ABI checks pass.

• Browser gates 1 and 3a (hosts/host-web/src/tests.rs, mod session_seek). Gate 2 headless eval (sdk/test/capability-evals.mjs): the export order, default generations and stale refusal. SDK suite: 565 of 565.

• Parity row (B16-R6, control_parity.rs::the_session_seek_is_alike_on_both_hosts_for_plain_and_late_seeks): a plain and a late anchored session seek at 48 and 96 kHz, with three sources (one shorter). The browser and C ABI seek reports are equal field by field, and the output bits are equal, at the call and after every block. The row reads the timeline on the browser only, because capi has no public test hook for it; capi's own gates pin the C ABI timeline.

• audit capi: pcm_digest 4f52089e4a8cf83c -> bffc21e857b5e134. Reason: the new audit step, miso_engine_v1_session_seek(session, 3, 8 * QUANTUM_FRAMES) and then one generation-3 quantum, each RESULT_OK, plays that quantum in call 5, where the run gave underrun silence before. The B16-R9 fold removed the audit's separate declare_discontinuity call. The digest did not move with it, because the audit session has no raised floor and no source-read offset, so neither declaration publishes. 0 violations; replacements == 1 holds.

• The full local CI-equivalent set (batch-gates.sh) ran on the fold tree d05a35d and passes, with one exception below. 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 and the workspace tests;
  • all 15 shell gates, the web build, check-web-audioworklet (callgraph pins included), check-sdk-headless (566 of 566), the 7 Python gates and the fuzz check.

• The exception was the doc job's test-support CI self-test (scripts/test-test-support-ci.py). It pins the debug-test step's feature string and host-web's manifest text, and B16-R8 (engine/test-support) and Seek the timeline and every source from the browser module export and the headless SDK #1643 (host-web forwarding control-plane and engine) made those pins stale. 0282d0b updates them. Its doctest-parity mutation now drops protocol/test-support, which nothing forwards. At the 16b head 0282d0b, the full doc job (every step, the self-test included), the capi and host-web test suites, check-capi-abi.sh and fmt pass again.

• Browser qualification passes on the fold tree on Chromium 151.0.7922.34, Firefox 153.0 and WebKit 26.5 (--check-matrix --self-test-mutations). Render-locked allocations are 0. Later commits change no web code: fold 3 changes capi tests, a header wrap, a host-web test name and a CI self-test script.

• Artifact miso-engine-v1-audio-worklet.simd128.wasm at the 16b head: 4,212,349 bytes, sha256 4c7c5c7af31d759d2744a5ed079effeebbf2b5fa0e4d37152b04e4d3e95c660d (the committed release pin is not re-pinned).

Re-pins

• None. The 24-byte fence word is charged in PlanStateInventory::retained_bytes. No source pin or ceiling moved. capi_retained_bytes stays inside its 175,296 ceiling (resource_lifecycle passes; 168,378 at batch 16a, plus the 24-byte word). Browser boot high-water growth: 19,857,408 bytes, unchanged, within the 20 MiB pin (20,971,520).

Review

• Batch review (opus-high): FAIL, no blocker. The fence design is confirmed sound, and gate 1b was red 3 of 3 with the fence off. Three majors, all folded in 07b8084:
  • M1: the stale-against-the-word rule had no test that separated it.
  • M2: the unfenced second mode was removed.
  • M3: a refused headless seek still declared a discontinuity. This is root ruling B16-R9, folded as above.
    Minors folded: a complete header refusal list, one qualification-doc wording fix, Seek the timeline and every source from the browser SDK and the PCM feed #1644 names the web session seek exports, a test comment, and the 3a lifecycle test now checks that no seek waits.
• Fold verification (opus-high): PASS, no blocker or major. Every fold rule is red under its mutation: the stale rule, declare-before-check, no declaration, an anchored declaration, the SDK's separate declaration, and the lifecycle order.
  • The verifier confirmed that the producers after the declaration are the very ones checked, so a valid seek cannot become INTERNAL.
  • PcmSourceRing::prepare(config) has no host caller; only the source crate's integration tests call it. So it stays ungated, which meets root ruling B16-R10's condition.
  • Its one rule with no gate, "a refused declaration pushes nothing", now has one: session_seek_declares::a_refused_declaration_pushes_nothing_and_leaves_the_generation_free (c2e6328). It is red when the declaration's error is ignored. The same commit rewraps one header line, renames one test and adds two record lines.

Issues to file from this batch's specs

• Ask for a control queue slot only when a declared discontinuity publishes #1707 ask-for-a-control-queue-slot-only-when-a-declared-discontinuity-publishes (root ruling B16-R10).
• Report source refusal diagnostics on the browser as on the C ABI #1706 report-source-refusal-diagnostics-on-the-browser (the Export transaction apply and anchored seek from the browser engine module #1293 review's MINOR 5; the C13 one-host difference "source submit diagnostics"; no issue existed). Report the timeline seek position to hosts #1704 (formerly TBD45) was filed from batch 16a.

Spec bodies to sync after merge

#1642 (tranche 1 and 2 records, B16-R8, B16-R9), #1643 (decision record, B16-R9), #1644 (caller of the web session seek exports; B15-R7 retired), #1323 (B15-R7 retired), #1706, #1707.

CI fold

• The first CI run failed in "release shape and panic-clobber policy" (cargo check --release --workspace --all-targets, no features): four host-web lib tests and four control_parity helpers called test-support-only functions without the feature. e2a782d gates them like structural_apply; the batch gate script now runs both no-feature checks.

🤖 Generated with Claude Code