demuxe 0.3.0-beta.3

package/docs/OPTIMIZATION-FLAC.md

@@ -0,0 +1,178 @@
+# Stage 2: maintained progressive FLAC preparation
+
+Historical checkpoint report. For subsequent local implementation and current coverage, see [completion status](OPTIMIZATION-COMPLETION.md).
+
+For the subsequent correctness fixes and current unequal-tail limitation, see
+[the review-fix report](OPTIMIZATION-REVIEW-FIXES.md).
+
+This is an uncommitted integration checkpoint, not completion of the requested
+optimization program. Starting commit remains
+`f2491f62c777fa55225aed9b0b7ecf2e340accf7` on
+`codex/optimization-integration`. No remote mutation or laboratory modification.
+
+## Implementation and timestamp repair
+
+The optional preparation profile compiles the maintained remuxer with audio-only
+FFmpeg decoders and a FLAC encoder. It contains **no video decoder or encoder**.
+It uses the saved modernization's FFmpeg **9.0.1**, locked patches and Emscripten
+4.0.14. Its own generated glue accompanies its own Wasm. Existing packet-copy,
+Hybrid and Software runtime artifacts remain unchanged; rebuilding all saved
+streaming engines is still a separate qualification gate.
+
+The historical scratch adapter's missing-DTS = PTS algorithm still reproduces
+`33600 >= 32528` and is retained as evidence. The replacement reuses the maintained
+remuxer's explicit H.264 SPS reorder bound and bounded Matroska PTS queue to derive
+missing decode timestamps in packet decode order. Established timestamps elsewhere
+are rescaled normally. Unestablished or discontinuous timestamps reject. No
+arbitrary monotonic clamp, video re-encoding, packet dropping or B-frame blanket
+ban was introduced. The existing codec packaging adapters derive video configuration
+and MIME. Actual packet ends correct the final adapted presentation duration.
+
+`native/adaptation/flac.h` decodes only the selected audio stream, buffers bounded
+integer PCM and feeds a continuous FLAC encoder during sequential playback. Metadata
+probing cannot invoke incidental audio decoders. The final partial frame and encoder
+are drained; decoded and encoded sample counts must agree. Audio/video offsets share
+the maintained source origin and positive mux preroll bias. Browser playback owns the
+final A/V clock. Native FFmpeg used by tests is offline fixture/verification tooling,
+never playback transcoding.
+
+## Explicit admission and fidelity
+
+```js
+const player = new Player(container, {
+  mode: 'native',
+  experimentalAudioAdaptation: 'flac',
+  experimentalBufferedNativeSeeks: true,
+  audioGain: 0.5, // optional, separately requested scalar effect
+});
+await player.open(fileOrQualifiedRangeSource);
+```
+
+Ordinary direct playback and supported audio packet copy are still attempted first.
+FLAC preparation is lazy-loaded only after the copy path reports unsupported audio.
+The existing controller carries remote source identity into that transition.
+General automatic FLAC admission is **disabled**. Explicit Native rejection remains
+visible to the application; it does not silently introduce Opus or another effect.
+
+Tested adaptation inputs are PCM S16/S24, conventional mono/stereo, 44.1/48 kHz.
+Admission requires established 16/24-bit integer precision, unchanged sample rate
+and mono/stereo channel order. Unknown precision, floating-point, 32-bit precision,
+multichannel layouts and midstream configuration changes reject. FLAC/DTS decoder
+support is compiled but has no broad input qualification; DTS with unknown decoded
+precision rejects. This stage makes no surround or lossy-input qualification claim.
+If later qualified for already-lossy input, FLAC would avoid an additional lossy
+generation; it would not restore the original recording.
+
+The gain combination changes amplitude intentionally. Sample-exact conversion
+checks concern decoded FLAC before browser output processing, not speakers or
+physical A/V synchronization. `selectAudioTrack(null)` retains the existing Native
+mute behavior; eliminating conversion for disabled audio is not qualified here.
+
+## Lifecycle and resources
+
+Preparation uses existing File/range/AVIO workers, cancellation mailboxes, source
+identities, deadlines, append admission and worker retirement. Normal playback
+converts ahead incrementally; paused playback stops conversion at the current
+bounded target. Distant seeks restart near the target and retain pause intent.
+Buffered seeks retain the worker/generation only with current MSE coverage and RAP
+eligibility. Overlapping public operations remain serialized.
+
+PCM FIFO is capped at 131072 samples and individual decoded frames at 65536.
+Preparation Wasm starts at 64 MiB with a 128 MiB maximum; existing transport,
+fragment and MSE caps remain in effect. Browser decoder allocations are opaque.
+Diagnostics record copied video packets, decoded frames/samples, encoded
+samples/packets, generated bytes, buffered ranges and cancellation snapshots.
+These are not a complete aggregate resident-memory accounting system.
+
+## Executed evidence
+
+Raw logs, browser JSON, captured output MP4, fixture commands and hashes are under
+`results/optimization-integration/stage2/`. Failed attempts are retained.
+
+| Check | Result and limit |
+|---|---|
+| Eight B0/B2 × zero/nonzero start × duration-match fixtures plus original edge | Chrome and Firefox pass through final output; all copied video packet payloads and PTS offsets preserved; audio decode-back byte exact |
+| Original edge video | Offline decoded frame hashes match; no missing final frames |
+| Two-audio fixture | Chrome selects mono 44.1 kHz PCM16, preserves selection across gain reopen, sample-exact decode-back |
+| Separate audio start offset | Firefox preserves 137 ms audio/video offset |
+| Paused adaptation + gain | Chrome/Firefox: conversion counters stable while paused, bounded ahead, buffered worker reuse, distant/overlapping seeks preserve pause |
+| Real authenticated ranges | Chrome/Firefox: authorization survives copy-to-adaptation transition |
+| Outstanding response-body barrier | Chrome/Firefox: destroy aborts pending open and retires all workers promptly |
+| Incorrect Content-Range | Chrome/Firefox reject |
+| PCM32, float and surround | Chrome explicit precision/layout rejection; cleanup passes |
+| Saved streaming overlay plus actual optimization delta | Assembly 12 compiles; 59 contracts pass |
+| Root contracts with owned range server | 61 pass |
+| Baseline output/signal checks | Chrome: direct, remux, gain, Hybrid, filtered Hybrid, Software pass |
+| Installed clean consumer | Five Chrome routes pass, including optional FLAC assets copied by the public CLI |
+
+The first range-server test command lacked its required server and failed with
+ECONNREFUSED; the corrected invocation passes. An authenticated test initially
+omitted `If-Range` from its test server's CORS allow-list; fixing the harness resolves
+that failure. The first adapter rejected unspecified Matroska mono/stereo layouts;
+explicit conventional-layout handling resolves that case. No failure is deleted.
+
+**Assembly evidence correction:** stage 1 assemblies 02–07 silently skipped tracked
+patches. Their passes establish only saved-overlay behavior. The new assembler
+uses reviewed three-way merges, records each merged file hash, and fails on unknown
+conflicts. Assembly 12 checks combined code. Saved HLS/DASH manifests, qualification
+gates, lockfiles and patch collections remain unchanged. Live/ABR admission has not
+been broadened, and no replacement streaming library was introduced.
+
+## Reproduction and packaging
+
+```sh
+python3 experiments/optimization-integration/fixtures.py
+python3 experiments/optimization-integration/prepare.py --output build/streaming-new
+# Build from the assembled tree so its exact saved locks and patches are used:
+python3 build/streaming-new/streaming/scripts/build-audio-adaptation.py \
+  --sdk /path/to/emsdk-4.0.14 --archive /path/to/verified-ffmpeg.tar.gz \
+  --output /absolute/path/to/new-adaptation-build
+# Copy only the generated matching remux.mjs/remux.wasm to web/engine-adaptation.
+npm run build
+node tests/audio-adaptation.mjs
+BROWSER=firefox node tests/audio-adaptation.mjs
+node tests/audio-adaptation-lifecycle.mjs
+node tests/audio-adaptation-cost.mjs
+python3 scripts/package-beta.py --output build/package-new \
+  --adaptation-build /path/to/versioned-engine-directory
+```
+
+The optional local package includes matched assets, runtime hashes and FFmpeg
+notices. A companion contains preferred patched FFmpeg source, exact patches/locks,
+configuration and immutable preparation source snapshots. Release packaging with
+adaptation is explicitly rejected: full SDK/source-companion release qualification
+is still open. No unrelated benchmark Wasm or LibAV dependency ships.
+
+## Remaining gates
+
+Native ASS and its paused-resize fix, ASS/adaptation/gain combinations, Opus delay
+and drain, full fidelity-policy routing, complete source/worker fault matrix,
+subtitle fullscreen/PiP/casting behavior, HLS/DASH adaptation and sustained browser
+qualification remain incomplete. Safari/mobile are untested. General automatic
+adaptation is disabled. First/steady fragment tuning, FLAC setting comparisons,
+module reuse, Hybrid copy reductions and new Software YUV artifacts are deferred;
+no performance improvement from these candidates is claimed. See the full candidate
+inventory in [the integration report](OPTIMIZATION-INTEGRATION.md).
+
+## Short cost screen
+
+Two cold and two warm trials per plan passed on the same 30-second, 160×90
+PCM24 fixture. Each measured interval includes open, at least 10 seconds playback,
+and destroy. This extends the established CDP process-CPU and `ps` RSS method.
+New processes contribute their lifetime CPU; disappearing processes invalidate a
+trial. The first attempt failed its accounting/setup checks and is retained.
+
+| Condition | Plan | Mean browser CPU seconds | Mean peak RSS MiB | Mean open ms | Mean progress ms |
+|---|---|---:|---:|---:|---:|
+| cold | native | 3.69 | 1005 | 382 | 652 |
+| cold | hybrid | 5.55 | 1106 | 524 | 775 |
+| warm | native | 3.36 | 1107 | 143 | 414 |
+| warm | hybrid | 5.37 | 1179 | 243 | 501 |
+
+Open is promise completion; progress is the first observed public position beyond
+150 ms, not an independent first-photon measurement. Cold means fresh browser,
+not flushed OS caches. RSS includes all observed browser processes and is not
+exclusive memory. External OS media services are excluded. These small-fixture
+results do not qualify universal cost rankings, sustained playback, seek CPU,
+or other new plans. Automatic route ordering remains unchanged. Raw counters
+and per-trial diagnostics are in `stage2/cost-1789507138369/result.json`.

