Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
# Contributing to ArSonMix

**Status: CURRENT navigation (2026-11-11).** Development is not gated by a separate architecture committee or manual Actions approval. This page points to maintained code, exact tests and the existing smart CI mechanism. Do not use historical PRs or old workstream handoffs as the current branch.

## Start with the actual product

The **only approved GUI** is the deterministically assembled `/preview/` used by the JUCE WebView2 desktop app. The browser preview is presentation/reference, **not** a PCM producer. The native audio owner is one JUCE callback with one installed ChannelId/EdgeId graph; legacy M4 compatibility cannot silently override it.

Read [AGENTS.md](AGENTS.md), [current architecture ownership](docs/architecture/README.md), [feature-extension playbook](docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md) and [smart CI policy](docs/SMART_CI_RUNNER_WORKFLOW.md). Then inspect *live* main, open PR HEADs and the actual touched code. [Maintainability issue #527](https://github.com/masarray/arsonmix/issues/527) records incomplete architecture work.

## Where to change behavior

| Intent | Primary existing owner | Nearest verification |
| --- | --- | --- |
| 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 |
| 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.

## 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.

A UI intent is not complete on ACK alone: verify an independent accepted same-revision snapshot. `LOGICAL_ONLY`, `RETAINED`, `INSTALLED` and **audible hardware** are different facts. A rejected/stale command must preserve the previous accepted mixer and output safety. SOURCE ONLY must preserve channel PCM/meter while cutting MAIN output, without losing user FX state.

## Targeted validation and delivery

For JS protocol edits, use `node --test tests/approved_native_m2_contract.test.cjs` from the repo root and the relevant contract suites. For C++ work, choose the nearest CMake/CTest targets and build on the repository's supported JUCE/MSVC workflow. Do not skip full qualification for a changed native behavior. Use path-scoped **fast** checks while iterating; after green quick checks, the connected GitHub owner agent dispatches **one** exact-SHA `ui` for visual/gesture changes or **one** exact-SHA `native` for C++/ASIO/FX changes. When a hardware-test ZIP is required, use `fat` **instead of duplicate native**, and verify its SHA/artifact provenance. See the [runbook](docs/SMART_CI_RUNNER_WORKFLOW.md).

**Never call CI PASS physical FAT.** Actual ASIO routing, hotplug, plugin-editor continuity, audible PCM, noise and latency must be witnessed on equipment. Keep that evidence separate from unit tests and do not promote a product release on an unqualified ZIP.

When finishing a scoped PR, record changed responsibilities, main and PR SHAs, test results and failures, exact dispatched lane (or why none), rollback/previous accepted-state proof, physical FAT status and remaining work. Favor one cohesive change over many cosmetic cleanups.
5 changes: 3 additions & 2 deletions docs/ADR_DEVICE_INDEPENDENT_MIXER_SESSION_20261107.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
# ADR — ArSonMix Device-Independent Mixer Session & Crash-Safe Resume

**Owner correction 2026-11-09 — regular-user / player first sound:** [Smart Zero-Friction Operator Workflow](ADR_ARSON_PLAYER_ZERO_FRICTION_SMART_WORKFLOW_20261109.md) supersedes any sentence below requiring an extra user ARM, MONITOR ON/OFF, Apply Graph, route confirmation checkbox or repeated Start **after a fresh explicit Play on an exactly matching previously verified physical output**. The Play gesture itself is the operator's requested activation; prepare/restore must be an internal transaction with real native readback. Do not autoplay on launch, auto-unmute MAIN, silently swap to new physical output, or override intentional SOURCE ONLY/BUS. A genuinely unknown/different device requires one contextual output selection; all identity and PCM safety protections remain binding. This is a product policy for future implementation, not evidence the engine currently satisfies it.
**Status: IMPLEMENTATION DESIGN / NOT YET IMPLEMENTED**
**Status: IMPLEMENTED PARTIALLY / HISTORICAL DESIGN BASELINE (reconciled 2026-11-11).**
Device-independent **logical** ChannelId session/editing and durable .smix workspace have been implemented in [#513](https://github.com/masarray/arsonmix/pull/513) and consolidated in [#530](https://github.com/masarray/arsonmix/pull/530). Non-destructive JUCE device Apply/selector and real-device readback are implemented in [#534](https://github.com/masarray/arsonmix/pull/534), [#538](https://github.com/masarray/arsonmix/pull/538) and [#540](https://github.com/masarray/arsonmix/pull/540). These do **not** certify physical ASIO rebind, exact VST3 state recovery or unattended device loss; hardware FAT is **PENDING** ([#412](https://github.com/masarray/arsonmix/issues/412)). The remaining sections record the original design and PR #418-era audit, not a replacement for the [current code ownership map](architecture/README.md). In particular, its old explicit-ARM-after-every-restart wording is superseded by the operator workflow correction above.
**Date:** 2026-11-07
**Canonical integration:** PR #418, preserve ONE JUCE audio callback, native ChannelId PCM ownership, and the single assembled `/preview/` GUI.
**Historical design-time integration:** PR #418 (not the current main integration entrypoint). Preserve ONE JUCE audio callback, native ChannelId PCM ownership, and the single assembled `/preview/` GUI.
**Driver incident:** Operator confirms WASAPI works; ASIO4ALL was reconfigured from existing WDM inputs to VB-Cable capture + Realtek playback and the host showed `Current device is not open; refresh`. Software replay is not physical qualification.

## 0. Non-negotiable user outcomes
Expand Down
6 changes: 4 additions & 2 deletions docs/architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ Status: CURRENT ORIENTATION (audit 2026-11-11). This document describes verified

**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).

**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.

**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
Expand Down Expand Up @@ -36,12 +38,12 @@ Assembled /preview/ DOM (presentation only)
| 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 |
| Audio device apply preflight (M2a) | src/NativeDeviceApplyCoordinator.h; src/Main.cpp (remaining orchestration) | Single message-thread transaction guard, JUCE open boundary, typed request/pin checks, accepted readback and fail-closed rollback. Next: extract full apply/rebind orchestration without duplicating DeviceManager |
| Audio device apply preflight (M2a) | src/NativeDeviceApplyCoordinator.h; src/Main.cpp (remaining orchestration) | Single message-thread transaction guard, JUCE open boundary, typed request/pin checks, accepted readback and fail-closed rollback. Remaining: simplify Main orchestration where proven, and independently witness physical restart/rebind FAT |
| Modal setup transaction (M2b) | src/Main.cpp::showDeviceSetup; NativeDeviceApplyCoordinator.h | Persistent one-owner lease across visible JUCE selector, explicit Apply and automatic ASIO restart; repeated Setup clicks never re-mute; selector close completes readback/rebind before releasing lease |
| Live hardware readback (M2c) | src/NativeDeviceApplyCoordinator.h; src/Main.cpp | Consolidated actual device-object readback on CONTROL, strict ASIO driver instance identity and live mask/rate/buffer verification before Apply/rollback; no new device owner or callback |
| 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 actual 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; success/fault/overlap and muted/unpatched readback; no audio authority change |
| 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. |
| 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. |
Expand Down