Skip to content
2 changes: 2 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,5 @@
> **LATEST FACTUAL STATUS / 2026-11-01 — READ FIRST:** [Current ArSonMiX main/CI/PR/hardware/Studio Console reconciliation](docs/RECONCILED_PROGRESS_ARSONMIX_20261101.md). Verified main `0ed375f4cbf7`: Windows native CTest/ZIP and Chromium CI PASS, real MAONO/ASIO/WASAPI physical FAT **NOT PASS**. Production JUCE callback still uses one **fixed 10CH+4AUX** `LiveDryRoutingLab` with CH1 legacy VST lease; #242/#244/#246/#250 dynamic ChannelId/Bus session is native-prepared PCM only, **NOT live Add Bus/CH11**. Merged #255/#256/#257 add PCM alias safety, per-physical-input telemetry and visible START AUDIO/PCM path truth. #258 stereo native L/R + CH2–10 FX is **DRAFT** (UI and Windows native CI both PASS at exact PR head; still DRAFT and hardware FAT unqualified); #259 one-APPLY workflow is **OPEN with UI CI failure** (standalone HTML drift at latest checked head), so today's shipped UI still has START AUDIO. New #260 lock-free stereo pair is **DRAFT** (prepared dynamic DSP only, Windows CI pending); #261 per-channel FX Console is **DRAFT stacked on #258**, latest UI CI failed; neither is shipped or hardware qualified. #251 opt-in WASAPI de-click is OPEN/default OFF; #15 0FX crackle remains a hardware release blocker; FactoryFX release lock remains empty. Never bulk-merge overlapping #251/#258/#259; reconcile on exact current HEAD, keep one audio callback, native epoch/revision/ARM protection, no GUI DSP and no false audible/latency claims. Older "LATEST" timestamps below are historical and superseded as status claims; PRD/ARD/HANDOFF v4 architecture still applies.

> **TOP-LEVEL PRODUCT CONTRACT v4 / 2026-10-31 — STUDIO ONE CONSOLE FUNCTIONAL PARITY, LIVE VST HOST, NOT DAW.** Read [PRD v4](docs/PRD_ARSONMIX_LIVE_STUDIO_CONSOLE_PARITY_V4_20261031.md), [ARD v4](docs/ARD_ARSONMIX_LIVE_STUDIO_CONSOLE_PARITY_V4_20261031.md), [GUI v4](docs/GUI_ARSONMIX_STUDIO_CONSOLE_V4_20261031.md), [execution HANDOFF v4](docs/HANDOFF_ARSONMIX_STUDIO_CONSOLE_V4_20261031.md), [source-verified parity matrix](docs/STUDIO_CONSOLE_PARITY_MATRIX_V4_20261031.md) **before editing any engine, routing, GUI, FX, hardware or Show**. ArSonMiX = Windows-first REALTIME LIVE PERFORMANCE VST3 HOST + FULL DIGITAL MIXER, inspired by Studio One's Console/Bus/FX/VCA/Listen/Cue/Scenes, not timeline/arranger/audio editor/recording/bounce. All main/physical/virtual output destinations remain user-selectable, no OBS-only assumption. Keep premium compact gunmetal GUI on low-end iGPU (no blur/heavy hover), one native primary mix callback/one ACTIVE prepared ChannelId DSP graph and safe independent-clock secondary consumer; no JS PCM engine, duplicate audio renderer, fake plugin/meter, plugin copy on callback, RT lock/alloc, accidental auto ARM or false LIVE ACK. **CURRENT ENGINE REALITY at audit main 6022a4fc:** #243 First Sound merged; #242 ChannelId Bus offline batch merged; #244 M3B dynamic publisher merged and native 16-lane tests passed, but LIVE callback still processes fixed 10CH+4AUX through LiveDryRoutingLab, CH1 legacy FX, native MASTER FX/pan unimplemented, fixed-10CH Show, real hardware #15 0-VST crackle still unqualified. Full Console parity MUST wait for actual callback cutover, master/VST/PDC/Listen, dynamic GUI, and physical FAT. Continuous gain/pan/send uses RT parameter plane; device/graph topology uses off-RT prepared transaction with epoch/revision ACK and safe/guarded swap; avoid forcing MUTE for every safe routine gesture in the final product. Old v3 milestones/status statements below are HISTORICAL; do not treat them as current instructions or remerge old PRs. Refresh GitHub main and PR head every turn.

