feedBack-desktop/docs/audio-ownership-plan.md

Audio Ownership & Mixer Plan — Routes, Leases, and the Engine-Owned Mixer

Follow-up track to docs/audio-engine-tlc.md (Part V step 7, "ownership work", deferred there because it needs the rig_builder repo). Drafted 2026-07-14 on refactor/audio-engine-tlc after the TLC phases + PR #107 review fixes landed.

Goal: the audio engine owns audio settings, devices, chains, and output. Everything else — bundled screens, plugins, minigames — is a client that requests routes and holds leases. One ownership model (leases), one output model (mixer channels), meeting at the route.

Substrate this plan builds on (already shipped on the TLC branch):

Shipped	Used here as
chainGeneration + mutation serializer	tamper-evident seal under the lease protocol; becomes per-route
refcounted monitor-mute arbiter	precedent + implementation pattern for lease scopes
single persistence store (file-backed)	where lease-relevant user prefs (tone engine) live
PackedStereoRing template	the mixer channel's ring
RendererBus (ring + resampler + prime gate + fill clamp + metrics)	becomes MixerChannel, instantiated N times
executor route map + outcome vocabulary + authorization gating	grows into the lease registry
rebuild barrier + editor try-lock discipline (PR #107)	unchanged; leases sit above it

---

1. Terminology (binding — settle it before any code)

Term	Meaning	Today's artifact
source	engine-side pool entry (SourceChain, max 8): capture binding + detection + its own SignalChain	sources[i]
route	the executor/lease-level name for a source's chain or a mixer channel; what callers request and hold	route key (desktop-main)
slot	a processor position within a chain	ProcessorSlot, slotId
lease	exclusive, revocable authority over one scope (a route's chain, device config, …)	monitor-mute arbiter (single-scope precursor)
channel	a mixer input: ring + gain/mute/meter, owned by the engine, held by a client	RendererBus (the only one today)

"Slot" is NOT used for sources/routes anywhere — it already means chain position and overloading it will corrupt every future review. The user-facing "player slot" is the desktop-main route bound to source 0.

---

2. The lease registry

Lives in the main process as an extension of audio-effects-executor.ts (it already has routes, outcome strings, and authorization gating). Native stays dumb: per-route chainGeneration remains the detection layer beneath the polite JS protocol — a lease violation that somehow reaches native is still caught as a foreign write.

Two primitives, not one

The conflict inventory (§6) shows two distinct shapes of contention, so the registry offers two primitives:

1. Exclusive lease — conflicting authority; one holder at a time (refusal / takeover semantics as below). For: chains, device config, transport.
2. Refcounted demand — additive intent ("I need X on") where multiple consumers legitimately overlap; the engine acts while count > 0. For: engine-run/capture, detection arming. This is the monitor-mute arbiter generalized into a registry primitive — same semantics, one implementation instead of one per setting.

Scopes

Exclusive-lease scopes:

• device-config — device/type/sample-rate/buffer AND input-channel select (one global scope)
• signal-chain:<route> — a specific route's chain, including its noise gate (per-route)
• playback — backing transport + playhead authority (one global scope; the playback screen acquires on song load, releases on exit — verified 2026-07-14 that splitscreen followers are transport read-only)
• monitor-state — already arbitrated; folds into the registry as a scope
• mixer-channel:<id> — an output channel's gain/mute (per-channel; the holder is whoever requested the channel)

Refcounted-demand scopes:

• capture — "the engine must be running and capturing"
• detection:<route> — "ML note detection must be armed on this route"

Different holders hold different scopes concurrently. The tuner reading pitch holds nothing — reads are never lease-gated, only mutations.

Holder identity is DERIVED, never declared

The main process derives holderId from the IPC sender (webContents id + plugin manifest), never from a caller-supplied string. Main-process / engine-internal callers use a fixed enum of well-known synthetic ids (§8.4). Granularity limit: plugins sharing one renderer are distinguished only by capability-layer attribution — see compound identity, §9. Consequences, all load-bearing:

• Death invalidation is automatic: webContents destroyed → every lease, demand, and channel handle it held is released; reload gets a short grace window instead (§8.2). No heartbeat protocol needed for the realistic failure modes.
• No spoofing, no accidental identity collisions between plugins.
• getHolder() and telemetry name the real owner, which is what makes the takeover UI and field diagnostics honest.

Layered values (base + override)

For settings both the user AND a lease holder legitimately write (first case: the noise gate, §6.2): the user surface writes a persistent base preference; the scope's lease holder may set an override that lives exactly as long as the lease; release (or revocation, or holder death) restores the base. The monitor-mute arbiter's user-pref-plus-overrides model applied to arbitrary scalars — implemented once in the registry, used by any scope that declares a layered setting.

API shape (executor-level, contract-snapshotted)

acquireLease(scope, holderId, opts) -> { granted | refused(holder, reason) }
releaseLease(scope, holderId)
getHolder(scope) -> holderId | null
events: lease-granted, lease-released, lease-revoked, lease-refused

Policy decisions (settled in discussion, 2026-07-14)

• Refusal by default. A second caller is refused while the scope is held. No silent stealing — that recreates today's races with extra steps.
• User-initiated takeover as the only revocation path for contended scopes (practically: desktop-main). The UI offers "take over"; the registry revokes with a lease-revoked event so the old holder can degrade gracefully. Per-route leases make contention rare — a refused caller can usually request its OWN route instead of fighting.
• Death-triggered invalidation — the hard requirement. Leases are tied to observable lifecycles: webContents destroyed (reload = grace window, §8.2), plugin teardown, or executor route release. A wedged/crashed holder must never brick a scope until restart. Pattern precedent: vst-crash-guard sentinels.

---

Ownership at a glance

Every aspect of the engine, its owning authority, and who holds what. "Engine" in the authority column means: the engine is the only mutator; everyone else goes through the named scope/API. Reads (meters, playhead, chain state, detection results) are always free.

Aspect	Authority	Scope / primitive	Typical holder	Everyone else
Devices, types, sample rate, buffer sizes	Engine	device-config lease	audio_engine device screen	read-only; route requests
Input channel select (per source)	Engine	device-config lease (per-route later)	device screen	request via route API (6.6)
Engine run / capture state	Engine	capture demand (refcount)	any consumer needing live input (tuner, minigames, notedetect, bongocat)	raw start/stop = device screen only
Signal chain of a route (slots, params, presets)	Engine	signal-chain:<route> lease	tone engine (Rig Builder or native) for desktop-main; requester for own routes	refused (held); takeover UI on desktop-main
Noise gate (per route)	Engine	layered value on signal-chain:<route>	base: user settings UI; override: chain lease holder	refused
Monitor mute / kill	Engine	monitor-state (arbiter: user pref + overrides)	user pref + transient suppressors	via arbiter only
Master / backing / input gains	Engine	user-scoped, native-clamped (TLC fix)	user UIs	last-writer-wins, sanitized
Backing transport + playhead	Engine	playback lease (global)	playback screen	refused; verifier feed rides the scope's contract (6.5)
Detection arming (ML/ONNX)	Engine	detection:<route> demand (refcount)	notedetect, minigames, strum-fighter — concurrently	reads (getActiveDetection) always free
Verifier offsets (per route)	Engine	route's detection scope	calibration UI of the route holder	plugin-local verifiers unaffected (6.7)
Mixer: channel lifecycle + audio content	Engine	tier-3 produce handle (§5.1)	the channel's requester	no handle, no writes
Mixer: channel gain / mute (the fader)	Engine	tier-2 mix control — NOT leased	the user, via any mixer UI (audio-mix capability for plugins)	last-writer-wins, native-clamped, event-synced
Mixer: default channel #0 content	Engine	channel #0 produce handle	juce-audio feeder (feedBack repo)	push refused without handle
Mixer: which channels StreamSink taps	Engine	structure (tier 4)	stream-settings UI via lease	read-only
Settings persistence	Main process	file store (single writer since TLC)	audio-bridge	localStorage = migration source only

Rule of thumb encoded above: content and structure are held; faders and reads are free.

3. Route requests — input AND output through one API

Callers never touch source indices (the stageSlots fragility lesson: no client-side index coupling). They request a route with properties and get an opaque handle they now hold.

requestRoute({ kind: 'input-physical', device, channel })  -> route | refusal
requestRoute({ kind: 'input-virtual', midi: true })        -> route | refusal
requestRoute({ kind: 'output', label, latencyHint })       -> route | refusal
releaseRoute(route)

• input-physical — a device+channel binding (existing bind rules: pool cap 8 sources, 3 extra devices, duplicate/primary checks). Comes with a leasable signal chain. Consent-gated: binding a microphone/interface is a privacy-adjacent user-visible act → flows through the executor's existing authorization gating (user-action / restore-selection); a plugin cannot silently start capturing.
• input-virtual — NEW engine capability (addVirtualSource()): a pool source with no capture binding, silent input feed, full chain + detection + mixer participation. MIDI reaches its chain via the existing per-slot queueMidiMessage. Unlocks: MIDI-driven minigames (VSTi in the chain), metronome, device-setup test tone.
• output — a mixer channel: ring + gain/mute/meter, no chain. Cheap; granted freely up to a hard cap (~16–32, refusal no-capacity); channels silent + unfilled for N min are reaped (channel-removed), holder re-requests transparently on next push.
• Composite for free: an input route's chain output IS a mixer channel; requesting an input route implicitly yields its output channel.

Refusal vocabulary (extends the executor's outcome strings): no-capacity, device-unavailable, already-bound, user-action-required, held.

Asymmetry to encode deliberately: output = cheap + consent-free; input = scarce + consent-gated.

The device-setup flow creates the physical routes the user wires up (desktop-main = source 0); plugins request additional routes.

---

4. Tone-engine consolidation

A "tone engine" is simply the holder of signal-chain:desktop-main.

• New user setting (file-backed store): which provider auto-acquires that lease on session start / song load — Rig Builder, Audio Engine native, (future providers register through a capability).
• Everyone else's chain writes are refused, not raced. Kills, permanently: rig_builder's transient-kill/_rbUnmuteTimer timing hacks, the audio_engine screen's ~30 direct clearChain sites, the legacy direct loadPreset path (audio-effects.legacy-native-load).
• Tone auto-switching moves INTO the tone engine (decision): switching is a tone-engine responsibility, not a separate service. The audio_engine bundle's applyToneMappingsNow / applyToneAutomationFor migrate behind the provider interface.
• Cross-repo sequencing: executor lease API lands first (this repo), rig_builder migrates second (own repo), legacy path goes log-once- deprecated, then dies.

---

5. The engine-owned mixer

Every audible thing becomes a channel on one native mixer:

Mixer (engine-owned)
  ├─ guitar buses        (input routes' chain outputs — incl. virtual sources)
  ├─ backing player      (engine-internal channel)
  ├─ default channel #0  (permanent: renderer master via loopback capture —
  │                       every sound that doesn't claim a bespoke channel)
  ├─ plugin channels     (stems, metronome, minigame SFX — requested routes)
  └─ → device output; StreamSink taps configurable channel subsets

• MixerChannel = RendererBus generalized. The ring, producer-side linear resampler, prime gate, fill clamp, flush flag, and metrics move as-is behind a channel registry; per-channel gain/mute/meter on top.
• Channel #0 is the permanent default, not a compat shim (decision, 2026-07-14): the getDisplayMedia loopback capture keeps feeding it, so any renderer audio that never requests a bespoke channel — legacy plugins, UI sounds, one-off <audio> tags — still reaches exclusive-mode outputs with zero integration work. Bespoke channels are the opt-in upgrade for producers that want their own gain/mute/meter/diagnostics.
• Double-audio guard: a producer that migrates to a bespoke channel must route its WebAudio graph away from the renderer master (its own destination), otherwise it plays twice — once through its channel, once through #0's capture. The channel-request API docs make this the requester's contract; the stems migration is the reference example. A diag heuristic (bespoke channel active + #0 meter elevated) flags violations (§8.6).
• Direct tester payoff: the stems plugin pushes PCM into its own channel instead of riding the aggregate #0 path, so a renderer main-thread stall no longer starves stem audio behind everything else, and per-channel underflow counters mean field logs name WHICH channel starved (the ASIO stem-glitch investigation wanted exactly this).
• Latency: each channel reports its residency into getLatencyBreakdown (one owner for every term — the TLC invariant holds).
• Transport v1 = per-channel IPC push (today's known-good renderer-bus path). Channel handles are opaque so a SharedArrayBuffer ring can replace the transport later without API change.
• Format contract v1: interleaved stereo float32 at a declared source rate, producer-side resample. Multichannel/int16 are non-goals.
• Reclaim behavior: channel death (holder gone) fades to silence — never a click, never a stuck channel.

5.1 Exposed surface — authority stays in the engine, control is tiered

Principle: the engine owns the mixer; callers get tiers of access. The key separation is producer vs. mix: the holder controls a channel's content and lifecycle, but the fader belongs to the user — mix controls must work from any UI without holding anything (OS-volume-mixer model).

Tier	Who	Gate	Surface
1. Observe	anyone	none (read-only)	mixer.listChannels() → id, label, kind (default / plugin / engine), holder, gain/mute, meters, fill + underflow counters; events channel-added / channel-removed / channel-changed. Fully event-driven mixer UIs — playback screen, plugins, diag overlay all render from the same feed.
2. Mix	user-facing UIs; plugins via the existing audio-mix capability	capability, NOT a lease	mixer.setChannelGain(id, v) / mixer.setChannelMute(id, bool). Engine clamps natively (sanitizeStreamGain pattern — no JS-side trust), broadcasts channel-changed so every open mixer view stays in sync. Last-writer-wins is CORRECT here (two sliders on one fader is solved UX; unlike chain writers there is no compound state to corrupt). Gains persist per holderId + label in the file store (§8.8).
3. Produce	the channel's holder only	opaque channel handle from requestRoute	push audio, flush, latency hint, release. The handle is the authority token; no handle, no writes.
4. Structure	lease holders	lease scopes (§2)	StreamSink channel taps, device config / sample rate, channel policy.

Why tier 2 is not lease-gated: routing "turn down the stems" through the stems plugin's lease would force every producer to reimplement a volume API and would break the playback screen's mixer whenever a holder is busy or gone. The engine's native clamp + single event stream keeps authority intact while multiple UIs share the fader.

Wiring: tiers 1–2 land on the preload surface as audio.mixer.* alongside the existing ~99 methods; IPC channels + result shapes join the phase-A contract snapshots. The playback screen's in-song mixer and the stem_mixer plugin both become tier-1/2 clients of the same endpoints — no bespoke side-channel per consumer.

---

6. Ownership conflict inventory — verified against code (2026-07-14)

Sweep of every audio write-API caller across feedBack-desktop, the feedBack server repo (static/ + plugins/), and the plugin repos. Beyond the chain / monitor-mute / gains / device-settings conflicts the TLC doc already catalogued (Part II), these need an ownership declaration:

6.1 🔴 startAudio — five-plus independent writers, no stop ownership

Callers found: audio_engine screen (multiple), audio-effects-executor (startAudio: true plans), bongocat (run-controller.js — starts the engine if not running, with a compensating stopAudio if superseded), tuner (feedBack/plugins/tuner/utils/audio.js — same start-then-undo hack), minigames (feedBack/plugins/minigames/screen.js), notedetect (screen.js, 2 sites). Every caller reimplements "isRunning? → start; remember whether I started it" with private undo logic — five copies of an implicit refcount, each of which can strand the engine running or stop it under another user.

Declaration: raw start/stop becomes user-only (device screen). Everyone else calls requestCapture(holderId) / releaseCapture(holderId) — a refcounted run demand on the lease registry (the monitor-mute arbiter pattern applied to engine-run intent; the phase-1 userWantsAudio split gave it a natural native anchor). Plan home: phase A (registry scope), migration in B/C.

6.2 🔴 Noise gate — settings UI vs. nam_tone presets

audio_engine screen: 17 setNoiseGate sites (user gate settings UI). nam_tone screen.js: writes gate threshold/enable on preset apply (2 sites). Last-writer-wins; the settings UI silently shows stale state after any NAM preset applies its own gate.

Declaration: the gate is part of the tone — it belongs to the signal-chain:<route> lease holder. The user's gate UI writes a base preference; the tone engine may override per-preset while it holds the lease, and the base restores on release (exactly the arbiter's user-pref-plus-overrides model). Plan home: phase C/D.

6.3 🔴 ML detection arming — boolean toggled by multiple armers

setNoteDetectionEnabled / chart+scoring consumers: notedetect (60 call sites — the primary owner), strum-fighter (game.js, chord modules), highway_3d (feedBack/plugins/highway_3d/screen.js). Arming is a plain boolean: whichever minigame/screen disarms last kills detection for a concurrent consumer (and arming is what gates the ONNX inference cost, so a leaked arm quietly burns CPU forever).

Declaration: detection demand becomes a refcounted registry scope (detection:<route>), same pattern as 6.1. getActiveDetection() stays free (read). Plan home: phase A scope, consumers migrate in C/E.

6.4 🟠 Renderer bus / default channel #0 — feeder lives in another repo

feedBack/static/js/juce-audio.js owns the loopback/stems/element capture modes and flips setRendererBus(enable, gain) at 8 sites; it is today the only legitimate feeder — but nothing enforces that, and the API is on the public preload surface next to the ones bongocat already helps itself to.

Declaration: channel #0's producer handle (§5.1 tier 3) is held by the juce-audio feeder module; setRendererBus/pushRendererAudio become the handle-scoped produce API and leave the free-for-all surface. Cross-repo: the feeder lives in the feedBack server repo. Plan home: phase B.

6.5 🟠 Backing transport + playhead — split-brain across repos

juce-audio.js (feedBack repo) drives loadBackingTrack/startBacking/ stopBacking; transport.js + player-controls.js drive start/stop/seek; the sloppak path freezes the engine playhead and notedetect pushes the corrected playhead via setPlayhead for the verifier. Three modules in two repos plus one plugin all steer "what time is it" — the TLC doc's frozen-playhead leak (Part I §5), now with its writer set mapped.

Declaration: one transport owner — the playback screen — holding the global playback scope; setPlayhead stops being a free-standing write and becomes part of the detection contract tied to that scope. Plan home: phase C, aligned with the tone-switching migration.

6.6 🟠 Input channel selection — notedetect writes device config

notedetect screen.js calls setInputChannel/setSourceInputChannel (4 sites) and reads loadDeviceSettings — a plugin mutating what the device screen owns. Its motive is legitimate (calibration needs the right channel) but the write path is a silent conflict with the device-config owner.

Declaration: channel select is device-config (or per-route input config) — notedetect requests it through the route API and the grant is user-visible. Plan home: phase C.

6.7 🟡 Verifier offsets — parallel calibration surfaces

Core screen sets native per-source verifier offsets; splitscreen runs its own contained-verifier offset UI (plugin-local, benign today); nothing stops two calibration UIs fighting over the native offset later.

Declaration: per-route setting under the route's detection scope. Low urgency; document now, enforce when 6.3 lands.

6.8 Resolution mechanics — three families, one migration strategy

The seven conflicts collapse into the registry's primitives; nothing needs a bespoke mechanism:

Family	Mechanism (§2)	Solves
Refcounted demand	capture, detection:<route> counters	6.1 startAudio, 6.3 detection arming
Exclusive lease (+ layered values for the gate)	signal-chain:<route>, playback, device-config	6.2 gate, 6.5 transport/playhead, 6.6 channel select, 6.7 verifier offsets
Producer handle	channel #0 tier-3 handle (§5.1)	6.4 renderer-bus feeder

Migration without a flag day — deprecation shims. Existing surfaces keep working while callers migrate lazily:

• startAudio() / stopAudio() from a plugin context become shims over requestCapture / releaseCapture with the derived holder (log-once deprecated). The five hand-rolled "did I start it?" undo hacks (bongocat, tuner, minigames, notedetect ×2) are deleted in their repos as they migrate; until then the shim makes them merely redundant, not harmful. Raw start/stop stays available to the device screen only.
• setNoteDetectionEnabled(true/false) becomes demand acquire/release on the derived holder. A holder that leaks its arm loses it on death — closing the "leaked arm burns ONNX inference forever" failure by construction.
• setNoiseGate from the settings UI writes the base preference; from the chain-lease holder it writes the override; from anyone else it is refused (held). nam_tone's preset gate rides its tone-engine lease (phase D).
• setPlayhead / backing transport calls check the playback scope; notedetect's verifier feed becomes part of that scope's detection contract rather than a free write.
• setRendererBus / pushRendererAudio become the produce API on channel #0's handle; the juce-audio feeder (feedBack repo) is granted it at startup. Enforcement is telemetry-gated (§8.5): unhandled callers log-once through phase B, refusal flips only at zero legacy calls.

Every shim logs once per session per caller with the derived holder id — that telemetry IS the migration progress dashboard, the same trick as rig_builder's legacy-native-load counter.

Inventory summary

Conflict	Writers today	Scope it maps to	Phase
startAudio/stop	5+ (2 repos + 3 plugins)	capture refcount	A (+B/C migration)
Noise gate	2 (core UI, nam_tone)	signal-chain:<route>	C/D
Detection arming	3+ (notedetect, strum-fighter, highway_3d)	detection:<route> refcount	A (+C/E)
Renderer bus feeder	1 legit (feedBack repo), unenforced	channel #0 produce handle	B
Backing transport/playhead	3 modules, 2 repos + notedetect	playback	C
Input channel select	2 (device screen, notedetect)	device-config / route	C
Verifier offsets	2 (core, splitscreen-local)	route detection scope	C+

7. Phasing

Same discipline as the TLC branch: contract snapshots first, no behavior change per move-phase, fixes as separate commits, every phase ships with its tests, existing suites stay green throughout.

Phase	Content	Repo(s)	Gate
A	Lease registry in executor: scopes, acquire/release/refuse, death invalidation, getHolder, events. Contract-snapshot the surface. No behavior change for non-participants.	desktop	holder-death matrix as e2e against real webContents lifecycles (§8.14); contract-check green
B	Mixer: MixerChannel from RendererBus (renderer bus = permanent default channel #0, byte-compatible), channel registry (native + IPC), tiered audio.mixer.* surface (§5.1, tiers 1–3), output-route requests (cap + idle reap, §8.9), channel groups (§8.13), double-audio diag heuristic (§8.6), stems → own channel (WebAudio graph rerouted off the renderer master — double-audio guard), StreamSink taps mixer	desktop	renderer-bus unit suite passes against channel #0 unchanged; stems-on-ASIO manual test (the tester's 5-stem file) incl. no-double-audio check; mixer surface contract-snapshotted; two concurrent mixer UIs stay in sync via channel-changed; per-channel metrics in diag
C	Chain ownership: per-route chainGeneration, audio_engine screen → lease-scoped executor ops, rig_builder migrates, legacy direct path log-once → deleted, takeover UI for desktop-main	desktop + rig_builder	storm test asserts refused not raced; rig_builder timing hacks deleted; legacy-native-load telemetry at zero
D	Tone-engine selection: user setting, provider registration capability, auto-switching migrates into providers	desktop + rig_builder	switch-engine e2e: mid-session provider swap without audio dropout
E	Virtual sources: addVirtualSource(), input-virtual route requests, MIDI→chain path e2e (VSTi minigame scenario)	desktop	virtual source in pool/mixer/verifier without device; pool-cap refusal test
F	Cleanup: slopsmith* aliases, localStorage keys, frozen legacy surfaces (TLC Part II §5 deprecation plan)	desktop	grep-zero on deprecated surfaces; contract snapshots updated deliberately

B before C deliberately: the mixer is independent of chain ownership, single-repo, and carries the direct tester-visible payoff (ASIO stems). C/D are the cross-repo track and can proceed in parallel after A.

Open items / risks

• Lease heartbeat vs. lifecycle-only invalidation: start lifecycle-only (webContents + plugin teardown cover the real cases); add heartbeat only if a holder class appears that neither covers.
• getDisplayMedia loopback: kept permanently as the feed for default channel #0 (decision, 2026-07-14) — the zero-integration path every renderer sound gets for free. Consequence accepted: the aggregate-path failure mode (a renderer stall starves EVERYTHING on #0 at once) remains possible for whatever still rides #0; the mitigation is migrating stall-sensitive producers (stems first) to bespoke channels, not deleting the default. Double-audio during migration is guarded by the requester contract in §5.
• Sample-rate authority: the mixer runs at device rate; channels resample producer-side (unchanged from RendererBus). device-config lease holder is the only writer of that rate.
• macOS is first-class for all phases (per 2026-07-14 decision); the message-thread constraints from PR #107 (try_lock on the message thread, serializer coverage for the inline macOS paths) apply to all new native surfaces.

---

8. Review decisions (2026-07-14, plan review)

Fourteen gaps found in review, each settled. These are binding alongside §2's policy decisions.

Lifecycle edges (the blockers — all Phase A)

1. Revocation handover = drain-then-grant. Revoke → serializer stops accepting the old holder's ops (lease-revoked fires here so it can stop enqueueing voluntarily) → queued ops drain → route generation bumps → new holder granted. No cancel path, no generation-fence-only race.
2. Reload = grace window. webContents reload (not destroy) suspends the holder's leases ~5–10 s keyed on manifest identity; the same identity re-requesting restores them; timeout or destroy releases for real and notifies waiters. Destroy stays immediate. F5 never changes ownership.
3. User stop suspends demands. Raw stop (device screen) always wins: engine stops, capture demands enter suspended (not cleared), holders get capture-suspended / capture-resumed events. Only user start resumes. Same ride-through for device-config changes that restart the engine.
4. Well-known internal holders. Main-process / engine-internal callers use a fixed enum of synthetic ids (engine:backing-player, main:startup-restore, main:executor), registered at boot, lifecycle = process (or explicit module teardown). Same registry rules — internal callers can be refused, and telemetry names them honestly. No open registration API.

Mixer + migration

5. Channel #0 migration is telemetry-gated. setRendererBus / pushRendererAudio stay ungated but log-once with caller id through phase B; refusal flips only after telemetry shows zero legacy callers for a full release cycle. Never a silence window from cross-repo skew.
6. Double-audio gets a diag heuristic. Bespoke channel active AND #0 meter concurrently elevated → diag-overlay warning + log marker naming the channel. No correlation DSP. Phase B gate item.
7. Demand leaks get diag visibility, not auto-release. Registry tracks per-holder demand age; diag overlay + field logs surface it ("notedetect holds detection:desktop-main for 47 min"). Policy may tighten later with data; no visibility-tied or timeout-based auto-release now.
8. Channel gain persistence keys on holderId + label, never label alone. Engine-internal channels use the well-known ids from (4).
9. Channel cap + idle reap — details folded into §3's output-route bullet; referenced from Phase B.

Scopes + UX

10. Base pref editable during override. Layered values accept base writes anytime (persist, apply on release); the owning UI shows an override-active indicator ("controlled by Rig Builder preset") so the audible no-op isn't mysterious.
11. playback is one global scope — folded into §2/§6.5. Evidence: splitscreen followers are transport read-only (one-way BroadcastChannel time/playstate from the main window; popup <audio> force-paused).
12. Startup restore re-binds user-created routes only. Plugin-requested physical input routes are not restored; the plugin re-requests on load and the consent gate applies fresh.
13. Channel groups in Phase B. Grouped channels share a prime gate / common clock reference so producers that need cross-channel sample alignment (multi-channel stems, metronome-against-backing) can opt in; ungrouped channels stay independent streams with no alignment guarantee.
14. Death-invalidation tests are e2e. The Phase A holder-death matrix must exercise real webContents lifecycles (crash, destroy, reload, navigation) — not a mocked event emitter.

---

9. Capability-pipeline integration (2026-07-14)

The renderer capability registry (static/capabilities.js + domain hosts, feedBack repo) is the plugin-facing half of this plan. Verified against code: the existing domains map near-1:1 onto the plan's scopes, so the plan reuses them instead of growing a parallel surface.

Division of authority

• Capability layer = policy, eligibility, attribution, UX. Manifest-declared roles, safety classes, consent surfaces, compatibility- shim telemetry, Capability Inspector.
• Lease registry = enforcement. Main process only. The capability layer is in-renderer and self-declared (registerParticipant is honor-system); anything checked only there is bypassable by direct preload callers — the exact 6.1/6.4 failure. Enforcement never lives renderer-side only.
• No mirroring. The capability layer reads lease state (getHolder, lease events) and renders it; it never caches its own copy of who-holds-what. One source of truth, no drift.

Plugins never see acquireLease

Capability commands are the plugin-facing API; domain hosts call the executor's lease/demand ops underneath. Refusals surface as capability outcomes. Mapping:

Plan scope / primitive	Capability domain (exists today)
signal-chain:<route> lease	audio-effects — routes, providers, executors, select-chain / load-plan / release-route, user-action-required outcome
playback scope	playback — already tracks requesterId + command sequence
detection:<route> demand	note-detection
capture demand	audio-input / audio-session
Mixer tier 1	observer role (any domain)
Mixer tier 2	audio-mix — exists, incl. fader-registry bridge
Mixer tier 3	produce handle issued through the domain host (stems domain for the stems producer)
Mixer tier 4	lease scopes (§2)
§4 provider selection	audio-effects register-provider / mappings — largely built; Phase D shrinks to "wire active-provider selection to lease auto-acquisition"
§6.8 shim telemetry	registerCompatibilityShim — legacy-native-load is already one of five registered shims; the Inspector renders migration progress for free

Compound holder identity (decision)

§2's derived identity has a granularity limit: all plugins share the main renderer webContents, so the main process cannot distinguish nam_tone from notedetect at the IPC boundary. Resolution — compound identity:

• Hard part (enforced): webContents id. Enforcement boundaries, death invalidation, and the "no spoofing" guarantee hold at this granularity.
• Soft part (attributed): capability-layer plugin id, carried for telemetry, diagnostics, and takeover-dialog naming. Plugin-level arbitration within one renderer is delegated to the capability domain host there — as the single dispatcher it can arbitrate honestly among its own participants, but this is a trust step, not enforcement, and is documented as such.
• Plugin teardown inside a living renderer is only visible to the capability layer → plugin-level release is capability-initiated (advisory); the hard backstop remains webContents death.

Alignment items

1. One outcome vocabulary. Plan refusals (held, no-capacity, …) extend the capability outcome set (denied, no-owner, user-action-required, stale, …) — never two parallel vocabularies.
2. Timeout class for takeover. Capability command dispatch has per-command timeouts; drain-then-grant (§8.1) can exceed them under a deep serializer queue. The takeover command gets a longer timeout class or completes asynchronously via a lease event.
3. Cross-repo note. Domain hosts live in the feedBack server repo; the lease registry lands in desktop (Phase A). Domain-host wiring to lease ops rides the same telemetry-gated migration as §8.5 — no flag day.