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.
// PERSISTED AS INTEGERS: never renumber an existing value, only append.
enum class OriginKind {
Unknown = 0,
Capture = 1,
Ingest = 2,
Recapture = 3, // regenerated in place from its recorded source recipe
Resample = 4, // baked from an instrument's own processing chain
// Kept distinct from Ingest — both bring in a foreign file, but only this one
// can answer "which package did this bank come from" later.
PackageImport = 5,
Unknown = 0,
Capture = 1,
Ingest = 2,
Recapture = 3, // regenerated in place from its recorded source recipe
Resample = 4, // baked from an instrument's own processing chain
PackageImport = 5, // package-sourced vs Ingest's user-picked; unrecoverable once merged
};
// 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.
//
// The record family behind file tracking. Covers: the relative-paths-only invariant,
// exact-string ownership, dedup, insertion order, the JSON round-trip (incl. golden
// byte literals over every persisted enum value), the append-a-kind-without-moving-"v"
// rule and its degrade-don't-block twin, the no-backfill rule, the legacy path-only
// lift, and the Fresh / Loaded / Unreadable / FutureVersion classification that keeps
// never-recorded apart from the two degraded states.
// Covers: relative-paths-only, exact-string ownership, dedup, insertion order, the
// JSON round-trip (incl. golden bytes over every persisted enum value), the append-a-
// kind rules, the no-backfill rule, the legacy path-only lift, and the Fresh / Loaded
// / Unreadable / FutureVersion classification.
#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
}
// Appending a value to the kind vocabulary must NOT move the document version: the
// 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.
// Pins the emitted "v" byte, not the internal constant — an older build reads bytes.
static void testAppendingAKindDoesNotMoveTheDocumentVersion() {
OriginLedger l;
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);
}
// The other half of the append rule: a kind this build does NOT know degrades to
// Unknown while the ledger still loads and the path stays owned. Losing the kind
// detail costs nothing today — no consumer reads it — but an Unreadable here would
// block prune entirely on nothing worse than a vocabulary gap.
// Pins three unrecognized kind values (future, far-future, negative) all landing on
// Unknown with the ledger still Loaded and the path still owned.
static void testUnknownKindDegradesWithoutBlockingTheLedger() {
const std::string blob =
"{\"v\":2,\"records\":["