Merge ps-w1-t2-sample-intrinsics: S2 Sample seam fields (rootNote + loop points)

src/bank_model.cpp

@@ -35,6 +35,10 @@ bool Levels::operator==(const Levels& o) const {
     return peakDb == o.peakDb && rmsDb == o.rmsDb && lufs == o.lufs;
 }
 
+bool LoopPoints::operator==(const LoopPoints& o) const {
+    return start == o.start && end == o.end;
+}
+
 bool Sample::operator==(const Sample& o) const {
     return id == o.id && displayName == o.displayName && relativePath == o.relativePath &&
            sourceMode == o.sourceMode && sourceRange == o.sourceRange &&
@@ -43,7 +47,8 @@ bool Sample::operator==(const Sample& o) const {
            lengthSeconds == o.lengthSeconds && lengthBeats == o.lengthBeats &&
            captureTempo == o.captureTempo &&
            captureTimeSigNum == o.captureTimeSigNum &&
-           captureTimeSigDenom == o.captureTimeSigDenom && key == o.key && levels == o.levels &&
+           captureTimeSigDenom == o.captureTimeSigDenom && key == o.key &&
+           rootNote == o.rootNote && loop == o.loop && levels == o.levels &&
            clipped == o.clipped && tier == o.tier && contentHash == o.contentHash &&
            provenance == o.provenance && createdTimestamp == o.createdTimestamp;
 }
@@ -253,6 +258,21 @@ void writeSample(std::string& out, const Sample& s) {
     w.keyBegin("key");
     if (s.key) writeEscaped(out, *s.key); else out += "null";
 
+    // Phase S seam fields (D-B). Emitted as null when absent (same shape as `key`
+    // and `provenance`) so pre-Phase-S JSON — which lacks these keys entirely —
+    // parses to empty optionals and re-serializes without invention.
+    w.keyBegin("rootNote");
+    if (s.rootNote) out += numToStr(*s.rootNote); else out += "null";
+
+    w.keyBegin("loop");
+    if (s.loop) {
+        ObjWriter lp(out);
+        lp.keyRaw("start", numToStr(s.loop->start));
+        lp.keyRaw("end", numToStr(s.loop->end));
+    } else {
+        out += "null";
+    }
+
     w.keyBegin("levels");
     {
         ObjWriter l(out);
@@ -608,6 +628,41 @@ bool Parser::parseSample(Sample& s) {
                 if (!parseString(k)) return false;
                 s.key = k;
             }
+        } else if (key == "rootNote") {
+            bool wasNull = false;
+            if (!expectNullOr(wasNull)) return false;
+            if (wasNull) {
+                s.rootNote.reset();
+            } else {
+                int v = 0;
+                if (!parseInt(v)) return false;
+                // Valid MIDI note range: 0..127 inclusive (boundaries valid).
+                if (v < 0 || v > 127) return false;
+                s.rootNote = v;
+            }
+        } else if (key == "loop") {
+            bool wasNull = false;
+            if (!expectNullOr(wasNull)) return false;
+            if (wasNull) {
+                s.loop.reset();
+            } else {
+                if (!consume('{')) return false;
+                LoopPoints lp;
+                do {
+                    std::string lk;
+                    if (!parseKey(lk)) return false;
+                    std::int64_t lv = 0;
+                    if (!parseInt64(lv)) return false;
+                    if (lk == "start") lp.start = lv;
+                    else if (lk == "end") lp.end = lv;
+                } while (consume(','));
+                if (!consume('}')) return false;
+                // Invariant: 0 <= start <= end. start == end is a valid zero-length
+                // marker; a negative index or start > end is malformed, not silently
+                // clamped (mirrors the enum-range rejection above).
+                if (lp.start < 0 || lp.end < lp.start) return false;
+                s.loop = lp;
+            }
         } else if (key == "levels") {
             if (!consume('{')) return false;
             do {

src/bank_model.h

@@ -63,6 +63,22 @@ struct Levels {
     bool operator==(const Levels& o) const;
 };
 
+// Sample-accurate sustain-loop bounds, as frame indices into the captured file
+// (Phase S seam field, D-B). A bank intrinsic — a fact about the file, like
+// sampleRate or length — consumed by the future MIDI-playback instrument to hold
+// notes past the recorded length. Modeled as one optional struct (not two loose
+// optionals) so "both points or neither" is a structural invariant, not a rule to
+// re-check at every boundary. Frame indices, not seconds, because the loop is a
+// per-sample-frame contract; the instrument reads the file's sample rate to relate
+// them to time. Invariant (enforced at the deserialize boundary): 0 <= start <= end.
+// start == end is a valid zero-length loop marker.
+struct LoopPoints {
+    std::int64_t start = 0;
+    std::int64_t end   = 0;
+
+    bool operator==(const LoopPoints& o) const;
+};
+
 // The metadata record for one captured sample. The audio itself lives in a
 // project-relative file; `relativePath` is ALWAYS relative (enforced at the
 // BankIndex::add boundary — see AddResult).
@@ -95,6 +111,18 @@ struct Sample {
 
     std::optional<std::string> key;  // musical key, when known
 
+    // Phase S seam fields (D-B) — bank intrinsics for the MIDI-playback instrument,
+    // additive like `provenance` (M1). Both default cleanly empty: pre-Phase-S
+    // samples deserialize without them and re-serialize without inventing values.
+    //  - rootNote: MIDI note (0..127) the sample was recorded at, so the instrument
+    //    can repitch it across the keyboard. DISTINCT from the musical `key` above:
+    //    `key` is a human label ("F#m"); `rootNote` is the exact pitch for repitch.
+    //    Populated at/after capture only where derivable — left empty (never guessed)
+    //    when the source is not a single played note.
+    //  - loop: sustain-loop bounds, populated only where explicitly set.
+    std::optional<int>        rootNote;
+    std::optional<LoopPoints> loop;
+
     Levels levels;
     bool   clipped = false;
 

src/capture.cpp

@@ -530,6 +530,11 @@ CaptureResult OfflineRenderBackend::capture(const CaptureRequest& request) {
         }
     }
     s.createdTimestamp = static_cast<std::int64_t>(std::time(nullptr));
+    // Phase S seam fields (rootNote / loop) left empty (D-B). An offline render of a
+    // master mix / track / time-selection is not a single played note, so no root
+    // note is derivable here — we do NOT guess one. Loop points are set later by an
+    // explicit user action, not at capture. Leaving them empty is the honest default;
+    // the instrument (Phase S) treats an absent root note as "not a pitched sample".
 
     result.status  = CaptureStatus::Ok;
     result.sample  = s;

src/realtime_record.cpp

@@ -58,6 +58,9 @@ Sample sampleFromRecordedCapture(const RecordedCapture& cap) {
     // finalized and on disk — the hash is over the finished file bytes. Left empty
     // here because sampleFromRecordedCapture runs before the file exists (the
     // mapping is pure / DAW-free); the shell patches it in after the move+trim.
+    // Phase S seam fields (rootNote / loop) left empty (D-B) — same reasoning as the
+    // offline path: a realtime record of wet output is not a single played note, so
+    // no root note is derivable; loop points are set by a later explicit action.
     s.createdTimestamp = cap.createdTimestamp;
     return s;
 }