From fd54118e91c151e6c2195fc1218af2cf61a0c92c Mon Sep 17 00:00:00 2001 From: Ari Sulistiono Date: Thu, 29 Oct 2026 06:40:51 +0700 Subject: [PATCH] P4: versioned four-AUX native snapshot persistence and verified return FX states --- docs/P4_NATIVE_SHOW_STORE_STAGE2_20261029.md | 9 +- src/NativeShowSchema.h | 149 +++++++++++++++---- src/NativeShowStore.h | 42 ++++-- tests/native_show_schema_test.cpp | 42 +++++- tests/native_show_store_test.cpp | 19 ++- 5 files changed, 219 insertions(+), 42 deletions(-) diff --git a/docs/P4_NATIVE_SHOW_STORE_STAGE2_20261029.md b/docs/P4_NATIVE_SHOW_STORE_STAGE2_20261029.md index cc306b4be..cef682cde 100644 --- a/docs/P4_NATIVE_SHOW_STORE_STAGE2_20261029.md +++ b/docs/P4_NATIVE_SHOW_STORE_STAGE2_20261029.md @@ -1,6 +1,6 @@ # P4 stage 2 — Native Studio/Shows transactional generation store -**Status:** Engine-independent storage implementation; not yet wired to a live SAVE/RECALL button. +**Status:** Engine-independent storage with versioned 10-INPUT/4-AUX snapshots; not yet wired to a live SAVE/RECALL button. ## Source and boundaries - `src/NativeShowStore.h` owns CONTROL/IO-thread `commit(show,snapshots,vendorBlobs)` and `load(showId)`. The application must call it with its normal `PortableWorkspace::dataRoot()` (already `Studio/` in portable mode). All files land under `Studio/Shows//`. @@ -10,6 +10,13 @@ - Policy caps per generation: 64 snapshots, 128 supplied blobs, 8 MiB per VST3 binary, 128 MiB of assembled data. This is deliberately narrower than the standalone schema limit of 256 snapshots. Future scalable manifests need paging before raising these limits. - `StudioBackup` already enumerates all ordinary files in Studio, so each Show HEAD/generation is included in the same independent SHA256-verified USB backup. `tests/studio_backup_test.cpp` now asserts it. Browser cache and diagnostics remain excluded. +## P1K AUX return storage extension (snapshot schema version 3) +- Ten INPUT source strips stay distinct from exactly four additional AUX stereo FX return lanes, identified `aux-001` through `aux-004`; each persists enabled, MAIN flag, mute, linear gain, and ordered vendor FX references. +- Up to 32 input-only `auxSends` persist source CH0..9, destination AUX0..3, PRE/POST, gain 0..1 and pan -1..1. The decoder rejects duplicate (source,destination,tap), disabled destination, invalid gain/pan and malformed/partial AUX arrays. No AUX feedback path is expressible. +- Newly encoded snapshots are **schemaVersion 3**; Show metadata stays V2. The `SnapshotV2` C++ DTO remains source-compatible but now serializes version 3. Older version 2 snapshots lacking AUX fields decode with all returns inactive. Version 2 payloads carrying AUX data are *rejected*: older executables must not silently drop AUX on re-save. +- INPUT and AUX VST3 state references share SHA256, UID, catalog identity and bypass validation. `NativeShowStore` refuses missing AUX bytes *before disk writes* and verifies every distinct referenced blob *before replacing loaded outputs*. Tests exercise corrupt FX, route rejection, legacy migration, rollback and portable backup. +- The extension is **not** live audio state capture/recall. Plugin state capture thread, device preflight and application of a prepared graph remain separate gates. + ## Failure and recovery notes - Retired generations are kept for recovery; lifecycle pruning and disk quota UI still require a later implementation. An unsuccessful HEAD replacement may leave an orphan version which is not automatically loaded. - JUCE stream flush plus same-directory temporary replacement is not a guarantee against every sudden power-loss sequence; verified journaling/OS fsync policies and Windows fault injection remain future production gates. diff --git a/src/NativeShowSchema.h b/src/NativeShowSchema.h index 2cad38272..df4a70d3b 100644 --- a/src/NativeShowSchema.h +++ b/src/NativeShowSchema.h @@ -11,6 +11,8 @@ namespace armix::shows { constexpr int channels = 10; +constexpr int auxReturns = 4; // physical input strips are not consumed by AUX +constexpr int maxAuxSendsPerSnapshot = 32; constexpr int maxFxPerStrip = 8; constexpr int maxSendsPerSnapshot = 32; constexpr int maxSnapshotsPerShow = 256; @@ -35,10 +37,24 @@ struct Strip final { std::vector fx; std::vector sends; }; +// AUX is an extra, one-way stereo FX return, not INPUT CH9/10 or hardware I/O. +struct AuxReturn final { + bool enabled = false, toMaster = true, mute = false; + double gain = 1.0; + std::vector fx; +}; +struct AuxSend final { + int source = -1; // physical logical INPUT 0..9 + int destination = -1; // dedicated AUX 0..3 + bool preFader = false; + double gain = 0.25, pan = 0.0; +}; struct SnapshotV2 final { juce::String id, name, sourceBuild; juce::int64 createdMs = 0, modifiedMs = 0; std::array strips{}; + std::array aux{}; + std::vector auxSends; double masterGain = 1.0, masterPan = 0.0; bool masterMute = false, masterMono = false; }; @@ -119,9 +135,10 @@ inline void commonWrite(juce::var& v, const juce::String& id, inline juce::String encode(const juce::var& v) { return juce::JSON::toString(v, true); } -inline bool header(const juce::var& v,const char* format) { +inline bool header(const juce::var& v,const char* format, + int minVersion=2,int maxVersion=2) { int schema=0; juce::String kind; - return v.isObject() && integer(get(v,"schemaVersion"),schema,2,2) && + return v.isObject() && integer(get(v,"schemaVersion"),schema,minVersion,maxVersion) && str(get(v,"format"),kind,64) && kind==format; } } // namespace detail @@ -143,6 +160,9 @@ class Codec final { static juce::String encode(const SnapshotV2& s) { auto v=detail::object(); detail::commonWrite(v,s.id,s.name,s.createdMs,s.modifiedMs); + // V3 is mandatory for AUX-aware snapshots: old V2 readers must fail + // closed instead of silently dropping four AUX returns on re-save. + detail::put(v,"schemaVersion",3); detail::put(v,"format","arsonmix.native.snapshot"); detail::put(v,"sourceBuild",s.sourceBuild); auto master=detail::object(); @@ -159,13 +179,8 @@ class Codec final { detail::put(c,"fader",ch.fader);detail::put(c,"pan",ch.pan); detail::put(c,"mute",ch.mute);detail::put(c,"solo",ch.solo); detail::put(c,"toMaster",ch.toMaster); - juce::Array fx, sends; - for(const auto& f:ch.fx) { - auto p=detail::object(); - detail::put(p,"catalogId",f.catalogId);detail::put(p,"uid",f.uid); - detail::put(p,"stateSha256",f.stateSha256);detail::put(p,"bypass",f.bypass); - fx.add(p); - } + const auto fx=encodeFx(ch.fx); + juce::Array sends; for(const auto& se:ch.sends) { auto p=detail::object(); detail::put(p,"destination",se.destination); @@ -177,6 +192,29 @@ class Codec final { strips.add(c); } detail::put(v,"strips",juce::var(strips)); + juce::Array aux, auxSends; + for(int i=0;i(i)]; + auto rec=detail::object(); + detail::put(rec,"id","aux-"+juce::String(i+1).paddedLeft('0',3)); + detail::put(rec,"enabled",bus.enabled); + detail::put(rec,"toMaster",bus.toMaster); + detail::put(rec,"mute",bus.mute); + detail::put(rec,"gain",bus.gain); + detail::put(rec,"fx",juce::var(encodeFx(bus.fx))); + aux.add(rec); + } + for(const auto& send:s.auxSends) { + auto rec=detail::object(); + detail::put(rec,"source",send.source); + detail::put(rec,"destination",send.destination); + detail::put(rec,"preFader",send.preFader); + detail::put(rec,"gain",send.gain); + detail::put(rec,"pan",send.pan); + auxSends.add(rec); + } + detail::put(v,"auxReturns",juce::var(aux)); + detail::put(v,"auxSends",juce::var(auxSends)); return detail::encode(v); } // Decode is transactional: an invalid record never mutates the caller's @@ -195,7 +233,7 @@ class Codec final { static bool decode(const juce::String& json,SnapshotV2& out) { if(json.getNumBytesAsUTF8()>maxJsonBytes) return false; const auto v=juce::JSON::parse(json); - if(!detail::header(v,"arsonmix.native.snapshot")) return false; + if(!detail::header(v,"arsonmix.native.snapshot",2,3)) return false; SnapshotV2 next; if(!detail::common(v,next.id,next.name,next.createdMs,next.modifiedMs) || !detail::str(detail::get(v,"sourceBuild"),next.sourceBuild,80,false)) @@ -231,23 +269,9 @@ class Codec final { (ch.source==2 && (ch.inputA<0||ch.inputB<0||ch.inputA==ch.inputB))) return false; const auto fxv=detail::get(rec,"fx"), sv=detail::get(rec,"sends"); - const auto* fx=fxv.getArray(); const auto* sends=sv.getArray(); - if(!fx||!sends||fx->size()>maxFxPerStrip || - (totalSends+=sends->size())>maxSendsPerSnapshot) return false; - for(const auto& p:*fx) { - FxRef f; - if(!p.isObject() || - !detail::str(detail::get(p,"catalogId"),f.catalogId,512) || - !detail::integer(detail::get(p,"uid"),f.uid,-2147483647,2147483647) || - !detail::str(detail::get(p,"stateSha256"),f.stateSha256,64) || - !detail::flag(detail::get(p,"bypass"),f.bypass) || - f.stateSha256.length()!=64) return false; - for(auto chHex:f.stateSha256.toStdString()) - if(!((chHex>='a'&&chHex<='f')||(chHex>='A'&&chHex<='F')|| - (chHex>='0'&&chHex<='9'))) return false; - ch.fx.push_back(std::move(f)); - } + if(!sends || (totalSends+=sends->size())>maxSendsPerSnapshot || + !decodeFx(fxv,ch.fx)) return false; for(const auto& p:*sends) { Send send; if(!p.isObject() || @@ -260,9 +284,82 @@ class Codec final { ch.sends.push_back(send); } } + // Existing stage-1 V2 records without AUX keys remain readable. A + // partially provided AUX record is never accepted silently. + const auto auxv=detail::get(v,"auxReturns"); + const auto auxsv=detail::get(v,"auxSends"); + int version=0; + if(!detail::integer(detail::get(v,"schemaVersion"),version,2,3)) + return false; + if(version==2) { + if(!auxv.isVoid() || !auxsv.isVoid()) return false; + out=std::move(next); return true; + } + const auto* aux=auxv.getArray(); + const auto* sends=auxsv.getArray(); + if(!aux || !sends || aux->size()!=auxReturns || + sends->size()>maxAuxSendsPerSnapshot) return false; + for(int i=0;i(i)]; + const auto& rec=aux->getReference(i); + juce::String id; + if(!rec.isObject() || + !detail::str(detail::get(rec,"id"),id,7) || + id!="aux-"+juce::String(i+1).paddedLeft('0',3) || + !detail::flag(detail::get(rec,"enabled"),bus.enabled) || + !detail::flag(detail::get(rec,"toMaster"),bus.toMaster) || + !detail::flag(detail::get(rec,"mute"),bus.mute) || + !detail::real(detail::get(rec,"gain"),bus.gain,0.0,4.0) || + !decodeFx(detail::get(rec,"fx"),bus.fx)) return false; + } + for(const auto& rec:*sends) { + AuxSend send; + if(!rec.isObject() || + !detail::integer(detail::get(rec,"source"),send.source,0,channels-1) || + !detail::integer(detail::get(rec,"destination"),send.destination,0,auxReturns-1) || + !detail::flag(detail::get(rec,"preFader"),send.preFader) || + !detail::real(detail::get(rec,"gain"),send.gain,0.0,1.0) || + !detail::real(detail::get(rec,"pan"),send.pan,-1.0,1.0) || + !next.aux[static_cast(send.destination)].enabled) + return false; + for(const auto& previous:next.auxSends) + if(previous.source==send.source && previous.destination==send.destination && + previous.preFader==send.preFader) return false; + next.auxSends.push_back(send); + } out=std::move(next); return true; } private: + static juce::Array encodeFx(const std::vector& fx) { + juce::Array encoded; + for(const auto& f:fx) { + auto rec=detail::object(); + detail::put(rec,"catalogId",f.catalogId); + detail::put(rec,"uid",f.uid); + detail::put(rec,"stateSha256",f.stateSha256); + detail::put(rec,"bypass",f.bypass); + encoded.add(rec); + } + return encoded; + } + static bool decodeFx(const juce::var& value,std::vector& out) { + const auto* fx=value.getArray(); + if(!fx || fx->size()>maxFxPerStrip) return false; + for(const auto& p:*fx) { + FxRef f; + if(!p.isObject() || + !detail::str(detail::get(p,"catalogId"),f.catalogId,512) || + !detail::integer(detail::get(p,"uid"),f.uid,-2147483647,2147483647) || + !detail::str(detail::get(p,"stateSha256"),f.stateSha256,64) || + !detail::flag(detail::get(p,"bypass"),f.bypass) || + f.stateSha256.length()!=64) return false; + for(auto chHex:f.stateSha256.toStdString()) + if(!((chHex>='a'&&chHex<='f')||(chHex>='A'&&chHex<='F')|| + (chHex>='0'&&chHex<='9'))) return false; + out.push_back(std::move(f)); + } + return true; + } static bool decodeShowArrays(const juce::var& v,ShowV2& next,ShowV2& out) { const auto orderV=detail::get(v,"snapshotOrder"); const auto safesV=detail::get(v,"channelSafes"); diff --git a/src/NativeShowStore.h b/src/NativeShowStore.h index a64b62346..87a7ab2f4 100644 --- a/src/NativeShowStore.h +++ b/src/NativeShowStore.h @@ -60,11 +60,16 @@ class NativeShowStore final { std::set suppliedHashes; for(const auto& blob:blobs) suppliedHashes.insert(blob.sha256.toLowerCase()); - for(const auto& snap:snapshots) + for(const auto& snap:snapshots) { for(const auto& strip:snap.strips) for(const auto& fx:strip.fx) if(suppliedHashes.find(fx.stateSha256.toLowerCase())==suppliedHashes.end()) return "Missing vendor state for "+fx.catalogId; + for(const auto& aux:snap.aux) + for(const auto& fx:aux.fx) + if(suppliedHashes.find(fx.stateSha256.toLowerCase())==suppliedHashes.end()) + return "Missing AUX vendor state for "+fx.catalogId; + } if(!root_.isDirectory() && root_.createDirectory().failed()) return "Studio Shows directory is not writable"; const auto showRoot=root_.getChildFile(show.id.toLowerCase()); @@ -177,20 +182,31 @@ class NativeShowStore final { !snap.id.equalsIgnoreCase(id))return "Invalid snapshot metadata"; total+=file.getSize(); if(total>maxGenerationBytes)return "Generation too large"; + // The same hash verification policy applies to INPUT and AUX FX. + // No partially readable Show is ever returned to the caller. + const auto checkState=[&](const FxRef& fx)->juce::String { + if(!validHash(fx.stateSha256))return "Unsafe state hash"; + const auto blobFile=dir.getChildFile("blobs").getChildFile( + fx.stateSha256.toLowerCase()+".bin"); + if(!blobFile.existsAsFile()||blobFile.getSize()>maxBlobBytes) + return "Missing/oversized vendor state"; + if(verifiedHashes.insert(fx.stateSha256.toLowerCase()).second) { + total+=blobFile.getSize(); + if(total>maxGenerationBytes) return "Generation exceeds read budget"; + if(!juce::SHA256(blobFile).toHexString().equalsIgnoreCase(fx.stateSha256)) + return "Vendor binary hash mismatch"; + } + return {}; + }; for(const auto& strip:snap.strips) for(const auto& fx:strip.fx) { - if(!validHash(fx.stateSha256))return "Unsafe state hash"; - const auto file=dir.getChildFile("blobs").getChildFile(fx.stateSha256.toLowerCase()+".bin"); - if(!file.existsAsFile()||file.getSize()>maxBlobBytes) - return "Missing/oversized vendor state"; - // Count and hash every unique immutable blob once, even if - // many FX snapshots intentionally reference the same state. - if(verifiedHashes.insert(fx.stateSha256.toLowerCase()).second) { - total+=file.getSize(); - if(total>maxGenerationBytes) return "Generation exceeds read budget"; - if(!juce::SHA256(file).toHexString().equalsIgnoreCase(fx.stateSha256)) - return "Vendor binary hash mismatch"; - } + const auto error=checkState(fx); + if(error.isNotEmpty())return error; + } + for(const auto& aux:snap.aux) + for(const auto& fx:aux.fx) { + const auto error=checkState(fx); + if(error.isNotEmpty())return error; } candidate.push_back(std::move(snap)); } diff --git a/tests/native_show_schema_test.cpp b/tests/native_show_schema_test.cpp index e4d77b0b6..d00fc2dfd 100644 --- a/tests/native_show_schema_test.cpp +++ b/tests/native_show_schema_test.cpp @@ -49,6 +49,12 @@ int main() { }); snap.strips[0].sends.push_back({5,true,0.4,-0.1}); snap.strips[6].solo=true;snap.strips[6].toMaster=false; + // Four AUX return lanes exist IN ADDITION to all ten input strips. + snap.aux[0].enabled=true;snap.aux[0].gain=0.82; + snap.aux[0].fx.push_back({"vault:aux-reverb",1234,juce::String::repeatedString("b",64),false}); + snap.aux[3].enabled=true;snap.aux[3].mute=true; + snap.auxSends.push_back({0,0,true,0.25,-0.2}); + snap.auxSends.push_back({6,3,false,0.75,0.3}); snap.masterGain=0.65;snap.masterMono=true; const auto encoded=Codec::encode(snap); SnapshotV2 loaded; @@ -59,6 +65,11 @@ int main() { assert(loaded.strips[0].sends[0].preFader); assert(loaded.strips[6].solo&&!loaded.strips[6].toMaster); assert(loaded.masterMono); + assert(loaded.aux[0].enabled && loaded.aux[0].gain==0.82); + assert(loaded.aux[0].fx.size()==1 && loaded.aux[0].fx[0].uid==1234); + assert(loaded.aux[3].enabled && loaded.aux[3].mute); + assert(loaded.auxSends.size()==2 && loaded.auxSends[0].preFader); + assert(loaded.auxSends[1].source==6 && loaded.auxSends[1].destination==3); auto broken=snap; broken.strips[0].fx[0].stateSha256="not-a-digest"; @@ -75,8 +86,37 @@ int main() { broken=snap;broken.strips[0].source=0; assert(!Codec::decode(Codec::encode(broken),loaded)); assert(!Codec::decode(juce::String::repeatedString("x",maxJsonBytes+1),loaded)); + // AUX corruption/rejection must not replace the last accepted record. + broken=snap;broken.aux[0].gain=5; + assert(!Codec::decode(Codec::encode(broken),loaded)); + broken=snap;broken.aux[0].fx[0].stateSha256="not-hash"; + assert(!Codec::decode(Codec::encode(broken),loaded)); + broken=snap;broken.auxSends[0].destination=4; + assert(!Codec::decode(Codec::encode(broken),loaded)); + broken=snap;broken.aux[0].enabled=false; + assert(!Codec::decode(Codec::encode(broken),loaded)); + broken=snap;broken.auxSends.push_back(broken.auxSends[0]); + assert(!Codec::decode(Codec::encode(broken),loaded)); + broken=snap;broken.auxSends.resize(maxAuxSendsPerSnapshot+1); + assert(!Codec::decode(Codec::encode(broken),loaded)); + // Compatible older V2 snapshot without the AUX extension: all AUX off. + auto legacy=juce::JSON::parse(encoded); + legacy.getDynamicObject()->removeProperty("auxReturns"); + legacy.getDynamicObject()->removeProperty("auxSends"); + legacy.getDynamicObject()->setProperty("schemaVersion",2); + assert(Codec::decode(juce::JSON::toString(legacy),loaded)); + assert(!loaded.aux[0].enabled && loaded.auxSends.empty()); + // Never allow AUX-bearing data to masquerade as V2; older clients would + // otherwise silently discard it when saving the Show. + auto downgrade=juce::JSON::parse(encoded); + downgrade.getDynamicObject()->setProperty("schemaVersion",2); + assert(!Codec::decode(juce::JSON::toString(downgrade),loaded)); + auto partial=juce::JSON::parse(encoded); + partial.getDynamicObject()->removeProperty("auxSends"); + assert(!Codec::decode(juce::JSON::toString(partial),loaded)); + assert(!loaded.aux[0].enabled && loaded.auxSends.empty()); assert(loaded.name=="Soundcheck 01"); - std::cout << "PASS: bounded ShowV2/SnapshotV2 JSON round-trips, 10CH references, safes, corrupted records, rollback\n"; + std::cout << "PASS: bounded ShowV2/SnapshotV2 JSON round-trips, 10 INPUT + 4 AUX, PRE/POST, FX hashes, legacy V2 decode, rollback\n"; return 0; } diff --git a/tests/native_show_store_test.cpp b/tests/native_show_store_test.cpp index 19305f7ac..cd882f492 100644 --- a/tests/native_show_store_test.cpp +++ b/tests/native_show_store_test.cpp @@ -37,8 +37,16 @@ int main() { blob.bytes.append(bytes,sizeof(bytes)); blob.sha256=juce::SHA256(blob.bytes).toHexString(); snap.strips[0].fx.push_back({"TestVendor|195",195,blob.sha256,false}); + // Separate AUX VST state is part of the immutable transaction. + BinaryState auxBlob; + const char auxBytes[]={'a','u','x','r','e','v','e','r','b',0,3}; + auxBlob.bytes.append(auxBytes,sizeof(auxBytes)); + auxBlob.sha256=juce::SHA256(auxBlob.bytes).toHexString(); + snap.aux[0].enabled=true;snap.aux[0].gain=0.6; + snap.aux[0].fx.push_back({"AuxReverb|202",202,auxBlob.sha256,false}); + snap.auxSends.push_back({0,0,true,0.35,0.0}); std::vector snapshots={snap}; - std::vector blobs={blob}; + std::vector blobs={blob,auxBlob}; const auto firstCommitError=store.commit(show,snapshots,blobs); if(firstCommitError.isNotEmpty()) std::cerr<<"initial Show commit failed: "< missingAux={blob}; + assert(store.commit(show,snapshots,missingAux).isNotEmpty()); + assert(store.currentGeneration(show.id)==first); + // Prepared show cannot reference snapshots not in the transaction. ShowV2 badShow=show; badShow.snapshotOrder.clear();