Q-W1 pt2: core/shell/app relocation + sub-namespaces; one concrete ui::Rect (LTRB fork retired); slot_map split from bank_book; BankIndex→BankModel; 59/59 green
This commit is contained in:
@@ -0,0 +1,253 @@
|
||||
#pragma once
|
||||
// sample_usage — the pure core of the pS-usage seam: ReaSampler 9000 instances count
|
||||
// as USAGE for the prune. Each live instance PUBLISHES the captures it holds (its v10
|
||||
// SampleRefs — sample ids + project-relative paths) to a per-instance project ext-state
|
||||
// key ("rsusage_<instanceGuid>", see ext_keys.h); the EXTENSION reads every usage record
|
||||
// at prune-scan time, keeps only the records backed by a live ReaSampler 9000 FX
|
||||
// instance, and folds the surviving paths into the prune's `referenced` set — so a file
|
||||
// any live instance holds can never be an orphan and BANK_PRUNE_FOLDER can never
|
||||
// delete it.
|
||||
//
|
||||
// PURE MODULE (CLAUDE.md §load-bearing split): NO REAPER types, NO VST3, NO SWELL,
|
||||
// NO vendor/ includes. Standard library only. The mirror of assignment_request (the
|
||||
// other VST<->extension ext-state wire): the wire format AND the two safety-critical
|
||||
// decisions (what to write on publish, which records count at prune time) live here so
|
||||
// they are provable without a DAW. The shells only move strings.
|
||||
//
|
||||
// -- The data-ownership boundary (load-bearing) -------------------------------
|
||||
//
|
||||
// The INSTRUMENT writes usage keys; the EXTENSION reads them. This is the ONE sanctioned
|
||||
// instrument->ext-state write (Daniel's ruling: "if that means the VST writes to the
|
||||
// bridge when it grabs a capture, so be it") and it does NOT weaken the read-only-BANK
|
||||
// invariant: the instrument publishes its OWN usage under its OWN per-instance key,
|
||||
// and never touches banks/view/tail/assign or any other extension-owned key. The bridge
|
||||
// enforces this structurally — its write entry point accepts only "rsusage_"-prefixed keys.
|
||||
//
|
||||
// -- THE SAFETY PROPERTY (overrides every other consideration) -----------------
|
||||
//
|
||||
// The un-prunable guarantee is a SAFETY property: every failure, ambiguity, or
|
||||
// uncertainty in this seam must FAIL-SAFE toward PROTECT. Over-protection (prune skips a
|
||||
// reclaimable file, or refuses to run at all) is an acceptable residual; under-protection
|
||||
// (deleting a file an instance may still be playing) is a data-loss bug. Three fail-safe
|
||||
// folds live in this pure module so they are provable without a DAW:
|
||||
// * sibling-collision -> UNION, never clean-replace over a foreign writer (ownerNonce);
|
||||
// * zero-identified -> records exist but NO instance was identified live -> protect
|
||||
// ALL records' paths (an identity-matcher failure must never
|
||||
// degrade toward delete);
|
||||
// * unreadable record -> ABORT the prune entirely (foldUsageRecords.abortPrune — a
|
||||
// record we cannot read may protect anything; halting deletes
|
||||
// nothing). Residual: readReasamplerExtState returning nullopt
|
||||
// for a >16 MB value is indistinguishable from "absent" at the
|
||||
// publish site — that narrow case takes the fresh-write branch
|
||||
// (not remint), noted here for completeness.
|
||||
//
|
||||
// -- Liveness (no stale-key false-protect, no false-delete) --------------------
|
||||
//
|
||||
// A usage record must protect exactly the captures of instances that still EXIST. Two
|
||||
// rejected designs shape the rules below:
|
||||
// * NO teardown clearing. The obvious "clear my key in terminate()" is WRONG here:
|
||||
// REAPER destroys the plugin instance when an FX is set OFFLINE — including the
|
||||
// extension's own Design View CPU-park (per-FX offline on inactive-mode tracks). A
|
||||
// terminate-time clear would strip the record of an instance that still exists in
|
||||
// the project, opening a prune-deletes-a-used-file window. Records are therefore
|
||||
// never cleared by the instrument; staleness is resolved by the EXTENSION at read
|
||||
// time against the live FX enumeration.
|
||||
// * NO challenge/response. Instances only poll ext-state on the EDITOR's UI timer
|
||||
// (pollBankSync); a closed-editor instance could never answer a prune-time
|
||||
// challenge, and its holds would be false-deleted. Publishing is therefore EAGER
|
||||
// (on load + on every play-set change via reloadInstrument), and liveness is
|
||||
// decided extension-side.
|
||||
//
|
||||
// The liveness rule (usageHeldPaths): a record counts iff the track it was published
|
||||
// from still exists AND that track still hosts at least one ReaSampler 9000 FX
|
||||
// instance (offline FX included — chain enumeration is chunk-level, so a parked
|
||||
// instance still protects its holds). A record whose track GUID could not be resolved
|
||||
// at publish time (empty) counts while ANY ReaSampler 9000 instance exists in the
|
||||
// project — the fail-safe fallback. And the identity-failure net: when records exist
|
||||
// but ZERO instances were identified live anywhere, EVERY record's paths are protected
|
||||
// (see the safety property above — indistinguishable from a matcher failure, so it may
|
||||
// never resolve toward delete). Residuals: a deleted instance whose track still hosts a
|
||||
// sibling 9000 keeps its record alive, and a project whose instances were all deleted
|
||||
// keeps its leftover records protecting until an instance is identified again — both
|
||||
// false-PROTECT only, bounded, documented, accepted.
|
||||
//
|
||||
// -- Identity & the copy problem (planUsagePublish) -----------------------------
|
||||
//
|
||||
// The publishing key is a minted per-instance GUID persisted in ComponentState (v11).
|
||||
// A persisted id is inherently COPYABLE (FX copy / track duplication clones component
|
||||
// state byte-for-byte), so two live instances can wake up sharing one key. Worse, two
|
||||
// same-track copies converge on byte-identical wires, so "existing == what I last
|
||||
// wrote" is NOT a sound ownership test — a sibling's byte-identical write would pass
|
||||
// it, and a later clean replace would silently drop the sibling's holds (the delete
|
||||
// direction). TWO in-wire facts close this:
|
||||
// * ownerNonce — a per-LIFETIME nonce minted fresh in memory each instance lifetime,
|
||||
// NEVER persisted (a persisted nonce would clone with the state, recreating the
|
||||
// ambiguity). Proves "exactly this incarnation wrote the key last".
|
||||
// * unioned — a STICKY multi-writer poison flag. "I wrote the key last" does NOT
|
||||
// imply "the key contains only my holds": after I union a sibling's holds under my
|
||||
// own nonce, a later nonce-matching clean replace would drop them. So the first
|
||||
// union sets unioned=true in the wire, and a unioned record REFUSES clean replace
|
||||
// forever — every subsequent write is a union (holds only accumulate). Over-protect
|
||||
// residual, accepted; a solo never-restarted instance keeps clean-replace
|
||||
// semantics, and a remint starts a fresh un-poisoned key.
|
||||
// The publish plan resolves every collision in the fail-safe direction:
|
||||
// * existing ownerNonce == mine AND not unioned -> clean replace (sole writer,
|
||||
// provably my content; holds the instance released genuinely drop).
|
||||
// * same track with a foreign nonce, OR unioned -> UNION of holds, written with
|
||||
// unioned=true (a same-track sibling, my own last-session record, or a
|
||||
// multi-writer key; nothing may be dropped — over-protects, never under-protects).
|
||||
// * foreign nonce, DIFFERENT track, not unioned-by-me -> RE-MINT (a cross-track copy
|
||||
// or move; the newcomer takes a fresh identity and leaves the original's record
|
||||
// untouched; a moved-away original's old record dies by the liveness rule).
|
||||
|
||||
#include <optional>
|
||||
#include <string>
|
||||
#include <unordered_set>
|
||||
#include <vector>
|
||||
|
||||
namespace reasampler::wire {
|
||||
|
||||
// One held capture: the bank sample id (attribution/debugging) + the project-relative
|
||||
// WAV path (the prune-protection payload — compared by EXACT string against the prune
|
||||
// core's `present` spelling, which both sides source from the same bank-blob spelling).
|
||||
struct UsageHold {
|
||||
std::string sampleId;
|
||||
std::string relativePath;
|
||||
|
||||
bool operator==(const UsageHold& o) const {
|
||||
return sampleId == o.sampleId && relativePath == o.relativePath;
|
||||
}
|
||||
};
|
||||
|
||||
// One instance's published usage: the REAPER track GUID it was hosted on at publish
|
||||
// time ("{...}" canonical form; empty when the host context could not resolve one), the
|
||||
// writing incarnation's per-LIFETIME ownerNonce (the exact "did I write this?" ownership
|
||||
// discriminator — see the copy-problem note above; never persisted in ComponentState),
|
||||
// the sticky multi-writer `unioned` poison flag (once true, clean replace is refused
|
||||
// forever — see the note above), plus every capture it holds. The record is
|
||||
// self-contained — the extension needs nothing from the instance beyond this value and
|
||||
// the live FX enumeration.
|
||||
struct UsageRecord {
|
||||
std::string trackGuid;
|
||||
std::string ownerNonce;
|
||||
bool unioned = false;
|
||||
std::vector<UsageHold> holds;
|
||||
|
||||
bool operator==(const UsageRecord& o) const {
|
||||
return trackGuid == o.trackGuid && ownerNonce == o.ownerNonce &&
|
||||
unioned == o.unioned && holds == o.holds;
|
||||
}
|
||||
};
|
||||
|
||||
// Encode a usage record to the wire string. Length-prefixed fields behind a magic tag
|
||||
// ("rsusage1"), the same idiom as assignment_request / provenance, so arbitrary bytes
|
||||
// in a GUID or path round-trip whole. Deterministic.
|
||||
//
|
||||
// FORMAT: "rsusage1" <len>':'<trackGuid> <len>':'<ownerNonce> <len>':'<unioned "0"|"1">
|
||||
// <len>':'<holdCount-decimal> then per hold: <len>':'<sampleId> <len>':'<relativePath>
|
||||
std::string encodeUsageRecord(const UsageRecord& rec);
|
||||
|
||||
// Parse a wire string produced by encodeUsageRecord. std::nullopt on malformed /
|
||||
// truncated / trailing-garbage input (never UB, never a partial value). The prune scan
|
||||
// treats an undecodable record as UNREADABLE and ABORTS (foldUsageRecords) — it must
|
||||
// never proceed with protection it cannot read.
|
||||
std::optional<UsageRecord> decodeUsageRecord(const std::string& wire);
|
||||
|
||||
// The publish decision computed BEFORE a write (see the identity note above).
|
||||
// * remint — true when the existing key value belongs to a live foreign instance
|
||||
// on another track: the caller must mint a fresh instance GUID and
|
||||
// write under the NEW key, leaving the existing record untouched.
|
||||
// * skipWrite — true when the write would change nothing that matters: byte-identical
|
||||
// to the existing value (idle reload tick), or a union over an
|
||||
// ALREADY-unioned record that adds no holds (the write would flip only
|
||||
// the ownerNonce — redundant ext-state churn, skipped; a false->true
|
||||
// unioned flip is never skipped, it is the multi-writer poison).
|
||||
// * wire — the encoded value to write (mine, or the same-track union).
|
||||
struct UsagePublishPlan {
|
||||
bool remint = false;
|
||||
bool skipWrite = false;
|
||||
std::string wire;
|
||||
};
|
||||
|
||||
// Decide what to write for `mine` given the key's current value. `mine.ownerNonce` is
|
||||
// THIS lifetime's nonce; `mine.unioned` is ignored (the plan computes the written
|
||||
// flag). Branches, in order:
|
||||
// * existing absent/empty -> write mine (unioned=false — sole known writer).
|
||||
// * existing undecodable -> REMINT (mine, unioned=false, under a fresh key)
|
||||
// rather than overwriting the corrupt key: overwriting would clear the prune-side
|
||||
// abort, leaving a same-key sibling's holds unprotected until it republishes.
|
||||
// Leaving the corrupt key in place keeps the prune-side abort (foldUsageRecords)
|
||||
// firing so no delete-ward window opens. The sibling writes its own decodable
|
||||
// record on the next publish tick; the corrupt key is eventually evicted once no
|
||||
// live instance references it. Narrow gap: a >16 MB value reads back as nullopt
|
||||
// (indistinguishable from absent), so it takes the fresh-write branch rather than
|
||||
// remint — both outcomes are safe; the gap is noted in the header's fail-safe list.
|
||||
// * nonce match AND !unioned -> clean replace (sole writer, provably my content;
|
||||
// released holds drop); skipWrite when
|
||||
// byte-identical (idle reload tick).
|
||||
// * same track OR unioned -> union(existing.holds, mine.holds), existing-first,
|
||||
// de-duped, written with unioned=TRUE under my
|
||||
// nonce — a sibling's holds are NEVER dropped. The
|
||||
// false->true unioned flip is ALWAYS written (it is
|
||||
// the poison that blocks the last writer's future
|
||||
// clean replace); skipWrite only when the existing
|
||||
// record is already unioned AND the union adds no
|
||||
// holds (the write would change nonce only).
|
||||
// * else (foreign, other track) -> remint = true, write mine (fresh un-poisoned key).
|
||||
UsagePublishPlan planUsagePublish(const std::optional<std::string>& existing,
|
||||
const UsageRecord& mine);
|
||||
|
||||
// The prune-side liveness fold: every project-relative path held by a LIVE instance,
|
||||
// de-duped, in (record, hold) input order. A record counts iff
|
||||
// * its trackGuid is non-empty and present in `liveTrackGuids` (a track that still
|
||||
// exists AND still hosts >= 1 ReaSampler 9000 FX — the caller's enumeration), OR
|
||||
// * its trackGuid is empty and `anyInstanceLive` is true (the fail-safe fallback for
|
||||
// a record published without a resolvable track context).
|
||||
// FAIL-SAFE NET (the safety property): when `records` is non-empty and
|
||||
// `anyInstanceLive` is false — records exist but NOT ONE instance was identified
|
||||
// anywhere — EVERY record's paths are returned (protect-all). Zero identified with
|
||||
// records present is indistinguishable from an identity-matcher failure, and a matcher
|
||||
// failure must never resolve toward delete. (Residual: leftover records in a project
|
||||
// whose instances were all genuinely deleted keep protecting — false-PROTECT only.)
|
||||
// Holds with an empty relativePath are skipped (nothing to protect).
|
||||
std::vector<std::string> usageHeldPaths(
|
||||
const std::vector<UsageRecord>& records,
|
||||
const std::unordered_set<std::string>& liveTrackGuids,
|
||||
bool anyInstanceLive);
|
||||
|
||||
// The prune-side entry fold over RAW read/decode results, one element per enumerated
|
||||
// rsusage_* key: nullopt = the key was present but could not be read or decoded
|
||||
// (oversized ext-state read, truncation, corruption). ANY nullopt sets abortPrune —
|
||||
// the prune must HALT and delete nothing (an unreadable record may protect anything;
|
||||
// proceeding with degraded protection is the delete direction). Otherwise delegates to
|
||||
// usageHeldPaths (including its protect-all net).
|
||||
struct UsageFoldResult {
|
||||
bool abortPrune = false;
|
||||
std::vector<std::string> heldPaths;
|
||||
};
|
||||
UsageFoldResult foldUsageRecords(
|
||||
const std::vector<std::optional<UsageRecord>>& decoded,
|
||||
const std::unordered_set<std::string>& liveTrackGuids,
|
||||
bool anyInstanceLive);
|
||||
|
||||
// FX-identity match for the live-instance enumeration (pure so the matcher itself is
|
||||
// testable; the shell only supplies REAPER's identity strings). `identity` is the value
|
||||
// of an FX's "fx_ident" or "original_name" named-config parm; the three needles are the
|
||||
// UPPERCASED channel constants:
|
||||
// * uidHexUpper — the 32-hex VST3 class UID (instrument_drop::vstClassIdHex),
|
||||
// * nameUpper — the factory display name ("REASAMPLER 9000"),
|
||||
// * outputNameUpper— the .vst3 module filename base ("REASAMPLER_9000") — the form
|
||||
// fx_ident is guaranteed to embed (it carries the module path),
|
||||
// which the space-separated display name can never match.
|
||||
// Substring, case-insensitive. NOTE the deliberate beta-substring over-protect: the
|
||||
// stable needles are substrings of the beta ones ("REASAMPLER 9000" ⊂ "REASAMPLER 9000
|
||||
// BETA", "REASAMPLER_9000" ⊂ "REASAMPLER_9000_BETA"), so a stable extension scanning a
|
||||
// project with beta instances matches them too — a WIDER protected set only (fail-safe;
|
||||
// it can never cause a delete).
|
||||
bool identityMatches(const std::string& identity, const std::string& uidHexUpper,
|
||||
const std::string& nameUpper, const std::string& outputNameUpper);
|
||||
|
||||
// ASCII-only uppercase (shared by the matcher and the shell's needle preparation).
|
||||
std::string toUpperAscii(const std::string& s);
|
||||
|
||||
} // namespace reasampler::wire
|
||||
Reference in New Issue
Block a user