diff --git a/AGENTS.md b/AGENTS.md index 7b0b210e2..51c285745 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -3,16 +3,23 @@ **ONLY approved/public/product GUI: https://masarray.github.io/arsonmix/preview/**. There must be ONE public preview, ONE actual rendered GUI, and ONE native Windows GUI. **/preview-v2/ is rejected**: do not display, promote, publish or base native design on it as a separate UI. Do not substitute another console from `web/index.html`, `web/mixer-layout.js`, `web/console-native.html`, PR #278 or old M3/V48 mock. **The JUCE ENGINE must stitch into the EXACT approved /preview/ GUI**, never redesign it. -## Multi-agent GitHub coordination — REQUIRED (issue #397) - -Before touching ArSonMix code, read [workstream ownership and collaboration contract](docs/workstreams/MULTI_AGENT_COORDINATION.md) and [coordination control tower #397](https://github.com/masarray/arsonmix/issues/397). GitHub main, active PRs, changed-file overlap and accepted native ABI are the shared state; independent ChatGPT threads cannot see each other's private unpushed work. - -- **GUI** owns `site/**` and browser presentation. ONLY the assembled `/preview/`, no alternative renderer. -- **ENGINE** owns `engine/**` and realtime DSP/PCM/device/VST3 sources; **#266** remains sole callback producer. -- **INTEGRATOR** alone owns `src/Main.cpp`, `CMakeLists.txt`, `integration/**` and `web/approved-native*` and assembles one Windows application. -- **FAT** owns native Windows evidence, packaging and independent QA; FAT must not edit production DSP or GUI to claim PASS. - -New PRs require the owner and linked issue metadata from `.github/PULL_REQUEST_TEMPLATE.md`. Existing Windows and Chromium workflows run the cheap, read-only source-owner/collision preflight; no extra workflow. Cross-owner changes must be handed off to the owner through issue #397, **not** implemented in parallel. Mark superseded older PRs `` while extracting unique verified changes. Pre-policy PRs #399 and earlier receive nonblocking findings while DRAFT; when marked ready_for_review they must meet the SAME strict gate and re-run CI. This is not permission to merge conflicting code. One exact-SHA integrator gates a Windows EXE on real native PCM + visual parity + FAT; missing hardware evidence is PENDING. +## One integration owner — binding product recovery (2026-11-05) + +Previous four-lane ENGINE / INTEGRATOR / FAT / GUI ownership and active-PR +collision gates are **superseded**. A single product integration PR may edit +engine, native host, GUI data bridge, tests, packaging and CI as necessary. +Declare `` in its PR body so the +existing lightweight qualification selector skips cross-thread admission, +not the actual Windows build, JUCE/CTest, browser gates or release checks. +No waiting for abandoned thread approvals; no fake milestone/progress claims. + +Before a change: fetch latest main HEAD, compare merged #266/#408/#406, +reconcile source file-by-file, and preserve functional VST3, Show, device +selection and the accepted GUI. Use **one integrated PR** with meaningful +product changes. Branch protection, review, exact-SHA tests, source integrity +and independently witnessed hardware FAT remain binding. No forced merge, +no uncontrolled callbacks, no silent auto-arm or output reroute. If real +hardware is unavailable, mark physical audio FAT **PENDING**. ## Verified current published GUI implementation `site/preview/index.html` was merely a wrapper/iframe pointing at a generated `/preview-buttons/index.html`. `scripts/build_pages.py` generates that **approved PNG hardware-button variant** using current `site/preview-v2/index.html` as an INTERNAL HTML/WIRE/FX/fader source, with specifically `site/preview-buttons/assets/mixer-control-keys.css`, `mixer-control-keys.js` and `mute-solo-pfl-56x37.png` as approved button source. **The assembled result behind /preview/ is the visual authority, not /preview-v2/ in isolation.** There must be exactly ONE deterministic assembled output and no independent published variant. Internal source files may survive only as build inputs until safely consolidated; they are NOT alternate product GUIs. **Current approved visual including PNG keys must never be silently replaced by the base variant.** diff --git a/docs/workstreams/MULTI_AGENT_COORDINATION.md b/docs/workstreams/MULTI_AGENT_COORDINATION.md index 943571dd8..32ff67f60 100644 --- a/docs/workstreams/MULTI_AGENT_COORDINATION.md +++ b/docs/workstreams/MULTI_AGENT_COORDINATION.md @@ -1,3 +1,9 @@ +> **SUPERSEDED — 2026-11-05.** Historical parallel-agent policy only. +> Current product execution is single integration owner under [AGENTS.md](../../AGENTS.md). +> No lane approval, stale PR collision or per-owner source-file barrier may +> delay integrated production changes. Retain quality, regression, exact-SHA, +> signed release/ZIP integrity and physical FAT safety gates. + # ArSonMix — Parallel Agent Coordination (binding for new work) **Control tower:** [issue #397](https://github.com/masarray/arsonmix/issues/397). diff --git a/integration/ApprovedNativeRuntimeSnapshot.h b/integration/ApprovedNativeRuntimeSnapshot.h index f1610740a..eaafd93b0 100644 --- a/integration/ApprovedNativeRuntimeSnapshot.h +++ b/integration/ApprovedNativeRuntimeSnapshot.h @@ -36,6 +36,57 @@ inline bool synchronizeApprovedRouteDeviceEpoch( return true; } +// First Sound is a REAL legacy M4 physical route before ChannelId migration. +// The approved native More-menu needs its actual epoch/revision to PATCH CH1. +// Prior G0 snapshots omitted legacyM4 entirely, permanently disabling PATCH +// and ARM even when JUCE had a valid prepared mixer. This CONTROL-only +// metadata does not admit ChannelId operations, synthesize PCM or arm output. +inline bool publishVerifiedFirstSoundState(juce::var& snapshot, + const juce::var& live) +{ + if(!snapshot.isObject() || !live.isObject()) return false; + const auto device=snapshot.getProperty("device",{}); + const auto route=live.getProperty("dryRoutingLab",{}); + if(!device.isObject() || !route.isObject()) return false; + const auto boolIs=[&](const juce::var& parent,const char* key,bool expected) { + const auto actual=parent.getProperty(key,{}); + return actual.isBool() && static_cast(actual)==expected; + }; + const auto epoch=device.getProperty("epoch",{}); + const auto routeEpoch=route.getProperty("epoch",{}); + const auto revision=route.getProperty("revision",{}); + const auto inputs=device.getProperty("enabledInputs",{}); + const auto outputs=device.getProperty("enabledOutputs",{}); + double rate=0.,frames=0.; + const bool physicalReady= + boolIs(live,"connected",true) && + boolIs(live,"directRouteAuthorized",true) && + boolIs(live,"adaptiveClockActive",false) && + boolIs(route,"active",true) && + boolIs(route,"ready",true) && + boolIs(route,"topologyFault",false) && + nativeV8Decimal(epoch) && + (routeEpoch.isInt() || routeEpoch.isInt64()) && + (revision.isInt() || revision.isInt64()) && + static_cast(routeEpoch)>0 && + static_cast(revision)>0 && + juce::String(static_cast(routeEpoch))==epoch.toString() && + inputs.isArray() && !inputs.getArray()->isEmpty() && + outputs.isArray() && outputs.getArray()->size()>=2 && + nativeV8Number(device.getProperty("sampleRate",{}),rate) && + nativeV8Number(device.getProperty("bufferFrames",{}),frames) && + rate>=8000. && frames>=16.; + auto firstSound=std::make_unique(); + firstSound->setProperty("active",physicalReady); + firstSound->setProperty("routeAccepted",physicalReady && + boolIs(route,"hasAcceptedRoute",true)); + firstSound->setProperty("routingRevision",physicalReady + ?juce::String(static_cast(revision)):juce::String("0")); + // Do not write the route to the graph or change native capability flags. + snapshot.getDynamicObject()->setProperty("legacyM4",juce::var(firstSound.release())); + return physicalReady; +} + inline bool projectInstalledNativeChannelIdGraph( juce::var& snapshot, const juce::var& live) { diff --git a/scripts/check_workstream_coordination.mjs b/scripts/check_workstream_coordination.mjs index 64adb8976..d3f4ceb8a 100644 --- a/scripts/check_workstream_coordination.mjs +++ b/scripts/check_workstream_coordination.mjs @@ -82,6 +82,22 @@ export function metadata(body = '', headRef = '') { return {owner, inferred, issue, parked}; } export function audit({pr, files, others = [], filesByPR = {}, fileStatuses = {}}) { + // 2026-11-05: explicit single-owner product recovery supersedes mandatory + // cross-thread lanes. Keep essential alternate-GUI and exact-source checks; + // collisions are reconciled through the normal Git diff + PR review, NOT + // a GitHub-API preflight that can block a working Windows build. + if (//i.test(pr.body || '')) { + const errors=[]; + for (const path of files) + if (['web/console-native.html','web/console-native.js', + 'web/console-native.css'].includes(path) && + fileStatuses[path] !== 'removed') + errors.push('ALTERNATE GUI '+path+' forbidden; keep approved /preview/.'); + return {ok:errors.length===0,legacy:false,lane:'PRODUCT', + owners:['SINGLE_INTEGRATION_OWNER'],errors,warnings:[], + changedFiles:files.length,activeCollisions:0}; + } + const current = metadata(pr.body || '', pr.head?.ref || pr.headRef || ''); const legacy = pr.number <= POLICY_EPOCH_PR && pr.draft === true; const errors = [], warnings = []; @@ -244,14 +260,21 @@ export async function auditGitHub({repo,number,token}) { if (!Number.isSafeInteger(number) || number<1 || !token) throw Error('A valid PR number and a GitHub read token are mandatory'); const prefix='https://api.github.com/repos/'+repo; - const [pr, others]=await Promise.all([ - apiJson(prefix+'/pulls/'+number,token), - allPages(prefix+'/pulls?state=open',token,4) - ]); + const pr=await apiJson(prefix+'/pulls/'+number,token); + const files=await allPages(prefix+'/pulls/'+number+'/files',token,10); + const changedPaths=files.map(f=>f.filename); + const fileStatuses=Object.fromEntries(files.map(f=>[f.filename,f.status])); + // Single-owner mode deliberately skips scanning all other PRs and their + // files: no waiting on abandoned ENGINE/FAT/INTEGRATOR workstreams. + if (//i.test(pr.body||'')) { + const result=audit({pr,files:changedPaths,fileStatuses}); + return {...result,runUi:requiresUiSmoke(changedPaths), + runNative:requiresNativeQualification(changedPaths)}; + } + const others=await allPages(prefix+'/pulls?state=open',token,4); const filesByPR={}; const scoped=others.filter(p=>p.number!==number && !metadata(p.body||'',p.head?.ref||'').parked); - const files=await allPages(prefix+'/pulls/'+number+'/files',token,10); // Bounded concurrency prevents API spikes on frequent PR pushes. for (let i=0;i{ @@ -261,7 +284,6 @@ export async function auditGitHub({repo,number,token}) { } const result = audit({pr,files:files.map(f=>f.filename),others,filesByPR, fileStatuses:Object.fromEntries(files.map(f=>[f.filename,f.status]))}); - const changedPaths = files.map(f=>f.filename); return {...result, runUi: requiresUiSmoke(changedPaths), runNative: requiresNativeQualification(changedPaths)}; } diff --git a/src/ApprovedConsoleNativeTransportV6.h b/src/ApprovedConsoleNativeTransportV6.h index 453f39288..240e21fb8 100644 --- a/src/ApprovedConsoleNativeTransportV6.h +++ b/src/ApprovedConsoleNativeTransportV6.h @@ -52,7 +52,7 @@ inline juce::var realDevicePorts (const juce::StringArray& labels, inline juce::var snapshot (const juce::var& live, juce::AudioDeviceManager& manager, - bool allOutputsDisarmed) + bool primaryOutputArmed) { // Message-thread read of the REAL engine and real current JUCE device. // When separate clocks are active, direct JUCE input pins cannot be @@ -87,7 +87,7 @@ inline juce::var snapshot (const juce::var& live, ? active->getCurrentSampleRate() : 0.0); dev->setProperty ("bufferFrames", active != nullptr && active->isOpen() ? active->getCurrentBufferSizeSamples() : 0); - dev->setProperty ("outputArmed", ! allOutputsDisarmed); + dev->setProperty ("outputArmed", primaryOutputArmed); root->setProperty ("device", juce::var (dev.release())); auto caps = std::make_unique(); diff --git a/src/Main.cpp b/src/Main.cpp index 5ff9bbd5a..f410bce6b 100644 --- a/src/Main.cpp +++ b/src/Main.cpp @@ -696,11 +696,14 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr juce::var approvedNativeSnapshot (const juce::var& live) { auto accepted=armix::native_console_m2::snapshot ( - live, engine_.devices(), engine_.allOutputsDisarmed()); + live, engine_.devices(), engine_.isMonitorEnabled()); // Native routing's generation advances on STOP as well as START. // Keep even disconnected G0 snapshots monotonic to invalidate UI. (void) armix::console::synchronizeApprovedRouteDeviceEpoch ( accepted, live); + // Actual prepared M4 epoch/revision enables the native First Sound + // hardware PATCH/ARM workflow before full ChannelId admission. + (void) armix::console::publishVerifiedFirstSoundState (accepted, live); (void) armix::console::projectInstalledNativeChannelIdGraph ( accepted, live); return accepted; @@ -2641,6 +2644,15 @@ class ConsoleWindow final : public juce::DocumentWindow, private juce::Timer, pr if (startupError_.isNotEmpty() && !bool (state.getProperty ("connected", false))) state.getDynamicObject()->setProperty ("error", startupError_); browser_.emitEventIfBrowserIsVisible ("arMixStatus", state); + // The WebView subscribes BEFORE audio startup. A one-shot G0 snapshot + // can therefore precede JUCE initialise() and leave PATCH CH1 grayed + // out forever. Publish the SAME real engine status at the existing + // 12 Hz control-thread cadence: physical pins, accepted ChannelIds and + // PCM meters update after startup, source patch, ARM and hotplug. + // No additional DSP callback, allocation or work on realtime thread. + if (consoleSubscribed_) + browser_.emitEventIfBrowserIsVisible ( + "arMixConsoleSnapshot", approvedNativeSnapshot(state)); } }; diff --git a/tests/approved_native_m2_contract.test.cjs b/tests/approved_native_m2_contract.test.cjs index 4820f388d..00be8090a 100644 --- a/tests/approved_native_m2_contract.test.cjs +++ b/tests/approved_native_m2_contract.test.cjs @@ -37,6 +37,28 @@ test("G0 current JUCE device snapshot is valid, never ChannelId PCM LIVE",()=>{ assert.equal(protocol.decimal(invalid),null); } }); +test("native G0 preserves verified first-sound M4 route without claiming ChannelId PCM",()=>{ + const g0=clone(fixtures.g0); + g0.legacyM4={active:true,routeAccepted:false,routingRevision:"12"}; + const initial=protocol.normalizeSnapshot(g0); + assert.ok(initial); + assert.equal(initial.admitted,false); + assert.deepEqual(initial.raw.legacyM4,g0.legacyM4); + g0.legacyM4.routeAccepted=true; + const patched=protocol.normalizeSnapshot(g0); + assert.ok(patched); + assert.equal(patched.raw.legacyM4.routeAccepted,true); + assert.equal(patched.admitted,false, + "a physical M4 patch is NOT fabricated ChannelId or product admission"); + // The existing JUCE 12Hz status publisher must also deliver late native + // snapshots: WebView's first subscribe occurs before device initialise(). + const nativeMain=read("src/Main.cpp"); + assert.match(nativeMain,/if \(consoleSubscribed_\)[\s\S]*?"arMixConsoleSnapshot", approvedNativeSnapshot\(state\)/); + const nativeBridge=read("web/approved-native-bridge.js"); + assert.match(nativeBridge,/const legacy=\(\)=>hardware\?\.raw\?\.legacyM4/); + assert.match(read("src/ApprovedConsoleNativeTransportV6.h"), + /"outputArmed", primaryOutputArmed/); +}); test("strict producer rejects JS Number identities, invalid hardware pins and fake LIVE",()=>{ const cases=[ s=>{s.device.epoch=69;}, diff --git a/tests/approved_native_v8_projection_test.cpp b/tests/approved_native_v8_projection_test.cpp index 004481c81..2248338c4 100644 --- a/tests/approved_native_v8_projection_test.cpp +++ b/tests/approved_native_v8_projection_test.cpp @@ -334,6 +334,69 @@ static void installedCallbackAdmissionRegression(const juce::var& rawBus) { assert(!static_cast(snap.getProperty("productionCallbackLive",false))); } +// A prepared physical M4 mixer must allow the user to PATCH CH1 even when +// universal ChannelId PCM has not yet been admitted. This is device truth, +// not a test-only callback or optimistic GUI state. +static void firstSoundRouteAdmissionRegression() { + auto snapshot=canonicalSnapshot(); + const auto device=snapshot.getProperty("device",{}); + auto* d=device.getDynamicObject(); + juce::Array inputs,outputs; + inputs.add(0);outputs.add(0);outputs.add(1); + d->setProperty("epoch","7"); + d->setProperty("sampleRate",48000.0); + d->setProperty("bufferFrames",128); + d->setProperty("enabledInputs",juce::var(inputs)); + d->setProperty("enabledOutputs",juce::var(outputs)); + const auto live=parse(R"JSON({ + "connected":true,"directRouteAuthorized":true,"adaptiveClockActive":false, + "dryRoutingLab":{"active":true,"ready":true,"topologyFault":false, + "hasAcceptedRoute":false,"epoch":7,"revision":12} + })JSON"); + assert(publishVerifiedFirstSoundState(snapshot,live)); + auto m4=snapshot.getProperty("legacyM4",{}); + assert(static_cast(m4.getProperty("active",false))); + assert(!static_cast(m4.getProperty("routeAccepted",true))); + assert(m4.getProperty("routingRevision","").toString()=="12"); + assert(!static_cast(snapshot.getProperty("graph",{}) + .getProperty("capabilities",{}).getProperty("callbackOwnsChannelIds",false))); + // After an actual source patch, ARM is enabled by existing JUCE native + // preflight; no ChannelId capability or product LIVE is fabricated. + live.getProperty("dryRoutingLab",{}).getDynamicObject() + ->setProperty("hasAcceptedRoute",true); + assert(publishVerifiedFirstSoundState(snapshot,live)); + m4=snapshot.getProperty("legacyM4",{}); + assert(static_cast(m4.getProperty("routeAccepted",false))); + auto reject=[&](const juce::var& degraded) { + auto fresh=juce::JSON::parse(juce::JSON::toString(snapshot,false)); + assert(!publishVerifiedFirstSoundState(fresh,degraded)); + const auto disabled=fresh.getProperty("legacyM4",{}); + assert(disabled.isObject()); + assert(!static_cast(disabled.getProperty("active",true))); + assert(!static_cast(disabled.getProperty("routeAccepted",true))); + assert(disabled.getProperty("routingRevision","").toString()=="0"); + }; + auto bad=juce::JSON::parse(juce::JSON::toString(live,false)); + bad.getProperty("dryRoutingLab",{}).getDynamicObject()->setProperty("epoch",8); + reject(bad); // ASIO re-opened, old physical pins must not be patchable + bad=juce::JSON::parse(juce::JSON::toString(live,false)); + bad.getDynamicObject()->setProperty("directRouteAuthorized",false); + reject(bad); + bad=juce::JSON::parse(juce::JSON::toString(live,false)); + bad.getProperty("dryRoutingLab",{}).getDynamicObject()->setProperty("topologyFault",true); + reject(bad); + bad=juce::JSON::parse(juce::JSON::toString(live,false)); + bad.getProperty("dryRoutingLab",{}).getDynamicObject()->setProperty("revision",0); + reject(bad); + bad=juce::JSON::parse(juce::JSON::toString(live,false)); + bad.getDynamicObject()->setProperty("adaptiveClockActive",true); + reject(bad); + auto withoutInput=juce::JSON::parse(juce::JSON::toString(snapshot,false)); + withoutInput.getProperty("device",{}).getDynamicObject() + ->setProperty("enabledInputs",juce::var(juce::Array{})); + assert(!publishVerifiedFirstSoundState(withoutInput,live)); +} + int main() { auto snap=canonicalSnapshot(); auto bus=realBusReadbackFixture(); @@ -366,6 +429,7 @@ int main() { controlIntentTranslationCases(snap,bus); installedCallbackAdmissionRegression(bus); + firstSoundRouteAdmissionRegression(); auto missingMain=realBusReadbackFixture(); missingMain.getProperty("channels",{})[1].getDynamicObject() diff --git a/tests/workstream_coordination_contract.test.mjs b/tests/workstream_coordination_contract.test.mjs index 34432af9a..0801731d2 100644 --- a/tests/workstream_coordination_contract.test.mjs +++ b/tests/workstream_coordination_contract.test.mjs @@ -14,6 +14,24 @@ const pr=(number,lane,branch,parked=false)=>({ const check=(current,files,others=[],filesByPR={})=> audit({pr:current,files,others,filesByPR}); +test('single-owner product recovery removes blocking lane and PR collisions but guards approved GUI',()=>{ + const current={number:420,state:'open',draft:false, + head:{ref:'integration/first-sound-native-g0-patch-20261105'}, + body:''}; + const changed=['src/LiveAudioEngine.h','src/Main.cpp', + 'integration/ApprovedNativeRuntimeSnapshot.h','AGENTS.md']; + const result=audit({pr:current,files:changed, + others:[pr(421,'ENGINE','engine/competing'),pr(422,'INTEGRATOR','integration/competing')], + filesByPR:{421:['src/LiveAudioEngine.h'],422:['src/Main.cpp']}}); + assert.equal(result.ok,true,'one integration PR is not blocked by inactive lane approvals'); + assert.equal(result.lane,'PRODUCT'); + assert.equal(result.activeCollisions,0); + assert.equal(audit({pr:current,files:['web/console-native.html']}).ok,false, + 'the forbidden alternate GUI remains a release blocker'); + assert.equal(audit({pr:current,files:['web/console-native.html'], + fileStatuses:{'web/console-native.html':'removed'}}).ok,true, + 'removing an obsolete visual variant is allowed'); +}); test('only one approved GUI has GUI ownership; no accidental native source authority',()=>{ for(const path of [ 'site/preview/index.html', 'site/preview-v2/index.html', @@ -207,8 +225,11 @@ test('coordinator uses existing native + Chromium CI, not a fifth workflow',()=> assert.match(ui,/ready_for_review/); assert.match(ui,/uses: \.\/\.github\/workflows\/p1-windows\.yml/); const guide=readFileSync('AGENTS.md','utf8'); - assert.match(guide,/MULTI_AGENT_COORDINATION\.md/); - assert.match(guide,/#397/); + assert.match(guide,/One integration owner/); + assert.match(guide,/arsonmix-integration: single-owner/); + assert.match(guide,/Branch protection, review, exact-SHA tests/); + assert.match(readFileSync('docs/workstreams/MULTI_AGENT_COORDINATION.md','utf8'), + /SUPERSEDED — 2026-11-05/); }); test('M2.6 always-on PR admission scopes Chromium to UI changes',()=>{