package/docs/OPTIMIZATION-INTEGRATION.md

@@ -0,0 +1,221 @@
+# Optimization integration: local stage checkpoint
+
+Historical checkpoint report. For subsequent local implementation and current coverage, see [completion status](OPTIMIZATION-COMPLETION.md).
+
+For the subsequent correctness fixes and current unequal-tail limitation, see
+[the review-fix report](OPTIMIZATION-REVIEW-FIXES.md).
+
+This is **partial implementation, not completion of the optimization program**.
+Do not promote adaptation, Native ASS, or the new experimental options to general
+automatic admission. A separate maintained audio-preparation engine has been built. Release qualification,
+physical A/V measurement, endurance and performance improvements are not claimed.
+See [the stage 2 report](OPTIMIZATION-FLAC.md) for the current adaptation evidence.
+
+## Starting point and isolation
+
+Remote refs were fetched on 2026-09-15. `origin/main` remained
+`51f0792fa6c5229a8695d908006a0a573bfc1c10`; the integration branch
+`codex/optimization-integration` starts at saved streaming checkpoint
+`f2491f62c777fa55225aed9b0b7ecf2e340accf7` in a dedicated worktree.
+The original checkout and the adaptation laboratory were not modified.
+An existing `origin/HEAD.lock` prevented the first generic fetch; fetching the two
+explicit refs with remote HEAD following disabled succeeded without deleting it.
+No commit, push, merge, tag, or publication was performed.
+
+The original adaptation/risk-review laboratory was found at
+`[local evidence path omitted from runtime package]`.
+Selected original source, patches, failure results and the edge fixture are copied
+under `results/optimization-integration/reference/`, with SHA-256 provenance.
+These are historical test references, excluded from runtime packaging.
+
+## Implemented stage
+
+- Conservative opt-in buffered remux seeks use **current** media and SourceBuffer
+  ranges, a retained random-access point, and accepted source/generation identity.
+  They preserve the worker, MediaSource and SourceBuffer. The consumer target moves
+  backwards without rewinding the producer or incorrectly evicting the new playhead.
+  Native waits for a target video-frame callback, not merely `seeked`, on this path.
+- MSE initialization removes its event listener and clears its deadline on success,
+  failure and cancellation. Source initialization accepts one completion only.
+  Failed-generation worker messages cannot negotiate a new buffer or append output.
+  Repeated remux destruction cannot revoke the same URL again.
+- Native scalar attenuation uses one media-element source and one GainNode output.
+  Gain 1 allocates no AudioContext on a new session. Play resumes a suspended
+  context; retirement disconnects nodes and closes it. Ordinary volume/mute stay
+  on the media element. Remote Native already requires CORS-clean media.
+- Hybrid can retain WebCodecs video with an explicitly admitted scalar mpv audio
+  filter. Constructor, dynamic setter, automatic selection and capabilities share
+  the feature policy. Unsupported chains go to Software in automatic mode or reject
+  in explicit Hybrid mode. They are never silently removed.
+- A finite internal plan registry names the accepted direct/remux/gain/Hybrid/filter/
+  Software plans and records source prerequisites, resources, fidelity and fallback.
+  Diagnostics expose the actual plan. This is an initial registry; it does not yet
+  implement all the requested source/feature/fidelity policy decisions.
+
+### Public API additions
+
+```js
+const player = new Player(container, {
+  experimentalBufferedNativeSeeks: true, // default false
+  experimentalHybridAudioFilters: true, // default false
+  audioFilters: 'lavfi=[volume=0.5]',
+});
+// Separately requested scalar attenuation (0..1, default 1):
+await player.setAudioGain(0.5);
+```
+
+`audioGain` is also a constructor option. It is experimental, not a claim of
+sample-exact final output. Native uses Web Audio; mpv routes use the scalar audio
+filter. `setAudioGain` uses the existing transactional replacement contract,
+preserving position, rate, mute and playback intent. It currently reopens the
+session; it is not an optimized live gain setter. Filters admitted on Hybrid are
+only `volume=N` and `lavfi=[volume=N]`, with finite decimal N from 0 through 1.
+`capabilities.features.audioGain` reports gain support; audio-filter availability
+still requires checking this documented qualified subset. Amplification,
+expressions, other filters and arbitrary chains are not newly admitted.
+
+The three public modes and existing default selection behavior are preserved.
+New buffered seeking and Hybrid filters remain explicitly experimental. No
+background Hybrid-to-Native handoff or per-open engine benchmark was added.
+
+## Timestamp blocker: historical reproduction and maintained replacement
+
+`experiments/optimization-integration/fixtures.py` generates eight small fixtures:
+B-frames 0/2 × start 0/2 seconds × matched/unequal audio duration. The unequal case
+has an awkward final audio-frame length. Commands and SHA-256 hashes are saved in
+`fixture-manifest.json`; packet/stream probes remain in `build/optimization-fixtures`.
+The original 8.1-second risk fixture is retained verbatim in the reference folder.
+
+`reproduce-timestamps.mjs` runs the **historical scratch worker**, read-only, using
+the original laboratory LibAV binary only as a reproducer. No benchmark binary is
+added to the product. All eight no-B-frame codec/case combinations convert; all
+eight B-frame combinations fail. Both original edge-fixture runs reproduce:
+
+```
+Application provided invalid, non monotonically increasing dts to muxer in stream 0: 33600 >= 32528
+```
+
+The scratch worker reconstructs absent DTS from PTS. That is invalid for reordered
+video. The failure exists independently of the streaming checkpoint. Neither
+clamping DTS, dropping packets, video transcoding nor a blanket B-frame ban was
+implemented. A maintained adaptation pipeline must preserve demux decode order and
+rescale established timestamps, or explicitly reject unavailable timestamp
+information. Stage 2 adds a maintained, opt-in FLAC adapter using the existing bounded
+Matroska/H.264 decode-order reconstruction instead of the scratch algorithm.
+All eight controlled fixtures and the original failure pass in Chrome and Firefox.
+General automatic FLAC and all Opus admission remain disabled. The original scratch adapter also hard-codes AVC MIME, 90-second
+duration, stereo/48 kHz and restricted PCM assumptions; those are not ported.
+
+## Complete candidate inventory
+
+| Candidate | Stage status and gate |
+|---|---|
+| Buffered Native seeks | Implemented, opt-in; Chrome/Firefox short output/refill checks |
+| Hybrid scalar audio filters | Implemented, opt-in; dynamic reconfiguration and signal checks |
+| Other Hybrid audio filters | Deferred; per-filter latency/continuity qualification required |
+| Native Web Audio scalar gain | Implemented, explicit request; signal/mute/zero/restore checks |
+| Native ASS/libass overlay | Deferred; original loader and paused-resize patch preserved, not integrated |
+| Progressive FLAC adaptation | Implemented for explicit Native trials; maintained FFmpeg 9.0.1; integer mono/stereo qualification only |
+| Explicitly permitted Opus adaptation | Blocked; no implicit lossy permission or fallback |
+| Adaptation + ASS | Disabled, constituent plans unqualified |
+| Adaptation + gain | Implemented, experimental; bounded playback/seek and selected-track tests |
+| Adaptation + ASS + gain | Disabled, constituent plans unqualified |
+| First versus steady fragment sizing | Deferred pending paired cost evidence; existing bounded fragment policy retained |
+| FLAC encoder settings | Deferred; sample-exact adapter and end-to-end benchmark required |
+| Compiled module/worker reuse | Deferred; no cross-source reuse or credential state introduced |
+| Hybrid compressed-packet copies | Inspected; unchanged pending ownership/copy-cost measurement |
+| Packet/configuration adapters | Preserved; codec/configuration tests pass; no replacement claimed |
+| Software YUV/GPU | Existing experimental presenter preserved, RGB default; no new artifact built |
+| Arbitrary Native/Hybrid GPU effects | Separately gated follow-up |
+| Separate audio/video SourceBuffers | Separately gated follow-up |
+| WebCodecs audio decoding | Separately gated follow-up |
+| Authenticated unchanged-byte transport prototype | Not revived; no demonstrated win |
+| Routine Hybrid-to-Native handoff | Not revived |
+| Client video transcoding | Not introduced |
+| Independently clocked custom audio with Native video | Not introduced |
+
+## Fidelity, source identity and fallback
+
+Original-track direct playback and packet-copy remux retain their preference.
+Explicit Native FLAC trials add selected-audio lossless conversion only. No new
+downmix, sample-rate change or lossy adaptation permission is introduced. The scalar effect is a separately requested transformation, not an
+encoding fidelity claim. Existing browser/mpv output resampling remains governed
+by the existing backend behavior. Final speaker output and physical A/V sync were
+not measured.
+
+Existing operation serialization, source-scoped track identities, immutable range
+checks, resource limits, cancellation and fallback loop protection remain active.
+The plan registry does not supersede mpv's streaming scheduler or clock. Existing
+source/integrity errors retain their terminal handling. Broader error classification
+and authorization-refresh policy unification remain outstanding.
+
+## Streaming baseline preservation
+
+The saved modernization remains staged rather than installed into the root runtime.
+Root engines use mpv 0.40.0 / FFmpeg 7.1.1. The final saved overlay uses mpv 0.41.0 /
+FFmpeg 9.0.1, pinned libass and its maintained browser/AVIO patches. Neither lock nor
+patch collection was changed. TypeScript 5.9.3 and Playwright 1.58.2 remain pinned.
+The saved candidate-26 release/live qualification blockers remain open.
+
+`experiments/optimization-integration/prepare.py` checks the exact saved checkpoint,
+runs its unmodified `prepare.py --timeline`, then merges the optimization delta.
+**Correction to stage 1:** assemblies 02–07 silently skipped tracked-file patches
+because `git apply` was invoked from the wrong directory. Their 59 test passes
+covered the saved overlay, not combined implementation. The original logs remain
+historical evidence. Assembly 08 exposed real patch conflicts. The assembler now
+uses a three-way merge and only explicitly reviewed additive resolutions; unknown
+conflicts stop with a saved artifact. Assembly 12 contains the actual delta,
+compiles, and passes all 59 saved integration contracts. These are source/contract
+checks, not rebuilt HLS/DASH browser qualification. The separate FFmpeg 9.0.1 FLAC
+preparation engine uses its own matching glue and explicit remux ABI.
+
+## Validation and evidence
+
+Evidence lives under `results/optimization-integration/` and the existing harness
+result directories referenced by its logs. Initial build passed. The initial unit
+run had 25 passes plus a browser-harness setup failure from missing generated VP8/
+VP9 fixtures; that run was not a playback regression. The first aggregate streaming
+unit invocation omitted its required environment variables; its failures remain
+saved, followed by the correctly configured run.
+
+New contract tests fail on the missing buffered-seek implementation before the
+change, then pass afterward. Cancellation tests establish an outstanding MSE open
+before supersession/destroy and assert no late worker allocation. These are injected
+contracts, not real network-fault coverage.
+
+Short Chrome and Firefox checks cover Native direct/remux/gain, ordinary Hybrid,
+filtered Hybrid and Software. Buffered seeks retain identities, present the target
+frame while paused, and resume through refill. Scalar checks compare signal
+amplitudes, mute, zero gain, unity restoration and closed retired contexts. All
+cases assert worker/surface cleanup. Earlier harness mistakes (reading an absent
+`state.paused`, and fetching a fixture from a server-disallowed path) remain saved.
+No amplitude claim is inferred from the earlier visual-only runs.
+
+Root playback uses six verified existing engine assets. `runtime-reuse.json`
+records SHA-256 and correspondence to the 51f0792 release archive. Browser glue
+matches exactly except the saved diagnostic product rename. No newer Wasm is paired
+with older glue. The assembled streaming source is tested separately without
+borrowing these engines.
+
+Representative commands:
+
+```sh
+npm ci --ignore-scripts --no-audit --no-fund
+npm run build
+node --test tests/optimization-contracts.mjs tests/remux-buffering.mjs tests/native-selection.mjs
+python3 experiments/optimization-integration/fixtures.py
+node tests/optimization-playback.mjs
+BROWSER=firefox node tests/optimization-playback.mjs
+LAB_VENDOR=/path/to/preserved/lab/repo/web/adapt/vendor node experiments/optimization-integration/reproduce-timestamps.mjs
+python3 experiments/optimization-integration/prepare.py --output build/optimization-streaming-new
+INTEGRATION_ROOT=build/optimization-streaming-new/streaming RETAINED_WORKER=build/optimization-streaming-new/streaming/web/filter-retained-engine-worker.js node --test experiments/streaming-modernization/integration/*.test.mjs
+```
+
+Stage 1 had **no paired CPU/memory benchmarks**. Stage 2 adds a bounded
+FLAC-versus-Hybrid cold/warm screen; see [its exact scope](OPTIMIZATION-FLAC.md). Correctness checks and existing
+historical percentages are not performance evidence. The requested cold/warm
+open→10-second playback→destroy comparisons, full lifecycle/range-fault matrix,
+broader adaptation codec/layout qualification, Native ASS/fullscreen/PiP,
+and final rebuilt streaming/browser suites remain outstanding. Safari and mobile
+are not qualified. This checkpoint delivers the implemented stages and preserves
+the unresolved work; it does not satisfy all requested completion gates.

