From 90772475a286dbd5b83182cb54f72925de96ca1b Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 11 Nov 2026 13:07:31 +0700 Subject: [PATCH] M6: refresh current FX host ownership and Harmony/multi-output integration playbook --- CONTRIBUTING.md | 12 ++++++++++-- docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md | 4 ++-- docs/architecture/README.md | 6 +++--- 3 files changed, 15 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 26d4fb348..0a1080665 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,12 +15,20 @@ Read [AGENTS.md](AGENTS.md), [current architecture ownership](docs/architecture/ | Logical tracks, WIRE, .smix edits | `src/NativeLogicalMixerControl.h`, `src/NativeLogicalMixerWorkspace.h`, `src/NativeMixerSessionStore.h` | `tests/native_mixer_session_store_test.cpp`, `tests/approved_native_m2_contract.test.cjs` | | Physical output/ASIO setup | `src/NativeDeviceApplyCoordinator.h`, `src/LiveAudioEngine.h`, `engine/device/` | `tests/native_device_apply_coordinator_test.cpp`, device/ASIO CTests | | Routing / actual PCM callback | `engine/core/DynamicNativeSessionPublisher.h`, `src/LiveDryRoutingLab.h`, `src/LiveAudioEngine.h` | `tests/live_channel_fx_graph_test.cpp`, routing golden-PCM tests | -| Built-in or VST3 effect | `src/NativeBuiltInFx.h`, `engine/core/DynamicChannelFxLeaseBank.h`, `src/NativeMixerSessionFxRestore.h` | `tests/native_fx_registry_extension_test.cpp`, FX lease/editor CTests | -| Native UI intents and readback | `web/approved-native-contract.js`, `web/approved-native-bridge.js` | `tests/approved_native_m2_contract.test.cjs`, assembled Chromium UI | +| Built-in or VST3 effect | `src/NativeBuiltInFx.h`, `src/NativeFxControlRequest.h`, `engine/core/DynamicChannelFxLeaseBank.h`, `src/NativeMixerSessionFxRestore.h` | `tests/native_fx_registry_extension_test.cpp`, FX lease/editor CTests | +| Native UI intents and readback | `web/approved-native-contract.js` (pure ACK, validation and presentation), `web/approved-native-bridge.js` (single browser/DOM adapter) | `tests/approved_native_m2_contract.test.cjs`, assembled Chromium UI | | User-facing UI assets | `scripts/build_pages.py`, `scripts/build_approved_native_gui.py`, approved `site/preview-buttons/` inputs | native bundle provenance and Chromium visual checks | A new FX should add a catalog descriptor, processor/editor specialization, state/PCM tests and accepted readback **without** creating a new callback, device manager, local JS graph or unrelated device handling branch. A new hardware output must require verified physical identity and preserve the logical .smix session across device loss. +## Cross-thread compatibility — check live HEAD, not a dated PR description + +The architecture lane is not an integration gate. The latest merged FX-host safeguards are [#565](https://github.com/masarray/arsonmix/pull/565) (unique prepared processor instance token) and [#567](https://github.com/masarray/arsonmix/pull/567) (shared native control envelope and deterministic effect mailbox). [#564](https://github.com/masarray/arsonmix/pull/564) and [#568](https://github.com/masarray/arsonmix/pull/568) own GUI ACK/readback and presentation rules. A current follow-on [#569](https://github.com/masarray/arsonmix/pull/569) tightens malformed input types; treat it as **unmerged until the live PR says otherwise**. + +Harmonice's active [#529](https://github.com/masarray/arsonmix/pull/529) builds on this shared `NativeFxControlRequest` for editor and user-preset actions; its vocal DSP and preset UI remain independently owned by that PR. The physical multi-output [#563](https://github.com/masarray/arsonmix/pull/563) edits device/graph/Main/bridge and may predate newer host changes. Do not overwrite either branch or cherry-pick its incomplete work. Before merging either, compare changed files to **current** `main`, resolve genuine semantic overlap, and qualify its own final combined HEAD. A green branch workflow alone is not proof of merged audio or field ASIO FAT. + +Native FX command envelopes use **exact decimal-string ChannelId/epoch/revision**, a **string requestId**, an **integer insert slot**, and an optional **string workspaceToken** for logical editing. The `hpres-` user-preset request family is not a `harm-` realtime DSP mailbox sequence. `deviceEpoch="0"` represents logical-only work and must never authorize hardware output. Add/modify an FX by extending the shared host contract and its native registry test, not by copying type coercion into another plugin-specific route. + ## Realtime safety and failure semantics Use CONTROL/message thread for graph compilation, VST3 construction/destruction/state, device transactions, JSON/disk and editor lifetime. Audio callback must not allocate, block, lock, access disk or log. Publish prepared immutable data and retire leases safely after realtime readers finish. ASIO primary must never wait for WASAPI secondary work. diff --git a/docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md b/docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md index 45f703c33..320d21f3f 100644 --- a/docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md +++ b/docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md @@ -6,7 +6,7 @@ Status: WORKING PLAYBOOK, v1 2026-11-11. Root [AGENTS.md](../../AGENTS.md) and [ | User asks for | Inspect these first | Must NOT add | | --- | --- | --- | -| Built-in FX (EQ, compressor, harmony, spatial/throw) | engine/builtin_fx/BuiltInFxCatalog.h, corresponding Channel*Processor.h, src/FactoryFxRegistry.h, relevant FX slot/lease code, existing tests | second callback/graph, duplicate generic DSP host, per-plugin device handler | +| Built-in FX (EQ, compressor, harmony, spatial/throw) | engine/builtin_fx/BuiltInFxCatalog.h, corresponding Channel*Processor.h, src/NativeBuiltInFx.h, src/NativeFxControlRequest.h, engine/core/DynamicChannelFxLeaseBank.h, existing tests | second callback/graph, duplicate generic DSP host, per-plugin device handler | | External vendor VST3 host behavior | src/PluginCatalog.h, src/LiveAudioEngine.h, engine/core/{LiveChannelFxGraph,DynamicChannelFxLeaseBank}.h, src/NativeMixerSessionFxRestore.h | processor create/destroy in callback, unverified plugin state capture, duplicated editor lease | | Channel / BUS / WIRE control | engine/core/{DynamicChannelRoster,DeviceIndependentMixerSession,DynamicNativeSessionPublisher}.h, src/NativeLogicalMixerWorkspace.h, integration/ApprovedNativeControlIntent.h, routing tests | strip index as persistent ID, hidden admission flow, optimistic JS graph, default device reset | | Native GUI control / FX editor interaction | web/approved-native-contract.js, web/approved-native-bridge.js, scripts/build_approved_native_gui.py, current assembled /preview/, associated JS/Chromium tests | independent GUI renderer, mock PCM, second subscription, a new public preview | @@ -30,7 +30,7 @@ Status: WORKING PLAYBOOK, v1 2026-11-11. Root [AGENTS.md](../../AGENTS.md) and [ ## Recipe A — new built-in FX -Define catalog identity and stable insert/slot semantics once. Implement DSP as its own processor with deterministic prepare, bounded process, state serialization and bypass/latency reporting. Register compiled processors in `src/NativeBuiltInFx.h` for the generic live insert, offline prepare, restore and native picker. Preserve the same editor/ACK readback and rack bypass mechanics as EQ/Compressor/Harmonice/Vocal Throw. Channel/BUS routing sees only generic FX lease, not the plugin brand. Verify zero/known latency/PDC, offline state, inserted audio, bypass, reorder/move and device restart. Keep plugin-specific UI ONLY in its editor component, not device setup. +Define catalog identity and stable insert/slot semantics once. Implement DSP as its own processor with deterministic prepare, bounded process, state serialization and bypass/latency reporting. Register compiled processors in `src/NativeBuiltInFx.h` for the generic live insert, offline prepare, restore and native picker. Reuse `src/NativeFxControlRequest.h` for the CONTROL-thread editor target (exact ChannelId/epoch/graphRevision, instance ID, integer slot and requestId); do not copy permissive `juce::var` coercion into another host handler. Both LIVE and LOGICAL_ONLY modes must keep their native identities distinct. Harmonice's `hpres-` user-preset commands are a non-DSP request namespace, not a `harm-` mailbox sequence. Preserve the same editor/ACK readback and rack bypass mechanics as EQ/Compressor/Harmonice/Vocal Throw. Channel/BUS routing sees only generic FX lease, not the plugin brand. Verify zero/known latency/PDC, offline state, inserted audio, bypass, reorder/move and device restart. Keep plugin-specific UI ONLY in its editor component, not device setup. **Design signal:** needing to modify a large per-plugin switch in Main, engine callback and browser bridge for every new audio processor indicates incomplete M4 host-seam consolidation. Solve shared host responsibility once and remove old branch at the same time. Do not add a new wrapper if only one plugin needs a unique capability. diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 0a144d6ad..e22be159a 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -2,9 +2,9 @@ Status: CURRENT ORIENTATION (audit 2026-11-11). This document describes verified repository source and the proposed ownership model; it does NOT certify the installed Windows application or physical audio. Refresh current main/PR HEAD before changing code. -**Feature milestone status:** H1 hotkeys [MERGED #536](https://github.com/masarray/arsonmix/pull/536), H2 VST3 parameter hotkeys [MERGED #551](https://github.com/masarray/arsonmix/pull/551), exact integrated Windows native **86/86 CTest PASS**; independent physical/vendor field FAT remains pending. O1/O2 FL-style physical multi-output is **NOT IMPLEMENTED**. Use the [O-only execution handoff](MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md) and [complete technical contract](FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md). +**Feature milestone status:** H1 hotkeys [MERGED #536](https://github.com/masarray/arsonmix/pull/536), H2 VST3 parameter hotkeys [MERGED #551](https://github.com/masarray/arsonmix/pull/551), exact integrated Windows native **86/86 CTest PASS** at the historical checkpoint; independent physical/vendor field FAT remains pending. O1/O2 FL-style physical multi-output is **NOT YET MERGED INTO MAIN**; active candidate [#563](https://github.com/masarray/arsonmix/pull/563) must pass integrated source/CI plus physical FAT. Use the [O-only execution handoff](MILESTONE_O_MULTIOUTPUT_NEW_THREAD_20261111.md) and [complete technical contract](FEATURE_HOTKEY_FL_OUTPUT_EXECUTION_20261111.md). -**Maintainability implementation snapshot (2026-11-11, audited at `main@64b123fbbfc3ed6ed5d11faee37b5aed372ef697`):** M0 [#528](https://github.com/masarray/arsonmix/pull/528) and M1 [#530](https://github.com/masarray/arsonmix/pull/530) merged; M2 device Apply/selector/readback [#534](https://github.com/masarray/arsonmix/pull/534), [#538](https://github.com/masarray/arsonmix/pull/538), [#540](https://github.com/masarray/arsonmix/pull/540) merged with **physical FAT pending**; M3 render evidence [#542](https://github.com/masarray/arsonmix/pull/542), [#560](https://github.com/masarray/arsonmix/pull/560) merged but legacy M4 fallback still reachable; M4 registry extension fixture [#553](https://github.com/masarray/arsonmix/pull/553) merged but full host lifecycle remains partial; M5 GUI negative ACK and FX snapshot guards [#555](https://github.com/masarray/arsonmix/pull/555), [#561](https://github.com/masarray/arsonmix/pull/561) merged but adapter separation partial; M6 native producer FX instance guard [#562](https://github.com/masarray/arsonmix/pull/562) merged but broader guardrails remain partial. Active follow-ons must be evaluated at their own current PR HEAD, not treated as already merged. See [contributor entrypoint](../../CONTRIBUTING.md), [#527](https://github.com/masarray/arsonmix/issues/527), and current GitHub PRs. +**Maintainability implementation snapshot (2026-11-11, checked at `main@b5b03669c616ac55a5d935023e0402ec7a99f7be`):** M0 [#528](https://github.com/masarray/arsonmix/pull/528) and M1 [#530](https://github.com/masarray/arsonmix/pull/530) merged. M2 [#534](https://github.com/masarray/arsonmix/pull/534)/[#538](https://github.com/masarray/arsonmix/pull/538)/[#540](https://github.com/masarray/arsonmix/pull/540) device transaction/readback code merged, **physical ASIO FAT pending**. M3 [#542](https://github.com/masarray/arsonmix/pull/542)/[#560](https://github.com/masarray/arsonmix/pull/560) bounded renderer evidence merged; legacy M4 retirement not proven. M4 [#553](https://github.com/masarray/arsonmix/pull/553) registration fixture, [#565](https://github.com/masarray/arsonmix/pull/565) FX lease token uniqueness and [#567](https://github.com/masarray/arsonmix/pull/567) shared control envelope merged, but editor/parameter lifecycle consolidation remains **partial**. M5 [#555](https://github.com/masarray/arsonmix/pull/555)/[#561](https://github.com/masarray/arsonmix/pull/561) negative ACK/FX guards, [#564](https://github.com/masarray/arsonmix/pull/564) readback effects, [#568](https://github.com/masarray/arsonmix/pull/568) pure presentation rules merged; further bridge isolation remains **partial**. M6 [#562](https://github.com/masarray/arsonmix/pull/562) producer identity guard and [#566](https://github.com/masarray/arsonmix/pull/566) contributor guide merged; guardrails still incremental. [#569](https://github.com/masarray/arsonmix/pull/569) is a **separate active candidate** until verified merged. For live Harmony [#529](https://github.com/masarray/arsonmix/pull/529) and multi-output [#563](https://github.com/masarray/arsonmix/pull/563), read the [cross-thread integration guidance](../../CONTRIBUTING.md) and their current HEAD, not this dated snapshot. Epic [#527](https://github.com/masarray/arsonmix/issues/527) remains open. **Entry points:** [Execution blueprint](MAINTAINABILITY_EXECUTION_V1_20261111.md) · [Fast feature playbook](FEATURE_EXTENSION_PLAYBOOK.md) · [Next-thread prompt](NEXT_THREAD_EXECUTION_PROMPT.md) · [Issue #527](https://github.com/masarray/arsonmix/issues/527). @@ -44,7 +44,7 @@ Assembled /preview/ DOM (presentation only) | Production audio compatibility | src/LiveDryRoutingLab.h; engine/core/UnifiedLegacyProductionAdmission.h | Retain only proven required M4/FAT migration semantics; never create another render authority | | Waves VST3 / crash-safe recovery | scripts/patch_juce_vst3_waveshell.py; src/Vst3DescriptionCache.h; src/StartupVst3RecoveryGuard.h | Correct JUCE 8 WaveShell class-ordering defect; require name+UID resolution; protect saved .smix from repeated startup vendor crashes | | M3a/M3b real render evidence | engine/core/ProductionRenderAudit.h; LiveDryRoutingLab::process/status; docs/architecture/M3_RENDER_PATH_EVIDENCE_20261111.md | One native or M4 render attempt per JUCE callback; same-epoch bounded windows before considering M4 retirement; no fallback deletion or physical FAT claim | -| Built-in DSP and VST lifecycle | engine/builtin_fx/**; src/NativeBuiltInFx.h; src/FactoryFxRegistry.h; src/PluginCatalog.h; engine/core/DynamicChannelFxLeaseBank.h; src/LiveAudioEngine.h | Per-processor DSP; one built-in registration for live insert, offline prepare, restore and native picker. Specialized editors and vendor lease remain with their existing owners. | +| Built-in DSP and VST lifecycle | engine/builtin_fx/**; src/NativeBuiltInFx.h; src/NativeFxControlRequest.h; src/FactoryFxRegistry.h; src/PluginCatalog.h; engine/core/DynamicChannelFxLeaseBank.h; src/LiveAudioEngine.h | Per-processor DSP; one built-in registration and typed CONTROL target across EQ/Compressor/Harmonice/Vocal Throw. Specialized DSP/editor semantics remain with their existing owners. | | Player | engine/player/**; src/Main.cpp dispatch | Worker decode / buffered PCM, one native graph virtual input, no independent hardware output callback | | Native status projection | integration/ApprovedNativeRuntimeSnapshot.h; integration/ApprovedNativeV8Projection.h; src/NativeLogicalMixerControl.h | Canonical installed and retained projection, with a forwarding include for old clients. Logical-only readback is separate and cannot admit PCM. | | GUI state, WIRE, device setup | web/approved-native-bridge.js; web/approved-native-contract.js; web/monitor.js; web/mixer-io.js; site/preview-v2/ (internal build input) | Render accepted native states only; one assembled/public/native /preview/; no competing DOM model or JS PCM |