From 4cae2bc8c89945adcf6f94de1a6195f334b43116 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 11 Nov 2026 02:37:31 +0700 Subject: [PATCH] docs(architecture): publish executable maintainability blueprint and M1 agent workpack --- AGENTS.md | 5 + .../FEATURE_EXTENSION_PLAYBOOK.md | 74 ++++++++ .../MAINTAINABILITY_EXECUTION_V1_20261111.md | 171 ++++++++++++++++++ .../NEXT_THREAD_EXECUTION_PROMPT.md | 42 +++++ docs/architecture/README.md | 77 ++++++++ 5 files changed, 369 insertions(+) create mode 100644 docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md create mode 100644 docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md create mode 100644 docs/architecture/NEXT_THREAD_EXECUTION_PROMPT.md create mode 100644 docs/architecture/README.md diff --git a/AGENTS.md b/AGENTS.md index c16363894..1d85d55be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,6 +5,11 @@ **ONLY approved/public/product GUI: https://masarray.github.io/arsonmix/preview/**. There must be ONE public preview, ONE actual rendered GUI, and ONE native Windows GUI. **/preview-v2/ is rejected**: do not display, promote, publish or base native design on it as a separate UI. Do not substitute another console from `web/index.html`, `web/mixer-layout.js`, `web/console-native.html`, PR #278 or old M3/V48 mock. **The JUCE ENGINE must stitch into the EXACT approved /preview/ GUI**, never redesign it. + +## Long-term maintainability execution — 2026-11-11 + +For real source ownership and future feature-extension work, read [Current Architecture](docs/architecture/README.md), [Maintainability Execution Blueprint](docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md), and [Fast Feature Playbook](docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md). A [ready-to-copy next-thread implementation prompt](docs/architecture/NEXT_THREAD_EXECUTION_PROMPT.md) begins coding M1 instead of repeating architecture research. [Issue #527](https://github.com/masarray/arsonmix/issues/527) tracks progress. These are implementation aids, NOT an extra coordination gate or an override of the approved /preview/, single native PCM callback, hard RT/audio safety, owner-authorized smart CI, or physical FAT rules. Keep the plan updated after proven source changes; do not create a new high-level plan instead of shipping a testable milestone. + ## New ChatGPT thread / repository-agent entrypoint — MUST READ FIRST (2026-11-06) This is the **binding workflow for a new ChatGPT thread working through the connected diff --git a/docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md b/docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md new file mode 100644 index 000000000..a0f793b63 --- /dev/null +++ b/docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md @@ -0,0 +1,74 @@ +# ArSonMix — Fast, Safe Feature-Extension Playbook + +Status: WORKING PLAYBOOK, v1 2026-11-11. Root [AGENTS.md](../../AGENTS.md) and [execution blueprint](MAINTAINABILITY_EXECUTION_V1_20261111.md) take precedence. This is the route to implement new capabilities without heavy repeated architecture analysis. + +## 60-second feature classification + +| 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 | +| 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 | +| Audio I/O / ASIO / WASAPI | engine/device/**, src/LiveAudioEngine.h, Main device apply boundary, device and mixer session tests | second JUCE AudioDeviceManager, implicit different physical output, callback waiting on secondary stream | +| ArSon Player source | engine/player/**, DynamicPreparedMixerBlock.h, Player virtual PCM tests, player native commands | independent audio output device/callback, auto-Play on launch, reset existing channel | +| Session / Show / backup | src/NativeMixerSessionDocument.h, NativeMixerSessionStore.h, NativeMixerSessionSaveWorker.h, relevant Show schema/migration tests | persisting device pointers, forcing fixed 10-strip truncation, reinitializing vendor FX state on reopen | +| GUI aesthetics / WIRE physics | ONLY actual approved /preview/ generated source and exact GUI test/provenance path | rewriting native audio or replacing owner-approved controls | + +**Before writing code:** check LIVE main, active PRs and actual installed GUI build inputs. Confirm the requested feature's ownership and actual native PCM route. Avoid reading 200 historical docs or proposing a new framework when current seam works. + +## Per-feature implementation checklist + +1. **Specify one user gesture and exact outcome.** Example: "Insert FX on CH07 -> FX loads prepared instance -> follows CH07's existing WIRE route to MAIN, editor opens, sound changes; no new monitor step." +2. **Reuse existing identities and clocks.** ChannelId, EdgeId, stable FX slot/lease ID, device epoch, graph revision, requestId. Snapshot/ACK carries only native accepted truth. +3. **Implement in owning domain.** DSP stays in processor; session mutation in session; hardware binding in device; audio publishing in graph; host transport in one control handler. Avoid unrelated Main device/Player code. +4. **Support failure before success.** Unsupported plugin, invalid state, duplicate/stale request, device offline, scan busy, bus cycle, failed preprepare, and missing saved vendor DLL must leave accepted graph/document intact. +5. **Add nearest tests first.** One unit/PCM fixture for domain behavior, one host/ACK/readback fixture, browser smoke ONLY if GUI changes; do not add all tests to every CI job. +6. **One meaningful PR and bounded CI.** Fast targeted on PR, exact-SHA UI if GUI changed, native OR fat if native changed, real hardware FAT separately when needed. Record changed files and failure/rollback. + +## 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. Hook into the existing Factory/FX host registration; 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. + +## Recipe B — add a channel or WIRE feature + +User intent -> native control transaction on stable IDs -> validate destination role, cycle, FX capability, SOURCE ONLY and existing source->MAIN edges -> prepare immutable graph -> publish atomically -> ACK, then accepted new graph readback. For no hardware, commit only logical document and show nonlive state; deferred physical binding must retain all edits. Physical source names and sparse pins are never inferred from browser ordinals. + +**Regression:** CH05 input -> FX -> MAIN; SOURCE ONLY preserves CH signal, silences MAIN; retarget/remove/reconnect; BUS FX -> MAIN; PARALLEL SEND not duplicated; rejected cycle leaves old audio unchanged. Device reconnect must not erase channel or wire. + +## Recipe C — add a GUI or transport command + +Contract version and typed payload -> one intent mapping -> native validation (requestId, expected doc/graph/device revision) -> ACK/negative ACK -> separately verified snapshot readback -> update existing /preview/ DOM. Never immediately paint the requested value as permanent. A visible busy/loading state may appear while Apply is in flight; it must correspond to an actual native transaction, not a fake completion. + +**Regression:** event once; duplicate/stale rejected; status change survives snapshot; older UI compatible; a rejected action does not repaint the old graph. Check assembled GUI output before editing any HTML/JS seed. + +## Recipe D — ASIO/device/restart change + +First assert retained document and VST leases exist independently of device. Preflight exact driver/ports, suppress unsafe output during transition, keep existing state intact until final graph binding, and rollback without clearing accepted edits. Known verified hardware may resume with one natural operator gesture; new output requires user choice. Never use WASAPI secondary stream backpressure to pace realtime ASIO. + +**Regression:** failed open, stale generation, same-driver reopen, new-driver missing pins, sample rate/buffer restart, source NONE->mono->stereo, no auto-unmute of intentionally muted MAIN; physical witness remains mandatory. + +## Recipe E — Player and virtual audio + +Decode/relink on worker, publish bounded PCM ring, adapt source into the canonical ChannelId input and existing FX/MAIN graph. Exactly one hardware output callback. The user's explicit Play initiates trusted output; not auto-playing or starting a second device on launch. Preserve user’s SOURCE ONLY and existing BUS routes. + +## Quick diagnosis by symptom + +| Symptom | First evidence to inspect | +| --- | --- | +| FX picker appears but no actual insert | native intent + ACK + accepted FX lease/readback + active graph; never treat browser picker success as audio | +| UI looks functional but silent | LOGICAL_ONLY vs installed; device epoch/pins, source, MAIN routing, output safety, channel meter vs MAIN meter | +| WIRE "not admitted" | accepted graph revision/epoch + installed producer, not cosmetic WIRE drawing | +| Session disappeared on device swap | .smix authoritative document vs ephemeral DeviceBinding, transaction rollback | +| VST editor wrong plugin after MOVE | stable processor instance/slot lease and editor owner, not UI ordinal | +| Crackles with 0 FX | input/output buffer discontinuity, independent clocks and callback schedule, not just DSP CPU | +| Code change alters /preview/ | deterministic source assembly, button assets, WebView bundle hash | +| New feature touches 7 unrelated modules | missing ownership seam; create one focused shared adapter rather than another special-case path | + +## Definition of a lightweight extension + +For a normal feature we expect a recognizable single-domain code owner, a small number of related touched modules plus tests, no extra PCM callback, no duplicate GUI/device model and clear test selection. This is a *review heuristic*, not a rigid maximum-file count: real cross-layer user workflows can legitimately touch engine, bridge, UI and persistence together. + +Never declare a latency, realtime CPU, user satisfaction or release improvement without comparing real measurements on the same setup. diff --git a/docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md b/docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md new file mode 100644 index 000000000..ba0f160d5 --- /dev/null +++ b/docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md @@ -0,0 +1,171 @@ +# ArSonMix Long-Term Maintainability — Executable Engineering Blueprint v1 + +**Status: IMPLEMENTATION PLAN / NOT A CODE FIX.** Re-audited 2026-11-11 at main 99f580d76bf20ea994d54f8916098c680897f41d. Issue: [#527](https://github.com/masarray/arsonmix/issues/527). Navigate through [architecture map](README.md), [fast feature playbook](FEATURE_EXTENSION_PLAYBOOK.md), and [next-thread execution prompt](NEXT_THREAD_EXECUTION_PROMPT.md). + +## A. Outcome: faster feature delivery with LOWER future thinking cost + +We want an agent who adds another built-in FX, VST3 control, channel command or Player feature to make a small, predictable, isolated change and its tests, without re-reading a 6,499-line application or rewriting the routing stack. Success is lower cross-module coupling, fewer special-case paths, one trustworthy ownership model, faster deterministic tests, and stable field audio. Splitting files just to make them shorter does NOT achieve the goal. + +**What is explicitly out of scope:** rewriting from scratch; a new framework; replacing JUCE/WebView2; GUI restyling; renaming all code to satisfy a design diagram; a second graph/renderer/callback; making current hardware FAT claims; migrating all historical docs/tests in one giant PR; slowing P0 product work with a new approval gate. + +**Hard invariants:** approved /preview/ assembled GUI only; single JUCE callback; one genuinely installed native ChannelId/EdgeId PCM authority; logical/offline state distinct; atomic graph prep/handoff; real device/pin identity and output authorization; RT nonblocking; .smix backward compatible; external VST3 lease/editor identity retained; no hidden MONITOR ritual on trusted settings; official smart CI policy. + +## B. Second audit — concrete coupling map + +| High-coupling path | Verified examples | Failure mode to prevent | Proposed owner | +| --- | --- | --- | --- | +| GUI command ingress | src/Main.cpp has handleLogicalMixerIntent, handleApprovedNativeControl, onParameter, applyCustomAudioDevice, FX-specific snapshot/edit methods and player commands | one more feature requires large host edits and risks unrelated device/callback logic | thin NativeCommandRouter + specific use-case services (extraction only) | +| Logical state | NativeLogicalMixerWorkspace copies candidate, validates, persists .smix, emits ACK; web/approved-native-bridge.js awaits later snapshot | offline edits accidentally treated as physical graph admission; partial commits or lost FX state | current MixerSessionDocument/Workspace/Store stay authoritative | +| Device/application lifecycle | Main.cpp applyCustomAudioDevice + LiveAudioEngine begin/finish/rebind + engine/device policies | repeated reset, duplicated Apply, stale pins/epoch, unintended output | one DeviceApplyCoordinator owned on CONTROL thread; no second AudioDeviceManager | +| Graph & callback | LiveDryRoutingLab, LiveAudioEngine, DynamicNativeSessionPublisher, RealtimeRoutePublisher | M4 compatibility silently competes with or downgrades installed ChannelId PCM | existing immutable publisher + single render-owner path, measured migration | +| Native status projection | src/ApprovedNativeV8Projection.h and integration/ApprovedNativeV8Projection.h share nativeV8Decimal/nativeV8Number but differ in installed/retained semantics | divergent validation, duplicate symbols if both included, stale/fake readback | one canonical validation/projection implementation with explicit mode | +| FX UI/host | Main.cpp has per-EQ/Comp/Harmony/Throw handlers; engine/builtin_fx has individual processors and shared FxSpsc | each new FX multiplies scattered branches | common host adapter for control/ACK/state/lease; each DSP stays specialized | +| Build & docs | approved UI assembled from internal seed + button overlay; 238 docs entries at top level | wrong GUI source or obsolete PR treated as current | canonical build provenance + short CURRENT architecture index | + +**Do not exaggerate:** a large file is a risk signal, not proof of poor correctness. Real unit/PCM suites and path-scoped CI already exist; preserve them. web/styles.css's font data must not be counted as code complexity. First secure the semantics, then reduce coupling. + +## C. Desired boundaries and dependency direction + +~~~ +GUI (one /preview/ renderer) + UI event -> approved-native-bridge (translator only) + -> NativeCommandRouter (validate request type/id/epoch/revision) + -> MixerSessionUseCase -> MixerSessionDocument/Store + -> RoutingUseCase -> existing native graph compiler/publisher + -> FxHostUseCase -> existing FX registry/lease/adapters + -> DeviceApplyUseCase -> existing JUCE DeviceManager/policies + -> PlayerUseCase -> existing decode worker/virtual native source + -> native ACK + later accepted snapshot (same authoritative sources) + REALTIME: prepared immutable graph -> one JUCE AudioIODeviceCallback -> verified output +~~~ + +This is a dependency target, not an instruction to add all those classes now. Extract a new use-case owner ONLY if existing code already has a cohesive responsibility and doing so removes direct dependencies from Main, UI or the callback. Avoid pure pass-through classes and mirrored session models. + +**Thread model** +- JUCE message/control: validate commands; device scans/open/close; native graph/FX preprepare; edit session; vendor editor/serialization coordination; emit ACK/readback. +- Background bounded workers: disk save, plugin scan, file decode, expensive analysis; never mutate installed PCM without control owner. +- Realtime callback: bounded deterministic DSP/render/read-only published graph and permitted atomics/SPSC only; zero allocation, lock, wait, filesystem, UI, log, plugin create/destroy. +- UI/browser: presentation/gesture staging only; no optimistic final state or independent routing authority. + +**State and revision model** +- Document revision: accepted logical state, persists independently of hardware and survives restart. +- Device generation: real endpoint/driver/pin binding lifecycle. +- Installed PCM graph revision: preprepared and admitted topology, tied to actual device generation and output safety fence. +- Command requestId: deduplicated and correlated to ACK; snapshot for SAME accepted revision must subsequently confirm state. +- LOGICAL_ONLY / RETAINED / INSTALLED / AUDIBLE are different predicates; never infer later ones from former ones. +- Stale/missing/invalid request: explicit negative ACK, *accepted model and audio output unchanged*. Offline edits cannot ask plugin to run or render a live meter. + +## D. Execution order: incremental, code-producing, with acceptance gates + +### M0 (THIS documentation PR): navigable execution contract +Deliver docs/architecture/{README,MAINTAINABILITY_EXECUTION_V1_20261111,FEATURE_EXTENSION_PLAYBOOK,NEXT_THREAD_EXECUTION_PROMPT}, plus a short AGENTS.md pointer. Record baseline and issue #527. Docs only: inspect diff/links; no Windows/Chromium/FAT. **Does not close #527.** Next thread starts M1 coding immediately. + +### M1 — One native projection contract + logical editor control boundary (FIRST CODE MILESTONE) + +**Why first:** structural duplication and very high-value extraction without touching the ASIO render callback. The latest main already has logical-only PR #513; M1 makes that growth point cheaper for future channel/FX features. + +**Affected sources to inspect before editing:** +- integration/ApprovedNativeV8Projection.h, integration/ApprovedNativeRuntimeSnapshot.h +- src/ApprovedNativeV8Projection.h and src/ConsoleLiveBridgeV6.h +- src/Main.cpp: logicalWorkspace methods (~1054-1340), approvedNativeSnapshot/handleApprovedNativeControl (~1320-1540) +- src/NativeLogicalMixerWorkspace.h, src/NativeMixerSessionDocument.h, src/NativeMixerSessionStore.h, src/NativeMixerSessionSaveWorker.h +- web/approved-native-bridge.js and web/approved-native-contract.js (contracts only; avoid repaint/rewrite) +- tests/approved_native_v8_projection_test.cpp; tests/native_mixer_session_store_test.cpp; tests/milestone_a_single_authority.test.cjs; tests/milestone_a_native_contract_test.mjs; tests/approved_native_offline_logical_smoke.py. + +**Implementation** +1. Inventory exact callers/definitions. Canonicalize shared decimal/number validation and projection semantics to ONE implementation with explicit installed/retained mode. Preserve the public function signatures through *thin forwarding compatibility only where called*; never ship two copies of the same function body or introduce header ODR collisions. Only installed PCM may set callbackOwnsChannelIds true. Retained and logical-only remain nonlive. Test rejection is mutation-free. +2. Extract the coherent logical edit/ACK/save unit from ConsoleWindow into a control-thread service that owns the *existing* NativeLogicalMixerWorkspace and coordinates the *existing* session store/worker. Keep one document, one commit/rollback, one correlated ACK and later native snapshot. Service may receive narrow injected references/callbacks; do not duplicate engines, plugin registry, rendering or browser models. +3. Leave Main.cpp responsible for creating one service, wiring JUCE events and forwarding results. Do not move whole file, device setup, or complicated unrelated editor/ASIO lifetimes as a "cleanup". +4. Ensure per-feature logical FX catalog validation, processor state capture and queued save remain correct for EQ, Compressor, Harmonice and Vocal Throw; preserve vendor VST3 state and read-only recovery. Control only: never capture arbitrary vendor state in callback. +5. Update tests that search exact source expressions only if the implementation legitimately moves; add behavior-level regression exercising the new service or same boundary. Do not weaken assertions. Preserve GUI source/hash parity. + +**M1 acceptance** +- Same valid/invalid installed/retained projections, monotonic revisions, zero snapshot mutation on rejects; no fake live meter or callback admission. +- Offline zero-device ADD/RENAME/REMOVE channel, BUS/WIRE, FX reference/bypass and .smix roundtrip: ACK + independent later readback. Duplicate/stale/busy/write-failure and recovery reject safely, with previous accepted document intact. +- Physical graph path remains untouched; compiled Windows native tests and browser-integration smoke qualified at latest exact SHA if C++ + bridge contract changed. +- Demonstrable shrinkage in ConsoleWindow's direct knowledge of logical-edit persistence/validation, not a size-only rename. New FX has one clear registration/intent seam. +- No prior approval required; one coherent PR, branch reconciled with active #512, no duplicate UI/PCM callback. + +### M2 — Device lifecycle boundary (after M1, coordinate with product P0) + +**Files:** src/Main.cpp applyCustomAudioDevice/showDeviceSetup, src/LiveAudioEngine.h beginManualAudioSetup/finishManualAudioSetup/rebind, engine/device/{DeviceSessionTransitionPolicy,AsioRestartRecoveryGate,EndpointIdentityPolicy,...}, src/NativeMixerSessionDocument.h. + +**Work:** own one idempotent device apply/rollback coordinator with explicit device generation, pin identity preflight, safe output gate, snapshot-before-apply, durable logical-session preservation and asynchronous/nonblocking progress. Do NOT reinstantiate DeviceManager or introduce a second audio callback. Setup panel opening must not reset session. Rejected driver open never overwrites accepted mixer. A known verified device should restore intended routing without extra user MONITOR/ARM ritual, while unknown output stays safely unbound pending one contextual choice. + +**Tests:** tests/device_independent_mixer_session_test.cpp, tests/device_session_transition_policy_test.cpp, tests/asio_restart_recovery_gate_test.cpp, tests/native_mixer_session_store_test.cpp, tests/approved_native_cold_start_smoke.py, relevant real hardware FAT. Confirm offline edit while no device, MAIN pin identity, NONE->MONO->STEREO, buffer/rate restart, failed apply/rollback and stream isolation. + +**Exit:** one guarded device transaction and no duplicate apply UI / reset entry points; retained graph/FX/session exact. Hardware FAT PENDING until witnessed, never claim green CI is physical pass. This milestone must not collide with active #512 or #412 work. + +### M3 — Production graph and M4 compatibility retirement (ONLY with direct PCM proof) + +**Files:** src/LiveDryRoutingLab.h, src/LiveAudioEngine.h, engine/core/{DynamicNativeSessionPublisher,RealtimeRoutePublisher,DynamicPreparedMixerBlock,UnifiedLegacyProductionAdmission,LiveChannelFxGraph}. + +1. Trace every actual render producer/fallback in the installed callback; write a call graph and counters for which path is exercised. Preserve CH1 vendor lease, admitted ChannelIds, ASIO output safety and playback. +2. Prepare a minimal behavior-preserving removal of one *proven dead* compatibility branch at a time. No blanket delete of M4/Lab APIs while they are still used. Do not enable legacy fallback when native graph admission fails. +3. Regression: any HW IN->CH05->FX->BUS FX->MAIN; SOURCE ONLY with nonzero channel meter and silent MAIN; WIRE re-target/remove/reconnect; parallel sends without unintended duplicate; FX slot reorder/remove/editor instance identity; mono/stereo; device stop/rebind. Include block-by-block golden PCM and startup/recovery failure paths. +4. Stress callback CPU and PDC; no heap/lock or vendor destruction, no device thread blocking due to WASAPI stream. +5. Exact-SHA Windows/native/FAT per smart policy, real physical listening remains independent. + +**Exit:** fewer competing branches and one proven PCM authority; no behavior regression. If product audio blocker remains, prioritize its root fix over cleanup. Do not silently change plugin sound. + +### M4 — Standard FX-host extension seam + +**Files:** src/FactoryFxRegistry.h, src/PluginCatalog.h, engine/builtin_fx/{BuiltInFxCatalog,ChannelEqProcessor,ChannelCompressorProcessor,ChannelHarmonyProcessor,VocalThrowProcessor,FxSpsc}.h, engine/core/{DynamicChannelFxLeaseBank,RealtimeNativeFxControl,LiveChannelFxGraph}.h, native FX request handlers in Main and web approved adapter. + +1. Keep unique DSP code per plugin; consolidate host *plumbing* only: catalog identity, stable slot ID, processor lease/editor ownership, input/output layout, prepared state, bounded parameter update + ACK, bypass/rack bypass, state versioning, PDC, meter readback. +2. Prove by registering a lightweight test processor through the same extension path as existing built-ins WITHOUT new plugin-specific branching across unrelated device, routing and GUI files. A production plugin is not required in the first structural fixture. +3. VST3 and built-ins share host lifecycle rules but NOT necessarily identical UI or DSP; genuine vendor GUI remains legitimate. Zero changes to DSP algorithms unless specified separately. +4. Tests: tests/live_channel_fx_graph_test.cpp, tests/native_mixer_session_store_test.cpp, tests/factory_fx_registry_test.cpp, targeted per-effect DSP tests, FX editor and stored-state browser smoke. Unavailable VST3 preserves placeholder/state, does not erase rack. + +**Exit:** documented recipe with predictable touched files; no new host-wide switch statement for every FX. + +### M5 — GUI native adapter reduction (UI only, preserve assembled authority) + +**Files:** web/approved-native-bridge.js, web/approved-native-contract.js, web/mixer-io.js, web/monitor.js, scripts/build_approved_native_gui.py, scripts/build_pages.py. + +- Identify script *actually packaged* into /preview/ first; archived web/app.js/web/bridge.js do not automatically mean another shipped GUI. +- Isolate typed intent serialization, ACK correlation and snapshot reconciliation as pure testable modules. Keep one DOM/view model (same scope) and one native subscription; split *by coherent domain*, not file length. +- Never create a shadow local graph, browser audio, extra subscription or a second device setup UI. UI shows pending vs accepted correctly and visibly responds to APPLY. +- Verify approved SVG/PNG assets, native caption, FX picker, WIRE gesture, bank/viewport geometry, pointer and hardware setup; tests/approved_native_m2_contract.test.cjs plus real Chromium smoke. +- Exit: a new native command has one documented handler and predictable GUI seam, with no duplicate listener. + +### M6 — Guardrails, documentation, and maintenance hygiene (incremental with M1-M5) + +- Keep this map updated when paths truly move; use ADR states CURRENT / IMPLEMENTED PARTIAL / SUPERSEDED / HISTORICAL (older docs stay available for archaeology). +- Add only *cheap*, measurable static checks if a regression demonstrates need: duplicate contract/handler ownership, forbidden callback operations or unexpected extra PCM source, inactive alternate GUI bundle, schema serialization compatibility. Prefer target-specific over broad regex false positives. +- Add C++ warnings/static analysis on changed modules when toolchain/profile permits, without blanket -Werror on vendor code. Consider deterministic clang-format conventions on touched code and a small JS formatting boundary; do not massive-reformat GUI. +- Preserve current path-scoped fast CI and exact-SHA milestone jobs. Do not add duplicate Windows/Chromium jobs or require owner to click Actions. +- No external dependencies or autogenerated abstraction frameworks without proving they remove real maintenance work. + +## E. Fast validation matrix (commands are from repository) + +| Change | Cheapest relevant check (choose actual impacted set) | Milestone qualification | +| --- | --- | --- | +| Projection + native session | CMake C++ test targets registered in CMakeLists.txt for approved native V8 and session; node --test tests/milestone_a_single_authority.test.cjs tests/milestone_a_native_contract_test.mjs | one native MSVC/CTest at exact candidate SHA | +| GUI native bridge | node --test tests/approved_native_m2_contract.test.cjs tests/gui_workflow_contract_test.mjs; approved GUI bundle source checks | one UI Chromium milestone at exact SHA if semantics/interaction changed | +| Graph/routing/FX lifecycle | relevant CTest (routing, FX, PCM, session, PDC), deterministic PCM before/after fixtures | one native or FAT (not both), plus UI only if changed | +| Device/physical output | device policy/ASIO restart and session tests; no fake playback assumptions | FAT package + independent real ASIO listening and failed-device recovery evidence | +| Documentation alone | inspect links, filenames and diff; no source build required | NO CI milestone; do not dispatch Windows | +| Release packaging change | specific installer/packaging tests; source provenance | release controller, exact artifacts and integrity separate | + +Target a *single* coherent feature PR; run cheap relevant tests while editing; read actual CI status; request /arsonmix-ci ui|native|fat only for a justified milestone using the authenticated PR top-level comment. FAT includes native MSVC + CTest and artifact, so never request native + fat for the same SHA. A qualified ZIP is still NOT physical listening proof. + +## F. Dependency/coordination strategy + +- main audit baseline: 99f580d76bf20ea994d54f8916098c680897f41d; always re-read current main before execution. +- Active draft #512 touches Main, LiveAudioEngine, LiveDryRoutingLab, native bridge, Harmony, session. Do NOT overwrite its HEAD or mass cherry-pick. Its work may merge after this document, so rebase/reconcile by changed-file semantics. +- Active draft #521 is experimental Harmonice latency; do not fold unqualified DSP study into architectural cleanup. +- #490 (cold-start logical editing), #412 (physical routing/FAT), #192 (dynamic mixer), #15 (crackle) retain product defect ownership. This plan does not close or supersede them. +- Build a scoped new branch for M1 based on LIVE main; one integrated PR for projection+logical-control boundary if both safe. If concurrent P0 overlap blocks one slice, complete a cohesive non-overlapping verified seam and record the exact deferred dependency; do not ask for another design approval or create a chain of empty planning PRs. + +## G. Engineering acceptance metrics (measure, do not invent baseline) + +For each implementation PR record BEFORE vs AFTER: modules touched for a normal feature, domain responsibilities located in Main, duplicate producer/validator count, complete test suite names/results, code paths invoking callback or device setup, compilation/test overhead if measurable, and actual audio lifecycle invariants. Future aspirational goal: adding a standard built-in FX primarily changes its DSP/registry/parameter/editor files and tests, not unrelated device/Main routing special cases. Quantify reductions only after diff inspection; line count alone is never a pass/fail criterion. + +**STOP/ROLLBACK:** if an extraction changes rendered PCM, plugin lease lifetime, accepted .smix, host physical identity, output safety or approved native GUI, revert that behavior slice and diagnose root cause instead of adding a temporary alternate path. Never compensate for a failed test by weakening it. + +## H. Deliverable protocol — every coding agent + +Report: exact repo/main/PR branch+head SHA; actual files and responsibilities removed/added; behavior unchanged or intentionally changed (specify); deterministic quick tests with evidence; exact one selected expensive lane and run URL or reason skipped; physical FAT PASS/FAIL/PENDING separately; concurrency conflicts; what specifically remains for next milestone. Do not claim a future background job or an unverified release. + +**FIRST NEXT ACTION:** [Use the complete new-thread execution prompt](NEXT_THREAD_EXECUTION_PROMPT.md) to code M1, not create another strategy-only document. diff --git a/docs/architecture/NEXT_THREAD_EXECUTION_PROMPT.md b/docs/architecture/NEXT_THREAD_EXECUTION_PROMPT.md new file mode 100644 index 000000000..07699aa77 --- /dev/null +++ b/docs/architecture/NEXT_THREAD_EXECUTION_PROMPT.md @@ -0,0 +1,42 @@ +# Ready-to-copy prompt — ArSonMix Maintainability Execution M1 + +**Use this as the first user message in a NEW ChatGPT thread with the connected GitHub app.** The body is written in Indonesian; repository blueprint and code remain in the project language. + +--- + +[$github](app://connector_76869538009648d5b282a4bb21c3d157) + +Lanjutkan langsung pekerjaan IMPLEMENTASI maintainability dan extensibility pada repo https://github.com/masarray/arsonmix. Saya meminta HASIL CODING NYATA dan PR yang bisa diverifikasi, bukan sekadar audit, strategi baru, atau diskusi konsep. Tujuan akhir: software mixer + VST3 host top global pro yang makin mudah dikembangkan, makin ringan di-maintain, reliabel, modular, dan tidak tambah ruwet ketika fitur baru bertambah. + +WAJIB BACA terlebih dahulu dari main TERBARU: +1. AGENTS.md dan docs/SMART_CI_RUNNER_WORKFLOW.md (otoritas workflow/keamanan). +2. docs/architecture/README.md +3. docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md +4. docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md +5. Issue #527 dan PR aktif yang menyentuh modul target; terutama draft #512 dan #521 jika masih aktif. Main/head SHA historis BUKAN otoritas, fetch ulang GitHub sekarang. + +**MISINYA: EKSEKUSI M1 — satu native projection contract + logical editor/control boundary** sesuai blueprint, mulai coding langsung tanpa meminta approval rencana: +- Buktikan semua pemakai dua ApprovedNativeV8Projection.h yang kini ada di src/ dan integration/. Satukan implementasi validator/projection ke satu sumber kanonis dengan mode INSTALLED vs RETAINED yang eksplisit; semua API publik pengguna lama tetap kompatibel hanya lewat forwarder tipis jika dibutuhkan. Tolak snapshot stale/bus invalid tanpa mutasi; LOGICAL_ONLY/RETAINED TIDAK BOLEH dianggap memiliki callback PCM atau output live. +- Ekstrak unit kontrol logical mixer di src/Main.cpp (handleLogicalMixerIntent, emitLogicalMixerAck, saveLogicalWorkspace, fungsi terkait) ke service yang BENAR-BENAR memindahkan ownership validasi/transaction/ACK/save, menggunakan NativeLogicalMixerWorkspace, MixerSessionDocument dan SessionStore yang sudah ada. Main tinggal application composition / bridge forwarding. Jangan membuat second document, proxy class kosong, atau callback/publisher baru. +- Berikan jalur extension standar untuk logical FX supaya penambahan FX baru tidak perlu menyebar switch/if produk ke banyak bagian Main, engine, dan GUI. Namun jangan menulis ulang DSP Harmony/Compressor/Vocal Throw atau mengubah bunyi, latency, preset, VST lease dan editor. Jika ekstraksi FX khusus belum aman, buat kontrak seam minimal yang diuji, jangan berbohong sudah sepenuhnya selesai. +- Uji rangkaian end-to-end: no-device logical ADD/RENAME/REMOVE channel/BUS/WIRE/FX, .smix Save/Open, duplicate/stale/busy/write-failure rollback, FX state, ACK lalu readback, native installed/retained projection, dan compatibility terhadap current main. Tambah behavior tests, jangan sekadar string-search asserts. Perbarui tes lama yang mengunci lokasi source hanya jika invariant yang sama tetap teruji. +- Jangan memperbarui GUI owner-approved /preview/ secara visual. WIRE/FX/routing/ASIO/VST asli dan session tidak boleh regresi. Tetap SATU native JUCE realtime callback, SATU accepted ChannelId PCM graph, SATU source of truth. Tidak ada WebAudio, mock meter, second renderer, hidden monitor/ARM wizard, device auto-switch yang tidak sah, allocation/lock/disk/VST teardown pada audio callback. + +**Metode kerja cepat dan aman:** +1. Fetch main saat ini, existing open PR dan HEAD, periksa diff yang relevan; jangan overwrite pekerjaan thread/PR #512 atau eksperimen #521. Buat branch M1 berdasarkan main terbaru bila belum ada branch in-scope. +2. Kerjakan satu milestone lengkap yang bermanfaat dengan implementasi + unit/PCM tests + native host seam + ACK/readback, dalam satu PR koheren. Jangan bikin PR untuk research atau satu test kecil; jangan hanya membuat dokumentasi lagi. Kalau ada konflik terhadap PR aktif, pilih perubahan yang aman berdasarkan actual diff, selesaikan milestone yang utuh dan jelaskan dependency spesifik. +3. Perubahan behavior harus dibuktikan, bukan diasumsikan. Tes cepat terkait setiap push; lanjut coding mandiri ketika CI quick sedang berjalan. Pada kandidat exact SHA, jalankan hanya UI dan/atau native/FAT sesuai docs/SMART_CI_RUNNER_WORKFLOW.md. FAT SUDAH mencakup native, jangan menjalankan native + FAT duplikat. Agent memakai komentar PR /arsonmix-ci yang sah, bukan meminta saya klik Actions. Hardware physical FAT tetap PENDING bila tidak ada bukti nyata. +4. Review diff kualitas: file responsibility berkurang, bukan sekadar LOC pindah; tidak muncul facade kosong, duplicate source of truth, broad catch swallow, callback branch atau state model baru; API dan CMake/test target tetap build. +5. Setelah verified dan green sesuai branch protection, rekonsiliasi dengan current main dan merge jika aman; bila blokir nyata, jelaskan tepat dan tinggalkan PR yang masih bisa langsung diteruskan. Jangan menunda dengan "akan dikerjakan nanti", jangan berhenti di rencana. + +**OUTPUT WAJIB:** +- Link PR, branch, main SHA dan PR HEAD SHA terakhir, file yang benar-benar diubah, fungsi/ownership yang berhasil disederhanakan, duplikasi yang dihapus. +- Test yang benar-benar dijalankan dengan PASS/FAIL dan URL; detail area yang belum teruji. Jangan mengklaim hardware FAT. +- Bukti bahwa penambahan fitur FX/channel berikutnya menjadi lebih sederhana (seam dan test yang digunakan), berikut sisa pekerjaan M2 menurut blueprint; update issue #527 / docs/architecture jika source ownership berubah. +- Target akhir bukan berkurangnya baris semata, tetapi pengembangan fitur ke depan menjadi jauh lebih praktis, stabil, dan tidak perlu audit besar berulang. + +Saya menginginkan hasil milestone M1 yang benar-benar selesai secara coding, bukan analisis tambahan. Mulai eksekusi langsung melalui GitHub connector. + +--- + +For agent consumption: the prompt above is an implementation request, not evidence of code being shipped. Avoid treating older exact SHAs as current. The binding native GUI and release/physical FAT rules in AGENTS.md prevail. diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 000000000..33cbadafc --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,77 @@ +# ArSonMix — Current Architecture & Source-of-Truth Map + +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. + +**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). + +## What this application is + +ArSonMix is a native JUCE live digital mixer and VST3 host with one approved assembled /preview/ GUI rendered by WebView2; browser preview is visual/simulated, not a browser audio engine. Native hardware audio authority is the ONE JUCE AudioIODeviceCallback and its installed ChannelId/EdgeId PCM graph, with M4 compatibility only where explicitly still needed. A logical/offline MixerSessionDocument can be edited without hardware but is NOT permission to claim audible PCM. + +The current path to reason about every feature is: + +~~~ +Assembled /preview/ DOM (presentation only) + -> web/approved-native-bridge.js + web/approved-native-contract.js + -> Native JUCE command transport in src/Main.cpp (MESSAGE/CONTROL thread) + -> accepted logical MixerSessionDocument / ChannelId + EdgeId model + -> validated mixer graph & FX lease preparation (CONTROL, not callback) + -> engine/core/DynamicNativeSessionPublisher.h + realtime publication + -> ONE src/LiveAudioEngine.h JUCE callback (with src/LiveDryRoutingLab.h compatibility integration) + -> verified ASIO/WASAPI device outputs, optional independent stream + -> native status/ACK then accepted revision readback -> exact same GUI +~~~ + +*Logical ACK/readback* means a durable native logical edit was committed and subsequently read back. *Installed PCM ACK/readback* means an actual prepared graph is installed and bound to genuine device/pin identity. They must never be conflated. A third state, *audible*, requires valid authorized output routing; a browser 'ready' event or successful CI cannot prove it. + +## Current file ownership (grounded in current main source) + +| Concern | Current primary files | Correct responsibility / future direction | +| --- | --- | --- | +| Application composition / bridge transport | src/Main.cpp; src/ApprovedConsoleNativeTransportV6.h | JUCE app lifecycle, WebView wiring, dispatch only; move domain-heavy control use-cases behind narrow services incrementally | +| Logical mixer & accepted session | src/NativeLogicalMixerWorkspace.h; src/NativeMixerSessionDocument.h; engine/core/DeviceIndependentMixerSession.h; engine/core/DynamicChannelRoster.h | Stable ChannelId/EdgeId, control-authoritative edits, revision guard, logical-only semantics | +| Session persistence | src/NativeMixerSessionStore.h; src/NativeMixerSessionSaveWorker.h; src/NativeMixerSessionFxRestore.h | .smix durable state, rollback, vendor-state retention and explicit schema migration | +| Native graph publisher & PCM | engine/core/DynamicNativeSessionPublisher.h; engine/core/RealtimeRoutePublisher.h; engine/core/DynamicPreparedMixerBlock.h | Validated immutable prepared graph, atomic publication, safe retirement, callback render state | +| Audio device policy | src/LiveAudioEngine.h; engine/device/**; src/Main.cpp currently applies device | Verified driver/pins, epochs, reopen/rebind, explicit physical output safety; independent from logical session document | +| Production audio compatibility | src/LiveDryRoutingLab.h; engine/core/UnifiedLegacyProductionAdmission.h | Retain only proven required M4/FAT migration semantics; never create another render authority | +| Built-in DSP and VST lifecycle | engine/builtin_fx/**; src/FactoryFxRegistry.h; src/PluginCatalog.h; engine/core/DynamicChannelFxLeaseBank.h; src/LiveAudioEngine.h | Per-processor DSP; common host lifecycle, source state, bypass, latency, editor lease and host registration | +| 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/ApprovedNativeV8Projection.h | Installed / retained / logical-only readback with one semantic contract and no forged output/PCM authority | +| 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 | +| UI build & publishing | scripts/build_pages.py; scripts/build_approved_native_gui.py; site/preview-buttons/ (approved PNG overlay source) | Deterministic single assembled renderer and native bundle provenance, not a second public GUI | +| Tests & CI | tests/**; CMakeLists.txt; .github/workflows/{ui-smoke,p1-windows,chat-ci-milestone}.yml | Cheap relevant checks every PR update, deliberate exact-SHA UI or native/FAT milestone; physical FAT separate | + +## Verified audit hotspots at main 99f580d76bf20ea994d54f8916098c680897f41d + +- src/Main.cpp: 6,499 lines. ConsoleWindow currently owns logical edits, native ACK/status, device selection/apply, built-in FX handlers, plugin editors, Player and UI responsibilities. +- src/LiveAudioEngine.h: 3,564 lines. The single callback shares a class with device lifecycle, legacy routing control, graph/plugin lifecycle, and monitoring policy. +- src/LiveDryRoutingLab.h: 3,261 lines. Production ChannelId paths coexist with legacy M4/Lab names/guards. +- web/approved-native-bridge.js: 3,646 lines. Many per-domain event/ACK/DOM pathways in one adapter. +- web/monitor.js: 2,118 lines; do NOT assume it is entirely in the currently assembled native GUI without checking the build. +- The two ApprovedNativeV8Projection.h headers define identical helper names and different public projection behavior. integration/ApprovedNativeRuntimeSnapshot.h uses the integration version for installed/retained paths; src/ConsoleLiveBridgeV6.h includes the src version. Never delete either without proving all callers and tests. +- tests/ contains large routing, device, source/session and FX test suites. This is a major asset. Some source-text contract tests intentionally assert exact code strings; refactoring may legitimately need to update these *only when behavior-equivalent tests also exist*. +- docs/ contains 238 direct entries. The 2026-11-07 Device-Independent ADR says "NOT YET IMPLEMENTED", while merged PR #513 implements *logical-only Milestone A*. This is partially stale wording, not permission to claim hardware binding works. +- web/styles.css is dominated in bytes by an embedded base64 font; file size is NOT a maintainability score by itself. + +## Truthful current limitations + +README v0.5.0-alpha.10 identifies Windows as an alpha field-test build. Full physical ASIO, real singer monitoring, vendor VST3 continuity, device-loss behavior and uninterrupted audio require independent FAT. [Issue #490](https://github.com/masarray/arsonmix/issues/490), [#412](https://github.com/masarray/arsonmix/issues/412), [#192](https://github.com/masarray/arsonmix/issues/192), and [#15](https://github.com/masarray/arsonmix/issues/15) remain product/field-quality owners. A code restructure must not claim these resolved. + +## Existing safety invariants (non-negotiable) + +1. Exactly one approved /preview/ GUI, assembled deterministically, shared between public preview and native host. Do not use /preview-v2/ as a separate product. +2. Exactly ONE JUCE realtime callback, one installed ChannelId PCM authority; JS never handles or fabricates PCM. +3. Stable native ChannelId/EdgeId and revision/epoch fences; stale or rejected commands never change accepted audio state. Never portray LOGICAL_ONLY or RETAINED as installed or audible. +4. Processors, VST3 scans, editor lifecycle, session/JSON/disk, and graph construction stay off realtime callback. No RT blocking, allocation, logs or locks. +5. ASIO mic monitoring remains independent of non-real-time playback/secondary WASAPI stream. Actual device and output-pin identity must be verified; never auto-reroute output or defeat user mute/intent. +6. Device changes preserve mixer document, FX state and WIRE; intentional SOURCE ONLY and MAIN mute are respected; no extra monitor/ARM wizard to recover trusted already-approved output. +7. Do not use docs-only work, mock GUI results or CI green as proof of physical audio FAT. + +## Reading order for a new coding agent + +1. Root [AGENTS.md](../../AGENTS.md), [Smart CI runbook](../SMART_CI_RUNNER_WORKFLOW.md), current main + active PRs. +2. This map, [execution blueprint](MAINTAINABILITY_EXECUTION_V1_20261111.md), [feature playbook](FEATURE_EXTENSION_PLAYBOOK.md). +3. Only files and existing tests relevant to the chosen execution milestone; do not spend time reciting historical documents. +4. Implement and validate a cohesive code milestone, record the exact SHA and follow the bounded CI policy. + +**Authority order:** current user instruction + root AGENTS.md/approved GUI and native safety contract > current tested code and merged source > this orientation/implementation plan > older dated workstreams. This map is a guide to engineering and can be updated after verified source changes.