From 7435e2767c3d26c49a3352d374c48a7981489991 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 10:36:37 +0700 Subject: [PATCH 1/3] docs: fast WIRE-first execute-only runbook with code packets and exit tests --- .../START_HERE_WIRE_FIRST_20261104.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/workstreams/START_HERE_WIRE_FIRST_20261104.md diff --git a/docs/workstreams/START_HERE_WIRE_FIRST_20261104.md b/docs/workstreams/START_HERE_WIRE_FIRST_20261104.md new file mode 100644 index 000000000..330112617 --- /dev/null +++ b/docs/workstreams/START_HERE_WIRE_FIRST_20261104.md @@ -0,0 +1,66 @@ +# START HERE — ArSonMix WIRE-First FAST EXECUTION RUNBOOK +**2026-11-04 | EXECUTE, DON'T RE-PLAN | user-approved release objective | NOT proof of shipped features** + +**One-line objective:** finish ONE Windows JUCE mixer with real VST3, universal-channel FL Studio-style WIRE routing, default physically visible/can-unplug CH→MAIN, deterministic safety guardian, no extra *sample delay from routing alone*, verified native PCM and hardware stability. **Do not ask the owner to debug an incomplete demo.** + +## 0. Start in 5 minutes, not another research phase +Read **this file first**. Refer to [PRD](../PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md) for user behavior and [ARD](../ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md) for technical rationale **only when implementing that part**. Root [AGENTS.md](../../AGENTS.md) and existing v8 [contract](../../contracts/console-puzzle-v8.json) are authoritative. FL routing official: https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer_iorouting.htm + +**Verified baseline (refresh once before coding):** main `1789000dcf92ce9a259bd457f6a1bd2e1155f9c3` (2026-11-04). GUI **V52 fader #360, V53 FX rack #367, V54 WIRE dot/FX bypass #368 ALREADY MERGED**. Do NOT redo/change their accepted designs. Docs #365 merged. ENGINE #266, NATIVE GUI #271, FAT #270 draft; reference WIRE #352 draft and diverged. Physical dry crackle #15 OPEN. Before touching files re-check only main, owner PRs, latest CI/conflicts, and the code you will edit—do not reproduce global competitor research. + +**One writer per file family:** reference GUI #351/#352 owns `site/preview-v2/index.html` and existing WIRE CSS + Playwright tests; native GUI #271 owns `web/**` and embedded HTML parity; ENGINE #266 owns `engine/core/**`, `src/**` and native C++ tests; FAT #270 owns fixture/contract validator, joined build and hardware qualification. Reconcile against fresh main; **never force-merge #352, overwrite V54, or build parallel DSP.** #361 FX/rail concept is already materially merged by V53; inspect source before doing more FX polish. + +## 1. LOCK the behavior (no design decisions remain) +- Ordinary channel on creation → **one real active POST_FADER unity CH→MAIN edge** even with no physical input. Existing saved intentionally disconnected state stays disconnected. +- CH→CH WIRE: one audible enabled edge per ordered pair in MVP, default post-fader. Multiple incoming and outgoing routes allowed, acyclic only. Normal send **retains MAIN**; explicit ROUTE ONLY atomically creates CH→target and removes CH→MAIN; other sends unchanged. +- No separate BUS/FX Return creation workflow now; **any universal channel receiving multiple wires IS a bus** and an insert-reverb channel receiving sends IS an FX return. Preserve current VST3 INSERT rack, existing native AUX/Show sessions and compatibility. Hide the new BUS/FX shortcut buttons in first-release UI, not their runtime legacy data. +- Every real CH→MAIN edge shows a **short MAIN-color cable dangling DOWN from channel OUT into the chassis**, and a matching **MAIN-color cable rising from below into pinned MAIN IN**. These are TWO visual fragments of ONE edge, NOT two PCM feeds. No full-width line, badges, cards, labels/CTAs, extra height or changing approved console geometry. CH→CH wires keep source channel colors. +- Focused channel selects exactly its CH→MAIN edge for MAIN jack interaction. MAIN sums N sources, but drag from MAIN jack must never disconnect all. No unique focus: only inspect via the existing Navigator/Matrix. Drag occupied MAIN plug >~10px, release in legitimate empty WIRE bay → disconnect that edge; drop on socket reconnect/replug; Escape/cancel/invalid drop → restore original edge/plug. Click and drag are distinct; a drop on already-connected MAIN cannot accidentally toggle sound off. Everything bound by edgeId. +- WIRE, OUT selector, MAIN, Matrix, Navigator, Scenes/Undo and sockets must derive from **ONE graph**, not unrelated `wireEdges` + `track.output` + `sendSlots` + split-input claims. Physical capture/output patches remain separate from internal routing. During GUI-only work status = SIMULATION; production LIVE only via native accepted graph snapshot + same-revision ACK. + +## 2. EXECUTE IN THESE FOUR WORK PACKETS — prove each, then continue + +### PACKET A — GUI canonical graph + MAIN gesture (reference owner #351) +**First edit target:** `site/preview-v2/index.html` around `make/init`, `wireFor`, `wireIsCycle`, `requestWireConnection`, `wireConnect`, `replugWireEdge`, `wireTray`, `wireDisplayRoutes`, `renderWireRouting`, `wireSnapTarget`, `finishFaderPointer`, `toggleDirectMain`, `saveScene/recallScene`, `setSofLevel`; WIRE stylesheet: `site/preview-v2/assets/mixer-wire-dots.css` **only after CSS ownership inspection**. + +**Do in this order:** +A1. Add a deterministic reference graph reducer/adapter with stable edge IDs. Initialize/migrate MAIN direct edges exactly once; normalize existing Bus A/demo legacy sends into graph or separate migration test—do not ship hidden initial sends. All route actions pass one `validateCandidateGraph` (whole-graph DFS/toposort including legacy import, atomic batch). Keep selected-edge identity, undo and scene-safe validation; no JS PCM. +A2. Change route projection/painting to include MAIN edge. Fix `#wireLayer` inside `#viewport` vs pinned sibling `#master`: render **two small coordinate-correct fragment layers**, or a lightweight parent overlay, using measured jack centers and the existing cable material. No hardcoded x positions, new CSS override stack, broad hit areas, or endless RAF. Collapsed 23px WIRE, horizontal banks, 1366×768 and pinned MAIN preserved. +A3. Include pinned MAIN in existing pointer-capture/drag/snap gesture; exact focused edge only; retain stable ID/gain for replug; accepted REMOVE/CONNECT only at intentional drop; ESC/pointercancel/invalid drop no state change. Make status of both fragments, OUT, Matrix and receive socket update from same reducer snapshot. Add keyboard route alternative using existing Matrix/Navigator. +A4. Hide +BUS/+FX Return creation under release flag; leave FX INSERT/power/reorder, PAN, mute/solo, meters/fader, V54 connected-dot behavior untouched. + +**PASS A:** (i) initial every channel MAIN pair exists exactly once; (ii) unplug CH1 only; (iii) indirect CH1→CH3→MAIN still valid when CH1 direct MAIN removed; (iv) CH1→CH3 and CH3→CH1 rejected; (v) reconnect/undo/cancel/replug; (vi) duplicate route across WIRE/Sends-on-Faders rejected; (vii) Scene+SAFE and Copy/Paste cannot sneak cycles; (viii) bank/density/screen reflows do not change graph or damage V51–V54. Extend existing `tests/pages_wire_v49_direct_controls_smoke.py`, `tests/preview_v15_drag_wire_smoke.py`, `tests/pages_wire_v46_precision_smoke.py`, `tests/pages_v54_wire_fx_context_smoke.py`; add ONE targeted canonical-MAIN model test and rendered interaction test. **Actual screenshots, not source-only guesses.** + +### PACKET B — native wire transaction + single PCM graph (ENGINE #266) +**Entry:** `engine/core/DynamicChannelRoster.h`, `DynamicConsoleRoutingView.h`, `DynamicPreparedMixerBlock.h`, `RealtimeRoutePublisher.h`, `src/LiveAudioEngine.h` and current #266 head. **Reuse** existing prepared graph + VST3 ownership, do not build a second audio engine or replace with generic graph framework. + +B1. Align one v8 schemaVersion=6 *additive* `APPLY_WIRE_TRANSACTION` (CONNECT/REMOVE/RETARGET and ROUTE_ONLY batch) and accepted `graph.edges[]` with GUI #271 and FAT #270 **in one shared real C++ producer fixture**; preserve `requestId/deviceEpoch/baseGraphRevision/baseRosterRevision`. Do not mark supportedOp until actual installed code works. +B2. Convert all old native send/primary/CH→MAIN into one graph owner; default CH creation adds one MAIN edge. Build candidate whole-DAG validator with physical/format/budget guards; prepare schedule, preallocate buffers and preserve plugin instances **off audio thread**. Publish atomic immutable revision with safe old-graph retirement. +B3. In ONE primary JUCE callback process incoming sum→insert FX→fader/pan/taps→outgoing edges in topological order **within same audio block**. No per-hop queue/buffer/worker, no RT heap, locks, filesystem, GUI, plugin instantiation, driver enumeration or DFS. RT gains are smoothing/atomics, not structural rebuild. +B4. Migrate occupied CH1 vendor VST3/editor/Orbit, CH2–10, AUX and Show without losing existing live capabilities; no new *special* BUS/FX Return needed. Device hotplug/clock stays safe. Don't use callback detach/reattach for routine fx/wire edits. + +**PASS B:** Native impulse same sample index direct CH1→MAIN vs 1/2/3-hop acyclic path with no plugin latency; fan-in/fan-out numerical mix; expected direct path removed only when source->MAIN edge disconnected; 2 independent real VST3 instances continue processing; invalid/stale/duplicate/cyclic transactions fully reject with previous sound and route intact; zero RT allocation/lock demonstrated. **Zero internal added routing samples ≠ zero total hardware ms.** + +### PACKET C — native GUI adapter (GUI #271, parallel with B on same fixture) +C1. Map reference GUI intent and physical two-stub MAIN cable to **real accepted ChannelId/edgeId snapshot** (no browser-owned audio graph). Existing `web/mixer-io.js`, `web/monitor.js`, `web/bridge.js` are source of native adapter/control conventions; keep generated standalone parity. +C2. Same `arMixConsoleIntent` envelope → native ACK → accepted same-epoch/revision `arMixConsoleSnapshot` → committed physical cable. Rejected/stale restores plug; pending not shown as LIVE. All WIRE/OUT/Matrix/Navigator share this snapshot; no fake processing, pins, VST3 catalog, or meters. +C3. Keep existing approved screen and FX rack; only expose operations that are installed in native `supportedOps`. No extra setup steps, modals, badges, visual redesign. **PASS C:** one actual C++ fixture drives UI connect/disconnect, graph projection, rejection rollback, backend verified device pins and correct audio state readback. + +### PACKET D — joined FAT + testable Windows build (FAT #270, with ENG/GUI) +D1. Compose **ONE exact SHA**, one native C++ snapshot/intent producer, same GUI consumer and schema validator: `node scripts/check_console_puzzle.mjs` then `node scripts/check_console_puzzle.mjs --release` (do not suppress real failures). Run actual Windows JUCE CTest, Chromium UI tests, embedding parity; record EXE hash and full installed supportedOps. +D2. Test 0FX **physical crackle #15 first** (isolated output-only test, capture-only stats, same ASIO device loopback, WASAPI and independent clock cases). Separate callback time/gaps from real discontinuities/render starvation. No low CPU = proven crackle-free claim. +D3. FAT one operator journey: choose verified physical input → CH1+CH2 → genuine different VST3 → direct MAIN; CH1→CH3→MAIN; add CH1 parallel direct MAIN, unplug focused MAIN physical plug, sound changes precisely and scene/undo restores; 0FX impulse vs 3-hop; device output mute/solo; 60-minute dry/FX soak with measured buffer, rate, CPU p50/p95/p99/max, xruns and actual roundtrip latency. Test 16/32/64 channels **only if admitted**, never pretend performance parity without matched hardware/workload. +**PASS D:** tested actual app with exact commit+Windows EXE, verified live callback sound, no WIRE feedback, no unexpected duplicate dry, #15 resolved with evidence, FX and Show state survive. If no hardware available, label physical FAT PENDING, **not READY FOR OWNER TEST**. + +## 3. Work efficiently +- Owner PRs are **not** independent products. Stop polishing cosmetic details after PASS A; keep integration B+C+D parallel using the exact C++ fixture. Never call three separate green CI jobs a finished mixer. +- Modify the smallest existing component/owner files. Existing WIRE physics, FX V53, fader V52, meter V51 and dot V54 are frozen unless a test proves a regression. No new generic routing engines, new FX systems, busy-loop monitoring workers, or extra UI cards/CTA. +- For each packet: **code → targeted tests → screenshots/PCM evidence → fix failures → exact-head checks → post one milestone note in #351 (GUI) or #192 (native)**. Do not create weekly planning documents or run arbitrary tests to look busy. +- On blocker: log exact file+line, failing command, owning PR and smallest corrective edit. Work on the next independent packet when safe, rather than waiting on external review. Do not solicit user UAT until coherent product evidence. +- Do not ask for already-known requirements or invent another design. Re-read the detailed PRD/ARD only to resolve a concrete implementation question. + +## 4. Final completion report to owner (required) +**Integrated SHA and Windows artifact**; precise production ops proven; GUI WIRE/MAIN video or screenshots; native PCM direct/nested impulse sample indices; device/driver/sample-rate/buffer and measured latency; CPU/xruns/crackle status; VST3/Show success; remaining reproducible blockers (if any). Link PR/CI. Mark as **READY FOR USER TEST** only after hardware-quality gate, otherwise **NOT YET QUALIFIED**. + +## 5. Pointers +[GUI execution #351](https://github.com/masarray/arsonmix/issues/351) · [ENGINE/ABI #192](https://github.com/masarray/arsonmix/issues/192) · [hardware #15](https://github.com/masarray/arsonmix/issues/15) · [ENGINE #266](https://github.com/masarray/arsonmix/pull/266) · [GUI #271](https://github.com/masarray/arsonmix/pull/271) · [FAT #270](https://github.com/masarray/arsonmix/pull/270) · [WIRE #352](https://github.com/masarray/arsonmix/pull/352) · [PRD](../PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md) · [ARD](../ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md). From 80991abf09a082f056a9a20bc4ae7dc5e06c63a6 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 10:37:06 +0700 Subject: [PATCH 2/3] docs: put four-packet fast coding runbook first for future agents --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index f67826f36..1502cb8e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,5 @@ +> **CODING AGENT FAST START (2026-11-04, latest):** Execute [WIRE-FIRST 4-PACKET RUNBOOK](docs/workstreams/START_HERE_WIRE_FIRST_20261104.md) **before** reading lengthy historical plans. It names the current merged V52/V53/V54 GUI checkpoint, exact source functions, four code/test packets, owners, and the one-Windows-mixer exit. Read PRD/ARD only for an actual unresolved code question. Do not re-plan, reopen completed GUI polish, implement redundant engine paths or claim real PCM from Pages. + > **NEW 2026-11-04 USER RELEASE-PRIORITY LOCK — READ BEFORE CODING:** [WIRE-FIRST PRD](docs/PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md) · [WIRE-FIRST ARD](docs/ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md) · [GUI/ENGINE/FAT EXECUTION HANDOFF](docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md). **Current release priority:** FL Studio-style canonical WIRE routing on universal channels; default connected-to-MAIN **real graph edge** with MAIN-colored short hanging cable at each source and matching cable rising to pinned MAIN IN; direct drag-to-disconnect/replug exact focused edge, one Guardian and one native callback. Source-colored channel-to-channel cables preserved. **Dedicated new +BUS and +FX RETURN workflow deferred** (preserve existing AUX/FX/Show compatibility and VST3 inserts). **Zero additional samples from pure internal WIRE graph**, not 0ms physical audio. No new badges/cards/text-heavy GUI, no layout/approved meter/fader regression. This is an overlay on release scope/priority; v8 socket, single-owner #266/#271/#270 and all realtime/safety/FAT contracts remain mandatory. GUI Pages cannot claim PCM. This instruction supersedes older sections below *only where they require dedicated Group/FX Return in the first release*. > **DO NOT REGRESS THE CURRENT PAGES GUI (2026-11-03):** Read [M1 / WIRE V48 / FX button V21 / PAN V23 checkpoint](docs/CHECKPOINT_GUI_M1_WIRE_V48_BUTTONS_V23_20261103.md) before touching `site/preview-v2/**`, published aliases or related UI CSS. Use component CSS ownership and exact-head CI; do not bulk-merge an outdated GUI/draft into this approved visual reference. This is *visual reference only*, not evidence that `web/**` or the native JUCE/VST3 engine is production ready. The v5.2 PRD/ARD and native audio safety rules below still govern production. From b63145bcad80ac4999545a5fc10d7269abdd8147 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 10:37:09 +0700 Subject: [PATCH 3/3] docs: put four-packet fast coding runbook first for future agents --- docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md b/docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md index 874d96caf..ccc067b9d 100644 --- a/docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md +++ b/docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md @@ -1,3 +1,5 @@ +> **FAST TRACK FOR NEW CODING THREADS:** [START_HERE_WIRE_FIRST_20261104.md](START_HERE_WIRE_FIRST_20261104.md) is the concrete four-packet execution sequence, source function shortlist and exact acceptance. Read it first; this longer handoff is background only. Baseline updated 2026-11-04: GUI V52 #360, V53 #367, V54 #368 merged on main; do not repeat their styling or act on outdated 'in flight' statements below. + # EXECUTION HANDOFF — WIRE-FIRST RELEASE / ONE REAL MIXER (2026-11-04) **READ FIRST, DO WORK.** Product [PRD](../PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md) / Architecture [ARD](../ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md) / native [v8 console contract](../../contracts/console-puzzle-v8.json) / root [AGENTS.md](../../AGENTS.md). This packet is a **prioritized execution handoff**, not claim of working engine, tested sound, published screenshot or passed CI. **Do not open another roadmap issue/clone engine; use current owners.**