Repository navigation
M4 operator routing safety: native Route Only / Send, anti-double-dry and fail-closed sidechain/PDC #404
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
masarray
merged 6 commits into
main
from
integration/m4-operator-routing-admission-20261105
Nov 4, 2026
Merged
M4 operator routing safety: native Route Only / Send, anti-double-dry and fail-closed sidechain/PDC #404
Changes from all commits
Commits
Show all changes
6 commits
Select commit
Hold shift + click to select a range
c18b47b
feat(m4): native-authoritative operator routing safety, sidechain/PDC…
masarray 8073a64
test(m4): use existing console-v6 trigger for cheap and native gates
masarray ed1165a
fix(m4): report feedback-cycle before destination-role rejection
masarray 9c13f59
fix(m4): verify exclusive route and exact send tap/gain in native ACK…
masarray a84ddb8
fix(m4): reconcile release-gate V8 adapter lookup with M3C INTEGRATOR…
masarray 7796943
test(m4): keep M3C source-path regression compatible with future full…
masarray File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| # M4 integration: operator routing admission, native DSP handoff | ||
|
|
||
| **One product:** existing approved `/preview/`, existing M2 native v8 protocol, ONE JUCE callback. Do not create GUI/PCM/graph alternatives. | ||
|
|
||
| ## What is executable now (integration control plane) | ||
|
|
||
| `integration/console-v6/m4-operator-routing.mjs` consumes the **already normalized/accepted** `web/approved-native-contract.js` snapshot, never Pages mock data. `planM4OperatorIntent(accepted, gesture)` can emit the existing native `APPLY_WIRE_TRANSACTION` for: | ||
| - `ROUTE_ONLY`: replace the source's exclusive primary OUT with a Group or MAIN, after cycle and parallel dry-path checks; | ||
| - `SEND_POST`: add a unity-gain POST send, including a wet-only-verified FX return, after duplicate and double-dry checks. | ||
|
|
||
| These are *candidate intents*, not applied changes. GUI/controller is still responsible for the same device epoch, graph revision, roster revision, request ID, native ACK and **later independently accepted readback**. In particular, do not paint a cable after the intent returns `ok:true`. No new source of truth is introduced. | ||
|
|
||
| This is not yet wired to the approved visual renderer: GUI owner must add minimal one/two-click gestures **only after** the owner accepts the intent API; retain all approved pixels and controls. Current M3 #402 remains the authoritative native adapter. | ||
|
|
||
| ## Explicit fail-closed boundaries | ||
|
|
||
| - `SEND_PRE`: ENGINE #266's v8 WIRE decoder currently permits only `POST_FADER`, although older native DSP accepts PRE. Requires decoder + exact tap readback proof. | ||
| - `SET_SEND_GAIN`: existing `readbackProvesIntent` checks WIRE presence, not the exact accepted gain. Requires native gain authority and ACK/readback proof. | ||
| - `GROUP_SELECTED` and `NEW_FX_RETURN`: engine core has graph support, but public M2 controller must add exact structural accepted-readback tests before these are operator actions. | ||
| - `SIDECHAIN`: must use a separate detector-only VST3 AUX input bus, never an audible WIRE connection. `src/VstBusLayout.h` currently disables all auxiliary input buses; there is no verified detector-only edge or native readback. No sidechain intent may be emitted before the ENGINE owner supplies real bus layout negotiation, detector buffer processing, precise latency handling and accepted ACK/readback. | ||
| - `PDC`: unknown latency fails closed; nonzero latency requires native graph compensation. Low-latency live-monitor mode must not silently acquire high buffered latency. | ||
|
|
||
| ## ENGINE owner (#266) handoff | ||
|
|
||
| 1. One prepared graph with explicit primary OUT, separate parallel audible send and *detector-only* sidechain edge; no feedback across either dependency graph. | ||
| 2. VST3 main stereo + optional auxiliary sidechain bus negotiation; no allocations/locks/plugin discovery within audio callback; genuine plugin/input bus ownership, enable/disable and readback. | ||
| 3. Graph-aware alignment across mixed dry/wet, send taps and detector path, plus explicit tradeoff of LIVE_LOW_LATENCY vs STUDIO_COMPENSATED mode. | ||
| 4. Native capability flags and exact accepted snapshot effects: PRE/POST, gain/tap, bus creation, plugin sidechain assignment, PDC and revisioned ACK. Until readback proves a new op, do not advertise it in `supportedOps`. | ||
|
|
||
| ## GUI owner handoff | ||
|
|
||
| Reuse `/preview/`. Map operator shortcuts (Group Selected, New FX Send, Route Only, External Sidechain selector) to accepted native intents *after* their capabilities are installed. No changed layout, fake meter, alternate GUI or JS PCM. | ||
|
|
||
| ## Acceptance and release | ||
|
|
||
| The M4 pure routing contract tests run in existing cheap `scripts/check_console_puzzle.mjs` before heavy Windows CI. They are source/control correctness only, not hardware FAT or real sidechain DSP. M3 #402/#266, Windows exact-head CTest, screenshot parity and physical #15 remain separate blockers. Never mark M4 complete or product LIVE based solely on these tests. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,220 @@ | ||
| // SPDX-License-Identifier: AGPL-3.0-only | ||
| // M4 operator intent ADMISSION for the ONE approved /preview/ + JUCE product. | ||
| // CONTROL PLANE ONLY: no audio buffers, second graph authority, plugin bus | ||
| // allocation, optimistic mutation, callback, or extra renderer. | ||
| // Accepts a previously normalized native v8/schemaVersion=6 readback and | ||
| // returns a controller.intent() request only when the existing native ABI | ||
| // can prove the requested result after ACK + matching accepted snapshot. | ||
| const MAX64=(1n<<64n)-1n; | ||
| export const M4_OPERATOR_ABI=Object.freeze({schemaVersion:6, | ||
| nativeWireOperation:'APPLY_WIRE_TRANSACTION',supportedWireTap:'POST_FADER'}); | ||
|
|
||
| const fail=(error,detail)=>({ok:false,error,detail}); | ||
| const id=value=>{ | ||
| if(typeof value!=='string'||!/^[1-9][0-9]*$/.test(value))return false; | ||
| try{return BigInt(value)<=MAX64;}catch{return false;} | ||
| }; | ||
| const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value); | ||
| const safeGain=value=>typeof value==='number'&&Number.isFinite(value)&&value>=0&&value<=4; | ||
| function admittedView(accepted){ | ||
| // A Pages demo or raw JSON is NOT a native-accepted graph. The caller must | ||
| // pass normalizeSnapshot() output from the existing M2 controller. | ||
| if(!accepted||accepted.admitted!==true||!object(accepted.device)|| | ||
| !object(accepted.graph)||!object(accepted.graph.capabilities)|| | ||
| accepted.graph.capabilities.callbackOwnsChannelIds!==true || | ||
| !id(accepted.device.epoch)||!id(accepted.graph.revision)|| | ||
| !id(accepted.graph.rosterRevision)|| | ||
| !Array.isArray(accepted.graph.channels)|| | ||
| !Array.isArray(accepted.graph.edges)) | ||
| return fail('NATIVE_CHANNELID_NOT_ADMITTED'); | ||
| if(!Array.isArray(accepted.graph.capabilities.supportedOps)|| | ||
| !accepted.graph.capabilities.supportedOps.includes(M4_OPERATOR_ABI.nativeWireOperation)) | ||
| return fail('NATIVE_WIRE_OPERATION_UNAVAILABLE'); | ||
| const channels=new Map(); | ||
| let main=null; | ||
| for(const ch of accepted.graph.channels){ | ||
| if(!object(ch)||!id(ch.id)||channels.has(ch.id)|| | ||
| !['INPUT','GROUP','FX_RETURN','MAIN','MONITOR'].includes(ch.role)) | ||
| return fail('INVALID_ACCEPTED_CHANNELS'); | ||
| channels.set(ch.id,ch); | ||
| if(ch.role==='MAIN'){ | ||
| if(main!==null)return fail('MULTIPLE_NATIVE_MASTERS'); | ||
| main=ch.id; | ||
| } | ||
| } | ||
| if(!main||accepted.graph.mainChannelId!==main) | ||
| return fail('MISSING_NATIVE_MASTER'); | ||
| const edges=[],edgeIds=new Set(),arcs=new Map([...channels.keys()].map(x=>[x,[]])); | ||
| for(const e of accepted.graph.edges){ | ||
| if(!object(e)||!id(e.edgeId)||edgeIds.has(e.edgeId)|| | ||
| !id(e.from)||!id(e.to)||!channels.has(e.from)||!channels.has(e.to)|| | ||
| e.from===e.to||e.from===main||e.signalKind!=='AUDIO'|| | ||
| e.enabled!==true||typeof e.primaryOutput!=='boolean'|| | ||
| !safeGain(e.gainLinear)) | ||
| return fail('INVALID_NATIVE_AUDIO_EDGE'); | ||
| edgeIds.add(e.edgeId);edges.push(e);arcs.get(e.from).push(e.to); | ||
| } | ||
| const path=(start,target,graph=arcs)=>{ | ||
| const visited=new Set(),stack=[start]; | ||
| while(stack.length){ | ||
| const cur=stack.pop(); | ||
| if(cur===target)return true; | ||
| if(visited.has(cur))continue; | ||
| visited.add(cur); | ||
| for(const to of graph.get(cur)||[])stack.push(to); | ||
| } | ||
| return false; | ||
| }; | ||
| // Do not use a rejected/feedback graph as a source of proposed changes. | ||
| for(const [src,targets] of arcs.entries()) | ||
| if(targets.some(to=>path(to,src)))return fail('ACCEPTED_GRAPH_CYCLE'); | ||
| return {ok:true,channels,main,edges,arcs,path,accepted}; | ||
| } | ||
| function sendsToMain(view,source,candidate){ | ||
| const next=new Map([...view.channels.keys()].map(x=>[x,[]])); | ||
| for(const e of candidate){ | ||
| // FX return explicitly verified as 100% wet does not count as | ||
| // second *dry* path. Unverified returns are conservatively counted. | ||
| const dest=view.channels.get(e.to); | ||
| if(dest?.role==='FX_RETURN'&&dest.wetOnly===true)continue; | ||
| next.get(e.from).push(e.to); | ||
| } | ||
| const count=(node,seen)=>{ | ||
| if(node===view.main)return 1; | ||
| if(seen.has(node))return 2; | ||
| const scope=new Set(seen);scope.add(node); | ||
| let n=0; | ||
| for(const to of next.get(node)||[]){ | ||
| n+=count(to,scope);if(n>1)return 2; | ||
| } | ||
| return n; | ||
| }; | ||
| return count(source,new Set()); | ||
| } | ||
| function planWire(view,request){ | ||
| const {kind,sourceId,destinationId}=request; | ||
| if(!id(sourceId)||!view.channels.has(sourceId)|| | ||
| !id(destinationId)||!view.channels.has(destinationId)) | ||
| return fail('UNKNOWN_NATIVE_CHANNELID'); | ||
| if(sourceId===destinationId)return fail('SELF_ROUTE_FORBIDDEN'); | ||
| const source=view.channels.get(sourceId),destination=view.channels.get(destinationId); | ||
| if(['MAIN','MONITOR'].includes(source.role))return fail('OUTPUT_BUS_CANNOT_SOURCE_SEND'); | ||
| // A dependency cycle is the strongest/most specific routing fault. | ||
| // Report it before the more general INPUT destination role rejection. | ||
| if(view.path(destinationId,sourceId))return fail('ROUTING_FEEDBACK_CYCLE'); | ||
| if(destination.role==='INPUT')return fail('INPUT_NOT_A_ROUTING_DESTINATION'); | ||
| const same=view.edges.filter(e=>e.from===sourceId&&e.to===destinationId); | ||
| const currentPrimary=view.edges.filter(e=>e.from===sourceId&&e.primaryOutput); | ||
| if(currentPrimary.length>1)return fail('MULTIPLE_ACCEPTED_PRIMARY_OUTPUTS'); | ||
| if(kind==='ROUTE_ONLY'){ | ||
| if(destination.role!=='GROUP'&&destination.role!=='MAIN') | ||
| return fail('EXCLUSIVE_ROUTE_REQUIRES_GROUP_OR_MAIN'); | ||
| if(currentPrimary.length===1&¤tPrimary[0].to===destinationId) | ||
| return fail('PRIMARY_ALREADY_AT_DESTINATION'); | ||
| if(same.length)return fail('DUPLICATE_NATIVE_ROUTE'); | ||
| const simulated=view.edges.filter(e=> | ||
| !(e.from===sourceId&&e.primaryOutput)); | ||
| simulated.push({from:sourceId,to:destinationId,primaryOutput:true}); | ||
| if(sendsToMain(view,sourceId,simulated)>1) | ||
| return fail('EXCLUSIVE_ROUTE_RETAINS_PARALLEL_DRY_PATH', | ||
| 'Native Route Only changes the primary OUT; existing parallel sends remain.'); | ||
| return {ok:true,intent:{operation:M4_OPERATOR_ABI.nativeWireOperation, | ||
| targetChannelId:sourceId,payload:{changes:[{ | ||
| op:'ROUTE_ONLY',from:sourceId,to:destinationId, | ||
| tap:'POST_FADER',gainLinear:1 | ||
| }]}},fence:fence(view)}; | ||
| } | ||
| if(kind!=='SEND_POST')return fail('UNKNOWN_ROUTING_GESTURE'); | ||
| if(destination.role==='MAIN') | ||
| return fail('MAIN_REQUIRES_PRIMARY_OUT','Use Route Only to MAIN.'); | ||
| if(same.length)return fail('DUPLICATE_NATIVE_ROUTE'); | ||
| if(destination.role==='FX_RETURN'&&destination.wetOnly!==true) | ||
| return fail('FX_RETURN_WET_ONLY_NOT_VERIFIED', | ||
| 'Return must be proven 100% wet by native accepted readback.'); | ||
| // Non-unity gain is intentionally blocked: current v8 wire | ||
| // readbackProvesIntent only confirms existence, NOT accepted send gain. | ||
| if(request.gainDb!==undefined&&request.gainDb!==0) | ||
| return fail('SEND_GAIN_ACK_READBACK_NOT_AVAILABLE'); | ||
| const simulated=[...view.edges,{from:sourceId,to:destinationId,primaryOutput:false}]; | ||
| if(destination.role!=='FX_RETURN'&&sendsToMain(view,sourceId,simulated)>1) | ||
| return fail('DOUBLE_DRY_TO_MAIN', | ||
| 'Choose Route Only for subgroup instead of mixing direct MAIN twice.'); | ||
| return {ok:true,intent:{operation:M4_OPERATOR_ABI.nativeWireOperation, | ||
| targetChannelId:sourceId,payload:{changes:[{ | ||
| op:'CONNECT',from:sourceId,to:destinationId, | ||
| tap:'POST_FADER',gainLinear:1 | ||
| }]}},fence:fence(view)}; | ||
| } | ||
| const fence=view=>Object.freeze({ | ||
| deviceEpoch:view.accepted.device.epoch, | ||
| graphRevision:view.accepted.graph.revision, | ||
| rosterRevision:view.accepted.graph.rosterRevision | ||
| }); | ||
| function sidechainGate(view,request){ | ||
| if(!id(request.sourceId)||!id(request.destinationId)|| | ||
| !view.channels.has(request.sourceId)||!view.channels.has(request.destinationId)) | ||
| return fail('UNKNOWN_NATIVE_CHANNELID'); | ||
| if(request.sourceId===request.destinationId|| | ||
| view.path(request.destinationId,request.sourceId)) | ||
| return fail('SIDECHAIN_DEPENDENCY_CYCLE'); | ||
| const dest=view.channels.get(request.destinationId); | ||
| if(dest.role==='MAIN'||dest.role==='MONITOR') | ||
| return fail('SIDECHAIN_TARGET_NOT_AN_INSERT_CHANNEL'); | ||
| if(typeof request.pluginInstanceId!=='string'|| | ||
| !request.pluginInstanceId.trim()|| | ||
| !Array.isArray(dest.inserts)|| | ||
| !dest.inserts.some(fx=>fx.instanceId===request.pluginInstanceId|| | ||
| fx.id===request.pluginInstanceId)) | ||
| return fail('VST3_INSERT_LEASE_NOT_VERIFIED'); | ||
| const aux=request.nativeAuxInput; | ||
| if(!object(aux)||aux.pluginInstanceId!==request.pluginInstanceId|| | ||
| !Number.isInteger(aux.busIndex)||aux.busIndex<1|| | ||
| ![1,2].includes(aux.channels)||aux.enabled!==true|| | ||
| aux.detectorOnly!==true) | ||
| return fail('VST3_AUX_DETECTOR_BUS_NOT_NEGOTIATED'); | ||
| const caps=view.accepted.graph.capabilities; | ||
| if(!caps.supportedOps.includes('CONNECT_PLUGIN_SIDECHAIN')|| | ||
| caps.nativeSidechainBusReady!==true) | ||
| return fail('NATIVE_SIDECHAIN_CAPABILITY_UNAVAILABLE'); | ||
| const pdc=assessM4Pdc({latencySamples:aux.latencySamples, | ||
| compensated:aux.compensated,monitorMode:request.monitorMode}); | ||
| if(!pdc.ok)return pdc; | ||
| // Even if future metadata appears, existing M2 controller does not | ||
| // prove a detector-only route in readbackProvesIntent(). Never emit an | ||
| // unprovable accepted sidechain or covert audible send. | ||
| return fail('SIDECHAIN_ACK_READBACK_UNIMPLEMENTED', | ||
| 'Require native detector-only edge + plugin-bus readback and exact ACK proof.'); | ||
| } | ||
| export function assessM4Pdc({latencySamples,compensated,monitorMode}={}){ | ||
| if(!Number.isSafeInteger(latencySamples)||latencySamples<0) | ||
| return fail('PLUGIN_LATENCY_UNVERIFIED'); | ||
| if(monitorMode!==undefined&&!['LIVE_LOW_LATENCY','STUDIO_COMPENSATED'].includes(monitorMode)) | ||
| return fail('UNKNOWN_MONITOR_LATENCY_MODE'); | ||
| if(latencySamples>0&&compensated!==true) | ||
| return fail('NATIVE_GRAPH_PDC_UNAVAILABLE'); | ||
| if(latencySamples>0&&monitorMode==='LIVE_LOW_LATENCY') | ||
| return fail('LIVE_MONITOR_LATENCY_POLICY_CONFLICT'); | ||
| return {ok:true,latencySamples}; | ||
| } | ||
| /** | ||
| * Produces a candidate native controller.intent operation ONLY. | ||
| * No message is sent by this function; GUI/Integrator must dispatch with | ||
| * existing M2 controller and wait for ACK + same-revision native readback. | ||
| */ | ||
| export function planM4OperatorIntent(accepted,request){ | ||
| const view=admittedView(accepted); | ||
| if(!view.ok)return view; | ||
| if(!object(request)||typeof request.kind!=='string') | ||
| return fail('INVALID_OPERATOR_REQUEST'); | ||
| switch(request.kind){ | ||
| case 'ROUTE_ONLY': | ||
| case 'SEND_POST':return planWire(view,request); | ||
| case 'SEND_PRE':return fail('NATIVE_PRE_FADER_WIRE_NOT_ADMITTED', | ||
| 'ENGINE #266 WIRE decoder currently accepts POST_FADER only.'); | ||
| case 'SET_SEND_GAIN':return fail('SEND_GAIN_ACK_READBACK_NOT_AVAILABLE'); | ||
| case 'GROUP_SELECTED':return fail('GROUP_CREATE_ACK_READBACK_UNIMPLEMENTED'); | ||
| case 'NEW_FX_RETURN':return fail('FX_RETURN_CREATE_ACK_READBACK_UNIMPLEMENTED'); | ||
| case 'SIDECHAIN':return sidechainGate(view,request); | ||
| default:return fail('UNKNOWN_OPERATOR_GESTURE'); | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
When an input already routes directly to MAIN and also sends to a Group with no output, Route Only from that Group to MAIN returns
ok:true: this check counts only the Group's single path, but the input now reaches MAIN twice, directly and through the Group. This is a valid acyclic accepted graph, and the resulting readback passes the new Route Only proof, so the advertised anti-double-dry protection does not prevent the duplicated audio. Check the simulated dry-path counts for affected upstream channels as well assourceId; the SEND_POST admission check needs the same treatment.Useful? React with 👍 / 👎.