Cut shell/actions, bank_ops, app comment bloat ~48% (comments only, zero code change)

src/ext_keys.h

@@ -1,36 +1,27 @@
 #pragma once
 // ext_keys — the SINGLE SOURCE OF TRUTH for the "reasampler" project ext-state
 // namespace + key names, shared by the extension (writer, via shell/persist) and the
-// VST3 instrument (reader, via the bridge). Both sides include this header so the
-// wire contract cannot drift between the two artifacts (the S4 reviewer flagged the
-// spike's duplicated constants as a drift risk).
+// VST3 instrument (reader, via the bridge), so the wire contract cannot drift
+// between the two artifacts.
 //
-// PURE HEADER: NO REAPER types, NO VST3 types, NO SWELL, NO vendor/ includes. The key
-// spellings are string constants; the NAMESPACE is channel-derived (Phase V, V4) so it
-// delegates to the pure app_version module (also REAPER-free / VST3-free). Both the
-// REAPER-facing persist shell and the SDK-facing VST bridge include this without pulling
-// either SDK.
+// PURE HEADER: NO REAPER/VST3/SWELL/vendor types. Key spellings are string
+// constants; the namespace is channel-derived (delegates to app_version, also SDK-free).
 //
 // FOREVER-STABLE once shipped: these strings key every already-saved project's