package/docs/OPTIMIZATION-REVIEW-FIXES.md

@@ -0,0 +1,78 @@
+# Review fixes: bounded work, track identity and frame-verified seeks
+
+Historical checkpoint report. For subsequent local implementation and current coverage, see [completion status](OPTIMIZATION-COMPLETION.md).
+
+All three findings from `results/optimization-review/REVIEW.md` are addressed.
+Work remains local and uncommitted on the saved integration checkpoint. This does
+not complete the wider optimization program or enable automatic FLAC admission.
+
+## Changes
+
+- **Bounded audio tails:** the preparation profile yields after roughly half a
+  second of decoded audio even if no further video packet arrives. A single
+  decoded frame remains subject to its existing sample cap. The controller limits
+  prepared source time separately from MSE buffered intersection. Pausing cannot
+  force conversion of an arbitrarily longer audio track.
+- **Explicit unequal-tail limitation:** a single combined SourceBuffer may stop
+  exposing playable coverage when its shorter track ends. If playing cannot
+  progress within the five-second preparation cap, the adapter reports
+  `Adapted track timelines cannot progress within the preparation budget; use Hybrid`.
+  Explicit Native does not silently change modes. The regression verifies that
+  the application can then switch the same source to Hybrid. Long unmatched tails
+  are not newly qualified for Native. Existing short duration mismatches remain
+  covered by packet and sample comparisons. No valid packet is dropped or clamped.
+- **Source-scoped audio identity:** both `remux` and `adapted-flac` use the same
+  stream-index identity. Public selections survive Native/Hybrid transitions,
+  gain replacement and automatic-selection activation. On return to Native, the
+  selected stream is passed to preparation before opening; the default track is
+  not temporarily adapted first.
+- **Frame-verified seeks:** frame callbacks are registered before issuing the seek and
+  accepted only once the browser reports seeking complete at the requested media
+  time. Registration cannot wait for the queued DOM `seeking` event, which can
+  arrive after the target compositor callback. The callback's frame timestamp can precede the target for low-frame-rate
+  or variable-frame-rate content. A future frame cannot satisfy the seek, and a
+  retired presentation/generation cannot complete it. The ten-second deadline and
+  cancellation cleanup remain. No broad timestamp tolerance or guessed frame rate.
+
+## Regression coverage
+
+`tests/optimization-review-regressions.mjs` adds three real-browser cases:
+
+1. One-second video plus 30-second PCM24 audio: paused work stays below seven
+   seconds, remains stable, and the unmatched-tail limitation settles explicitly
+   during playback. The source remains usable through Hybrid.
+2. Public second-audio selection across Native → Hybrid → Native, gain replacement,
+   and automatic selection. The same public track ID persists, and Native's
+   preparation/cancellation counters contain only the selected 44.1 kHz stream.
+3. Three cycles of buffered seeks at 2.5, 2.75, 4.5 and 2.25 seconds in a 1 fps video. Paused
+   playback preserves the worker and generation. Browser canvas pixels agree for
+   targets covered by the same frame and differ for a different frame. The test
+   waits for actual buffered eligibility after refill; Firefox's first fixed-delay
+   attempt exercised the safe regeneration path and was retained as harness evidence.
+
+Chrome and Firefox pass all three cases. Eighteen targeted root contracts pass,
+including new stale-generation and low-frame-rate seek contracts. Assembly 15
+contains the actual combined streaming delta, compiles, and passes 59 saved
+streaming contracts. Full rebuilt HLS/DASH browser qualification remains gated.
+Additional fidelity, lifecycle and installed-consumer results are indexed in
+`results/optimization-integration/stage3/summary.json`.
+
+## Reproduction
+
+```sh
+python3 experiments/optimization-integration/fixtures.py
+npm run build
+node --test tests/optimization-contracts.mjs tests/remux-buffering.mjs tests/native-selection.mjs
+node tests/optimization-review-regressions.mjs
+BROWSER=firefox node tests/optimization-review-regressions.mjs
+node tests/audio-adaptation.mjs
+node tests/audio-adaptation-lifecycle.mjs
+```
+
+The maintained FLAC engine was relinked with the same saved FFmpeg 9.0.1 libraries,
+locked patches and Emscripten 4.0.14. It has matching new glue and Wasm in a fresh
+versioned build directory. Original engine artifacts, failed reproducers, stage 2
+results and the laboratory remain preserved. No new dependencies, codec upgrades,
+streaming gates or public playback modes were introduced. Earlier cost screens
+remain evidence for their original artifact hashes; they were not rerun for this
+correctness fix and do not qualify the new artifact's performance.