ytplayer/plans/phase3-staged-apply-decision.md

Phase 3 staged apply — accepted owner decision

The owner accepted this decision on 2026-10-08. It refines master §2c.5: background downloading never implies that an executing classic script can be safely replaced.

1. Already executing groups stay pinned until the session ends or the next user-initiated, playback-guarded reload. P2P/direct and every stateful instance are never re-evaluated live. Phase 4 must provide disposal and state handoff before live replacement is allowed.
2. A group that has not executed can immediately use newer verified cached URLs only when its contract and dependency contracts equal those expected by the running core's embedded manifest. For a different contract, keep the running build's N-1 URLs, set Lazy.reloadRequired, and request the existing Refresh UI banner through the unchanged meta-build versus /api/version comparison.
3. New core boot may receive a verified N-1 response for an uncached new URL only when group contracts match. The response retains its actual hash; it is never stored under the new hash. Contract changes join the blocking download set.

Reason: direct-media.js owns private room, pending transfer and waiting maps; WebRTC callbacks retain these closures. Re-evaluating the singleton redirects messages away from those transfers. P2P sockets/timers and piano/MIDI/floating windows have similar state. Contract equality alone does not migrate it.

Implemented in 4853c2c and 5d6a154. Node loader tests cover pinned execution, compatible unexecuted selection, incompatible N-1 plus reload-required, and incompatible dependencies. Worker tests cover same-contract fallback without cache poisoning and changed-contract readiness before commit. perf/lazy.mjs checks these decisions with real workers on Chromium and WebKit.