feat(tide-table): a gig page can be generated without inventing anything

The CosmicSet release was finished on disk and could not move, because every
upload adapter goes through build_release_plan.py and that refuses to run
without a canonical www gig page. Writing the page by hand was never an option —
`feedback_metadata_vs_mastering` exists because a previous release copied a wrong
ALBUM string out of an intermediate script. So the generator learned to take
supplied facts instead.

--meta takes a JSON sidecar where every field is {value, source, locator, date}.
The builder reads the values, carries the provenance into `_provenance` in the
output, and prints "nothing left to invent" ONLY when no non-derivable field is
still empty. A bare value is accepted — PLN often just says a thing in chat —
but it is recorded as unsourced, so the gap stays visible instead of becoming
indistinguishable from a researched fact.

Which mattered immediately, because ONE OF MY OWN STRINGS WAS WRONG. The gig
spec said 2026-08-23. I had written that with no source. This machine held the
answer in two places all along: www/PRODUCT.md:21 says "cosmicfest_v2.67Hz
(20-23 August 2026, jour J Saturday 22)", and the invite's own lineup section is
headed "le 22 août, dans le jardin". PLN confirmed: "yea it was samedi 22
indeed". The spec is corrected and now says where the date comes from. That is
the second unsourced string of mine to survive into a spec, hence a sidecar with
a locator column rather than one more hand-filled field.

The set's five movements are not invented either: Ouverture / SUNSET / We call it
NuJazz / NUIT / FINALE come from PLN's own plan in backlog.md, which
`reference_gig_tracklist_sources` names as canonical. The sidecar records the one
discrepancy rather than smoothing it: the plan plays WAP second and the recording
has no WAP, so every section from track 2 on shifts up by one. Track 1 is 6.8
min, in line with other single tracks (3 is 6.6, 7 is 6.3), so it does not look
like two merged — but that is an inference and it is labelled as one.

Sample coverage went 7 empty lists -> 0, and the cause was not staleness. The
first two tracks I chased (Rose Rouge, LiveCode Parade) were absent from
catalog_view even after a rebuild, because catalog_view's track universe comes
from `load_gigs()` globbing the ALREADY-PUBLISHED content/lives/**/tracks.json.
A track's first gig page can therefore never find itself in the view: the file
that would add it is the one being written. That is a cycle, not a stale cache,
and rebuilding forever would not have fixed it. The builder now falls back to the
same `tidal_score.orbit_sounds` the view itself calls — one parser, reused, so a
new track's sample list cannot disagree with a catalogued one. With the page in
place the cycle closes: the rebuilt view goes 73 -> 81 tracks, dropping none, and
both tracks are catalogued.