-// stored state. Changing any of them orphans that state. See shell/persist/ext_state_io.h for the
-// per-key retirement / migration semantics — this header only owns the spellings.
+// stored state. Changing any of them orphans that state. See
+// shell/persist/ext_state_io.h for per-key retirement/migration semantics.
 
 #include "core/version/app_version.h"
 
 namespace reasampler {
 
-// The ext-state namespace all ReaSampler project state is stored under. CHANNEL-DERIVED
-// (Phase V, V4): delegates to the ONE app_version symbol so the extension (writer) and the
-// VST3 instrument (reader) resolve the SAME namespace per channel — "reasampler" on stable,
-// "reasampler_beta" on the isolated beta build. An accessor (not a constexpr literal)
-// because the value is fixed by the channel bit at build time. This is the wire-contract
-// reconciliation between S4 (shared ext_keys) and V4 (channel-isolated namespace): without
-// it a beta instrument would read the stable namespace and see empty state.
+// Channel-derived so the extension (writer) and the VST3 instrument (reader)
+// resolve the SAME namespace per channel ("reasampler" / "reasampler_beta") —
+// without this a beta instrument would read the stable namespace and see nothing.
 inline const char* kProjExtNamespace() { return version::extStateNamespace().c_str(); }
 
-// The multi-bank key: the whole serialized BankBook (pool + named banks). This is
-// the key the VST3 instrument reads to see the live bank (read-only, S4). ext_state_io
-// documents its authority + the legacy-key migration around it.
+// The whole serialized BankBook (pool + named banks) — read-only by the VST3
+// instrument. ext_state_io documents the legacy-key migration around it.
 inline constexpr const char* kProjExtBanksKey = "banks";
 
 // The retired legacy single-bank key (read once on load to migrate into the pool).
@@ -45,48 +36,34 @@ inline constexpr const char* kProjExtTailKey = "tail_setting";
 // The per-project minted-GUID identity key.
 inline constexpr const char* kProjExtGuidKey = "project_guid";
 
-// The S9 BANK-GENERATION key. The EXTENSION stamps a monotonic decimal counter here that it
-// bumps on every bank-content mutation that changes what a live instance would PLAY (capture
-// add, re-capture-in-place, sample remove, move/copy affecting banks, ingest import). The VST3
-// instrument READS it off the audio thread on a UI-timer cadence and, when the value differs
-// from what it last saw, calls reloadInstrument() so a recapture/ingest refreshes playing
-// instances hands-free (the S9 change-detection trigger). WIRE-SHARED (instrument reads it);
-// the instrument never WRITES it (the extension owns it, same read-only-over-bank rule as the
-// assignment request). Additive to the persist blob — an absent stamp reads as generation 0
-// (a pre-S9 project), and the first bump (>= 1) then reads as a change. FOREVER-STABLE once
-// shipped: changing this spelling resets every already-shipped instance's change-detection
-// baseline (a one-time spurious reload), so it is fixed like every sibling key.
+// The EXTENSION stamps a monotonic counter here, bumped on every bank-content
+// mutation that changes what a live instance would PLAY. The VST3 instrument reads
+// it on a UI-timer cadence and calls reloadInstrument() on a change; it never
+// writes this key. Additive: an absent stamp reads as generation 0 (pre-existing
+// projects). FOREVER-STABLE — changing the spelling resets every shipped instance's
+// change-detection baseline (a one-time spurious reload).
 inline constexpr const char* kProjExtBankGenKey = "bank_generation";
 
-// The S8 ingest ASSIGNMENT-REQUEST key. The EXTENSION writes an assignment request here
-// after an ingest-with-assign (arrange capture / Media-Explorer import / drop-onto-panel):
-// "the active sampler instance should now play THIS sample." The value is the pure
-// assignment_request wire format ("rsassign1" + bankId + sampleId + generation) — see
-// assignment_request.h for the exact grammar. WIRE-SHARED because the VST3 instrument
-// READS it (in a later dispatch, S8 instrument-side follow-up) to update its own selection
-// and reload; the instrument never WRITES it (the extension writing its own namespace does
-// not violate the instrument's read-only-over-the-bank rule). FOREVER-STABLE once shipped:
-// changing this spelling strands any pending request an already-shipped instrument watches.
+// The EXTENSION writes an assignment request here after an ingest-with-assign:
+// "the active sampler instance should now play THIS sample." Value is the pure
+// assignment_request wire format ("rsassign1" + bankId + sampleId + generation).
+// The instrument reads it to update its own selection and reload; it never writes
+// it. FOREVER-STABLE — changing the spelling strands any pending request an
+// already-shipped instrument watches.
 inline constexpr const char* kProjExtAssignKey = "assign_request";
 
-// The pS-usage PER-INSTANCE USAGE-RECORD key prefix. The INSTRUMENT writes one key per
-// instance — "rsusage_<instanceGuid>" — carrying the sample_usage wire record of every
-// capture that instance holds; the EXTENSION enumerates the prefix at prune-scan time
-// and folds live instances' holds into the prune's `referenced` set so a held capture
-// can never be pruned. This is the ONE sanctioned instrument-side ext-state write
-// (Daniel's ruling — the VST publishes its OWN usage; it never mutates banks/view/
-// tail/assign, and the bridge's write entry point structurally accepts only this
-// prefix). WIRE-SHARED in the write->read direction the other keys reverse. The "rs"
-// qualifier is deliberate: a future key that happens to start with "usage_" must never
-// be swept into the FX-liveness fold (whose abort-on-unreadable rule would then halt
-// every prune), so the prefix is namespaced like the wire magics (rsusage1/rsassign1).
-// FOREVER-STABLE once shipped: changing the prefix strands every saved project's usage
-// records (prune falls back to bank-references-only until instances republish —
-// graceful, but the instance-hold protection lapses for stale-saved projects).
+// The INSTRUMENT writes one key per instance — "rsusage_<instanceGuid>" — carrying
+// the sample_usage wire record of every capture that instance holds; the EXTENSION
+// enumerates the prefix at prune-scan time so a held capture can never be pruned.
+// This is the ONE sanctioned instrument-side ext-state write (it never mutates
+// banks/view/tail/assign; the bridge's write entry point structurally accepts only
+// this prefix). The "rs" qualifier keeps a future "usage_*"-prefixed key from being
+// swept into the FX-liveness fold. FOREVER-STABLE — changing the prefix strands
+// every saved project's usage records (prune falls back to bank-references-only
+// until instances republish).
 inline constexpr const char* kProjExtUsageKeyPrefix = "rsusage_";
 
-// The full per-instance usage key for a minted instance GUID (the one composition
-// point, shared by the instrument's writer and the extension's enumerator).
+// Shared by the instrument's writer and the extension's enumerator.
 inline std::string usageKeyFor(const std::string& instanceGuid) {
     return std::string(kProjExtUsageKeyPrefix) + instanceGuid;
 }