Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
36 commits
Select commit Hold shift + click to select a range
5dc4f8f
feat(io3a): publish truthful secondary ASIO capture readback to appro…
masarray Nov 19, 2026
5c067aa
test(io3a): include string_view explicitly for portable readback stat…
masarray Nov 19, 2026
9834622
merge(io3a): inherit IO-2D qualified .smix durability guard without l…
masarray Nov 19, 2026
e54d647
fix(io3a): defer approved UI changes until generated /preview/ bundle…
masarray Nov 19, 2026
348432a
merge(io3a): retain native readback while inheriting IO-2D graph-reti…
masarray Nov 19, 2026
7c829df
fix(io3a): require fresh real ASRC PCM windows, not successful primin…
masarray Nov 19, 2026
0a378d4
fix(io3a): use recent valid ASRC frames and capture freshness for nat…
masarray Nov 19, 2026
d7aab5c
test(io3a): reproduce real ASRC priming silence and stale capture clo…
masarray Nov 19, 2026
a99c0e0
test(io3a): verify new-lease usable frame delta instead of same cumul…
masarray Nov 19, 2026
ccaaedf
feat(io3b): validate exact typed secondary ASIO capture intent agains…
masarray Nov 19, 2026
85a1321
feat(io3b): route typed explicit ASIO B install through existing cons…
masarray Nov 19, 2026
ac9aacc
test(io3b): canonical ChannelId A/B capture intent, stale epoch, dupl…
masarray Nov 19, 2026
7ded941
merge(io3b): inherit reconciled main GUI and IO2D host without changi…
masarray Nov 19, 2026
014b3d6
fix(io3b): correlate accepted B capture ACK to installed exact PCM an…
masarray Nov 19, 2026
fd657b5
fix(io3b): accept existing opaque v8 session requestIds; keep replay …
masarray Nov 19, 2026
3a21046
merge(io3b): reconcile typed B capture control with exact qualified A…
masarray Nov 19, 2026
dcd1aed
fix(io3b): bind capture install request targetChannelId to installed …
masarray Nov 19, 2026
2572342
test(io3b): exact B-source target and opaque v8 requestId, reject mis…
masarray Nov 19, 2026
d702d01
docs(io3b): exact native capture request/ACK contract and explicit un…
masarray Nov 19, 2026
4517b3f
merge(io3): reconcile native B CONTROL/readback with latest N-MOD Dev…
masarray Nov 20, 2026
bb749fe
fix(io3a): forward real ASIO B readback into approved native console …
masarray Nov 20, 2026
c8c8a46
merge(io3): retain IO2D multi-restart recovery, immutable B source re…
masarray Nov 20, 2026
8a79992
feat(io3c): correlate ASIO B ACK to later hardware lease readback in …
masarray Nov 20, 2026
af40b8e
test(io3c): reject ACK-only B sound and mismatched later driver/pin/e…
masarray Nov 20, 2026
cc5145c
docs(io3c): record exact native B ACK+later v8 lease readback and rem…
masarray Nov 20, 2026
8ebe0a2
feat(io3d): advertise Device B intent only from verified disarmed ASI…
masarray Nov 20, 2026
60a54b3
feat(io3d): publish qualified Device B request capability from native…
masarray Nov 20, 2026
51659f0
fix(io3d): reject Device B control commands absent from exact native …
masarray Nov 20, 2026
856b74c
test(io3d): fail-closed Device B capability, replay, disarmed ASIO an…
masarray Nov 20, 2026
a44a86e
fix(io3d): keep capability regression on mutable approved snapshot
masarray Nov 20, 2026
8e098f0
fix(io3d): whitelist actual pinned ASIO class proof before offering B…
masarray Nov 20, 2026
ceab365
test(io3d): verify only native pinned ASIO registration may expose B op
masarray Nov 20, 2026
21d2143
feat(io3d): fail closed invalid Device B intents before one native AC…
masarray Nov 20, 2026
05f2ac0
test(io3d): negative GUI B source request matrix without driver open …
masarray Nov 20, 2026
a916cab
merge(io3): reconcile verified IO-2E cross-epoch native recovery into…
masarray Nov 20, 2026
e9d6797
docs(io3d): reconcile native B capability and contract guards with IO…
masarray Nov 20, 2026
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
Original file line number Diff line number Diff line change
@@ -0,0 +1,85 @@
# IO-3B — Typed secondary ASIO capture control (native-only integration contract)

