Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions docs/CONSOLE_BRIDGE_INTEGRATION_CONTRACT_V6.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This document describes **implemented integration types and executable PCM/readb
- \`tests/console_native_integration_test.cpp\` renders actual native offline PCM for IN1→CH7, IN2→CH2, sends to MONITOR, Group Selected with exclusive primary OUT, parallel wet FX Return, stale-device/invalid-pin rollback and mute. The test refuses to call this offline graph physically LIVE.

## Fields (target UI serialization)
All \`ChannelId\`, destination IDs and request IDs are decimal **strings** in JS (64-bit native identity must not be downcast to Number). Only version 6 represents these roles. Sample:
**Wire synchronization v6 (integration patch):** `ChannelId` and destination IDs are canonical unsigned **decimal strings**, never JS Number; `requestId` is a bounded printable **opaque string** per WebView session (e.g. `gui-live:41`) echoed unchanged by ACK, not a native integer or a global monotonically increasing counter. `device.epoch`, `graph.revision` and roster revisions are canonical decimal **strings** on GUI #271; native must preserve all uint64 bits and GUI compares with BigInt. Only v6 represents these roles. Sample:
\`\`\`json
{
"schemaVersion": 6,
Expand All @@ -35,7 +35,7 @@ All \`ChannelId\`, destination IDs and request IDs are decimal **strings** in JS
\`\`\`
The snippet is **illustrative**, not evidence that physical INPUT 1 is bound to ChannelId 7. A device callback pin number is not a sparse Windows hardware pin ID. The native source/physical-output owner must supply separate verified \`sourceBinding\` and actual \`OUTPUT ARMED\` readback. No fallback to IN1 or mock data if missing.

Intent envelope: \`{requestId,deviceEpoch,baseGraphRevision,baseRosterRevision,operation,targetChannelId}\`. A single native writer should reject stale epoch/revision, a previously completed duplicate ID and unsupported operations, then dispatch an existing native graph edit. ACK reports the same requestId, accepted/rejected, **current accepted** revisions and precise reason. An accepted graph **does not** imply physically audible LIVE: a full-fidelity production callback plus verified device/output gate is needed.
Intent envelope: `{requestId,deviceEpoch,baseRevision,baseRosterRevision,op,targetChannelId,payload}` as currently emitted by GUI #271. Native maps `baseRevision` to the internal `baseGraphRevision`, checks exact device epoch and accepted revisions, canonical decimal ChannelIds, and validates the operation against **runtime native supportedOps**, not the UI fixture. A single native writer maintains a **bounded recent completed-ID cache** (not an arbitrary numerical sequence comparator) across editor reconnects and rejects duplicate IDs, stale epoch/revision and unsupported operations before dispatching an existing accepted native graph edit. This adapter is control-plane *preflight* and does not yet instantiate that native writer. ACK reports the same requestId, accepted/rejected, **current accepted** revisions and precise reason. An accepted graph **does not** imply physically audible LIVE: a full-fidelity production callback plus verified device/output gate is needed.

## Invariants and merge gate
1. On rejected native intent, the accepted graph revision, source bindings and PCM remain unchanged. Never send an optimistic UI 'LIVE'.
Expand All @@ -45,3 +45,9 @@ Intent envelope: \`{requestId,deviceEpoch,baseGraphRevision,baseRosterRevision,o
5. ENGINE owns adding source/FX readback from the native accepted snapshot in #266. GUI owns serialization/rendering in #268. Integration test owner does not edit those files.

**Scope note:** This is one integration prerequisite, not the full Universal Live Console milestone. Do not merge this test as a claim that CH11, Group or FX Return have shipped.

## Wire identity / duplicate ACK regression (2026-11-01)
The integration C++ test now proves an opaque `requestId` is echoed unchanged in both accepted and rejected replies, previously completed requests are rejected even across multiple editor IDs, a new editor restarting from sequence 1 is permitted, invalid control characters/overlong tokens are rejected, and native uint64 ChannelId strings reject overflow, leading zero and UI-fixture aliases. Snapshot projection refuses a JS-unsafe epoch/revision. The actual native WebView command dispatcher in ENGINE #266 must implement this v6 mapping and ACK/replay; the existence of the C++ test is not evidence of production bridge or physical sound.

## Serialization-ready accepted readback (no fake physical LIVE)
`toConsoleWireReadbackV6` converts the accepted native revision to decimal-string tokens and role/format text values expected by GUI #271: INPUT, GROUP, FX_RETURN, MONITOR, MAIN; MONO/STEREO. Golden C++ tests now include >2^53 numeric preservation. This helper is a **control-thread DTO** only. It neither emits JUCE JSON nor supplies actual device pins, VST3 state, callback ownership or hardware sound, which remain ENGINE #266's integration responsibility.
106 changes: 97 additions & 9 deletions integration/ConsoleNativeContractV6.h
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@
#include "../engine/core/DynamicAcceptedSession.h"
#include <algorithm>
#include <cstdint>
#include <limits>
#include <span>
#include <string_view>
#include <string>
#include <utility>
#include <vector>
Expand All @@ -22,7 +25,7 @@ struct ConsoleIntentV6 final {
patchInput, patchOutput, addChannel, groupSelected, addFxReturn,
setInsert, setSend, setMix, recallShow
};
std::uint64_t requestId=0; // monotonic per live connection; never a strip index
std::string requestId; // Opaque per-WebView-session token, echoed exactly in ACK.
std::uint64_t deviceEpoch=0,baseGraphRevision=0,baseRosterRevision=0;
Operation operation=Operation::patchInput;
ChannelId target{};
Expand All @@ -33,14 +36,27 @@ enum class IntentFaultV6 : std::uint8_t {
staleGraph, staleRoster
};

// This is a preflight ONLY. The real JUCE control writer applies the native
// intent and returns ACK. lastCompletedId comes from that writer: do not
// mutate it here, or attempt to ACK a draft UI edit.
// The GUI sends an opaque string ('gui...:sequence'). Numeric <= comparison
// between different GUI incarnations is INVALID; an old editor reconnect can
// legally send a lower sequence. The existing native control writer owns a
// bounded recently-completed request-ID cache and supplies a VIEW of it here.
// This function does not retain IDs, emit ACK, create DSP or change the graph.
// Reject malformed IDs before they enter native diagnostic logs.
inline bool validConsoleRequestId(std::string_view id) noexcept {
if(id.empty() || id.size()>128)return false;
return std::all_of(id.begin(),id.end(),[](unsigned char ch) noexcept {
return ch>=0x21 && ch<=0x7e;
});
}
inline IntentFaultV6 validateConsoleIntent(
const ConsoleIntentV6& intent,std::uint64_t actualDeviceEpoch,
std::uint64_t lastCompletedId,const DynamicAcceptedSession& accepted) noexcept {
if(!intent.requestId)return IntentFaultV6::invalidRequest;
if(intent.requestId<=lastCompletedId)return IntentFaultV6::duplicateOrOldRequest;
std::span<const std::string_view> completedRequestIds,
const DynamicAcceptedSession& accepted) noexcept {
if(!validConsoleRequestId(intent.requestId))
return IntentFaultV6::invalidRequest;
if(std::find(completedRequestIds.begin(),completedRequestIds.end(),
std::string_view(intent.requestId))!=completedRequestIds.end())
return IntentFaultV6::duplicateOrOldRequest;
if(!actualDeviceEpoch || intent.deviceEpoch!=actualDeviceEpoch)
return IntentFaultV6::staleDevice;
if(intent.baseGraphRevision!=accepted.acceptedGraphRevision())
Expand All @@ -50,9 +66,29 @@ inline IntentFaultV6 validateConsoleIntent(
return IntentFaultV6::none;
}

// ChannelId is a native uint64 but a JSON string, *never* JavaScript Number.
// Reject malformed/overflowed/noncanonical identities instead of sending an
// intent to a guessed strip ordinal. Caller verifies this ID exists in the
// exact accepted native graph before authorizing a command.
inline bool parseNativeChannelId(std::string_view token,ChannelId& out) noexcept {
if(token.empty() || (token.size()>1 && token.front()=='0'))return false;
std::uint64_t value=0;
for(const char ch:token) {
if(ch<'0'||ch>'9')return false;
const auto digit=static_cast<std::uint64_t>(ch-'0');
if(value>(std::numeric_limits<std::uint64_t>::max()-digit)/10u)
return false;
value=value*10u+digit;
}
if(value==0)return false; // Zero is the explicit unconnected OUT sentinel.
out=ChannelId{value};return true;
}


struct ConsoleAckV6 final {
enum class Status : std::uint8_t { acceptedGraph, rejected };
std::uint64_t requestId=0,deviceEpoch=0,graphRevision=0,rosterRevision=0;
std::string requestId; // Must match user's opaque intent byte-for-byte.
std::uint64_t deviceEpoch=0,graphRevision=0,rosterRevision=0;
Status status=Status::rejected;
IntentFaultV6 preflight=IntentFaultV6::none;
DynamicAcceptedSession::Fault nativeFault=DynamicAcceptedSession::Fault::none;
Expand All @@ -65,7 +101,7 @@ struct ConsoleAckV6 final {
inline ConsoleAckV6 consoleAckFromNative(
const ConsoleIntentV6& intent,IntentFaultV6 preflight,
const DynamicAcceptedSession& accepted,
const DynamicAcceptedSession::Result* nativeResult=nullptr) noexcept {
const DynamicAcceptedSession::Result* nativeResult=nullptr) {
ConsoleAckV6 ack;
ack.requestId=intent.requestId;ack.deviceEpoch=intent.deviceEpoch;
ack.graphRevision=accepted.acceptedGraphRevision();
Expand All @@ -78,6 +114,10 @@ inline ConsoleAckV6 consoleAckFromNative(
ack.status=ConsoleAckV6::Status::acceptedGraph;
return ack; // Never claim productionCallbackLive here.
}
inline std::string_view consoleWireAckStatus(const ConsoleAckV6& ack) noexcept {
return ack.status==ConsoleAckV6::Status::acceptedGraph
?std::string_view{"ACCEPTED"}:std::string_view{"REJECTED"};
}

struct ConsoleSendV6 final {
std::string destinationId; // Decimal string avoids JS Number precision loss.
Expand Down Expand Up @@ -127,6 +167,7 @@ inline bool projectAcceptedConsoleV6(
const DynamicAcceptedSession& native,std::uint64_t deviceEpoch,
std::uint64_t exactGraphRevision,
ConsoleAcceptedReadbackV6& destination) {
// GUI v6 uses canonical decimal-string uint64 revisions and BigInt.
if(!deviceEpoch || !exactGraphRevision ||
native.acceptedGraphRevision()!=exactGraphRevision)return false;
const auto* view=native.acceptedRouting(deviceEpoch,exactGraphRevision);
Expand Down Expand Up @@ -157,4 +198,51 @@ inline bool projectAcceptedConsoleV6(
destination=std::move(next);
return true;
}

inline std::string_view consoleWireRole(ChannelRole role) noexcept {
switch(role) {
case ChannelRole::input: return "INPUT";
case ChannelRole::group: return "GROUP";
case ChannelRole::fxReturn: return "FX_RETURN";
case ChannelRole::monitor: return "MONITOR";
case ChannelRole::main: return "MAIN";
}
return "UNKNOWN";
}
struct ConsoleWireChannelV6 final {
std::string id,role,processingFormat,name,primaryOutId;
std::vector<ConsoleSendV6> sends;
std::size_t primaryInputCount=0,parallelSendInputCount=0;
bool sourcePinVerified=false,actualPcmPresent=false;
};
struct ConsoleWireReadbackV6 final {
std::uint32_t schemaVersion=6;
std::string deviceEpoch,graphRevision,rosterRevision,mainId,monitorId;
std::vector<ConsoleWireChannelV6> channels;
ProductionCapabilitiesV6 capabilities{};
bool productionCallbackLive=false;
};
// Control-only serialization model, NOT a device, JSON emitter or audio renderer.
inline ConsoleWireReadbackV6 toConsoleWireReadbackV6(
const ConsoleAcceptedReadbackV6& a) {
ConsoleWireReadbackV6 out;
out.deviceEpoch=std::to_string(a.deviceEpoch);
out.graphRevision=std::to_string(a.graphRevision);
out.rosterRevision=std::to_string(a.rosterRevision);
out.mainId=a.mainId;out.monitorId=a.monitorId;
out.capabilities=a.capabilities;out.productionCallbackLive=a.productionCallbackLive;
out.channels.reserve(a.channels.size());
for(const auto& c:a.channels) {
ConsoleWireChannelV6 ch;
ch.id=c.id;ch.role=std::string(consoleWireRole(c.role));
ch.processingFormat=c.format==ProcessingFormat::mono?"MONO":"STEREO";
ch.name=c.name;ch.primaryOutId=c.primaryOutId;ch.sends=c.sends;
ch.primaryInputCount=c.primaryInputCount;
ch.parallelSendInputCount=c.parallelSendInputCount;
ch.sourcePinVerified=c.sourcePinVerified;
ch.actualPcmPresent=c.actualPcmPresent;
out.channels.push_back(std::move(ch));
}
return out;
}
} // namespace armix::integration
78 changes: 72 additions & 6 deletions tests/console_native_integration_test.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@
#include <cassert>
#include <cmath>
#include <cstdint>
#include <limits>
#include <string_view>
#include <vector>

using namespace armix::mixer;
Expand Down Expand Up @@ -70,20 +72,62 @@ int main() {
assert(!snap.productionCallbackLive);
assert(!snap.capabilities.universalLive());
assert(!snap.capabilities.group&&!snap.capabilities.fxReturn);
const auto firstWire=toConsoleWireReadbackV6(snap);
assert(firstWire.schemaVersion==6 && firstWire.deviceEpoch=="69");
assert(firstWire.graphRevision=="2" && firstWire.rosterRevision=="2");
assert(firstWire.channels[6].id==std::to_string(ch7.value));
assert(firstWire.channels[6].role=="INPUT");
assert(firstWire.channels[6].processingFormat=="MONO");
assert(!firstWire.productionCallbackLive);
auto huge=snap;
huge.deviceEpoch=std::numeric_limits<std::uint64_t>::max();
huge.graphRevision=9007199254740993ULL;
const auto encoded=toConsoleWireReadbackV6(huge);
assert(encoded.deviceEpoch=="18446744073709551615");
assert(encoded.graphRevision=="9007199254740993");

ConsoleIntentV6 intent;
intent.requestId=41;intent.deviceEpoch=epoch;
intent.requestId="gui-live:41";intent.deviceEpoch=epoch;
intent.baseGraphRevision=2;intent.baseRosterRevision=2;
intent.operation=ConsoleIntentV6::Operation::groupSelected;
intent.target=ch7;
assert(validateConsoleIntent(intent,epoch,40,native)==IntentFaultV6::none);
assert(validateConsoleIntent(intent,epoch,41,native)==IntentFaultV6::duplicateOrOldRequest);
assert(validateConsoleIntent(intent,epoch+1,40,native)==IntentFaultV6::staleDevice);
// Multiple WebViews can coexist/reconnect. Dedup by opaque request ID,
// NOT by numeric sequence: 'gui-new:1' remains valid after 'gui-old:41'.
const std::array<std::string_view,2> completedIds{
"gui-old:41","gui-live:40"};
const std::array<std::string_view,3> completedIncluding{
"gui-live:41","gui-old:41","gui-live:40"};
assert(validateConsoleIntent(intent,epoch,completedIds,native)==IntentFaultV6::none);
assert(validateConsoleIntent(intent,epoch,completedIncluding,native)
==IntentFaultV6::duplicateOrOldRequest);
assert(validateConsoleIntent(intent,epoch+1,completedIds,native)
==IntentFaultV6::staleDevice);
intent.baseGraphRevision=1;
assert(validateConsoleIntent(intent,epoch,40,native)==IntentFaultV6::staleGraph);
assert(validateConsoleIntent(intent,epoch,completedIds,native)
==IntentFaultV6::staleGraph);
intent.baseGraphRevision=2;intent.baseRosterRevision=1;
assert(validateConsoleIntent(intent,epoch,40,native)==IntentFaultV6::staleRoster);
assert(validateConsoleIntent(intent,epoch,completedIds,native)
==IntentFaultV6::staleRoster);
intent.baseRosterRevision=2;
intent.requestId="gui-new:1";
assert(validateConsoleIntent(intent,epoch,completedIds,native)==IntentFaultV6::none);
intent.requestId="gui-live:41";
assert(validConsoleRequestId(intent.requestId));
intent.requestId="gui\nbad:42";
assert(validateConsoleIntent(intent,epoch,completedIds,native)
==IntentFaultV6::invalidRequest);
intent.requestId=std::string(129,'x');
assert(validateConsoleIntent(intent,epoch,completedIds,native)
==IntentFaultV6::invalidRequest);
intent.requestId="gui-live:41";
ChannelId parsed{};
assert(parseNativeChannelId("18446744073709551615",parsed) &&
parsed.value==std::numeric_limits<std::uint64_t>::max());
assert(!parseNativeChannelId("18446744073709551616",parsed));
assert(!parseNativeChannelId("ch-07",parsed));
assert(!parseNativeChannelId("07",parsed));
assert(!parseNativeChannelId("0",parsed));
assert(parseNativeChannelId(std::to_string(ch7.value),parsed) && parsed==ch7);

std::array<float,32> a{},b{},left{},right{},ml{},mr{};
a.fill(.2f);b.fill(.4f);
Expand All @@ -108,6 +152,8 @@ int main() {
assert(!stale.ok());
auto nack=consoleAckFromNative(intent,IntentFaultV6::none,native,&stale);
assert(nack.status==ConsoleAckV6::Status::rejected);
assert(nack.requestId==intent.requestId);
assert(consoleWireAckStatus(nack)=="REJECTED");
assert(nack.graphRevision==2 && !nack.productionCallbackLive);
const auto prev=snap;
assert(!projectAcceptedConsoleV6(native,epoch+1,2,snap));
Expand All @@ -121,11 +167,23 @@ int main() {
group=added.edit.createdIds[0];
auto ack=consoleAckFromNative(intent,IntentFaultV6::none,native,&added);
assert(ack.status==ConsoleAckV6::Status::acceptedGraph);
assert(ack.requestId=="gui-live:41");
assert(consoleWireAckStatus(ack)=="ACCEPTED");
assert(ack.graphRevision==3 && !ack.productionCallbackLive);
assert(projectAcceptedConsoleV6(native,epoch,3,snap));
assert(find(snap,ch7)->primaryOutId==std::to_string(group.value));
assert(find(snap,ch2)->primaryOutId==std::to_string(group.value));
assert(find(snap,group)->primaryInputCount==2);
const auto groupWire=toConsoleWireReadbackV6(snap);
// The accepted roster order is NOT the operator display order. Resolve
// the actual accepted ChannelId, never assume a newly added bus is last.
const auto groupWireIt=std::find_if(groupWire.channels.begin(),
groupWire.channels.end(),[&](const auto& c) {
return c.id==std::to_string(group.value);
});
assert(groupWireIt!=groupWire.channels.end());
assert(groupWireIt->role=="GROUP" &&
groupWireIt->primaryInputCount==2);
assert(render()&&approx(left[31],(.2f+.4f)*center*2.f));
assert(approx(ml[31],(.2f*.2f+.4f*.3f)*center));

Expand All @@ -139,6 +197,14 @@ int main() {
assert(liveCh7 && liveCh7->primaryOutId==std::to_string(group.value));
assert(liveCh7->sends.size()==2); // MONITOR remains, wet SEND added
assert(find(snap,wet)->parallelSendInputCount==1);
const auto returnWire=toConsoleWireReadbackV6(snap);
const auto returnWireIt=std::find_if(returnWire.channels.begin(),
returnWire.channels.end(),[&](const auto& c) {
return c.id==std::to_string(wet.value);
});
assert(returnWireIt!=returnWire.channels.end());
assert(returnWireIt->role=="FX_RETURN" &&
returnWireIt->parallelSendInputCount==1);
assert(render());
assert(approx(left[31],(.2f+.4f)*center*2.f+.2f*center*.25f*.5f));
assert(approx(ml[31],(.2f*.2f+.4f*.3f)*center));
Expand Down
Loading