From d048201affd19406c6ad728c85b56b99f8735ca7 Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Sun, 1 Nov 2026 12:57:14 +0700 Subject: [PATCH] docs(product): lock PRD/ARD v5.2 to user-approved PR #278 one-console mixer UX --- AGENTS.md | 2 + ..._UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md | 53 +++++++++++++++++-- ...X_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md | 45 +++++++++++++++- ...PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md | 2 + docs/workstreams/ENGINE_PUZZLE_V8.md | 2 + docs/workstreams/FAT_PUZZLE_V8.md | 2 + docs/workstreams/GUI_PUZZLE_V8.md | 2 + 7 files changed, 103 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index dc8aa9a2c..82ebae383 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,3 +1,5 @@ +> **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. + > **MANDATORY CURRENT AUTHORITIES — 2026-11-01:** [Product PRD v5.1](docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md#8-mandatory-v51-product-delivery-amendment--puzzle-socket-v8), [Architecture ARD v5.1](docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md#j-mandatory-v51-abi-and-module-boundary-amendment--puzzle-socket-v8), [shared puzzle socket v8](docs/PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md), [machine-required fields](contracts/console-puzzle-v8.json), and binding owner packets [ENGINE #266](docs/workstreams/ENGINE_PUZZLE_V8.md), [GUI #271](docs/workstreams/GUI_PUZZLE_V8.md), [INTEGRATION #270](docs/workstreams/FAT_PUZZLE_V8.md). **This v8 override supersedes historical v6/v7 priority/sequence**, preserves realtime safety, and bans three separately green PRs from being called one mixer. A real native-producer fixture, same-schema consumer, exact combined SHA and internal QA are required. Review/CI fail-closed; no user UAT until feature-complete S3. > **ACTIVE RELEASE ORCHESTRATION v7 (2026-11-01):** [ONE PRODUCT RELEASE TRAIN](docs/RELEASE_TRAIN_UNIVERSAL_CONSOLE_V7_20261101.md) and owner packets [ENGINE](docs/workstreams/ENGINE_DELIVERY_V7.md), [GUI](docs/workstreams/GUI_DELIVERY_V7.md), [INTEGRATION/RELEASE](docs/workstreams/INTEGRATION_RELEASE_DELIVERY_V7.md). Complete one real feature-parity Windows mixer BEFORE requesting owner/customer UAT. PRD/ARD v5 remain normative product/architecture; v7 supersedes older v6 delivery sequencing, not v6 realtime safety. #274/#275 are GUI patch sources and #276 is partial staging, not a final user build. diff --git a/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md b/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md index 120d148ef..151817520 100644 --- a/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md +++ b/docs/ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md @@ -1,5 +1,5 @@ -# ArSonMix ARD v5.1 — Universal Realtime Mixer Graph + Operator-First Console -Date: 2026-11-01 | Updated: 2026-11-01, mandatory puzzle-socket ABI amendment | Status: **BINDING ARCHITECTURE TARGET (not a claim of implemented online graph)** | Companion: [PRD v5](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. +# 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. ## A. Source-grounded audit and non-negotiable direction @@ -150,7 +150,7 @@ Prove safe online graph handoff for add/reorder VST, Group/FX send, and format c - Typed graph/compiler: engine/core/DynamicChannelRoster.h, DynamicPreparedMixerBlock.h, DynamicNativeSessionPublisher.h, LiveChannelFxGraph.h, PreparedMixerBlock.h, NativeDryRouteCommand.h; migrate, not duplicate. - Native Show and FX leases: src/NativeShowSchema.h and current native plugin registry/editor code; replace CH1-specific ownership incrementally. - GUI: web/app.js, web/mixer-io.js, web/monitor.js, web/bridge.js, web/mixer-layout.js; source-owned web/styles-src, scripts/build_ui_css.py, offline standalone. -- Engineering baseline: [ADR R5](ADR_R5_NATIVE_MONO_STEREO_CHANNEL_BUS_ROUTING_20261030.md), [PRD v5](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md), [current code ledger](RECONCILED_PROGRESS_ARSONMIX_20261101.md), [issue #192](https://github.com/masarray/arsonmix/issues/192), [hardware #15](https://github.com/masarray/arsonmix/issues/15). +- Engineering baseline: [ADR R5](ADR_R5_NATIVE_MONO_STEREO_CHANNEL_BUS_ROUTING_20261030.md), [PRD v5.2](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md), [current code ledger](RECONCILED_PROGRESS_ARSONMIX_20261101.md), [issue #192](https://github.com/masarray/arsonmix/issues/192), [hardware #15](https://github.com/masarray/arsonmix/issues/15). - Functional evidence (not internal algorithms): https://fenderstudiopromanual.fender.com/en/Content/Mixing_Topics/Effects_Signal_Routing.htm ; https://fenderstudiopromanual.fender.com/en/Content/Recording_Topics/Audio_Tracks.htm ; https://assets.wavescdn.com/user-guides/emotion-lv1-classic-console-user-guide.html ; https://helpx.adobe.com/audition/desktop/mixing-multitrack-sessions/multitrack-routing-eq-controls.html . ## J. MANDATORY V5.1 ABI AND MODULE-BOUNDARY AMENDMENT — PUZZLE SOCKET V8 @@ -187,3 +187,50 @@ Events: \`arMixConsoleSubscribe\`, \`arMixConsoleSnapshot\`, \`arMixConsoleInten Canonical machine inventory lives in \`contracts/console-puzzle-v8.json\`. Executable seam validator from PR #279 (once merged) is \`node scripts/check_console_puzzle.mjs\` for cheap G0 tests and \`node scripts/check_console_puzzle.mjs --release\` for fail-closed integrated-source preflight. A PASS proves **only schema/source compatibility**, not audible sound; require Windows native/Playwright/physical QA separately. Never weaken tests to hide missing native operations. No independent PR may redefine a field, operation enum, status or channel ID format. Changes to socket need an issue #192 diff, updated ENGINE-produced fixture, GUI consumer and FAT checker in one integration checkpoint. File owners do not write another lane's business logic. Incompatible changes are merged into a controlled integration branch and rejected until all three puzzle pieces pass the same fixture. Avoid CI waste: targeted tests before push, full workflow only for integrated slices. User is not the debugger for incomplete builds. + + +## K. NORMATIVE V5.2 DESIGN-TO-NATIVE EXECUTION CONTRACT — PR #278 REFERENCE + +**2026-11-01; PRECEDENCE:** [PRD v5.2 §9](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) design lock is the authoritative operator-facing architecture decision: **user-approved PR #278 Adobe Audition Mixer-style one-Console screen** + Studio One fast workflows. The v8 schemaVersion **remains 6**, the v8 puzzle contract stays the shared transport; this §K overrides old workbench/modal workflow assumptions and does NOT relax core realtime/rollback/lease guarantees. The design study \`design-references/audition-mixer-study/index.html\` is deliberately separated from production and contains simulated meter and plugin implementations; **never copy the demo as DSP**. + +### K1. Rendering/ownership boundaries +- Single **JUCE native audio callback** supplies PCM. Engine #266 alone owns immutable accepted ChannelId graph, device pin inventory, actual VST3 scan/lease/editor, physical outputs, mixer routing, Show and true PCM meters. +- **GUI #271** maps PR #278 strip geometry and interaction layout to *read-only* native \`ConsoleSnapshot\` projection and sends \`ConsoleIntent\`. It may maintain transient focus, selection, bank, drawer state but may not create accepted channels/ports/plugin instances or update output claims optimistically. One accepted state source, no permanent parallel M4/HTML simulator audio routing path. +- **FAT #270** owns one executable operator workflow matrix that drives real produced fixtures and actual callback PCM, verifies native ACK→snapshot→meter and packages an exact SHA Windows build. #278 standalone smoke only certifies visual reference behavior; it never certifies native host. + +**UI render strategy:** DOM structure stable under meter/hover/fader drag, targeted property updates with bounded meter rate, no full \`innerHTML\` list rerender at PCM meter frequency; original lightweight fader art, scalable narrow mode, pinned MAIN and compact top/section rail. Preserve existing live plugin editors. Treat device drawer as infrequent configuration UI; operator keeps mixing in the single Console. Copy settings excludes physical I/O by default. + +### K2. Contract mapping — every approved visible action has a native operation or a clear UI-only concern +The canonical intent envelope remains \`{requestId,deviceEpoch,baseGraphRevision,baseRosterRevision,operation,targetChannelId,payload}\` with string uint64 IDs, same-epoch ACK and accepted snapshot. **Operation names below are target capabilities for coordinated implementation**, NOT claims that existing ENGINE handles them. Add missing operations via the native canonical versioned contract and update GUI/FAT together; never invent an undocumented browser alias. \`supportedOps\` becomes true only when the installed callback or control thread performs the operation. + +| PR #278 surface | Native ownership / contract (target) | UX action and readback | +| --- | --- | --- | +| DEVICE drawer (ASIO/WASAPI, pins/buffer) | Enumerate verified \`device.*\`; guarded separate \`SET_DEVICE\`/clock transaction | Choose once, explicit re-open warning only for real device change | +| IN selector, M/ST processing | \`SET_SOURCE\`, \`SET_PROCESSING_FORMAT\`; real source endpoint and channel fields | One gesture→request→ACK→fresh same-revision snapshot; no invented IN2 | +| OUT selector | \`SET_PRIMARY_OUT\`; actual allowed Group/MAIN/output endpoints | Direct strip OUT without extra matrix; no feedback cycle/double dry | +| Fader, Pan, Trim, Mute, Solo | \`SET_FADER\`, \`SET_PAN\`, \`SET_TRIM\`, \`SET_MUTE\`, \`SET_SOLO\` | RT-bounded atomics or smoothing, no global mute/restart; pan center snap in GUI | +| FX slots, native Plugin Manager | \`LIST_PLUGINS\` query, \`LOAD_FX\`, \`REMOVE_FX\`, \`BYPASS_FX\`, \`REORDER_FX\`, \`OPEN_FX_EDITOR\` | Real vendor VST3 instance & editor, off-callback lease, accepted rack | +| Send slot, PRE/POST, target/level/pan | \`UPSERT_SEND\`, \`SET_SEND_TAP\`, \`SET_SEND_LEVEL\`, \`SET_SEND_PAN\`, \`REMOVE_SEND\` | Native PRE/POST wet flow and legal targets; native max sends determines slots | +| + Audio, + Bus, + FX Return | \`CREATE_CHANNEL\`, \`CREATE_GROUP_BUS\`, \`CREATE_FX_RETURN\` | Stable ChannelId and truly audible role, never browser-only \`tracks.push\` | +| Channel **LINK FADERS** | \`SET_LINK_GROUP\` (control grouping; separate from summing) | Relative faders and optional linked mute/solo with safe undo | +| Route selected to **GROUP BUS** | \`ROUTE_SELECTED_TO_GROUP\` or a checked batch \`SET_PRIMARY_OUT\` | Serial summing PCM, only one primary dry route | +| Sends on Faders | UI presentation mode targeting existing native send ops | Only send gains move, channel primary faders preserved | +| Solo/Role filter, banks, Narrow, rename | UI selection/display; rename via \`RENAME_CHANNEL\` | No unsolicited changes to DSP or physical I/O | +| Scene, Show, Safe | \`SAVE_SHOW\`, \`RECALL_SHOW\`, \`SET_SCENE_SAFE\` | Native stable IDs, vendor chunks and device remap/rollback | +| Cue/PFL / Monitor | \`SET_CUE\`, \`SET_MONITOR_OUTPUT\` with verified legal endpoints | Real independent monitor PCM/output or honestly disabled | +| Meters/clip | Native \`telemetry.*\` including actual channel/master L/R/clip | Fixed green/yellow/red reference ladder, no fake waveform/random levels | + +**Semantic corrections relative to #278 demo:** Its "Group" UI is a relative **fader link**, not a summing bus. Its 16 sends are a visual capacity test, not proof of 16 simultaneous native sends; show up to admitted capability, with 4 legacy AUX remaining until expanded. Its FX plugin metadata and meter are mocks; do not import static fake device port labels. Remove DAW automation row, READ/WRITE/TOUCH, record and transport controls (unless there is a *genuine live-specific* need separately approved). Show/Scene remains. A generic output-ARM ACK is not proof acoustic output exists. + +### K3. Graph/control safety and low latency +- Realtime callback never allocates, locks, scans plugins, opens editors, performs JSON or invokes GUI; structural edits prepare/wire immutable graph with native actor on control thread and publish atomically at safe boundary. Old accepted sound survives validation failure, stale revisions, invalid pin, driver loss or rejected plugin. +- Continuous fader/pan/mute/send controls must use lock-free bounded parameter plane; do not reboot driver or globally mute just to change mixer value. For structural input or FX transactions, perform native admission/ACK with a bounded transition/crossfade where technically viable and prove no audible click; never require the user to manipulate staging and APPLY. +- Stereo capture requires two distinct active source pins; mono capture can feed stereo *processing* but cannot claim two physical input channels. Report actual driver/buffer/VST reported latency and available output pins. Asynchronous WASAPI secondary monitor cannot pull or slow the primary ASIO callback; independently rate-convert/buffer/best-effort where supported. + +### K4. Cross-thread acceptance gates tied to actual PR #278 workflow +- **S0 interface**: GUI #271 maps each relevant #278 control to exact \`supportedOps\` and emitted native-produced snapshot field; ENGINE #266 publishes verified field/operation inventory; FAT #270 runs consumer tests against the same source fixture hash. Missing operator capability means an explicit ENGINE blocker, not UI-guessing. +- **S1 first live path**: user action on PR #278-style strip IN1→CH07→MAIN, native ACK and RAW→CH→MAIN PCM without mandatory multi-step setup; correct single-pin Mono, fader/pan/mute. Actual production callback retains full occupied M4 CH1/vendor/Orbit and Show. +- **S2 full live mixer**: independent two channels+VST3, native Plugin Manager/editor, dynamic CH11, fader LINK vs real summing Group distinction, FX Return wet PRE/POST, Monitor/Cue, Scenes/Show; one full combined operator acceptance test with true PCM and no double-dry. +- **S3 release**: one source SHA, native Windows CTest, GUI Playwright visual/operator journey at 1024/1366/1680, generated HTML parity and low-end PC responsiveness; independent engineer physical 0FX/multichannel crackle FAT where available. **No user hardware UAT before internally coherent full Console**; acoustic FAT pending if no rig. + +**STOP-SHIP:** An engineer cannot declare completeness by green offline graph, green browser-only #278 demo, filled-in UI controls, synthetic plugin scanning, blank \`supportedOps\`, fixed-ten legacy path masked as universal, or separate owner branch CI. The integrated app must fulfill PRD §9 in one Windows EXE. 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 f934cbc58..8c2443966 100644 --- a/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md +++ b/docs/PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md @@ -1,5 +1,5 @@ -# ArSonMix PRD v5.1 — Operator-First Live Mixer Console -Date: 2026-11-01 | Updated: 2026-11-01, mandatory puzzle-socket delivery amendment | Status: **NORMATIVE PRODUCT TARGET, NOT SHIPPED FEATURE ATTESTATION** | Supersedes the workflow and priorities in PRD v4.1. Companion: [ARD v5.0](ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md). +# 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). ## 1. Product promise and non-goals @@ -139,3 +139,44 @@ All features below must coexist in one app and one verified integrated SHA: Each owner must produce a **Puzzle Handoff** on [epic #192](https://github.com/masarray/arsonmix/issues/192): source SHA and changed files, one shared fixture version/hash, real operation supported by the installed callback or explicit NOT CONNECTED, tests at that SHA, cross-owner blocker and its corrective code change. A standalone green CI, offline Group or browser screenshot is not accepted as milestone completion. **Exit sequence:** S0 same producer fixture + consumer + validator → S1 actual native callback one-input/direct-console complete sound path → S2 complete two-VST3/dynamic/Group/Return/Monitor/Show mixer → S3 one exact-SHA Windows/Chromium/package, independent hardware qualification or explicit PENDING → only then user UAT. Do not reduce scope or skip a failed gate for speed. + + +## 9. NORMATIVE V5.2 PRODUCT DESIGN LOCK — USER-APPROVED PR #278 MIXER WORKFLOW + +**Approved 2026-11-01; precedence:** This §9 overrides any older GUI navigation/layout defaults in this PRD, v7, v8 handoffs or legacy M4 workbench. **The user explicitly selected [PR #278](https://github.com/masarray/arsonmix/pull/278), \`design-references/audition-mixer-study/index.html\` at its reviewed design-study baseline, as the correct visual and workflow direction.** This is the primary product design reference; the source remains isolated as an interactive browser study and **does not produce audio**. Adopt its **geometry, visual hierarchy, and fast interactions**, not its simulated audio, dummy device labels, fake plugin instances, or DOM full-rebuild implementation. No competing GUI concept or fresh redesign without explicit owner decision. [ARD v5.2 §K](ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) specifies the engineering realization. + +### P9.1. Product identity: DAW-grade mixer experience, NOT a DAW editor +ArSonMix is a **native realtime virtual digital mixer** (karaoke, stage, podcast, radio, livestream) with **Adobe Audition Multitrack MIXER as the primary single-window interaction/geometric reference** and Studio One/Fender Studio Pro Console as secondary **productivity** patterns (narrow strips, channel banks, multi-selection, copy/paste, groups, scenes and flexible plugin operations). eMotion LV1 informs live cue/sends/banking and operational reliability. No timeline, waveform editing, song sequencer, READ/WRITE/TOUCH automation lanes, MIDI arranger or DAW transport/record-arm workflow. In #278, remove \`auto-section\` as DAW automation; **input TRIM remains useful**. Do not copy copyrighted app assets or misleading OEM labels. + +### P9.2. Exact operator homepage and strip anatomy +**On launch the main window IS the live Mixer Console**, not Audio Setup, signal-flow editor or an engineering workbench. One uninterrupted horizontal strip surface, compact title/action bar and a small collapsible section rail. Each strip aligns in consistent horizontal bands across channels (top→bottom): +1. **IN and OUT directly selectable on every eligible strip**, actual ASIO/WASAPI capture/render pins and native Bus roles; format M/ST is a separate adjacent processing-width choice where supported. +2. **VST3 insert rack:** ordered, real slots with enable/bypass, drag-reorder, click slot→search/add effect, double-click/open editor, safe add/remove; no detached FX-workspace prerequisite. +3. **SENDS:** actual available slots, destination, PRE/POST, enabled state and send level/pan; Sends-on-Faders for fast monitor/FX mixes. #278's 16-slot demonstration is a UX scalability reference, NOT permission to advertise 16 working sends when native has only four. +4. **EQ/trim and PAN:** compact EQ access to actual plugin/native EQ only, digital gain trim, pan center snap with a bipolar track filled from center toward L/R (not a left-origin fill). +5. **MUTE/SOLO/CUE controls**, native safety semantics and no recording/DAW automation toggles. +6. **FADER and real fixed-color L/R LED peak meters:** green→yellow→red thresholds stay in place; only segments reached by actual PCM light up, clipping latches appropriately. No simulated/animated random meter in production. +7. **Channel name, role/color and selection** at footer. Always **pin MASTER/MAIN** on right and keep a consistent visible signal path. Input, Bus, FX Return, Monitor and MAIN remain semantically distinct native roles; no CH10 relabel trick. + +Horizontal banking, Narrow mode, filter by channel role/solo, collapsible rail, Ctrl/Shift multi-select, inline rename and Ctrl+C/Ctrl+V settings copy must be available as in #278. Copy/paste never silently reassigns physical I/O, driver ownership, or hardware device selection. Avoid excessive modal layering, 10-row patch wizard, mandatory Software Input alias creation, repeated STAGE→MUTE→APPLY→ARM and three separate FX/ROUTE/SENDS workspaces for common use. Expert matrix may exist under a deliberately optional **Advanced Routing** surface; device choice is ONE compact drawer. + +### P9.3. The immediate live-audio interaction contract +User flow MUST be: launch → select real audio interface/device ONCE → choose \`IN1\` directly on CH07 (one gesture) → actual capture signal on native channel meter → fader/VST3/Send edits with immediate audible low-latency effect → choose legal output on MAIN/monitor. No full device stop/reopen or global mute for routine fader, pan, FX bypass or safe channel source changes; structural plugin/graph mutations may internally prepare/swap and ACK. UI does not show technical revision numbers as a user task. Playback/capture availability and PCM are distinct truth states; no fake stereo pin pair on a one-pin device; VB-Cable capture remains silent unless fed by the playback side of that cable. Latency is physically nonzero depending on driver/buffers/plugin chain; aim for minimum safe realtime roundtrip, don't claim literal zero ms. + +### P9.4. Menu/feature semantics that cannot be conflated +- **\`LINK FADERS\`** (relative level + optional linked mute/solo across selected channels) is a control group. It is NOT a DSP summing Group Bus. \`ROUTE TO GROUP BUS\` creates/chooses a native **serial Group Bus**, with exactly one primary dry path onward to MAIN. Both controls must be named/behave distinctly. +- **\`FX RETURN\`** is a native parallel wet receive path; bus and send cycles rejected. Source sends PRE/POST with correct gain/pan, no doubled dry. +- **\`SCENE / SHOW\`** stores/restores real native accepted mixer state and VST3 vendor chunks; optional Scene Safe protects live targets. Demo state-only Scene Save is unacceptable. +- **\`PLUGIN MANAGER (F8)\`** searches native scanned/validated VST3 catalog with category, vendor, favorites/recent/hidden and real load/editor/bypass/reorder. Demo JSON/import and dummy plugin list are not production functionality; scanner/errors never block realtime audio callback. +- **\`CUE/PFL / MONITOR\`** requires real separate monitor DSP/output support before enabling, no demo-only illuminated buttons. No fake arming/record functions from a DAW. + +### P9.5. Non-negotiable operator acceptance journeys +1. From ONE Console select device, direct \`CH07 IN1\` and MAIN output without modal setup workflow; on one-pin interface see \`IN1 MONO\` only. +2. Select \`CH02 IN2\` independently where real pin 2 exists; load/bypass/reorder two genuine VST3 effects while audio remains continuous and corresponding native meters respond. +3. Multi-select channels, **LINK FADERS** with relative changes; separately create **Group Bus**, route selected primary outputs to bus→MAIN and verify no duplicate dry. Add true FX Return and POST/PRE sends in parallel. +4. Find/install/select plugin from native Plugin Manager, open actual vendor editor; switch narrow/filters/banks without losing pinned MASTER or mutating DSP. +5. Save/recall actual Scene/Show with stable ChannelIds; use Cue/PFL/Monitor if backend supports real legal endpoint; input/device fault shows clear no-PCM status, not false LIVE. +6. Verify all controls in actual packaged Windows WebView2 build (not just the #278 HTML demo), 1024×600, 1366×768, 1680×900 and standard iGPU; no heavy blur, glow, hover-triggered full DOM rerender, jitter or excessive large fonts/cards. +7. FAT validates one exact combined engine+GUI+test SHA and independent hardware evidence when available; if not, mark acoustic QA PENDING without passing certification. User UAT only after feature-complete integrated candidate. + +**Priority enforcement:** When UX conflicts arise, this user-approved #278 workflow wins for operator interaction. ARD RT/thread safety, physical truth, plugin lease ownership, ChannelId semantics, accepted native ACK, and sound integrity remain inviolable. ENGINE #266 serves the controls; GUI #271 implements the production screen in \`web/**\`; INTEGRATION #270 tests the operator journey. No parallel standalone UI as another release product. diff --git a/docs/PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md b/docs/PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md index e76721dd1..cf83e6a01 100644 --- a/docs/PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md +++ b/docs/PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md @@ -1,3 +1,5 @@ +> **PR #278 USER UX DESIGN AUTHORITY:** [PRD v5.2 §9](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) + [ARD v5.2 §K](ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) lock the selected single Audition-style live Console, direct I/O, FX/sends/fader and pinned MASTER. This v8 document governs software socket and realtime constraints, but may not reintroduce multi-stage patch wizard, legacy multi-workspace main UX or blur the difference between LINK FADERS and native GROUP BUS. UI owner #271 implements actual native controls, #266 publishes native operations, #270 proves combined audio/GUI. No demo DSP masquerading as live. + > **NORMATIVE UPDATE:** Read [PRD v5.1 §8](PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md), [ARD v5.1 §J](ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) and specific owner packets [ENGINE](workstreams/ENGINE_PUZZLE_V8.md), [GUI](workstreams/GUI_PUZZLE_V8.md), [FAT](workstreams/FAT_PUZZLE_V8.md). The v8 machine contract describes required fields, but no hand-authored synthetic fixture can substitute a real native C++ snapshot. PR #279 adds cheap and strict fail-closed preflight; it is not physical sound certification. # ArSonMix V8 — Puzzle Contract / Three Independent Modules, One Product diff --git a/docs/workstreams/ENGINE_PUZZLE_V8.md b/docs/workstreams/ENGINE_PUZZLE_V8.md index 84d649442..ae608a9e8 100644 --- a/docs/workstreams/ENGINE_PUZZLE_V8.md +++ b/docs/workstreams/ENGINE_PUZZLE_V8.md @@ -1,3 +1,5 @@ +> **MANDATORY UX SPECIFICATION AMENDMENT:** [PRD v5.2 §9](../PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) and [ARD v5.2 §K](../ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) require native operations serving the owner-approved [PR #278](https://github.com/masarray/arsonmix/pull/278) one Console IN/OUT/FX/SEND/PAN/FADER/MAIN workflow. One-gesture route requests; fader/pan/bypass RT controls, native Plugin Manager and live VST3/editor, independent LINK FADERS versus summing BUS, true FX RETURN, PFL/Cue, Show. Engine alone owns native accepted state. Provide each `supportedOps` only after actual production callback admission. This supersedes any staged-wizard routing assumptions. + # THREAD A — ENGINE: binding puzzle handoff (PR #266) **READ FIRST:** [PRD v5.1](../PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) §8, [ARD v5.1](../ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) §J, [v8 socket](../PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md), [machine inventory](../../contracts/console-puzzle-v8.json). This replaces previous engineering *sequencing*, but never relaxes realtime safety. Continue existing PR #266 code. Do not write web/** or CI workflow YAML; do not claim a hidden/offline VST or Group is production. diff --git a/docs/workstreams/FAT_PUZZLE_V8.md b/docs/workstreams/FAT_PUZZLE_V8.md index e870cf24c..336ac6214 100644 --- a/docs/workstreams/FAT_PUZZLE_V8.md +++ b/docs/workstreams/FAT_PUZZLE_V8.md @@ -1,3 +1,5 @@ +> **MANDATORY UX SPECIFICATION AMENDMENT:** [PRD v5.2 §9](../PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) and [ARD v5.2 §K](../ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) require FAT to test user-approved [PR #278](https://github.com/masarray/arsonmix/pull/278) single Console workflow in real native Windows WebView, NOT demo HTML. Exact one-step channel IN1→CH07→MAIN PCM, real FX/editor, LINK FADERS vs summing Group, wet Return, cue/monitor, Show and pinned MASTER, one source SHA; 1024/1366/1680 and standard GPU. Hardware independent QA/PENDING. A green mock-up never qualifies UAT. + # THREAD C — INTEGRATION/FAT: binding puzzle handoff (PR #270, epic #192) **READ FIRST:** [PRD v5.1](../PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) §8, [ARD v5.1](../ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) §J, [v8 socket](../PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md), [machine inventory](../../contracts/console-puzzle-v8.json). You are SOCKET TESTER and MERGE CAPTAIN, not a fourth GUI/audio implementation. Primary PR #270 owns CI YAML, package/provenance, cross-layer contract and independent hardware engineering FAT. #276 is internal partial staging, not customer UAT; #279 is shared executable preflight to integrate after approved review. #274/#275 belong to GUI owner. diff --git a/docs/workstreams/GUI_PUZZLE_V8.md b/docs/workstreams/GUI_PUZZLE_V8.md index 0e91c81a8..83fb71d68 100644 --- a/docs/workstreams/GUI_PUZZLE_V8.md +++ b/docs/workstreams/GUI_PUZZLE_V8.md @@ -1,3 +1,5 @@ +> **MANDATORY UX SPECIFICATION AMENDMENT:** [PRD v5.2 §9](../PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) and [ARD v5.2 §K](../ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) designate [PR #278](https://github.com/masarray/arsonmix/pull/278) as the user-approved single Console UI baseline. Adapt it in GUI #271 as real WebView native renderer; no legacy workbench/tab wizard fallback as finished UI. Publish every #278 control→native op mapping in issue #192. Do not import fake meters/catalog/ports or confuse linked faders with native Group Bus. This supersedes older GUI layout goals in this packet. + # THREAD B — GUI: binding puzzle handoff (PR #271) **READ FIRST:** [PRD v5.1](../PRD_ARSONMIX_OPERATOR_FIRST_LIVE_MIXER_V5_20261101.md) §8, [ARD v5.1](../ARD_ARSONMIX_UNIVERSAL_REALTIME_CONSOLE_V5_20261101.md) §J, [v8 socket](../PUZZLE_INTEGRATION_CONTRACT_V8_20261101.md), [machine inventory](../../contracts/console-puzzle-v8.json). Continue #271 as the SINGLE GUI branch; #274 generated asset and #275 First Sound are source patches to selectively reconcile, not competing product releases. Do not modify src/**, engine/core/**, or FAT workflow YAML.