**Scope:** approved ArSonMix `/preview/` **single** v8 console request/ACK/readback transport; Windows JUCE primary ASIO A plus one independently-clocked input-only ASIO B. **Not yet an operator-facing GUI or physical FAT result.** Cross-workstream source: [multi-device ARD](../ARD_ARSONMIX_MULTI_DEVICE_IO_V2_20261118.md), [coordination #812](https://github.com/masarray/arsonmix/issues/812).

## Native command (implemented source boundary, not enabled in published picker)

```json
{
"operation":"INSTALL_SECONDARY_CAPTURE",
"requestId":"<one existing v8 session requestId>",
"deviceEpoch":"91",
"baseGraphRevision":"25",
"baseRosterRevision":"9",
"targetChannelId":"9007199254740993",
"payload":{
"confirmed":true,
"secondaryDriver":"<exact selected verified ASIO capture driver name>",
"secondaryInputPins":[0,7],
"captureRate":44100,
"capturePeriod":128,
"sources":[
{"channelId":"9007199254740993","deviceRole":"SECONDARY",
"leftPhysical":7,"rightPhysical":-1,"stereo":false}
]
}
}
```

All IDs are **canonical uint64 decimal strings**; do not round through JavaScript Number. `targetChannelId` must be an installed INPUT that is actually assigned to B in the `sources` list. Every source row must refer to an exact installed ChannelId and a selected, observed native **physical** input index (not a dense JUCE callback ordinal). `secondaryInputPins` must be unique, sorted, 1–16 channels and within supported driver bit bounds. `PRIMARY` input rows, when needed to preserve currently accepted A channels, use the accepted A physical mask. Incomplete A/B rows are rejected by the native qualified graph compiler.

The native CONTROL decoder `integration/QualifiedCaptureConsoleIntent.h` checks the exact installed public graph, matching internal nativeBus revision/roster, operator confirmation, requestId and input roles. The one `Main.cpp::handleApprovedNativeControl` dispatcher invokes `LiveAudioEngine::installSecondaryAsioCapture`, which **rechecks** actual ASIO driver identity, registration class, current A/B pins, negotiated sample rate/buffer and native leases before publishing one ChannelId PCM/FX owner. Outputs must already be disarmed; **no speaker is auto-armed**.

## ACK and later readback

The existing `arMixConsoleAck` replies with requestId, `status` ACCEPTED/REJECTED, errorCode and installed deviceEpoch/graphRevision/rosterRevision. Native controller also includes `secondaryCapture` diagnostics (driver, physical mask, generation, lease, clock and fault) on this operation. ACK acceptance requires verified installed B capture readback, not merely driver `open()` success, and `productionCallbackLive` / `sourceAudibleProven` remain **false**. The approved consumer must request a *later* `arMixConsoleSnapshot` and verify the same B identity, mask, epoch, lease, ChannelId map and advanced graph revision. `WAITING_FOR_PCM` and `PCM_FLOW_OBSERVED` are native diagnostics, **not proof that the assigned channel is audible**; priming/underflow frames do not count as B PCM.

**IO-3C controller milestone (implemented, fast tested):** The existing `web/approved-native-contract.js::readbackProvesIntent` now recognizes `INSTALL_SECONDARY_CAPTURE`, but only when a previously correlated native `arMixConsoleAck` supplied the exact installed Device B lease and a **later independent** `arMixConsoleSnapshot.secondaryCapture` matches driver class/name, verified physical mask, capture generation, device lease, epoch, rate and period. `WAITING_FOR_PCM` is a valid *installed but not yet flowing* state, **never proof of audible ChannelId signal**. The test in `tests/approved_native_m2_contract.test.cjs` covers stale/forged ACK, wrong mask, mismatched lease, mismatched driver and failure to publish optimistic PCM. Fast UI, Fast Native, M1–M2 and ImerSip P9 PASS for commit `af40b8e7`. The public `/preview/` Source Picker still does not expose this operation; **the user cannot yet activate B in the GUI**. IO-3D conditionally advertises `INSTALL_SECONDARY_CAPTURE` on the real native snapshot only for an admitted, pinned ASIO callback with output disarmed, idle CONTROL state and unconfigured/remappable B. This is an offer to start a transaction, **not** proof that B is installed, available or audible. Follow-up must deliver the approved operator UI with verified driver inventory, capability, canonical Pages generation and full Chromium/Windows tests. No second WebView event bus or standalone preview.

## IO-3D — fail-closed native capability and GUI contract (implemented on draft #830)

The one `Main.cpp::approvedNativeSnapshot` now calls
`publishQualifiedSecondaryCaptureCapability` from
`integration/ApprovedNativeRuntimeSnapshot.h`. It exposes the existing v8
`INSTALL_SECONDARY_CAPTURE` operation only when the installed ChannelId
callback owns the same graph, the primary is exact pinned/attested ASIO,
MAIN/MONITOR output is disarmed, no independent WASAPI render clock is active,
the primary physical input mask exists, the B map is not already installed,
and control-side device/session/graph operations are idle. An arbitrary
browser intent is rejected by the **native** decoder unless this capability
is currently installed; the engine still rechecks device masks and lease
identities before any B driver open.

The pure `web/approved-native-contract.js::validQualifiedCaptureRequest`
guards the same public command preflight against malformed driver names, rate
or period, unsorted/duplicate B pins, nonexistent/stale INPUT ChannelIds,
unselected physical A/B pins, duplicate source rows and mono/stereo
inconsistency. Invalid requests are refused without emitting
`arMixConsoleIntent` or mutating accepted graph/PCM. Tests:
`tests/approved_native_v8_projection_test.cpp` (actual native capability
projection/denials) and `tests/approved_native_m2_contract.test.cjs`
(positive lease matching and invalid-intent no-emit matrix). These are
source-level and control contract proofs, **not** two-device physical FAT.

`IO-2E` parent #825 adds retained qualified A+B lease retirement across
primary device epochs: only an explicit output-disarmed A-only session
replacement retires the old B map; implicit cross-epoch commits are rejected.
The device binding is independently verified before the restore.

Current PR stack: #825 is the native foundation; draft #830 is based on its
latest native HEAD and owns this typed command/readback. Parent Windows
exact-HEAD requalification and child Windows/Chromium qualification must be
verified separately before promotion.

## Persistence, fallback and hardware qualification

Current v1 `.smix` cannot store both physical driver identities/pins. While a qualified A+B graph is installed, Save/autosave is intentionally **rejected before replacing the last known-good file**. Explicit loading of a saved primary-only `.smix` now uses `QualifiedMapChange::replaceWithPrimaryOnly` under a fully muted native transaction, returning to direct A PCM and retiring the B capture reader **only after** successful publication; WIRE/FX-only edits continue inheriting the exact qualified B map. This is a safe temporary guard, not an IO-5 persistence implementation.

Real simultaneous two-vendor ASIO input PCM, CLI driver open constraints, Windows installer, latency and hardware FAT remain **NOT RUN**. The synthetic native fixtures prove graph/ASRC policy, not hardware compatibility or actual acoustic performance. Independently routed BUS/CH Device B output remains a future scope, not the existing WASAPI MAIN mirror.

## Required follow-up

1. Parent IO-2D #825 exact-head Windows MSVC/CTest + Codex + protected Required CI Gate, then merge.
2. Reconcile stacked #830 with *latest main*, run its own exact-head Windows and approved GUI gates.
3. IO-3C actual compact Device B picker and later accepted readback in existing approved `/preview/` only; regenerate canonical embedded GUI with scripts and test compiled resources.
4. IO-5 durable physical binding schema and offline remap before enabling A+B Save; physical two-vendor ASIO FAT before shipping product capability.
103 changes: 103 additions & 0 deletions engine/device/SecondaryCaptureReadbackState.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <cmath>
#include <cstdint>

// IO-3A: portable CONTROL-thread readback, never an audio renderer or a
// driver-open / source-audibility assertion. All timing is monotonic host time.
namespace armix::device {
enum class SecondaryCaptureReadbackState {
notConfigured, needsRemap, degraded, waitingForPcm, pcmFlowObserved
};

// ASRC renderedFrames counts *all* output, including priming and starvation.
// Only frames with a usable FIR input window represent captured PCM.
// This is playback-time evidence, not proof of an audible ChannelId source.
constexpr std::uint64_t secondaryUsableAsrcFrames(
std::uint64_t rendered, std::uint64_t priming,
std::uint64_t underflow) noexcept {
return rendered>priming && rendered-priming>underflow
? rendered-priming-underflow : 0;
}

// Off-RT stateful freshness guard. A single callback or an old cumulative
// counter cannot keep B labelled "PCM_FLOW_OBSERVED" indefinitely. Observe
// BOTH independent producer progress and genuinely usable ASRC output within
// the same bounded recent interval. Baseline the first observation for each
// native-issued device lease, including after reset or counters wrap.
class SecondaryCaptureFlowEvidence final {
public:
static constexpr double freshnessMs=500.;
std::uint64_t recentUsableFrames(
std::uint64_t deviceLease, std::uint64_t captureBlocks,
std::uint64_t rendered, std::uint64_t priming,
std::uint64_t underflow, double nowMs,
bool admitted) noexcept {
const auto usable=secondaryUsableAsrcFrames(
rendered,priming,underflow);
if(!deviceLease||!std::isfinite(nowMs)||nowMs<0.) {
reset();
return 0;
}
if(deviceLease!=lease_ || captureBlocks<lastCaptureBlocks_ ||
usable<lastUsableFrames_) {
lease_=deviceLease;
lastCaptureBlocks_=captureBlocks;
lastUsableFrames_=usable;
captureProgressMs_=-1.;
usableProgressMs_=-1.;
return 0;
}
if(!admitted) {
lastCaptureBlocks_=captureBlocks;
lastUsableFrames_=usable;
captureProgressMs_=-1.;
usableProgressMs_=-1.;
return 0;
}
if(captureBlocks>lastCaptureBlocks_)captureProgressMs_=nowMs;
if(usable>lastUsableFrames_)usableProgressMs_=nowMs;
lastCaptureBlocks_=captureBlocks;
lastUsableFrames_=usable;
const bool freshCapture=captureProgressMs_>=0. &&
nowMs>=captureProgressMs_ &&
nowMs-captureProgressMs_<=freshnessMs;
const bool freshUsable=usableProgressMs_>=0. &&
nowMs>=usableProgressMs_ &&
nowMs-usableProgressMs_<=freshnessMs;
return freshCapture&&freshUsable?usable:0;
}
void reset() noexcept {
lease_=lastCaptureBlocks_=lastUsableFrames_=0;
captureProgressMs_=usableProgressMs_=-1.;
}
private:
std::uint64_t lease_=0,lastCaptureBlocks_=0,lastUsableFrames_=0;
double captureProgressMs_=-1.,usableProgressMs_=-1.;
};

// The last parameter is RECENT usable ASRC frames, not authorized pull calls.
constexpr SecondaryCaptureReadbackState classifySecondaryCapture(
bool installedMap, bool remapRequired, bool opened,
bool faulted, bool primaryEpochMatches,
std::uint64_t captureBlocks, std::uint64_t recentUsableFrames) noexcept {
if(remapRequired)return SecondaryCaptureReadbackState::needsRemap;
if(!installedMap)return SecondaryCaptureReadbackState::notConfigured;
if(!opened||faulted||!primaryEpochMatches)
return SecondaryCaptureReadbackState::degraded;
if(!captureBlocks||!recentUsableFrames)
return SecondaryCaptureReadbackState::waitingForPcm;
return SecondaryCaptureReadbackState::pcmFlowObserved;
}
constexpr const char* secondaryCaptureStateName(
SecondaryCaptureReadbackState state) noexcept {
switch(state) {
case SecondaryCaptureReadbackState::notConfigured:return "NOT_CONFIGURED";
case SecondaryCaptureReadbackState::needsRemap:return "NEEDS_REMAP";
case SecondaryCaptureReadbackState::degraded:return "DEGRADED";
case SecondaryCaptureReadbackState::waitingForPcm:return "WAITING_FOR_PCM";
case SecondaryCaptureReadbackState::pcmFlowObserved:return "PCM_FLOW_OBSERVED";
}
return "DEGRADED";
}
} // namespace armix::device
67 changes: 67 additions & 0 deletions integration/ApprovedNativeRuntimeSnapshot.h
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,73 @@
// its installed realtime callback owns the accepted publisher/epoch.
// G0/M4 and any forged nativeBus without that predicate MUST stay unadmitted.
namespace armix::console {
// IO-3A: project only genuine native engine status into the ONE approved
// CONTROL snapshot. No browser-selected device, DSP graph or positive LIVE
// state is manufactured by this diagnostic projection.
inline bool projectSecondaryCaptureNativeReadback(
juce::var& approved,const juce::var& live) {
if(!approved.isObject()||!live.isObject()||
!approved.getProperty("device",{}).isObject())return false;
const auto secondary=live.getProperty("secondaryCapture",{});
if(!secondary.isObject() ||
secondary.getProperty("role","").toString()!="INPUT_ONLY_ASIO" ||
!secondary.getProperty("status",{}).isString() ||
!secondary.getProperty("installedInputMap",{}).isBool())return false;
approved.getDynamicObject()->setProperty("secondaryCapture",secondary);
return true;
}

// IO-3D: an installed primary ChannelId callback may *offer* an explicitly
// confirmed Device B capture transaction. The existing native engine is still
// the final authority: offering the op is NOT an ASIO driver compatibility,
// audible PCM, saved session, or physical dual-device FAT claim.
// This only enriches the ONE approved v8 capability array; no extra transport.
inline bool publishQualifiedSecondaryCaptureCapability(
juce::var& approved,const juce::var& live,bool controlIdle) {
if(!controlIdle||!approved.isObject()||!live.isObject())return false;
const auto device=approved.getProperty("device",{});
const auto graph=approved.getProperty("graph",{});
const auto caps=graph.getProperty("capabilities",{});
const auto secondary=live.getProperty("secondaryCapture",{});
if(!device.isObject()||!graph.isObject()||!caps.isObject()||
!secondary.isObject()||
device.getProperty("backend","").toString()!="ASIO"||
device.getProperty("outputArmed",juce::var(true))!=juce::var(false)||
!static_cast<bool>(caps.getProperty("callbackOwnsChannelIds",false))||
!static_cast<bool>(live.getProperty("directRouteAuthorized",false))||
static_cast<bool>(live.getProperty("adaptiveClockActive",true))||
(live.getProperty("asioRegistryAttestation","").toString()!=
"POSTOPEN_REGISTERED_ASIO_DRIVER_CLASS_PINNED" &&
live.getProperty("asioRegistryAttestation","").toString()!=
"SAVED_PREFLIGHT_POSTOPEN_REGISTRATION_CONSISTENT")||
secondary.getProperty("role","").toString()!="INPUT_ONLY_ASIO"||
static_cast<bool>(secondary.getProperty("installedInputMap",true))||
static_cast<bool>(secondary.getProperty("driverReady",true))||
static_cast<bool>(secondary.getProperty("driverFault",true)))
return false;
const auto state=secondary.getProperty("status","").toString();
if(state!="NOT_CONFIGURED"&&state!="NEEDS_REMAP")return false;
const auto pins=device.getProperty("enabledInputs",{});
const auto channels=graph.getProperty("channels",{});
const auto ops=caps.getProperty("supportedOps",{});
if(!pins.isArray()||pins.getArray()->isEmpty()||
!channels.isArray()||!ops.isArray())return false;
bool hasInput=false;
for(const auto& ch:*channels.getArray())
if(ch.getProperty("role","").toString()=="INPUT") {
hasInput=true;break;
}
if(!hasInput)return false;
auto verified=*ops.getArray();
if(!verified.contains(juce::String("INSTALL_SECONDARY_CAPTURE")))
verified.add(juce::String("INSTALL_SECONDARY_CAPTURE"));
if(auto* c=caps.getDynamicObject()) {
c->setProperty("supportedOps",juce::var(verified));
return true;
}
return false;
}

// Legacy M2 counted only device START callbacks; the actual routing epoch
// also advances on STOP. After ASIO/WASAPI re-open they can differ (e.g.,
// G0 start=2 while accepted routing epoch=3). Always use the installed
Expand Down
Loading
Loading