VST3 Rack v2.0 — execution parent / evidence ledger

[masarray]

Mission

Build the separate VST3 Rack OBS filter as a professional graphical serial multi-VST3 system without weakening the existing Single Host crash-isolation/realtime contract.

This is the parent/evidence ledger for Rack work. Implementation proceeds as small vertical tracer bullets, one fresh context/ticket at a time.

Authoritative read order

1. AGENTS.md
2. docs/CODEX_EXECUTION_CONTRACT.md
3. Rack sections of docs/NORTH_STAR_PRD.md
4. docs/rack/ADR-0002-RACK-RUNTIME-ARCHITECTURE.md
5. docs/rack/ADR-0003-ISOLATED-RACK-EDITOR.md
6. docs/rack/VST3_RACK_RESEARCH.md
7. docs/rack/RACK_EDITOR_SPEC.md
8. docs/rack/VST3_RACK_EXECUTION_SPEC.md
9. docs/rack/VST3_RACK_TICKETS.md
10. docs/rack/CURRENT_STATUS.md
11. current child ticket + exact repository fixed point

Do not use prior chat as architecture authority when repository docs exist.

Locked v2 shape

• separate OBS VST3 Rack filter;
• separate Rack helper executable and independent Rack protocol;
• one isolated Rack helper process per Rack filter;
• serial effects chain first, not free-form graph;
• protocol-neutral deep HostedPlugin seam extracted from proven Single behavior;
• immutable chain-generation swaps off realtime path;
• preallocated ping-pong serial processing;
• whole-block wet validity: active-chain failure => original dry block;
• stable slot IDs independent of order;
• evidence-based crash breadcrumb + bounded recovery/quarantine;
• automatic Session Snapshot != named reusable Rack Preset;
• dedicated graphical Rack Editor owned by the isolated Rack helper;
• OBS Properties is only a thin launcher/status surface with Open Rack;
• vendor editors remain floating helper-owned native windows in v2;
• default GUI candidate after UI-0 proof: pinned Dear ImGui + Win32 + DirectX 11, helper-only;
• initial qualification scope: max 8 mono/stereo Float32 VST3 effects.

The previous stock-OBS-Properties-as-full-editor plan is superseded by ADR-0003. Do not reintroduce private OBS Qt/widget injection.

First gate

REG-0 must complete before Rack production code.

The existing normative contract historically requires Single v1.0 lock before Rack, while current product direction makes Rack the next major target. REG-0 resolves that explicitly with evidence/ADR; do not silently pretend S6 passed and do not silently ignore the contract.

If REG-0 returns GO, the next fresh ticket is UI-0, a short helper-only GUI dependency/window proof. UI-0 loads no VST3 and does not implement Rack runtime. It must finish with GO IMGUI or BLOCKED before R0-1 begins.

Dependency spine

