Controls batch 15a: replace an unadopted candidate plan (#1310), prepare across a withdrawn one (#1344), capacities for a superseding candidate (#1398)

[tamashi095]

Controls batch 15a: a structural edit is never refused because a replacement plan is waiting. It supersedes the unadopted candidate, keeping every acked edit, queued observation record, source chunk and held seek that the new plan still uses. The C ABI's plan capacities and resource admission count every plan held at once. The batch also carries the batch 15 spec checks and root rulings for the source and latency chain.

Closes #1344
Closes #1398
Closes #1310

What changed

• Prepare a successor across a withdrawn candidate plan #1344 A successor can be prepared across a withdrawn candidate. PreparedHost::carried_base holds exactly the running plan's (P0's) inventory rows that the withdrawn plan's hand-over reads (PlanStateInventory::restricted_to), and the base is charged (carried_base_retained_bytes). Source rings with an equal declaration are donated from the withdrawn plan to the successor: the consumers move first, then the producers, and the donor is left vacant. A submit to the donor is refused (Vacated), never acked. A fed successor producer refuses the donation (SuccessorFed). crates/engine/src/realtime/plan.rs gains read-only as_any / executor_any twins (control side only; one attempt; accepted by root).
• Size the C ABI's plan capacities and resource admission for a superseding candidate #1398 The plan tables hold three plans at once: 4 report rows, 2 pending providers, 2 retired providers and a retirement capacity of 3. The replacement and live admissions sum every held plan and model, maximum_replacement_peak_bytes included, and count each held epoch's carried rings once. The lag refusal is deleted. A full table is INTERNAL, with a debug assert, because the sizes make it unreachable. AdmissionPeak::WithReprepare was dropped by root ruling: it had no production caller, and Classify a latency-growth edit and publish its warm successor from the control plane #1403 adds it with its first caller.
• Supersede an unadopted candidate plan by compare-and-swap #1310 A structural edit while a candidate A waits withdraws A by compare-and-swap and prepares B against P0 with a kept base: P0's model and monitor overlay, plus the edit ramps committed after P0 merged with B's (B wins on every row it writes, including a write with no length; B15-Q3). Observation records queued on A are re-queued on B (B15-Q4), and the browser copies the forwarded records from the core. A refused B republishes A unchanged. If render took A first (Taken), or the mailbox is empty while a candidate is pending, every pending epoch up to the newest is promoted before the rebuild. A refusal at the three-plan peak is BACKPRESSURE when the edit fits against the newest held plan alone, and COMPILE_REJECTED otherwise. A paused browser page drops superseded candidate shapes from the core's held epochs, so it commits every edit as the C ABI does. crates/engine/src/realtime/plan_exchange.rs gains the reservation's plan / plan_mut accessors (control side only; one attempt; accepted by root).
• The four-lane builtin_bank_bytes ceiling falls from 21,056 to 14,272, from the AArch64 measurement of 12,969 (CI job 116713280504).
• Specs (docs only):
  • Batch 15 checks of Keep every node's latency from dropping during playback #1285, Export transaction apply and anchored seek from the browser engine module #1293, Anchor every seek on the plan's source-read clock #1316, Document the seek contract and the C ABI growth rule in the header #1317, Report held source blocks apart from underruns #1318, Test held seeks across swaps and supersession, and add a seek to audit capi #1319, Let a source consumer check and replay its next blocks for a prime #1320, Reset latency floors at a host-declared discontinuity #1323, Give a plan a source-read clock that leads its render clock #1396, Duck-swap a strip whose state cannot continue across a plan swap #1324, Prepare a successor across a withdrawn candidate plan #1344, Size the C ABI's plan capacities and resource admission for a superseding candidate #1398 and Supersede an unadopted candidate plan by compare-and-swap #1310 against main. Root rulings are recorded as B15-R1..R9 and B15-Q1..Q4 (root decisions under owner delegation).
  • The Diff a replacement document against the committed model and export replace from the browser engine module #1386 re-brief: SESSION_REPLACE 0x0013 and EditPath::Unchanged (5). It is split into (a) core + C ABI, and (b) browser transport, which is Export the browser session replace transport #1697.
  • Amendments to Check the warm-successor deadline in miso_engine_v1_service and report its outcome #1360, Duck-swap the strips a latency growth restarts, and fall back to the transition when a warm successor cannot adopt #1397, Classify a latency-growth edit and publish its warm successor from the control plane #1403, Attribute each claim's revisions exactly in the watermark and share one seqlock #1482, Seek the timeline and every source from the browser module export and the headless SDK #1643 and Seek the timeline and every source from the browser SDK and the PCM feed #1644.
  • Decision 17 C13 names each direct export that batch 15 approved.
  • The specs of 52 closed issues are removed; git history keeps them.

Evidence

• The full local CI-equivalent set (batch-gates.sh) passes on the integrated tree at 5fb2d33: fmt, bench and realtime policy (150 marked regions in 32 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 and check, check-sdk-headless (564 of 564), the 7 Python gates and the fuzz check. The last commit, 5ea0698, changes only C header comments; check-capi-abi passes on it.
• Browser qualification passes at 5fb2d33 on Chromium 151.0.7922.34, Firefox 153.0 and WebKit 26.5 (--check-matrix --self-test-mutations); render-locked allocations are 0 in every scenario.
• audit capi: pcm_digest bf7dcedd1d92621f (unchanged), 0 allocations, locks and syscalls.
• Supersede an unadopted candidate plan by compare-and-swap #1310 gate 5: back-to-back structural edits race render (64 edits: about half withdrawn, half taken). None is refused as backpressure. The settled output is bit-identical to a fresh plan of the final model, and render allocates nothing.
• Parity rows in hosts/host-web/tests/control_parity.rs: eight structural edits on a paused host commit alike on both hosts (48 and 96 kHz).
• No acked chunk is dropped by a supersession. If A created a source's ring (A added the source or redeclared it) and the host has fed that ring since (a chunk, a seek or an end of region), and the donation does not move the ring to B, B is refused with BACKPRESSURE before it commits (host_core::drops_acked_fresh_source, called in the core's rebuild right after the donation check). This covers four cases: B puts the source back in its P0 form, B redeclares it a third way, B removes it, and A added it and B removes or redeclares it. Nothing changes: the reservation is dropped, A stays published, no event is queued and the revision does not move. Once render adopts A, the retry commits on A. A host that does not render keeps getting BACKPRESSURE until it renders (accepted by root). Both hosts refuse alike: parity row control_parity::a_supersession_that_would_drop_acked_pcm_is_backpressure_alike_on_both_hosts covers the reverted, third-way and removed cases at 48 and 96 kHz (same code, same revision, retry commits alike, bit-equal output, and the acked chunk is heard once the plan latency has passed, against a control run that never fed it). C ABI test supersede_tests::a_supersession_that_would_drop_acked_pcm_on_a_fresh_source_is_backpressure (five cases) and host-core withdrawn_successor::the_guard_refuses_exactly_a_fed_fresh_ring_the_donation_leaves_behind (refused and not-refused cases). With the fold-2 guard (reverted case only), the other four capi cases commit and the chunk is lost.
• A known gap, recorded in the header, the Supersede an unadopted candidate plan by compare-and-swap #1310 and Prepare a successor across a withdrawn candidate plan #1344 records, and placeholder Carry an owner a superseding candidate keeps unchanged from P0 from P0's state #1698: a source or owner that A restarted or removed, and that B puts back in its P0 form, starts fresh in B. Carry an owner a superseding candidate keeps unchanged from P0 from P0's state #1698 (the first K slice of batch 15b) carries it from P0 and lifts the refusal for the reverted case only. The other cases stay refused until an issue gives B a way to read those chunks, or the owner rules that a removed source's chunks may drop.
• A source that the caller's own edit removes discards its queued audio (a direct P0 -> B removal, or B removing a source that A carried unchanged from P0). The caller asked for the removal, so this is not an unintended drop. The header and CONTROL_PROTOCOL_SEMANTICS.md say so. No counter reports the discarded frames yet: placeholder Count the frames a caller's own source removal discards #1699.
• Fold 2 also fixes a C ABI wedge (two Taken withdrawals while render lagged its retirements, then a published adoption, answered INTERNAL forever) and charges a plan render displaced until the service step reclaims it. The browser keeps a waiting candidate's spectrum hand-over until render adopts it (before, any service step or command between the commit and the adoption dropped it, for every capture kind).

Re-pins (each from a measurement)

• capi_retained_bytes: 159,354 to 165,922 (Size the C ABI's plan capacities and resource admission for a superseding candidate #1398 tables +1,904; Supersede an unadopted candidate plan by compare-and-swap #1310 carried and kept rows), then 168,810 after fold 2 (x86-64, +2,888: a third retired provider slot of 1,648 bytes, and a 248-byte parked resource row in each of the five provider slots), within the 175,296 ceiling, which stays.
• Four-lane builtin_bank_bytes ceiling: 21,056 to 14,272 (AArch64 12,969 + 10 %, rounded up to 64).
• No browser expected-resources row moved.

Review

• Batch review (opus-high): FAIL. B1 paused browser kept superseded shapes; M1 two-Taken race; M2 carried bytes double-counted; M3 Prepare a successor across a withdrawn candidate plan #1344 gates weak; M4 hygiene; minors. Fold 1 fixed all of them and added the spec work (52 closed specs removed, B15 labels, C13, Seek the timeline and every source from the browser SDK and the PCM feed #1644, Diff a replacement document against the committed model and export replace from the browser engine module #1386 split, Export the browser session replace transport #1697, Carry an owner a superseding candidate keeps unchanged from P0 from P0's state #1698).
• Fold 1 verification: FAIL. B-1 C ABI wedge (two Taken withdrawals while render lagged its retirements, then a published adoption, answered INTERNAL forever); M-1 a plan render displaced but not yet reclaimed was not charged; minors m-1..m-5. Root added the acked-chunk guard to fold 2.
• Fold 2 (9f0513d, 20b417e): RETIRED_PROVIDERS = RETIREMENT_CAPACITY and drain before promotion; parked epochs keep their resource rows and both admissions charge them; the reverted-source guard on both hosts; m-1..m-5; the browser keeps a waiting candidate's spectrum hand-over until adoption. The guard's parity row was silent at the adoption block on both hosts because the rig's session has plan latency (3 blocks at 48 kHz, 7 at 96 kHz); the row now checks the acked chunk after that latency against a control run.
• Fold 2 verification: FAIL. B-A five private intra-doc links failed the doc job; M-A the guard covered only the reverted case (a third-way redeclaration, a removal, and an added-then-removed or redeclared source also dropped the acked chunk). Root ruled: widen the guard to every fed ring A created that the donation does not move. Minors m-A (record), m-B (drain order is defence in depth, not tested), m-C.
• Fold 3 (5fb2d33): host_core::drops_acked_fresh_source after the donation check, five capi cases, host-core unit cases, a parity row for three cases on both hosts, docs and records, the removal contract (Count the frames a caller's own source removal discards #1699), B-A, m-A, m-B; m-C became moot.
• Fold 3 verification: PASS. Three minors: two header wording points, folded in 5ea0698; the parity row does not cover the added-source case (covered by the capi and host-core tests; both hosts share the core path).

Issues to file from this batch's specs

• Diagnose Simd4 on AVX2 refusing the nine-track console fixture #1694 diagnose-simd4-on-avx2-refusing-the-nine-track-console-fixture.
• Read the browser's armed observation taps from the core #1695 read-the-browsers-armed-observation-taps-from-the-core.
• Charge the monitor overlays and edit ramps in the retained rows #1696 charge-the-monitor-overlays-and-edit-ramps-in-the-capi-row.
• Export the browser session replace transport #1697 export-the-browser-session-replace-transport (Diff a replacement document against the committed model and export replace from the browser engine module #1386's browser half).
• Carry an owner a superseding candidate keeps unchanged from P0 from P0's state #1698 carry-an-owner-or-source-a-superseding-candidate-keeps-unchanged-from-p0 (first K slice of batch 15b).
• Count the frames a caller's own source removal discards #1699 (no spec file yet; root to brief): count the frames a caller's source removal discards, and report them on both hosts.
• Already filed, with bodies on this branch: Report the plan latency on the browser #1688, Retire the browser master boot word #1689, Read the master strip's meter on the C ABI #1690.

Spec bodies to sync after merge

#1285, #1293, #1310, #1316, #1317, #1318, #1319, #1320, #1323, #1324, #1344, #1360, #1386, #1396, #1397, #1398, #1403, #1482, #1522, #1643, #1644, #1654, #1688, #1689, #1690.

🤖 Generated with Claude Code

---

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