From cb3e771840697495dcbb0b70a07156d2eafb5e56 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 07:51:32 +0700 Subject: [PATCH 1/6] docs(prd): lock WIRE-first live routing and MAIN physical patch behavior --- docs/PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md | 82 ++++++++++++++++++++ 1 file changed, 82 insertions(+) create mode 100644 docs/PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md diff --git a/docs/PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md b/docs/PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md new file mode 100644 index 000000000..537225462 --- /dev/null +++ b/docs/PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md @@ -0,0 +1,82 @@ +# ArSonMix PRD — WIRE-First Live Routing (2026-11-04) + +**Status:** APPROVED USER PRODUCT DIRECTION / SPECIFICATION, NOT IMPLEMENTATION OR AUDIO QUALIFICATION. **Target release:** first integrated, reliable Windows live mixer. **Priority:** overrides older PRD v5.2 clauses prescribing dedicated Group Bus / FX Return creation in the *first* release, without deleting existing native-compatible AUX/Show/FX code or relaxing safety. **Companions:** [ARD WIRE First](ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md), [owner execution handoff](workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md). Existing [PRD v5.2](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) and [ARD v5.2](ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) remain in force where not superseded. + +## 1. Customer intent and release scope +ArSonMix shall feel like the approved beautiful, compact, high-quality hardware-style live Console (PR #278, #351 and approved V51 meter/V52 fader checkpoints), perform low-latency native ASIO/WASAPI mixing with real VST3, and expose FL Studio-like arbitrary legal internal routing through physical-feeling WIRE jacks. **No fresh UI redesign, text-based routing badges/cards/CTA, DAW timeline, second audio engine, or special-purpose BUS/FX routing system.** + +**Now:** universal audio channel, direct verified physical input, mono/stereo processing, native inserts (EQ/reverb/compressor etc.), fader/pan/mute/solo/PFL when truly supported, OUT jack, IN jack, multiple fan-in/fan-out WIRE edges, pinned MAIN, live meters, Matrix/Navigator for advanced/accessible operations, safe Show/session persistence and observed device health. + +**Next development, not current release blockers:** dedicated +BUS/Group Bus wizard, dedicated +FX RETURN workflow, new role-specific routing subsystems, advanced sidechain graph, DCA/VCA, optional experimental free-feedback routing. Existing legacy AUX, Group and FX Return code/state are **preserved for compatibility and migration**, but new first-release creation entrypoints are feature-flagged off until complete. An ordinary universal channel can sum multiple incoming audio edges, contain VST inserts and work as a submix or wet return. A user can choose a channel named Reverb or Vocals; role is NOT a new graph. + +**Product truth:** zero *added samples* for pure internal graph routing without latency-producing processors, as measured by deterministic PCM tests; not zero device/driver/converter roundtrip milliseconds. Performance at least competitive with LV1-class workflow on comparable supported hardware; claims of being lighter/better require side-by-side comparable measurements. No guaranteed xrun-free on arbitrary third-party VST3/host hardware. + +## 2. Reference behaviors (follow evidence, not copied intellectual property) +Image-Line: +- Mixer Track routes to one or multiple other Mixer Tracks. A new send retains source-to-Master by default. +- Send is post-fader by default. PRE-fader/pre-FX needs an explicitly defined tap/processing model; do not silently reinterpret. +- 'Route selected to this track only' creates the route and disconnects Master in one logical operation. +- Clicking Master send allows disconnect. Feedback-producing options are disabled. +- The FL Studio manual specifically describes a cable to Master visually dropping off the lower mixer edge rather than spanning the entire screen. ArSonMix takes this ergonomic pattern further with a paired MAIN-colored under-chassis cable. + +Waves eMotion LV1 Classic: Latency Optimized processes the signal path in one processing cycle with no internal routing latency. DSP Optimized may improve efficiency with latency trade-offs. Prefer a single-cycle low-latency live graph; compare DSP headroom and latency *with explicit buffer hardware conditions*. + +Official references: +- https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer.htm +- https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer_iorouting.htm +- https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer_mixermenu.htm +- https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer_trackprops.htm +- https://assets.wavescdn.com/user-guides/emotion-lv1-classic-console-user-guide.html + +## 3. Visual and interaction contract — no routing explanations disguised as new UI +**Preserve** the selected machined graphite/chassis visual, genuine existing 3D/recessed jacks, meter/fader geometry, icon/color/identity, FX Rack, compact rail and pinned equal-width MAIN. Routing identity is conveyed by *physical geometry*, material and cable color, not by new text labels, cards, arrows, buttons, tooltips floating permanently or badges. + +**Paired MAIN cable design:** every channel with an active direct-to-MAIN edge visibly has a short cable colored from the existing MAIN channel palette emerging from its OUT jack, hanging downward into the hidden chassis. The pinned MAIN has a matching short cable emerging upward from below into its IN socket. Both fragments represent **the same logical edge** (not two sends or extra DSP), and no full-width MAIN cable spans channels. Short hanging curves must have restrained realistic wire sheath, smooth tangent/weight, subtle shading and precise plug/metal tip geometry; no neon/glow/filter/everlasting bounce. Existing channel-to-channel WIRE remains source-channel colored. Nothing encroaches on PAN/MUTE/fader or expands strip height. + +**Focused MAIN edge semantics:** MAIN receives many channel feeds; its single visible physical jack is a context-sensitive inspector for the specifically focused/selected source edge. Selecting CH7 must make MAIN jack operate on CH7->MAIN, not on all feeds. Without a uniquely identified source, clicking/dragging MAIN must NOT disconnect all channels: offer existing unobtrusive route selection through Navigator/Matrix or require selecting one channel. The unselected aggregated state may remain physically plugged if >=1 MAIN feed exists; do not imply a specific source without selection. + +**Physical gestures:** +- New audio channel: direct MAIN audio edge ON by default; both cable fragments immediately exist in GUI simulation and accepted native projection when capability live. +- Select channel: see its direct MAIN cable state, plus all selected-source WIRE paths; off-bank route remains valid. +- Drag plug out of MAIN IN: thresholded drag candidate, live moving plug physics only; release in intended empty WIRE bay disconnects **only focused source->MAIN**. No accidental global mute. Escape, pointercancel, invalid drop or unchanged selection restore original exact graph + tip position. Reconnect by OUT->MAIN IN snap. Drag back onto origin cancels disconnect. Keyboard and touchscreen-safe alternative via pre-existing Matrix/Navigator. +- A short click on connected MAIN socket inspects/selects the edge; explicit click toggle can be supported when deliberate/not confused with drag. It must never silently toggle when the user intended drag. +- Drag CH1 OUT -> CH3 IN normally adds a parallel post-fader route and retains CH1->MAIN. Route-only is an explicit command/macro: atomic create CH1->CH3 and remove CH1->MAIN; other unrelated existing sends preserved. +- Disconnect CH1->MAIN while CH1->CH3->MAIN still exists: audio may continue through CH3; do not falsely report silence. The WIRE graph, not last edited control, determines audible reachability. +- Selected cable maps to exact stable edge ID for gain, unplug, replug, Undo. Multiple edges arriving at one jack never imply 'disconnect all'. Replug retains gain/tap when valid. +- Viewing/banking/filtering/collapsing/reducing motion does not change any routing edge or audio. In collapsed WIRE space show only minimal physical stub/dot; no resizing approved meter/fader/chassis. +- WIRE displayed colors and connections derive from accepted graph / GUI candidate state only, not CSS guesses or hard-coded CH indices. + +## 4. Single connected control surface +WIRE jack, visible cable, channel OUT selector, MAIN socket, WIRE Navigator and Matrix, WIRE gain, Sends-on-Faders if retained as a view, Scenes/Undo all operate on exactly one canonical channel/edge graph. INPUT physical patch is different from internal channel audio routing and cannot be conflated with WIRE receiving socket. Plugin Insert FX is within a channel, not a separate routing network. + +The legacy reference fields 'wireEdges', 'track.output', 'sendSlots', 'track.input' can be imported/migrated but must not independently own accepted routing after conversion. Existing inbound sends, primary output, PRE-FX split and MAIN must be visible or introspectable in the same graph; never create an invisible second feed. + +Aesthetic feedback uses a lit physical jack, plug occupation, cable movement/selection color, and subtle inactive finish. Error detail may appear transiently in the **already existing** console status mechanism or accessible semantic status, not new badges/cards/overlays. + +## 5. Context-aware behavior and safety +Smart Routing Guardian makes deterministic decisions using current graph, source, destination, tap, selected edge, device epoch and user action. It shall NOT use AI inference, noisy periodic graph polling, hidden reconfiguration, automatic wet/dry plugin control, or uncontrolled worker thread creation. + +- ALLOW: legal fan-in, fan-out, chained universal channels, quiet source-only nodes, independently named reverb/monitor channel. +- WARN without forced changes: reconvergent dry paths / potential doubled dry (+6.02 dB for two identical 0 dB paths), high plugin latency, mute PRE-fader semantics, orphan output/reachability. +- BLOCK: cycle from *any* edge type, self route, invalid or inactive ID, stale epoch/revision, incompatible format/resource budget, duplicate enabled audible edge with same semantics, unsupported live operation, unsafe output ownership. +- If an existing route is under control, 'already connected' means inspect not toggle-away on casual drop. +- Emergency output mute never waits for Guardian/UI; guard external virtual-cable/physical/acoustic feedback separately because internal DAG cannot see all external loops. + +**MVP edge policy:** one enabled audible edge per source/destination pair, including MAIN, with canonical POST_FADER tap and independent gain. This avoids ambiguous multi-tap duplication. Future multi-edge per pair or sidechain requires explicit identity, distinct send semantics, UI affordance and audio tests; do not silently merge distinct taps by pair in future. + +## 6. Definition of Done (all mandatory, no partial release claims) +1. On GUI reference, CH1..CHN initially show MAIN colored cable stubs and exactly one corresponding logical MAIN edge each; no phantom duplicate sums. +2. MAIN plug is draggable from its pinned IN, can disconnect/reconnect exactly the selected CH's edge; drag cancel and invalid drop 100% restore; no global MAIN mute. +3. CH->CH sends, Master send, matrix, OUT, Undo, Scenes and WIRE visual produce identical graph snapshots after all legal gesture sequences. Invalid graph changes never persist. +4. Cycle and duplicate detection pass all multi-step adversarial sequences: WIRE+legacy SEND, WIRE+OUT, WIRE+PRE-FX split, Scene+SAFE, Copy/Paste, cross-bank and late replug. No invisible legacy send. +5. Added dedicated BUS and FX Return commands are absent/disabled via feature flag on the WIRE-first release UI, *without deleting existing native AUX/Show sessions*. FX inserts remain valid. +6. True native input->channel->MAIN PCM, 2 independent source channels, CH->CH->MAIN, parallel dry/wet, 3-hop chains, multiple fan-in/fan-out, unplug/reconnect, RT mute/fader, 2 independent native VST3, Show roundtrip proven on one callback and one accepted graph; dynamic CH11 when claiming dynamic channels. +7. Pure-routed graph adds **0 samples** beyond source->sink transport under same callback, measured by impulse sample index; plugin latency/PDC reported honestly and resolved or warned on reconvergence. +8. 48 kHz test profiles 64/128/256 frames when actually supported; 16/32/64 channels as admitted by memory/callback budget; 0/medium/high FX cases. Publish callback p50/p95/p99/max vs deadline, xruns, PCM path latency, memory, UI frame work and precise device conditions; do not certify 'lighter than LV1' absent comparable same workload hardware. +9. No audio callback allocation, locks, UI, plugin scan, disk, graph rebuild, driver enumeration, expensive vector traversal or JS roundtrip. No new crackling; 0-FX physical incident #15 remains stop-ship until reproduced, root-caused and retested. +10. Exact integrated SHA same producer/GUI/validator, Windows package + Chromium functional/visual parity + actual/native device evidence. Screenshot or GUI demo PASS alone is NOT release. + +## 7. Priorities and compatibility +This PRD overrides **first-release feature ordering**, NOT the v8 schema, native lease ownership or any user-approved console geometry. Continue existing PR #266 ENGINE, #271 GUI, #270 FAT, #352/GUI #351 visual and #360 fader checkpoint with clear file ownership. Dedicated BUS/FX returns remain preserved capabilities and next-development work; don't delete DSP code or unknowingly break saved shows. + +Read [handoff](workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md) for exact files, owners, milestones, tests, and restart procedure. From c31e0f01e2c4a1f3d29f18f7e872f1ce5b3ab551 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 07:55:19 +0700 Subject: [PATCH 2/6] docs(ard): specify canonical WIRE Guardian PCM and physical MAIN cable mechanics --- ..._WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 docs/ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md diff --git a/docs/ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md b/docs/ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md new file mode 100644 index 000000000..92493af14 --- /dev/null +++ b/docs/ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md @@ -0,0 +1,127 @@ +# ARD — WIRE-First Canonical Routing, MAIN Patch and Zero-Added-Latency Engine + +**Date:** 2026-11-04. **Status:** normative target, not PCM completion evidence. Companion [PRD](PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md) and [execution handoff](workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md). This overrides dedicated BUS/FX creation as a *first-release priority*, not the existing v8 ABI, native ownership, VST3 leases, Show/legacy AUX compatibility, approved GUI layout, or release/safety gates. + +## A. Verified current-state inventory — main 0215986fbbe2c67971680952f75f069950ac653e + +- GUI reference site/preview-v2/index.html is simulated. Current JS stores routes in wireEdges, track.output, sendSlots/activeSend and track.input split markers. wireDisplayRoutes excludes default CH->MAIN. wireIsCycle does not traverse all legacy sends. Sends-on-Faders and Copy/Paste/Scene can bypass unified cycle/duplicate validation. A screen that looks linked can differ from the actual intended signal graph. +- WIRE SVG #wireLayer sits inside #viewport (banks), whereas pinned #master is a sibling. Current geometry cannot represent a true MAIN endpoint; MAIN receiver specifically omits incoming WIRE edge handling in wireTray/pointerdown. requestWireConnection blocks some drops and toggleDirectMain mutates track.output independently. +- engine/core/DynamicChannelRoster.h has stable ChannelId and ChannelSendRef(primaryOutput). DynamicConsoleRoutingView.h is an accepted-session *projection*. DynamicPreparedMixerBlock.h is an offline prepared PCM kernel, NOT the installed callback. Current production remains 10 CH + 4 AUX/CH1 special VST path. ENGINE #266 is sole owner of native cutover; GUI #271, FAT #270 are drafts; #15 physical 0FX crackle OPEN. +- contracts/console-puzzle-v8.json schemaVersion 6 already defines native requestId, deviceEpoch, baseGraphRevision, baseRosterRevision, operation, targetChannelId, ACK and accepted graph snapshot. Preserve that envelope. Do not invent a parallel browser-native protocol. + +## B. Graph schema and ownership + +One typed directed graph G=(V,E). All universal channels, including MAIN as sink, use stable ChannelId (decimal uint64 serialized as canonical strings). Every audible route, including default CH->MAIN, is an edge with a stable edgeId. GUI channel index, name, bank, physical pin and role are never identity. Physical capture SourcePatch and physical render OutputPatch are separate from internal WIRE edges. + +Proposed control-thread model (target, not deployed API): + +~~~text +Channel { id, format: MONO|STEREO, verifiedSourcePatch, nativeFxInstanceIds, + fader, pan, mute, solo, meteringTap } +AudioEdge { edgeId, from: ChannelId, to: ChannelId, + tap: POST_FADER|PRE_FADER|PRE_FX, + gainLinear: finite_nonnegative, enabled: bool, signalKind: AUDIO } +GraphSnapshot { deviceEpoch, graphRevision, rosterRevision, mainChannelId, + channels, edges, installedCapabilities, pluginLatency, outputPatch } +~~~ + +MVP policy: exactly **one enabled audible edge per source/destination pair** (not one per channel), POST_FADER default, no self or cycle, MAIN terminal and one summing input for N sources. Keep edgeId separate from pair key to permit future explicit multi-tap/sidechain expansion. Route-only is an **atomic macro** to connect source->target and remove source->MAIN; other sends stay. No duplicate physical PCM due to compatibility primaryOutput or legacy sends. Source-only has zero MAIN edges and remains capable of sending elsewhere. + +CREATE_CHANNEL accepted transaction installs CH plus one unity CH->MAIN edge. An unpatched channel is silent but connected logically. A saved Show intentionally disconnected from MAIN must stay disconnected; do not default-repair it during restore. Legacy .output==Master and sendSlots must be migrated into one graph once, with conflict detection rather than silent audio duplication. + +**Ownership domains:** +1. Native/control plane: unique canonical graph, native plugin leases, true device inventory, supportedOps/epoch/revision, accepted snapshots. +2. GUI: transient channel selection, focused source/edge, hover, drag, cable physics, PENDING; never declares accepted LIVE independently. +3. Routing Guardian: deterministic control-plane intent validator and graph compiler, event-driven. +4. Audio callback: immutable accepted topological schedule, preallocated PCM scratch, bounded realtime parameter atomics. No JS/WebAudio routing engine. + +## C. Native Console v8 intent/ACK integration + +Reuse arMixConsoleSubscribe, arMixConsoleSnapshot, arMixConsoleIntent, arMixConsoleAck; preserve string IDs and session-unique requestId. ACK accepted is *not* proof of audible LIVE until matching revision/epoch accepted snapshot from installed callback. All capabilities fail closed if unsupported. + +**Proposed additive operation APPLY_WIRE_TRANSACTION** (not yet supported; agree with owner #266/#271/#270 and issue #192 before shipping). Reuses v8 intent envelope: + +~~~json +{ + "requestId":"session:63", + "deviceEpoch":"7", "baseGraphRevision":"42", "baseRosterRevision":"11", + "operation":"APPLY_WIRE_TRANSACTION", "targetChannelId":"1003", + "payload":{ + "reason":"ROUTE_ONLY", + "changes":[ + {"op":"REMOVE","edgeId":"7201"}, + {"op":"CONNECT","from":"1003","to":"2000","tap":"POST_FADER","gainLinear":1.0} + ] + } +} +~~~ + +IDs above are illustrative. Atomic CONNECT/REMOVE/RETARGET by stable edge ID; batches commit all-or-nothing. RETARGET preserves gain/tap/identity after validation. A drag out of MAIN removes only selected source->MAIN edge. Undo replays inverse of an **accepted** transaction with freshness check; no direct JS graph restore to native. Continuous fader/pan/mute/send gain use RT-safe parameter plane with no topology rebuild. Adapt legacy SET_PRIMARY_OUT and UPSERT_SEND to the same graph once, not to a separate DSP routing path. Additive changes to snapshot edge inventory and supportedOps require native-generated fixture + GUI consumer + FAT validator updated in one integration checkpoint. Never claim new operation installed before it really is. + +## D. Guardian implementation and safety + +Control thread maintains adjacency indexed by ChannelId, edgeId hash, native channel format/role, per-source outgoing and per-target incoming. Use full candidate DAG validation (Kahn topological sort or DFS, O(V+E)) for scene, batch, copy/paste, migration and retarget. On single connection can test target reaches source in candidate; do not prematurely micro-optimize into untested cache. MAIN has no audio outgoing edges. Candidate must include all legacy-converted and current edges to catch mixed WIRE/SEND/OUT/split loops. Validate before allocating/preparing, then recheck base epoch/revisions at publish. + +- BLOCK: cycle/self, duplicate audible same-pair, MAIN feedback, invalid ChannelId or tap, NaN/Inf/negative gain, stale revision, unsupported operation, invalid physical endpoint or mono/stereo mapping, memory/CPU admission exceeded, illegal plugin I/O, unsafe output-arm transition. +- WARN (operator decides): two dry routes reconverge (+6.0206 dB if signals identical at 0 dB), clipping/headroom, high plugin latency, no path to armed output, PRE-fader mute implication. Do not auto-mute, change wet/dry, pan or rewire. +- ALLOW: N-way fan-in/fan-out, legal nested routing, unpatched or deliberately silent source-only, FX insert on ordinary universal channel. +- External virtual-cable/physical/acoustic feedback cannot be proven absent by internal DAG alone; separate input/output patch warnings, physical output mute, limiter/clip indication and endpoint policy required. + +Detect reconvergence efficiently via DAG reachability/ancestors or bounded merge-node check, not exponential enumeration of all source->sink paths. Route validation runs on structural events, NOT every audio callback or animation frame. Audio observer consumes decimated nonblocking telemetry (actual capture discontinuity vs output starvation where available, plugin exception/fault, callback budget, xrun counters, peak), not continuous graph rescans. Emergency output mute must work without control worker/GUI response. + +## E. Realtime PCM graph — zero added samples, measurable not slogan + +Build on existing DynamicChannelRoster, DynamicPreparedMixerBlock, RealtimeRoutePublisher and native leases. No second audio callback, new JS DSP or full replacement with generic AudioProcessorGraph. JUCE AudioProcessorGraph documents node routing, async/non-auto rebuild and processing cautions; use as proven pattern, but adopt existing repo's prepared runtime for ownership/lease correctness. + +CONTROL (off callback): +1. Normalize all user intent into immutable candidate edges and verified SourcePatch/OutputPatch; validate IDs and graph DAG. +2. Topologically sort once; precompute edge gain/pan/mono-stereo coefficients, fan-in accumulator offsets, per-node source patches and send tap stages. Allocate bounded scratch for MAX ACCEPTED FRAMES and choose overflow behavior (fail-safe rather than RT malloc). No per-WIRE queue. +3. Prepare native plugin instances using actual supported I/O, sample rate, frame limit and declared latency; retain stable instance IDs on route-only changes. Reconcile existing CH1 vendor/Orbit/Show ownership before engine cutover. +4. Publish prepared graph at bounded callback boundary with proven lifetime/epoch reclamation. Do not create/destroy plug-in objects or free old graph on callback. If publish fails, old graph/PCM stays. +5. Callback once per device block: clear only needed preallocated accumulators, read verified capture frames, process each channel **once** in topological order, apply ordered inserts/taps/fader/pan/mute, accumulate edges to downstream buffers in the **same callback**, sum MAIN and map to verified output pins once. No worker thread hop, per-edge FIFO, per-hop buffer period, or synchronous locks. + +**Zero-added-sample criterion:** with latency-free FX and aligned capture/render callback, direct source->MAIN and source->CH2->CH3->MAIN impulses arrive at the same *relative sample index*, regardless of number of legal WIRE hops. This is an internal processing assertion, not a 0ms microphone-to-speaker claim. Third-party VST3 can report nonzero getLatencySamples and kLatencyChanged; plugin reactivation and PDC rebuild run off RT. Automatic full PDC on parallel reconvergence may add audible monitoring delay: release LIVE default chooses bounded latency policy and warns/rejects oversized plugin delays, not silently delaying all monitors. Future per-output full PDC uses measured policy. + +**Thread and memory invariants:** no heap, lock, UI, disk/logging, driver enumeration, JSON, VST3 scanning/opening/editor, graph DFS, implicit shared_ptr destructor or blocking call in processBlock. Parameter plane uses proven lock-free targets + smoothing. Stale controls are denied by epoch/revision. Support zero/variable-sized callback safely, out-of-bounds prevention and CPU budget. Xrun risk is measured, never guaranteed away for unknown drivers/plugins. Do not introduce threads solely to parallelize wires: profile first, as DSP parallelization can trade latency for throughput. + +## F. Two physical MAIN cable fragments from ONE graph edge + +Preserve approved console surface, MAIN pinned width, fader, meters, FX, theme, WIRE node and cable machinery. + +1. For each connected source->MAIN edge, paint a short MAIN-colored, gravity-draped cable emerging from that channel's OUT and disappearing into the lower edge of the WIRE patch bay. When disconnected, omit that cable and expose an empty matching socket. No text/badge/card/CTA or full-width diagonal. +2. At pinned MAIN, paint one matching MAIN-colored cable emerging from below and entering MAIN IN. It represents **the focused exact source->MAIN edge**, or a noninteractive aggregate occupied state if multiple sources and no unique focus. Never imply one MAIN feed per geometric visible plug or allow aggregate disconnect. +3. Channel-to-channel wires keep source channel colors. MAIN cables derive color from existing MAIN channel/theme token, use the existing shared cable sheen/inner shading and metal plug cap. Realistic cubic sag, 0.5-2px restrained edge definition; no glow, endless ripple or shadow filters. Display may collapse to minimal cable stub at 23px compact WIRE, with zero strip geometry growth. +4. Existing #wireLayer is scoped to #viewport and MAIN is sibling #master. Use shared jack geometry coordinator with **two local overlay fragments** or a small parent-space overlay; read actual jack center rects, correct transform/scroll, clip to bay, keep pointer hit targets restricted to plug/socket. Do not use fixed pixels for x/y of MAIN or giant spanning path. +5. Refactor receiving socket gesture to include MAIN. Currently pointerdown ignores master in incomingWireEdges, while finish checks blankInBay only inside viewport. Resolve exactly one focused incoming edge by edgeId, give plug pointer capture and a >~10px deliberate drag threshold, same 22/24/31px snap zones as validated current WIRE, and accept detached end in a safe WIRE bay including MAIN strip. Escape/pointercancel/invalid release leaves topology+visual unchanged; drag back onto origin cancels. Commit on release only. +6. Drawing is projection of accepted graph; during drag it's a **transient visual candidate**. On GUI-only mock show simulated state explicitly in pre-existing status/footer (not new routing labels); native UI uses PENDING -> ACK -> matching accepted snapshot then committed cable. If ACK rejected, physically spring plug back and preserve accepted state. +7. Avoid idle RAF, DOM remount and geometry recalculation per pointermove; measure only on graph/layout/ResizeObserver/bank changes, use CSS transforms or affected SVG path update on active drag. Respect reduced motion, device pixel ratio and touch cancellation. One selected edge controls both visual fragments. + +**MAIN socket and channel selection:** every channel initially MAIN-connected. Selecting source CH1 makes MAIN jack editable for CH1 edge only. If no source focused, click MAIN may inspect incoming routes via existing Navigator; never disconnect all. Dragging an *already connected* source OUT into MAIN should select its edge, not silently toggle away. Disconnect/reconnect leaves unrelated CH->CH sends intact. For a source with no direct MAIN, its MAIN-colored channel stub is gone even if audio reaches MAIN indirectly via another universal channel. + +## G. Migration and compatibility + +Implement one import adapter for legacy reference wireEdges/track.output/sendSlots/track.input. Map active legacy Master outputs to a single MAIN edge, send slots to identified edges and input splits to typed source taps or explicit graph edge depending on semantics. Flag conflicting duplicates and ambiguous taps; DO NOT silently remove a user's saved audio routes. Use accepted revision to recompute strip OUT, WIRE, Matrix, Navigator, scenes and undo from same projection. Persist intentional disconnected MAIN on Show restore. + +Keep existing 10CH+4AUX/CH1 vendor VST3 and saved Show compatible until production ChannelId cutover is complete. Hide first-release +BUS/+FX Return *creation* via capability flags, do not delete their data/runtime implementation or break old sessions. Universal channel can become submix/reverb return through ordinary incoming wires and its own insert rack. Exact installed capability flags are truthful, not future-proof visual decoration. + +## H. Tests and independent proof + +**Graph unit/property/model tests:** fixed seeds + hundreds of deterministic randomized edit sequences, canonical edge invariants, topological sort, cycles after WIRE+legacy SEND, WIRE+OUT, WIRE+split, recall SAFE, copy/paste, duplicate S-o-F, MAIN multi-incoming, invalid/stale epoch, crossbank, repeated add/remove, Undo. Compare GUI projections after every accepted event; no collision by channel display name. + +**GUI Chromium/Playwright:** real rendered jack endpoints and paired stub anatomy across 1024/1366/1680/1920 widths, 768/900/1080 heights, Comfort/Standard/Compact, bank changes, 100%-150% scaling/zoom, collapsed WIRE, focus/unfocus, 0/1/N feeds, socket click/drag/replug/back/cancel/Escape, pointer capture/reduced motion; check selected edge binding and no fader/meter geometry regression. No fake audio proof. + +**Native PCM golden:** 44.1/48/96k when supported, 64/128/256/512 frames, 1/2/3+ hops vs direct impulse same relative sample index; fan-in and fan-out expected amplitude within a test tolerance; no double process on a channel; fader/post, mono/stereo, disconnect/reconnect, PDC warning; VST3 instance lease and Show state. Screen interaction/graph mutation must not hold audio callback. + +**Performance/reliability:** 16/32/64 admitted channels and multiple wires; source+FX densities, callback p50/p95/p99/max and deadline, xrun/capture discontinuity/output starvation distinguished, memory allocations, Windows native and UI frame time; target headroom under ~50% of callback period for supported reference normal workloads, long soak 60min 0FX/fullFX, physical loopback RTT vs reported latency. Document backend/device hardware; do NOT advertise 'faster/lighter than Waves LV1' without matched workload and environment. #15 0FX physical crackle unresolved and stop-ship regardless of CPU callback timing. + +**Release chain:** One actual C++ producer fixture -> #271 consumer -> #270 validator against existing v8 schema, same exact integrated Windows SHA and executable, actual PCM/ports and physical FAT. Passing docs/GUI screenshots means PLANNED, not IMPLEMENTED. + +## I. Original engineering references +- https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer.htm +- https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer_iorouting.htm +- https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer_trackprops.htm +- https://assets.wavescdn.com/user-guides/emotion-lv1-classic-console-user-guide.html +- https://docs.juce.com/master/classjuce_1_1AudioProcessorGraph.html +- https://steinbergmedia.github.io/vst3_doc/vstinterfaces/classSteinberg_1_1Vst_1_1IAudioProcessor.html +- https://steinbergmedia.github.io/vst3_doc/vstinterfaces/namespaceSteinberg_1_1Vst.html +- https://learn.microsoft.com/en-us/windows-hardware/drivers/audio/low-latency-audio From f17f112029ba3a4bebe08bc1472ec55f572d50b6 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 07:57:05 +0700 Subject: [PATCH 3/6] docs(handoff): assign GUI ENGINE FAT milestones and exact acceptance for WIRE-first release --- ...DOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md diff --git a/docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md b/docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md new file mode 100644 index 000000000..874d96caf --- /dev/null +++ b/docs/workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md @@ -0,0 +1,115 @@ +# 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.** + +## 0. Source-of-truth recovery procedure before ANY code edit +1. Read GitHub main SHA, issue #351 (GUI), issue #192 (native dynamic graph/ABI), issue #15 (0-FX physical crackle); inspect PR #266 ENGINE, #271 GUI, #270 FAT, #278 approved design, #352 WIRE direct controls, #360 V52 fader, #361 FX rail; latest checks and conflicts. This document sampled main **0215986fbbe2c67971680952f75f069950ac653e**, not a promise latest tomorrow. +2. Read approved checkpoint docs/CHECKPOINT_GUI_M1_WIRE_V48_BUTTONS_V23_20261103.md and current V51 meter checkpoint; do not edit accepted meter/fader CSS while PR #360 runs. +3. Discover existing code/tests; grep reusable functions before writing new code. Use *one writer per HTML/CSS owner*. #352 is draft/diverged; cherry-pick/reconcile only passing deltas onto fresh main, not blind force merge. +4. Work in meaningful integrated milestones below. Keep UI/ENGINE/FAT in owner PRs; use one controlled integration SHA, same native C++ fixture, no separate fake backend. +5. If GUI pages looks finished but native callback isn't installed, label it GUI SIMULATION. If native PCM can't be observed, label NOT INTEGRATED. No user UAT until coherent Windows product. + +## 1. Current repo and responsibility map (verified 2026-11-04) + +| Owner | Existing work / state | Paths and duties | +| --- | --- | --- | +| Reference GUI #351, #278, #352, #346/#347/#349 | Approved visual; direct cable/physics #352 draft, conflicts; #360 fader V52 draft | site/preview-v2/index.html, site/preview-v2/assets/mixer-wire-dots.css and current WIRE CSS owners; browser tests; NEVER overwrite V51 meters or V52 fader. | +| GUI NATIVE #271 | Draft, does not prove real WIRE to callback | web/**, generated standalone GUI, GUI producer-fixture consumption / snapshot+ACK / capability binding | +| ENGINE #266, issue #192 | Draft sole runtime owner; ChannelId prepared/offline, no full callback cutover, current live M4 10+4 AUX | src/**, engine/core/**, native VST3 lease / one callback / PCM / accepted graph, request handler | +| FAT #270 | Draft exact-SHA harness | contracts/** (coordinated), native fixture->GUI replay validator, CI/test/packaging / physical evidence | +| Physical audio blocker #15 | OPEN; crackling reported with **zero FX** | device/capture/render/discontinuity root cause, independent output/input/dry tests. Never infer audio clean from low callback CPU. | +| GUI FX #361 | Separate approved refinement task, not route owner | Preserve inline FX rack and native stable VST3 state; never replace FX with a router shortcut. | + +**Why this change:** legacy browser routing currently has four representations (wireEdges, track.output, sendSlots, input split) and no MAIN cable in wireDisplayRoutes; #wireLayer exists inside #viewport while #master is outside, master incoming drag is filtered, MAIN click/drop may be blocked. This is source-observed, not hypothetical. Do not fix by CSS fake wires alone. + +## 2. Release priority / non-goals +**P0:** one universal channel, valid physical/source patch, real VST3 inserts, user-flexible internal WIRE and default CH->MAIN. Can have CH1+CH2->CH5->MAIN, and CH1->CH6 (insert reverb) ->MAIN plus dry CH1->MAIN. A channel receiving WIRE and physical input sums the permitted sources correctly. **No separate BUS or FX DSP owner**. Dedicated +BUS/+FX RETURN creation and role-specific workflow **deferred** behind feature flags; do not delete legacy AUX/Show or block compatibility. Sidechain and multi-tap same source/destination future opt-in. +**UX:** no route badges, descriptions, boxes, decorative buttons, extra panels or full cross-console MAIN cable. Preserve very dense graphite visual and existing route controls. Only physical MAIN-colored hanging source stub plus matching upward main plug; accepted state shown physically. + +## 3. M1 — CANONICAL GUI REFERENCE, MAIN PLUG AND GUARDIAN (one meaningful GUI deliverable) +**Owner:** GUI reference #351/#352; coordinate HTML owner with FX #361 and fader #360. + +M1.1 — Normalize GUI to one state reducer: +- Define a typed channel/edge store (ChannelId/edgeId strings; mainId explicitly one of channels; POST_FADER default, gain, enabled). +- Derive WIRE svg, MAIN stub, channel OUT, navigator, matrix, plugged/unplugged socket state and route counts from ONE computed snapshot; remove independent mutations to track.output/sendSlots. A compatibility import with explicit duplicate/tap conflict resolution handles saved previews/scenes; no silent route deletion. +- Every existing action calls one reducer intent (add/remove/retarget edge, route-only batch, gain, selection). Selection/bank/drag may be transient; audio topology never changes from hover or view change. +- Add default MAIN edge for each newly created ordinary channel. Existing restored deliberate MAIN disconnections stay disconnected. Do NOT create two sends when source.output==Master and wireEdge already exists. +- Existing browser reference can run reducer locally but never label it LIVE. No WebAudio/audio engine in JS. + +M1.2 — Physical MAIN cable and socket interaction: +- Render per-connected-channel short MAIN-palette-colored sheath dropping from OUT into chassis, and pinned MAIN sheath rising from below into IN; paired stubs mirror same edgeId. One master socket sums N sources but gesture operates only chosen source edge. Existing color/material/shading and hardware plug artwork only. No full-span source->MAIN line, no text/status badges/cards. +- Fix current #viewport/#master sibling geometry with one measured coordinator and small overlays/painter, using actual DOM jack center rectangles; preserve bank geometry, scroll, collapsed 23px, pinned MAIN width and FX/fader regions. No absolute x guesses or extra padding panels. +- Integrate source->MAIN in canonical wireDisplayRoutes; main receiving socket in click and existing pointer capture and drag selection (currently master is skipped). Pull MAIN plug >~10px, physically follow cursor, release in valid empty WIRE bay disconnect selected edge; can drag plug back to MAIN IN; invalid/cancel/Escape restores; reconnect with magnetic snap. Do not confuse click with detach. No change to unrelated channel WIREs. Stable selected edge gain/mode/Undo. +- On no unique selected MAIN source do not disconnect all: use existing navigator/matrix selection. Click connected source OUT to MAIN again must not auto-disconnect due to drag-drop collision. +- One transient cable spring per gesture, obey reduced motion, no idle RAF or full DOM remount on pointermove. + +M1.3 — Guardian integration and adversarial GUI tests: +- One authoritative full-candidate DAG validator for every source of edges: WIRE, channel OUT, legacy send, old PRE-FX split, Send-on-Faders, Scene/SAFE and Copy/Paste. +- Cycle/duplicate/invalid/revision blocked before candidate commit. WARN dry reconvergence/high latency, DO NOT auto-change signal. Route-only is single atomic batch preserving unrelated sends. The existing demo-only route-choice UI should not be replaced by another modal forest. +- Fast tests should assert no duplicate route after source-WIRE then Send-on-Faders, no hidden sends, no cycle via each mixed path, no MAIN global disconnect, same snapshot across all editors, undo of exact accepted revision. +- Borrow 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_v50_wire_popout_layout_smoke.py; add dedicated MAIN/equivalence/graph-model/property tests. Fix tests when incorrect, never weaken a real regression to turn CI green. + +**M1 exit:** source HEAD + screenshot proof across 1024/1366/1680/1920 (Comfort/Standard/Compact, zoom 100-150%), one- and multi-edge MAIN plug interactivity, batch/cancel/Undo, no FX/rail/fader/meter drift, JS test suites and exact branch CI. This is GUI-only, no native PCM certification. + +## 4. M2 — ONE NATIVE WIRE GRAPH + ACTUAL VST3/PCM (engine + GUI slice, NOT a new engine) +**Owner ENGINE #266 and GUI native #271 using same v8 socket; FAT #270 validates concurrently.** + +M2.1 — Contract alignment: +- Before implementing WIRE op, inspect real C++ producer and existing ConsoleIntent operation inventory. Propose additive APPLY_WIRE_TRANSACTION for graph batch connect/remove/retarget and corresponding accepted edge inventory, using v8 schemaVersion=6 base envelope. Do not invent JS-only operation. Add supportedOps only after installed handler+callback. The 3 owners share exact producer fixture and validator; if old SET_PRIMARY_OUT/UPSERT_SEND can be safely adapted, centralize both in one graph transaction. +- Response ACK matches requestId+epoch+revision; GUI switches cable to committed only on matching snapshot, rejection restores physical plug exactly. Pending never presented as live sound. +- Native channel creation atomically starts with one edge to MAIN; physical input selection is distinct, deliberately source-only channels remain silent at MAIN. Channel IDs stay stable on reorder/bank/rename; edge IDs remain stable through retarget. Existing M4 and Show must not be lost. + +M2.2 — One engine callback: +- Reuse DynamicChannelRoster, DynamicPreparedMixerBlock, Native prepared PCM and RealtimeRoutePublisher, migrate CH1 special vendor lease/Orbit/FX state and existing CH2-10/4 AUX/Show BEFORE cutting over M4 (exact #266 owner mandate). +- Control thread compiles whole candidate DAG, topo schedule, preallocated buffer layout, mono/stereo conversion coefficients and latency metadata; callback executes in single device period, zero per-hop FIFO/worker, no allocations/locks/UI, only bounded atomics and prepared VST chain. No force-close or recreate VST3 editor simply because routing changed. +- Direct and nested 1/2/3-hop paths show identical onset sample at 0FX/0-plugin latency; fan-in/fan-out amplitudes agree with reference. MAIN source disconnected does not remove indirect CH->CH->MAIN audio. Safe param smoothing and graph handoff preserve audio (no unexpected global mute). +- Plugin PDC getLatencySamples and kLatencyChanged processed off audio thread. Live latency budget explicit; parallel reconvergence warns on unaligned latency; don't claim perfect time alignment if not implemented. +- Device epoch, output ownership and ARM safe; physical port labels from backend, no phantom stereo or invented device. + +M2.3 — Native GUI projection: +- Native web/** consumes same accepted edges; preserve compact approved channel controls; no parallel track.output graph or simulated meters. Same WIRE and MAIN drag intentions render exact state from real snapshot. If operation unsupported, use honest disabled physical capability, not decorative pretending to process audio. +- Real VST3 on *different* channels, open native editors, save vendor state and reload. GUI-only plugin manager metadata never qualifies as native scan. + +**M2 exit:** end-to-end Windows callback and GUI at one integrated commit: verified physical input->CH07->MAIN, two independently FX-processed channels, CH1->CH3->MAIN chain, CH1 direct MAIN disconnect/reconnect while CH3 indirect path persists, simultaneous fan-in/fan-out, 1 click/drag controls, true native PCM and meter, Show restored. No CH11 claim unless independent accepted native channel actually works. + +## 5. M3 — PERFORMANCE / FAT / RELEASE GATE +**Owner FAT #270, ENG #266 and GUI #271 fix failing defects in their lanes.** + +- Run actual native-generated fixture -> GUI consumer -> contract validation; no hand-crafted incompatible mock. Validate accepted snapshots and rejected stale intents. Package one exact-SHA signed/provenance Windows build. +- 0FX physical isolation #15: output-only test tone, capture-only counters, dry-through; compare same ASIO device vs WASAPI shared/exclusive and virtual/BT endpoints. Capture/output driver clocks, samples/period, discontinuities, *real* output starvation when detectable, drift, buffer behavior. Callback gap alone != proven xrun. Root-cause and retest rather than hiding crackle via buffer enlargement without disclosed latency consequence. +- Matrix profiles: 44.1/48/96k where supported; buffer 64/128/256/512; one pin MONO/independent L-R; 16/32/64 admitted channels; 0/2/N VST3; direct/nested/parallel route; one-hour dry and full-FX, rapid route edits/undo/Show and forced plugin/driver faults. Record CPU p50/p95/p99/max callback time as fraction of period, xruns, memory, true loopback latency and UI responsiveness. First headroom target below 50% of period for typical supported normal-load case, NOT false LV1 comparison. +- No user UAT until product-complete internal package and repeatable audio qualification; if no physical rig, mark FAT PENDING and stop release claim. Separate Windows/Chromium-green does not suffice. #15 remains hard blocker. + +## 6. Agent acceptance / restart ledger (each owner posts one meaningful milestone) +Each completion report should contain: +- Owner and exact PR branch/HEAD, affected files, current integration SHA, base SHA. +- Contract schema version + **C++ native-produced fixture hash** and supportedOps, exact command and actual result. +- Concrete operator journey now *audibly* supported (or GUI SIMULATION / NOT INTEGRATED); 0FX/loopback hardware state. +- Failures with reproduction and root cause, one corrective action in owning lane; no percentages, vanity progress, screenshots called PCM, unknown future work. +- Single next integrated vertical-slice acceptance condition. + +**Preflight commands to discover/execute, only when actually supported on working tree:** +~~~bash +node scripts/check_console_puzzle.mjs +node scripts/check_console_puzzle.mjs --release +node --test tests/live_graph_contract_test.mjs +node --test tests/live_routing_ui_contract_test.mjs +python tests/pages_wire_v49_direct_controls_smoke.py +python tests/preview_v15_drag_wire_smoke.py +# native build/CTest/Playwright + Windows physical test according to existing CMake/CI owner; +# never claim these passed without an actual run on exact SHA. +~~~ + +**Do not waste time:** no parallel new graph builders, no generic rewrite to AudioProcessorGraph without demonstrated need, no callback-scanning watchdog, no extra CSS overrides, no handcrafted demo plugin/PCM, no new planning-issue proliferation, no premature full-PDC engine if user wants first sound. Solve the GUI-visible MAIN patch and full audio graph in meaningful integrated milestones. Keep FX Rack and visuals loved by operator. + +## 7. References and issue links +- [PRD WIRE](../PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md), [ARD WIRE](../ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md) +- [Master GUI execution #351](https://github.com/masarray/arsonmix/issues/351), [native scope #192](https://github.com/masarray/arsonmix/issues/192), [physical crackle #15](https://github.com/masarray/arsonmix/issues/15) +- [ENGINE #266](https://github.com/masarray/arsonmix/pull/266), [NATIVE GUI #271](https://github.com/masarray/arsonmix/pull/271), [FAT #270](https://github.com/masarray/arsonmix/pull/270) +- [approved design #278](https://github.com/masarray/arsonmix/pull/278), [WIRE #352](https://github.com/masarray/arsonmix/pull/352), [fader #360](https://github.com/masarray/arsonmix/pull/360), [FX/rail #361](https://github.com/masarray/arsonmix/issues/361) +- FL routing: https://www.image-line.com/fl-studio-learning/fl-studio-online-manual/html/mixer_iorouting.htm +- Waves latency mode: https://assets.wavescdn.com/user-guides/emotion-lv1-classic-console-user-guide.html +- JUCE graph: https://docs.juce.com/master/classjuce_1_1AudioProcessorGraph.html +- Steinberg latency changes: https://steinbergmedia.github.io/vst3_doc/vstinterfaces/namespaceSteinberg_1_1Vst.html + +**END TARGET:** ONE finished native Windows mixer, one low-latency callback, user-flexible SAFE WIRE graph, physically intuitive MAIN cable, exact engine acknowledgment and real audio. This packet doesn't certify it exists today. From e8b818328280fc985b4b0d50192ad10295966950 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 07:57:39 +0700 Subject: [PATCH 4/6] docs: link WIRE-first release priority without rewriting legacy design contracts --- AGENTS.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 7c9dc2588..f67826f36 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,5 @@ +> **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. > **USER APPROVED CONSOLE DESIGN LOCK (2026-11-01):** Normative [PRD v5.2 §9](docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md#9-normative-v52-product-design-lock--user-approved-pr-278-mixer-workflow) + [ARD v5.2 §K](docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md#k-normative-v52-design-to-native-execution-contract--pr-278-reference). [PR #278](https://github.com/masarray/arsonmix/pull/278) at `design-references/audition-mixer-study/index.html` is the **owner-selected one-Console geometry/workflow NORTH STAR**. GUI #271 must reproduce its dense direct IN/OUT→FX→SEND→EQ/TRIM/PAN→MUTE/SOLO→FADER/METER workflow using native snapshot/ACK; ENGINE #266 supplies real operations; FAT #270 tests it on one actual Windows build. Strip out DAW automation/record, mock meters/FX, fake pins. Distinguish LINK FADERS from DSP GROUP BUS. This UX decision overrides older workbench, multi-tab setup and modal-first interpretations; v8 ABI and realtime safety remain inviolable. No alternate design study or customer partial UAT. From 318a5987d10a275455841fc63a390bb3ac0777da Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 07:57:43 +0700 Subject: [PATCH 5/6] docs: link WIRE-first release priority without rewriting legacy design contracts --- docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md b/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md index 8c2443966..262588cb0 100644 --- a/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md +++ b/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md @@ -1,3 +1,5 @@ +> **2026-11-04 NORMATIVE WIRE-FIRST RELEASE PRIORITY OVERRIDE (approved user direction):** Before executing the older dedicated Group Bus and FX Return first-release flows below, read [PRD WIRE-FIRST](PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md), [ARD WIRE-FIRST](ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md) and [execution handoff](workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md). First release: flexible FL-like WIRE universal-channel routing, physically beautiful MAIN-colored default connected paired cable stubs and real MAIN socket unplug/replug, Guardian, single accepted graph, native PCM and VST3. **Defer dedicated +BUS/+FX RETURN creation/workflow** to next development while preserving all existing compatible AUX and Show code and native VST3 inserts; universal channels can still become submix/FX return via incoming WIRE. No new UI badges/cards/CTA or approved geometry changes. Original v8 native socket, safety, one-callback and exact-SHA release gates below remain binding. This note is release-priority precedence, NOT a claim of shipped functionality. + # ArSonMix PRD v5.2 — Operator-First Live Mixer Console Date: 2026-11-01 | Updated: 2026-11-01, user-approved PR #278 one-console design lock (v5.2) | Status: **NORMATIVE PRODUCT TARGET, NOT SHIPPED FEATURE ATTESTATION** | Supersedes the workflow and priorities in PRD v4.1. Companion: [ARD v5.2](ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md). From 706e679a036c2fd3e7ee4d314959dd458e66f72c Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Wed, 4 Nov 2026 07:57:46 +0700 Subject: [PATCH 6/6] docs: link WIRE-first release priority without rewriting legacy design contracts --- docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md b/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md index 151817520..c1ada1dbb 100644 --- a/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md +++ b/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md @@ -1,3 +1,5 @@ +> **2026-11-04 NORMATIVE WIRE-FIRST ARCHITECTURE OVERLAY:** Read [ARD WIRE-FIRST](ARD_WIRE_FIRST_ZERO_ADDED_LATENCY_20261104.md), [PRD WIRE-FIRST](PRD_WIRE_FIRST_LIVE_ROUTING_20261104.md) and [execution handoff](workstreams/HANDOFF_WIRE_FIRST_GUI_ENGINE_FAT_20261104.md) for latest user-approved release scope: canonical internal ChannelId/EdgeId WIRE graph (including every default CH->MAIN edge), MAIN-colored short physical cable fragments, focused MAIN jack unplug/replug, event-driven Guardian, zero *additional* samples for pure internal routes, no dedicated BUS/FX Return first-release UI. Preserve existing FX insert/Show/AUX state and all realtime safety. Current v8 schemaVersion=6, genuine C++ fixture/ACK, engine #266, native GUI #271 and FAT #270 remain the mandatory contract. Older Group/FX-specific feature targets below are deferred, not deleted or proof of implementation. + # ArSonMix ARD v5.2 — Universal Realtime Mixer Graph + Operator-First Console Date: 2026-11-01 | Updated: 2026-11-01, user-approved PR #278 one-console design lock (v5.2) | Status: **BINDING ARCHITECTURE TARGET (not a claim of implemented online graph)** | Companion: [PRD v5.2](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md). Supersedes workflow/implementation ordering in ARD v4.1 while preserving safety, signal-processing and accepted GUI baseline.