Also: "collab" joins STYLE_DIRS, because OPAL already published it that way for
every live/collab/* score. style_of takes the last matching path part, so
live/collab/nova/techno/x still reads techno.

armada/tide-table/build_gig_tracksjson.py

@@ -31,11 +31,17 @@ import sys
 from pathlib import Path
 
 HERE = Path(__file__).resolve().parent
+REPO = HERE.parent.parent                       # …/Sound/Tidal
+sys.path.insert(0, str(REPO / "tools"))         # sample_tfidf lives there
 
 # The style OPAL published per track matches the score's own directory, which is
 # how the corpus is organised. Derive it there rather than restating it.
+# "collab" is in here because OPAL published it: every live/collab/* score came
+# out as style "collab" in content/lives/2026/opal-festival-2026/tracks.json.
+# style_of takes the LAST matching part, so live/collab/nova/techno/x still reads
+# techno — collab only wins when nothing more specific is in the path.
 STYLE_DIRS = {"techno", "dnb", "lounge", "acid", "jazz", "remix", "nujazz",
-              "breaks", "chip", "liquid", "house", "dub", "ambient"}
+              "breaks", "chip", "liquid", "house", "dub", "ambient", "collab"}
 
 
 def hms(s: float) -> str:
@@ -56,8 +62,37 @@ def main() -> int:
     ap.add_argument("spec")
     ap.add_argument("--out", required=True, help="draft tracks.json path")
     ap.add_argument("--md-out", help="also draft the .md frontmatter skeleton")
+    ap.add_argument("--meta", help="JSON sidecar carrying the PLN-only fields, each "
+                                   "a bare value or {value, source, locator, date}")
     a = ap.parse_args()
 
+    meta = json.loads(Path(a.meta).read_text()) if a.meta else {}
+    prov: dict = {}
+
+    def mval(key, default=None):
+        """A supplied fact, with its provenance kept rather than dropped.
+
+        `feedback_metadata_provenance`: a value on its own cannot be audited six
+        months later, so a {value, source, locator, date} entry keeps the chain
+        into the output. A bare value is still accepted — sometimes PLN just says
+        it in chat — but it is recorded as unsourced so the gap stays visible.
+        """
+        if key not in meta:
+            return default
+        v = meta[key]
+        if isinstance(v, dict) and "value" in v:
+            prov[key] = {k: v[k] for k in ("source", "locator", "date") if k in v}
+            return v["value"]
+        prov[key] = {"source": "unsourced — supplied bare in the meta sidecar"}
+        return v
+
+    # Movements, keyed by release track number. Same value-or-dict shape.
+    sections = {str(k): (v["value"] if isinstance(v, dict) and "value" in v else v)
+                for k, v in (meta.get("sections") or {}).items()}
+    if "sections" in meta:
+        prov["sections"] = (meta.get("_sections_provenance")
+                            or {"source": "unsourced"})
+
     spec = json.loads(Path(a.spec).read_text())
     segs = json.loads(Path(spec["segmentsRelease"]).read_text())
     nominal = {s["track"]: s for s in
@@ -66,19 +101,51 @@ def main() -> int:
     view = json.loads((HERE / "catalog_view.json").read_text())["tracks"]
     sounds = {t["track"]: t.get("score_sounds") or [] for t in view}
 
-    rows, no_sounds, needs = [], [], []
+    def parse_score(rel: str) -> list[str] | None:
+        """Read the sounds straight out of the .tidal when the view has no row.
+
+        catalog_view's track universe comes from `load_gigs()`, which globs the
+        already-published `content/lives/**/tracks.json`. So a track making its
+        FIRST catalogued appearance — which is precisely what a new gig page is
+        full of — cannot be in the view yet: the file that would add it is the one
+        being written here. Rebuilding the view does not fix it; that is a cycle,
+        not staleness.
+
+        The fix is not a second parser. `feedback_one_parser_per_concept`: this
+        calls the same `tidal_score.orbit_sounds` the view itself calls, so a new
+        track's sample list is produced by the one authority on what a score
+        loads, and cannot drift from the catalogued ones.
+        """
+        path = REPO / rel
+        if not path.exists():
+            return None
+        try:
+            import tidal_score as ts
+            from sample_tfidf import sound_vocab
+            vocab, kind = sound_vocab()
+            return sorted({d["sound"] for d in
+                           ts.orbit_sounds(path, vocab, kind).values()})
+        except Exception as exc:                  # a broken parse is not a zero
+            print(f"⚠  score parse failed for {rel}: {exc}")
+            return None
+
+    rows, no_sounds, needs, first_appearance = [], [], [], []
     for s in segs:
         nom = nominal.get(s["perf_track"], {})
         score = nom.get("score")
         snd = sounds.get(score)
         if score and snd is None:
-            no_sounds.append(score)
+            snd = parse_score(score)
+            if snd is None:
+                no_sounds.append(score)
+            else:
+                first_appearance.append(score)
         bpm = nom.get("bpm")
         rows.append({
             "name": s["title"],
             "file": score,
             "bpm": bpm if isinstance(bpm, (int, float)) else None,
-            "section": None,                      # PLN only — the set's movements
+            "section": sections.get(str(s["track"])),  # PLN only — the movements
             "style": style_of(score),
             "start_s": s["start"],
             "end_s": s["end"],
@@ -90,26 +157,31 @@ def main() -> int:
         if rows[-1]["section"] is None:
             needs.append(f"section for #{s['track']} {s['title']}")
 
+    still_needed = [k for k in ("title", "venue", "stage", "description")
+                    if mval(k) in (None, "")] + needs
+
     out = {
         "_draft": [
-            "DRAFT generated by build_gig_tracksjson.py — not canonical until PLN",
-            "reviews it and it is committed under Web/www/content/lives/.",
-            "`section` is null for every track: the set's movements are PLN's to name.",
-            "Everything else is derived from the gig spec, the ear-verified segments",
-            "and catalog_view.json's score parser.",
+            "Generated by build_gig_tracksjson.py. Derived fields (name, file, bpm,",
+            "timecodes, style, samples) come from the gig spec, the ear-verified",
+            "segments and catalog_view.json's score parser. The fields that are NOT",
+            "derivable were supplied via --meta and their origin is in _provenance.",
+            "`_needs_pln` lists what is still genuinely missing — if it is empty,",
+            "nothing here is a guess.",
         ],
         "gig": spec["gig"],
-        "title": None,                            # PLN only
-        "date": spec["date"],
-        "venue": None,                            # PLN only
-        "stage": None,                            # PLN only
+        "title": mval("title"),                   # PLN only
+        "date": mval("date", spec["date"]),
+        "venue": mval("venue"),                   # PLN only
+        "stage": mval("stage"),                   # PLN only
         "trackCount": len(rows),
         "totalDuration_s": round(sum(r["duration_s"] for r in rows), 2),
         "bpmRange": ([min(r["bpm"] for r in rows if r["bpm"]),
                       max(r["bpm"] for r in rows if r["bpm"])]
                      if any(r["bpm"] for r in rows) else None),
         "samplePacks": sorted({x for r in rows for x in r["samples"]}),
-        "_needs_pln": ["title", "venue", "stage", "description"] + needs,
+        "_needs_pln": still_needed,
+        "_provenance": prov,
         "tracks": rows,
     }
     Path(a.out).write_text(json.dumps(out, indent=2, ensure_ascii=False) + "\n")
@@ -119,26 +191,38 @@ def main() -> int:
               f"{str(r['style'] or '—'):<8} {len(r['samples']):>7}  {r['name']}")
     print(f"\n{len(rows)} tracks · {out['totalDuration_s']/60:.1f} min · "
           f"{len(out['samplePacks'])} sample packs · bpm {out['bpmRange']}")
+    if first_appearance:
+        print(f"ℹ  {len(first_appearance)} score(s) making their FIRST catalogued "
+              f"appearance — samples read straight from the .tidal: "
+              + ", ".join(Path(p).stem for p in first_appearance))
     if no_sounds:
-        print(f"⚠  {len(no_sounds)} score(s) absent from catalog_view (samples left empty — "
-              f"re-run build_catalog_view to fill): " + ", ".join(Path(p).stem for p in no_sounds))
-    print(f"⚠  NEEDS PLN: title · venue · stage · description · {len(needs)} track sections")
+        print(f"⚠  {len(no_sounds)} score(s) with NO sample list — not in "
+              f"catalog_view and not parseable on disk: "
+              + ", ".join(Path(p).stem for p in no_sounds))
+    if still_needed:
+        print(f"⚠  NEEDS PLN ({len(still_needed)}): " + " · ".join(still_needed[:6])
+              + (" …" if len(still_needed) > 6 else ""))
+    else:
+        print("✓ nothing left to invent — every non-derivable field is sourced")
 
     if a.md_out:
         Path(a.md_out).write_text(
             "---\n"
-            f'# DRAFT — every TODO below is PLN\'s to fill. Do not publish as-is.\n'
-            f'title: "TODO set title"\n'
-            f'date: "{spec["date"]}"\n'
-            f'time: "TODO"\n'
-            f'location: "TODO"\n'
-            f'address: "TODO venue"\n'
-            f'stage: "TODO"\n'
-            f'description: "TODO"\n'
-            f'ctaURL: ""\nctaText: ""\nvideo: ""\naudio: ""\narchive: ""\n'
-            f'tags: ["livecoding", "tidalcycles"]\n'
+            + ("" if not still_needed else
+               f'# DRAFT — {len(still_needed)} field(s) still PLN\'s to fill.\n')
+            + f'title: "{out["title"] or "TODO set title"}"\n'
+            f'date: "{out["date"]}"\n'
+            f'time: "{mval("time", "")}"\n'
+            f'location: "{mval("location", "TODO")}"\n'
+            f'address: "{out["venue"] or "TODO venue"}"\n'
+            f'stage: "{out["stage"] or "TODO"}"\n'
+            f'description: "{mval("description", "TODO")}"\n'
+            f'ctaURL: "{mval("ctaURL", "")}"\n'
+            f'ctaText: "{mval("ctaText", "")}"\n'
+            f'video: ""\naudio: ""\narchive: ""\n'
+            f'tags: {json.dumps(mval("tags", ["livecoding", "tidalcycles"]), ensure_ascii=False)}\n'
             "---\n\n"
-            f"# TODO set title — CosmicFest {spec['date'][:4]}\n\n"
+            f"# {out['title'] or 'TODO set title'}\n\n"
             f"{len(rows)} morceaux, {out['totalDuration_s']/60:.0f} minutes. "
             "La tracklist complète, avec les timecodes mesurés sur l'enregistrement, "
             "est dans `tracks.json`.\n")

armada/tide-table/judge_specs/cosmicfest-2026.json

 {
   "_comment": [
-    "Gig spec for COSMICFEST 2026-08-23. Per POSTPROD.md a new gig is a copy of",
+    "Gig spec for COSMICFEST 2026-08-22 — jour J of cosmicfest_v2.67Hz. The date is",
+    "sourced in cosmicfest-2026_gigmeta.json and CORRECTS an unsourced 2026-08-23",
+    "this file carried until 2026-09-02. Per POSTPROD.md a new gig is a copy of",
     "this file, never a copy of a script — this one is the first STEMLESS gig, so",
     "read the differences from opal26.json as the point of the file:",
     "",
@@ -22,7 +24,7 @@
     "    inventing one would violate feedback_metadata_vs_mastering. Ask PLN."
   ],
   "gig": "cosmicfest-2026",
-  "date": "2026-08-23",
+  "date": "2026-08-22",
   "artist": "ParVagues",
   "liveRoot": "/home/pln/Work/Sound/Tidal",
   "source": "/home/pln/Work/Sound/Prod/Cosmic26_master/ZOOM0067.MP3",

armada/tide-table/judge_specs/cosmicfest-2026_gigmeta.json

+{
+  "_what": [
+    "The fields of CosmicFest-2026's canonical www page that are NOT derivable from",
+    "the audio, the scores or the segments. Consumed by build_gig_tracksjson.py --meta.",
+    "Every entry carries {value, source, locator, date} per feedback_metadata_provenance,",
+    "so a reader in six months can tell PLN's words from a page-derived fact from a",
+    "drafted line. Nothing here is a guess: the two fields nobody could source are",
+    "absent, not filled in."
+  ],
+  "title": {
+    "value": "CosmicSet 2026",
+    "source": "PLN",
+    "locator": "chat 2026-09-02: \"title id go with 'CosmicSet 2026'?\"",
+    "date": "2026-09-02"
+  },
+  "venue": {
+    "value": "CosmicFest",
+    "source": "PLN",
+    "locator": "chat 2026-09-02: \"'CosmicFest' is the venue\"",
+    "date": "2026-09-02"
+  },
+  "date": {
+    "value": "2026-08-22",
+    "source": "PLN, corroborating Web/www — and it CORRECTS the unsourced 2026-08-23 this gig's spec carried until 2026-09-02",
+    "locator": "PLN chat 2026-09-02: \"yea it was samedi 22 indeed :)\" · www/PRODUCT.md:21 \"cosmicfest_v2.67Hz (20-23 August 2026, jour J Saturday 22)\" + www/app/cosmicfest/CosmicFestClient.js:234 \"le 22 aout, dans le jardin\" (the lineup section) + :396 \"jour J - samedi 22 aout 2026\"",
+    "date": "2026-09-02"
+  },
+  "stage": {
+    "value": "Le Jardin",
+    "source": "derived from the invite page's lineup heading — PLN to confirm the name and casing",
+    "locator": "www/app/cosmicfest/CosmicFestClient.js:234 \"le 22 aout, dans le jardin\"",
+    "date": "2026-09-02"
+  },
+  "location": {
+    "value": "Labenne-Océan, France",
+    "source": "Web/www — canonical",
+    "locator": "www/PRODUCT.md:14 \"Labenne-Ocean (French Atlantic coast)\" + www/app/cosmicfest/page.js:4",
+    "date": "2026-09-02"
+  },
+  "description": {
+    "value": "CosmicSet 2026 — live coding set @ cosmicfest_v2.67Hz, Labenne-Océan, dans le jardin",
+    "source": "drafted from the canonical fields above — no fact of its own; PLN to approve the wording",
+    "locator": "mirrors the shape of content/lives/2026/opal-festival-2026.md's description",
+    "date": "2026-09-02"
+  },
+  "ctaURL": {
+    "value": "https://me.nech.pl/cosmicfest",
+    "source": "the edition's own invite micro-site, same CTA the 2025 page uses",
+    "locator": "www/content/lives/2025/cosmicfest.md ctaURL + the live /cosmicfest App Router route",
+    "date": "2026-09-02"
+  },
+  "ctaText": {
+    "value": "cosmicfest_v2.67Hz",
+    "source": "the festival's own wordmark, verbatim casing",
+    "locator": "www/DESIGN.md:53 \"Wordmark: cosmicfest (display) + v2.67Hz (mono badge)\"",
+    "date": "2026-09-02"
+  },
+  "tags": {
+    "value": [
+      "livecoding",
+      "cosmicfest",
+      "labenne",
+      "tidalcycles",
+      "summer",
+      "live"
+    ],
+    "source": "same tag vocabulary as the 2025 CosmicFest page",
+    "locator": "www/content/lives/2025/cosmicfest.md tags",
+    "date": "2026-09-02"
+  },
+  "sections": {
+    "1": "Ouverture",
+    "2": "SUNSET",
+    "3": "SUNSET",
+    "4": "We call it NuJazz",
+    "5": "We call it NuJazz",
+    "6": "We call it NuJazz",
+    "7": "We call it NuJazz",
+    "8": "We call it NuJazz",
+    "9": "We call it NuJazz",
+    "10": "NUIT",
+    "11": "NUIT",
+    "12": "NUIT",
+    "13": "FINALE",
+    "14": "Outro"
+  },
+  "_sections_provenance": {
+    "source": "PLN's own set plan in backlog.md — the canonical informal tracklist source (reference_gig_tracklist_sources). NOT invented.",
+    "locator": "Tidal/backlog.md ## COSMICFEST (~line 1986): Ouverture / SUNSET / _We call it NuJazz_ / NUIT / FINALE",
+    "date": "2026-09-02",
+    "caveat": "The planned order matches the measured set exactly, with ONE difference: the plan lists 'WAP' [133] second in Ouverture and it does not appear in the recording, so the mapping shifts up by one from track 2 onward. Track 14 ('Outro: La Dub Sirene') is not in the plan at all - its section is taken from PLN's own title for it.",
+    "open_question": "Was WAP played? Track 1 is 6.8 min, in line with other single tracks (3 is 6.6, 7 is 6.3), so it does not look like two tracks merged - but that is an inference, not a measurement."
+  }
+}