docs: fix overclaiming OriginKind comment and trim restated test comments

Enum comment claimed package-id lookup that no persisted field supports; reworded
to the real distinction. Trimmed CLAUDE.md-duplicated test comments and the header.
This commit is contained in:
2026-08-02 07:24:30 -04:00
parent 35b2a3a151
commit a197ff7d68
2 changed files with 13 additions and 22 deletions
+6 -8
View File
@@ -15,14 +15,12 @@ namespace reasampler::tracking {
// lifted from a legacy path-only manifest, or one whose creator did not know. // lifted from a legacy path-only manifest, or one whose creator did not know.
// PERSISTED AS INTEGERS: never renumber an existing value, only append. // PERSISTED AS INTEGERS: never renumber an existing value, only append.
enum class OriginKind { enum class OriginKind {
Unknown = 0, Unknown = 0,
Capture = 1, Capture = 1,
Ingest = 2, Ingest = 2,
Recapture = 3, // regenerated in place from its recorded source recipe Recapture = 3, // regenerated in place from its recorded source recipe
Resample = 4, // baked from an instrument's own processing chain Resample = 4, // baked from an instrument's own processing chain
// Kept distinct from Ingest — both bring in a foreign file, but only this one PackageImport = 5, // package-sourced vs Ingest's user-picked; unrecoverable once merged
// can answer "which package did this bank come from" later.
PackageImport = 5,
}; };
// One system-created file's birth record. `relativePath` is the key and is ALWAYS // One system-created file's birth record. `relativePath` is the key and is ALWAYS
+7 -14
View File
@@ -1,11 +1,9 @@
// Standalone tests for reasampler::tracking::OriginLedger — no REAPER, no framework. // Standalone tests for reasampler::tracking::OriginLedger — no REAPER, no framework.
// //
// The record family behind file tracking. Covers: the relative-paths-only invariant, // Covers: relative-paths-only, exact-string ownership, dedup, insertion order, the
// exact-string ownership, dedup, insertion order, the JSON round-trip (incl. golden // JSON round-trip (incl. golden bytes over every persisted enum value), the append-a-
// byte literals over every persisted enum value), the append-a-kind-without-moving-"v" // kind rules, the no-backfill rule, the legacy path-only lift, and the Fresh / Loaded
// rule and its degrade-don't-block twin, the no-backfill rule, the legacy path-only // / Unreadable / FutureVersion classification.
// lift, and the Fresh / Loaded / Unreadable / FutureVersion classification that keeps
// never-recorded apart from the two degraded states.
#include "../src/core/tracking/origin_ledger.h" #include "../src/core/tracking/origin_ledger.h"
@@ -187,10 +185,7 @@ static void testSerializeGoldenLiteralPinsEveryPersistedKind() {
CHECK(*back == l); // every field, not just the kind, survives the trip CHECK(*back == l); // every field, not just the kind, survives the trip
} }
// Appending a value to the kind vocabulary must NOT move the document version: the // Pins the emitted "v" byte, not the internal constant — an older build reads bytes.
// two rules sit side by side and pull in opposite directions — an unknown kind
// degrades, an unknown "v" blocks. Pinned on the emitted bytes rather than on the
// internal constant, because the byte is what an older build actually reads.
static void testAppendingAKindDoesNotMoveTheDocumentVersion() { static void testAppendingAKindDoesNotMoveTheDocumentVersion() {
OriginLedger l; OriginLedger l;
l.record(rec("bank/import.wav", OriginKind::PackageImport, "S-e")); l.record(rec("bank/import.wav", OriginKind::PackageImport, "S-e"));
@@ -202,10 +197,8 @@ static void testAppendingAKindDoesNotMoveTheDocumentVersion() {
CHECK(loadLedger("{\"v\":3,\"records\":[]}").status == LedgerStatus::FutureVersion); CHECK(loadLedger("{\"v\":3,\"records\":[]}").status == LedgerStatus::FutureVersion);
} }
// The other half of the append rule: a kind this build does NOT know degrades to // Pins three unrecognized kind values (future, far-future, negative) all landing on
// Unknown while the ledger still loads and the path stays owned. Losing the kind // Unknown with the ledger still Loaded and the path still owned.
// detail costs nothing today — no consumer reads it — but an Unreadable here would
// block prune entirely on nothing worse than a vocabulary gap.
static void testUnknownKindDegradesWithoutBlockingTheLedger() { static void testUnknownKindDegradesWithoutBlockingTheLedger() {
const std::string blob = const std::string blob =
"{\"v\":2,\"records\":[" "{\"v\":2,\"records\":["