REG-0
  -> UI-0 helper-only graphical dependency proof
  -> R0-1 protocol-neutral process seam
  -> R0-2 HostedPlugin extraction
  -> R1-1 two-plugin separate Rack helper
  -> R1-2 bypass + latency + whole-block fail-dry
  -> R1-3 immutable topology generations
  -> R1-4 crash breadcrumb + restart
  -> R2-1 Rack Session Snapshot
       |-> R2-2 missing/quarantine recovery
       `-> R2-3 Preset Save/Load independent reuse
  -> R3-0 production Rack Editor shell + command/snapshot bridge
  -> R3-1 native OBS Rack thin launcher/status filter
  -> R3-2 graphical slot editing + plug-in browser
  -> R3-3 vendor editor orchestration
  -> R3-4 complete preset management UX
  -> R4-1 deterministic runtime/UI stress matrix
  -> R4-2 package + OBS + representative commercial compatibility
  -> R5-1 v2.0 exact-head lock

Full ticket bodies are in docs/rack/VST3_RACK_TICKETS.md. Create child GitHub issues only when approaching unblocked state so issue text does not drift from accepted architecture.

Parent evidence ledger

For each merged child ticket, append:

Ticket:
Fixed-point base SHA:
Final source SHA:
PR:
Tests added/executed:
CI/compat run IDs:
Manual evidence (if required):
Review findings resolved:
Next unblocked ticket:

v2 non-goals

No sidechain, arbitrary graph/patchbay, parallel routing, MIDI, VST3 instruments, nested racks, embedded vendor editors, private OBS Qt integration, per-slot worker processes, Float64, arbitrary multichannel or cross-platform Rack in v2.

Those are post-v2 phases.

[masarray]

Rack architecture synchronization — accepted planning baseline

The isolated graphical Rack Editor strategy has been synchronized and merged to main.

• PR: docs: lock isolated graphical VST3 Rack editor strategy #59
• Squash merge / current architecture-doc source SHA: 97188252532b5e81e348442a2e97f3794fb3eeaf
• Scope: docs/planning only; no runtime/CMake/workflow/installer/protocol/DSP/scanner/shipping dependency changes.

Accepted planning changes:

• OBS Properties is thin status + Open Rack only.
• Primary graphical Rack Editor is owned by the isolated Rack helper process.
• VST3/vendor GUI/Rack graphical dependencies remain outside obs64.exe.
• v2 engine remains serial; free-form graph/routing is post-v2.
• vendor editors remain floating helper-owned native windows.
• helper UI follows command -> RackControlPlane -> immutable snapshot architecture.
• default Windows GUI candidate is pinned Dear ImGui + Win32 + D3D11, but only after the UI-0 proof gate.
• JUCE/atkAudio/Element are reference patterns, not copied source/public dependencies.
• execution spine is now REG-0 -> UI-0 -> R0 -> R1 -> R2 -> R3 -> R4 -> R5.

Current only unblocked ticket remains #57 REG-0. #57 must finish GO/BLOCKED and stop. If GO, create/run UI-0 in a fresh thread; do not jump directly into R0.

[masarray]

Parent evidence ledger update

Ticket: #57 REG-0 — GO
Fixed-point base SHA: 97188252532b5e81e348442a2e97f3794fb3eeaf
Final source SHA: f611fe671c66a5b414525a50459974c8e9d36beb (docs-only ADR authorization; runtime source unchanged)
PR: #60
Tests added/executed: no production tests added in REG-0; audited exact-head CI #351 / run 33061484347, including 23/23 Windows helper CTest + scanner smoke. PR #60 itself is docs-only.
CI/compat run IDs: current fixed-point CI 33061484347; qualified v0.5.0 Compatibility Test Build #156 33043181248; qualified v0.5.0 CI #334 recorded by PR #51.
Manual evidence: PR #51 records real-machine iZotope Ozone 11 / RX Ready and helper-owned native vendor editors opening normally; Compatibility #156 includes official OBS 29.1.3 loader probe.
Review findings resolved: Vst3Engine::process(AudioSlot&) is sufficiently narrow for protocol-neutral expansion; lifecycle/state/recovery ownership is sufficiently separated; historical S6->R0 order is explicitly superseded only for Rack v2 by ADR-0004 without claiming S6 complete. Existing suite lacks a direct deterministic real-VST3 engine-process characterization, so ADR-0004 makes that a mandatory pre-mutation gate inside R0-1.
Next unblocked ticket: UI-0, fresh engineering thread only.

[masarray]

Rack v2 evidence ledger — UI-0 GO IMGUI

Ticket #61 completed via PR #62.

• UI-0 audited base: f611fe671c66a5b414525a50459974c8e9d36beb
• Exact qualified source: 05d87d7e2eea4a2b4af1201be854674c192e4db8
• Final merged main: 060197707a372adce55db63434e7ab709a3d8262
• UI-0 ImGui Isolation Proof Epic: P2 daily-driver VST3 UX without sacrificing OBS isolation #4 / run 33077132801: SUCCESS
• CI #357 / run 33077132711: SUCCESS
• Compatibility Test Build #160 / run 33077132904: SUCCESS
• Dear ImGui accepted: v1.92.9 @ 01380c579715e62fb9a8d6ec0502c4ea83bfde6e, MIT.
• OBS 32.2.2 module build/test green; official OBS 29.1.3 loader/ABI-floor probe green; production PE/package/installer checks green.
• No R0/runtime extraction or Rack production runtime was implemented in UI-0.

Verdict: GO IMGUI. Next dependency is R0-1, and it must begin in a fresh engineering thread per the Rack handoff.

[masarray]

Rack v2 evidence ledger — R0-1 GO

Ticket: #63 R0-1 — GO
Fixed-point base SHA: 060197707a372adce55db63434e7ab709a3d8262
Qualified exact source SHA: dc3a52bdb8b6a15026f39c46130b42f0acee5c6a
Final merged main SHA: bcddeb78e0b666d8ba2b4ae6d9ce355142181d5d
Final merged tree: 956e8b3a5720e8242ea2993263521a2bca7d9c51
PR: #65 (squash merged with expected-head lock)

Tests added/executed:

• mandatory pre-mutation deterministic real-VST3 Single seam characterization on unchanged process(AudioSlot&);
• post-migration AudioSlot vs protocol-neutral ProcessBlockView deterministic parity;
• invalid block, mono/stereo adaptation, process failure propagation, project sample-position continuity;
• full existing lifecycle/state/latency/parameter/process-context/recovery/protocol regression suite;
• Windows helper/module + scanner smoke;
• supported OBS compatibility/package gates.

CI/compat run IDs:

• R0-1 Process Seam Characterization S2.4 final merge checklist #17 / 33161584526: SUCCESS
• CI #375 / 33161584578: SUCCESS
• Compatibility Test Build #162 / 33161584519: SUCCESS
• exact artifact ID 9682202575, digest sha256:ee5802f1d18ee61eabb88057973a30830bffb0214c46e03b944e1eb89ddd72e5

Manual evidence:

• real OBS Studio 32.1.2 + ArSonKuPik representative VST3;
• Single VST 3.x Plug-in registration visibility PASS after OBS source-info ABI-floor fix;
• normal processed audio PASS;
• helper-owned vendor editor open/hide/reopen PASS;
• exact-state continuity after forced helper recreation PASS;
• dry fail-open during helper loss/recovery PASS;
• runtime log confirmed bounded recovery attempt followed by helper ready with state=restored.

Review findings resolved:

• ProcessBlockView remains non-owning/protocol-neutral and Single AudioSlot remains an adapter;
• Single protocol layout/version unchanged;
• real-machine smoke exposed an OBS source-registration ABI mismatch (424 > 408) that the previous loader-only probe could not detect; narrow fix now registers only the used obs_source_info prefix via obs_register_source_s();
• no Rack protocol/helper, multi-plugin runtime, Rack OBS filter, production Rack editor, or Single protocol redesign entered R0-1;
• no open PR review threads remained at merge.

Next unblocked ticket: R0-2 HostedPlugin extraction, fresh engineering thread only. After R0-2, R1-1 is the first true Rack runtime ticket: two plug-ins in a separate Rack helper.