> **LATEST RECONCILIATION 2026-10-31 21:10 WIB (M3 MERGED; FAST1 OPEN):** Read [authoritative Studio Console progress and CI ledger](docs/RECONCILED_PROGRESS_STUDIO_CONSOLE_20261031.md) BEFORE old status notes below. M3 #242 is merged as offline ChannelId GROUP/FX BUS batch + real PCM tests; **NOT live ADD BUS / CH11**. #241 adds truthful raw input capture diagnostics under OUTPUT MUTE, **not** certified physical sound. #243 FAST1 one-click native route ACK→explicit ARM is OPEN, PR-head CI green but branch diverged from main and must be reconciled/CI-verified before merging. At last audit main d638fa5e Chromium passed, Windows native build pending; do not represent it as green yet. FactoryFX approved release lock remains empty; #15 real 0-FX crackle/FAT still open. Preserve M1 live POST send/AUX gains, DEVICE4 hardware M/L/R aliases, M2B borrowed-lane bus as interim only, one JUCE callback/graph, real native ACK, and operator-selected flexible physical/virtual outputs. Earlier 'after #234 / #235 OPEN' notes are **historical**; product/engine v3 PRD/ARD still authoritative.
Expand Down
55 changes: 55 additions & 0 deletions docs/RECONCILED_PROGRESS_ARSONMIX_20261101.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# ArSonMiX — authoritative realtime mixer progress reconciliation (1 Nov 2026)

**Audited baseline:** GitHub `main@0ed375f4cbf70bffa0832055eeb28096fe546509` after merged #257. This is a **point-in-time status ledger**, not a replacement for the [PRD v4](PRD_ARSONMIX_LIVE_STUDIO_CONSOLE_PARITY_V4_20261031.md), [ARD v4](ARD_ARSONMIX_LIVE_STUDIO_CONSOLE_PARITY_V4_20261031.md) or [engineering handoff v4](HANDOFF_ARSONMIX_STUDIO_CONSOLE_V4_20261031.md). Refresh main + PR SHA + exact-head checks before any further engineering.

## Product contract

Windows-first, low-latency, **LIVE PERFORMANCE** native digital mixer and VST3 host for stage, karaoke, podcast and broadcast. Studio One/Fender Studio Pro **Console**, not its DAW timeline/editor. Source, audio interface and physical/virtual output are **operator-selectable**; OBS or VB-Cable is NOT required. One JUCE callback, one accepted active mixer graph; avoid RT allocations/locks/device reopens, VST instance lifecycle in audio callback, JS DSP, false visual meters, automatic unsafe ARM, or literal "zero milliseconds" claims. Compact premium GUI must remain responsive on modest iGPU hardware.

## Verified CURRENT merged main and delivery evidence

| Area | Actually merged & tested in main | Hard boundaries |
| --- | --- | --- |
| **Single native production mix** | `src/LiveAudioEngine.h` calls **one** `LiveDryRoutingLab::process` on a native **10 CH + 4 internal stereo AUX** prepared routing graph, actual source selection, fader/PAN/mute/solo, PRE/POST sends, native channel FX and MAIN/MONITOR/secondary output selection. CH1 existing vendor VST3 chain survives through the legacy lease. | Not arbitrary runtime-addable live CH/Bus; no complete native Master FX/PAN, sidechain PDC, PFL/AFL/Cue/VCA. Product parity is incomplete. |
| **Hardware / first sound** | #239/#240/#241/#243/#254/#256/#257 merged. Hardware ASIO/Windows Audio device setup and real pin masks/epoch/ACK, named **aliases** to verified physical ports, truthful raw capture observation even if output MUTED, per-callback per-input PCM peak/seen telemetry, accessible **START AUDIO / MUTE OUTPUT**, and separate RAW CAPTURE → NATIVE ROUTE → post-fader → hardware output status. | Device dropdown is a draft until **APPLY DEVICE/ACK**. `NATIVE ROUTE ACK` ≠ audible MAIN. If sound continues while native MAIN is SAFE-MUTED or MASTER MUTE, investigate MAONO direct monitoring / Windows Listen / other parallel playback. |
| **P0 PCM integrity & diagnostics** | #247 zero-head capture candidate / 100k test, #249 dynamic in-place safety and #255 **production** in-place-safe MAIN/MONITOR with 10k-block native test, all merged. One callback; bounded raw capture evidence; no proof of measured render xruns. | Issue [#15](https://github.com/masarray/arsonmix/issues/15) remains **OPEN** until controlled physical dry 0-FX evidence passes. |
| **Studio Console dynamic engineering** | #242 stable ChannelId & Group/FX Bus roster, #244 M3B prepared 16-lane PCM, #246 M3C realtime atomic fader/pan/send targets, #250 M3D atomic Group/FX create/remove and rollback with retained gains. Native C++ offline/prepared PCM and negative ACK tested. | **NOT in the production callback**: `LiveAudioEngine` still uses fixed `LiveDryRoutingLab`; `web/app.js` and `web/monitor.js` still use fixed 10 strip drafts; `src/NativeShowSchema.h` still fixes 10 channels. NO live +CH11 / independent dynamic +BUS / CH1 unified FX lease, yet. |
| **UI / plugin catalog** | Existing native VST3 import/FX hosts, 10-strip native output signal, Studio-style routing/send/editor UI and compact premium shell. | Per-CH independent stereo L/R UI meters and CH2–CH10 convenient ADD FX are **PR #258**, NOT main. Native MASTER FX UI is explicitly unavailable. `config/factoryfx-approved-releases.json` has **`"plugins": []`**: no first-party approved bundle. |
| **Documentation** | #245 v4 PRD/ARD/GUI/handoff and #253 prior reconciliation merged. | Many AGENTS older sections and the Oct 31 progress ledger refer to historical heads/PR states. THIS top-of-file ledger supersedes their status timestamps, not architecture/safety contracts. |

