# L'Armada — Track × Recording Locate-Matrix (the fleet ledger)

> Goal: a **trustworthy map** of which catalog track lives in which recording, *where*
> (time-offset), and *how sure we are* — so we can pick best takes, form honest A/B/C
> comparisons, and mine sets (val-thorens, raise…) for releasable singles.

## Why this, why now

We tried to A/B PunkAChien and discovered we don't actually know what B is. The blind
cross-correlation that sourced "Hamburg PunkAChien" was a **false positive** (z=10 →
Insouciance→Liquid Finale). Empirical precision of acted-on locates so far = **1 TP / 1 FP
= 50%**. We have ~**1** ear-verified track↔take node and **0** systematic map. We can't
compare takes we haven't found. **Build the map before comparing anything.**

## The asymmetry that makes it tractable

We are NOT identifying tracks from nothing. We have strong priors:
- **23 canonical site tracklists** (raise 17, montreuil 15, val-thorens 14, cosmicfest 14…)
  — what was played at each gig, with the `.tidal` file per track.
- **63 Ardour takes** mapped (loosely) to gigs (`take_gig_map.md`; 16 labeled, 37 blank).
- Each track's **`.tidal` score** (samples, `dN`→orbit map, `setcps` tempo).
- A growing set of **released references** (SoundCloud 51, DSP 25, Bandcamp) = real audio
  of many catalog tracks.

So the job is mostly **"where in this take is the track the setlist says is there"** +
confidence, NOT blind search. Metadata collapses the hypothesis space; audio + ear confirm.

## Layered matcher (never blind xcorr again)

Each `(track, take)` cell accrues evidence from independent signals, then a **human gate**:

| layer | signal | strength | cost |
|---|---|---|---|
| **L0 metadata prior** | site tracklist × take→gig join | strong *whether*, zero *where* | free |
| **L1 ear gate (oracle)** | PLN confirms in the review UI | ground truth | human |
| **L2 cross-correlation** | track reference clip vs take onset-envelope → offset + z | strong *where* when a reference exists | cheap |
| **L3 tempo/structure** | `setcps` BPM + orbit-usage fingerprint vs take stem-map | disambiguates, no reference needed | medium |

Rules learned the hard way:
- **z-floor.** z=29 was right, z=10 was wrong → provisional accept floor **z ≥ 20**, and
  **everything still goes to the ear** before `verified`. z is a ranking aid, not a verdict.
- **References bootstrap.** Released versions seed L2. The first ear-verified instance of a
  track becomes the reference to find it in *other* takes (propagation).
- **Metadata ≠ truth either.** A tracklist may list a planned track that wasn't performed,
  or a take→gig label may be `(±3d)` fuzzy. Priors are priors.

## Data model

`track_recording_map.json` — array of cells:
```jsonc
{
  "track": "PunkAChien",            // canonical track id
  "tidal": "live/collab/raph/punkachien.tidal",
  "take": "Take89",                  // recording id (Ardour take or .aup)
  "gig": "2026/montreuil-algorave",  // site slug (provenance, not a fact about audio)
  "offset_s": 2309.1, "dur_s": 287.74,
  "signals": { "metadata": true, "z": 29.0, "tempo_ok": true },
  "state": "verified",               // absent | candidate | suspect | verified
  "src": "user:ear+derived:locate",  // provenance type:locator
  "as_of": "2026-06-05"
}
```
States: `candidate` (metadata says it should be here), `suspect` (audio hit but unconfirmed
/ low-z / conflicting), `verified` (ear-gated), `absent` (looked, not there).

## Output / payoff

- **Release-readiness by take-availability**: tracks appearing in ≥2 takes → A/B/C is
  *possible*; rank singles by how many clean takes exist. (PunkAChien shows in 4 setlists.)
- **Set-mining**: val-thorens / raise tracklists → their takes → extractable singles.
- A **Bridge "fleet matrix" UI** (track rows × take cols, cell = state+z) to review and
  ear-verify, reusing the design system.

## Build order (MVP-first)

- **L0 (this pass):** join site tracklists × `take_gig_map` → metadata candidate map +
  inverted `track → [takes]` index + coverage stats. Pure data, zero audio. Honest about
  unmatched gigs/takes.
- **L1:** minimal review UI — list candidates, play the take at the (eventually located)
  offset, mark `verified|suspect|absent`. Ear is the oracle.
- **L2:** cross-correlation offset-finder (`tidal-ears master locate` already exists) wired
  to references; fills `offset_s` + `z` for candidates; z≥20 + ear.
- **L3:** tempo + orbit fingerprint for reference-less disambiguation.

The misidentified `hamburg_stems` / `masters/hamburg_*` are kept as a salvage candidate
(Insouciance→Liquid Finale @ 39C3), not shipped as PunkAChien.