**Exact-head software CI:** [Windows x64 JUCE/MSVC native/CTest + archive, SUCCESS](https://github.com/masarray/arsonmix/actions/runs/41221285441) and [Chromium UI smoke, SUCCESS](https://github.com/masarray/arsonmix/actions/runs/41221285550), both on `main@0ed375f4`. Windows artifact `ArSonMix-GUI10CH-P012-Verified-Hardware-FAT-Windows-x64` is available in that run. It is a **FAT candidate**, NOT proof of actual MAONO audio, zero glitches, input latency or release quality. No production GitHub Release identified at audit.

## OPEN PR ledger — no optimistic merging

1. [#259 FAST2 one AUDIO I/O APPLY](https://github.com/masarray/arsonmix/pull/259): OPEN at `437dc25bd641`. Proposed device MUTE → device APPLY/epoch → native routing ACK → output ARM in one guarded operator gesture; removes separate START AUDIO. **NOT merged**; latest Chromium UI run [41222903673](https://github.com/masarray/arsonmix/actions/runs/41222903673) **FAILED** at `build_ui_css.py --check` with standalone HTML source/embed drift; multiple previous commits also failed. No evidence of successful latest head. Verify canonical source-to-standalone parity BEFORE another CI attempt. Fix source-owned JS → standalone embed parity, then run targeted tests BEFORE a new browser/Windows CI. Do not describe new one-APPLY flow as shipped today.
2. [#258 per-channel L/R and CH2–10 FX entry](https://github.com/masarray/arsonmix/pull/258): **DRAFT** at `75ddf061ebd4`. Separate post-fader L/R native meters (currently old GUI aggregates) plus real native routed FX stage for CH2–10. [Chromium 41221771644](https://github.com/masarray/arsonmix/actions/runs/41221771644) **SUCCESS**; [Windows native 41221771629](https://github.com/masarray/arsonmix/actions/runs/41221771629) **SUCCESS** at final audit on the exact PR head. Still **DRAFT** and requires explicit integration review and user physical 2-channel L/R + CH2–CH10 VST3 verification before merge/production claims. Overlaps #259 in `tests/mixer_io_operator_contract_test.mjs`.
3. [#251 opt-in WASAPI capture de-click](https://github.com/masarray/arsonmix/pull/251): OPEN at `291886812d4a`. A **default-OFF BETA diagnostic A/B**, no silent capture mutation on normal startup, only verified DIRECT stereo Windows Audio. Older PR-head Windows+UI CI passed, but branch was based on older main and overlaps #259 in `web/monitor.js` and #258 in integration tests. Do not mass merge; rebase/reconcile and compare against actual physical capture flags and audible marks. It is not a clock drift fix and cannot reconstruct missing PCM.
4. [#260 M3E coherent stereo fader/PAN target](https://github.com/masarray/arsonmix/pull/260): **DRAFT** at `8198d3a1cc52`. Prepared dynamic DSP atomic packed stereo L/R gain target and extreme-PAN native regression; [Windows native 41222553574](https://github.com/masarray/arsonmix/actions/runs/41222553574) **IN PROGRESS** at audit. **Not** the complete 10CH+4AUX production callback cutover and not hardware tested; no effects on today's production audio.
5. [#261 M4 multi-channel native FX console](https://github.com/masarray/arsonmix/pull/261): **DRAFT**, `29fab485d34d`, **stacked on #258**. Proposed per-channel CH1–10 native FX draft retention for CH2+CH3, true source gating and single routing APPLY, without duplicate FX render; latest [Chromium 41222955020](https://github.com/masarray/arsonmix/actions/runs/41222955020) **FAILED** in Node/JavaScript contract stage. Do not land until #258 is reconciled/merged and #261 retargeted/retested.
6. #225/#229 FactoryFX, historical #59/#60 and old #1–#128 feature PRs: overlapping/old, NOT authoritative current code. Selective source audit only. Never bulk merge.

**Known parallel changes:** #259 and #258 touch common operator test. #261 is stacked directly on #258; never merge the child before reconciling its parent. #260 modifies only dynamic C++ until later M3E production cutover. #251 and #259 both touch `web/monitor.js`; #251 and #258 both touch `tests/live_routing_ui_contract_test.mjs`. Order and rebase each PR serially against actual main, never infer safe integration from GitHub's "mergeable" flag alone.

## P0 hardware truth — BEFORE a release claim

On the supplied user screenshots, CH07 stereo IN1/2 was `LIVE · ACK` while AUDIO SETUP/SIGNAL CHECK showed `OUTPUT SAFE-MUTED`. The sound heard in that state was **not established as processed by ArSonMix MAIN**. Earlier [#15 field evidence](https://github.com/masarray/arsonmix/issues/15) separately showed a routed/ARMED 48 kHz / 480-frame 0FX `VB-Cable CABLE Output capture → MAONO headphone render` with 113 WASAPI *capture discontinuity* flags across 8,126 callbacks, while DSP peak 375 μs / 10,000 μs and over-budget callbacks=0. #259 cites another user 0FX report with 23 flags over 11,744 callbacks. These flags are **NOT proven renderer starvation** and the traces alone do not prove clock drift or DSP overload.

Controlled physical FAT, not CI:
- Use safe headphone volume, no VST3, actual native *readback* of device endpoints and source/output pins; **MUTE / APPLY / native ACK / ARM** as required by the *actual merged* build.
- Confirm source → CH07 (or verified CH) → post-fader meter → MAIN PCM → MAONO hardware. Pull CH fader to −∞, MUTE CH, then MUTE MASTER; **audible sound must follow**. If sound persists, isolate MAONO direct monitoring, Windows Listen or another player/output route. Avoid feedback loops.
- A/B **same-interface MAONO full-duplex ASIO** versus **VB-Cable capture → MAONO Windows Audio** and isolated OUTPUT ONLY / CAPTURE ONLY / DRY THROUGH, matched rates and wired output. Mark crackle events and COPY FULL REPORT, distinguish capture flags from callbacks and render xruns.
- Require **≥30 minutes clean 0FX** on the intended supported wired path, followed by 1FX and multiFX, safe device restart/epoch, channel pan/fader, physical input/output switch, and audible bus routing, before calling this product reliable.

## Meaningful next milestones — strict order

**Gate 0 — physical First Sound P0:** Qualify *latest merged main* on real hardware; correct #259 source/embed parity and A/B operator workflow with one coherent user action (but keep explicit ARM safety and panic MUTE). Reconcile #258 after completed native CTest and **real** L/R / CH2–10 FX FAT evidence; only then integrate #261 with a clean retargeted CI. Keep #251 default OFF pending informed acoustic A/B. No pointless buffer-size/CPU-worker speculation.

**Gate 1 — M3E one-callback dynamic cutover:** First validate #260's lock-free paired stereo coefficient control against old dynamic PCM; then, in one substantial isolated code PR, retire legacy CH1 special FX ownership safely and connect `DynamicAcceptedSession` / `DynamicNativeSessionPublisher` to the single existing native callback IN PLACE OF old `LiveDryRoutingLab`. Preserve all existing 10CH/4AUX, ASIO/WASAPI source masking, Show, plugin editor/Orbit, phys MAIN/MONITOR/secondary, fader/sends and epoch/rollback; sample-matched native tests + 10k/100k soak; no UI fake dynamic until real hardware-tested output.

**Gate 2 — actual dynamic Studio Console:** Source-of-truth ChannelId GUI Add Mono/Stereo CH, Group and FX Return, Add Bus for Selected (exclusive primary OUT vs parallel FX sends), remove/reorder, per-lane FX/meter, validated native ACK and Show migration. Maintain compact keyed/virtualized GUI; no costly full DOM remount per audio meter or mouse hover.

**Gate 3 — top-tier operational mixing:** True Master FX/PAN, VST3 latency PDC/sidechain, Listen/PFL/AFL/Cue, VCA/Scenes/Recall Safe, portable first-party FX approval packaging, native performance/latency and multi-hour low-end hardware certification. No DAW timeline or OBS-specific design.

**CI budget:** use cheap source-level/Node and native targeted regression first; existing Chromium and ONE Windows MSVC/CTest workflow at exact PR head only after code is coherent. Docs-only reconciliation must not trigger extra expensive build. Never treat physical FAT as CI.

**Canonical links:** [Product/GUI v4 PRD](PRD_ARSONMIX_LIVE_STUDIO_CONSOLE_PARITY_V4_20261031.md), [ARD](ARD_ARSONMIX_LIVE_STUDIO_CONSOLE_PARITY_V4_20261031.md), [GUI](GUI_ARSONMIX_STUDIO_CONSOLE_V4_20261031.md), [Handoff](HANDOFF_ARSONMIX_STUDIO_CONSOLE_V4_20261031.md), [prior ledger](RECONCILED_PROGRESS_STUDIO_CONSOLE_20261031.md) (historical).