refactor: rebuild orchestration around a track selection

docs/logboek.md

@@ -29,7 +29,7 @@ Waarom:
 
 Wat ik heb laten vallen of uitgesteld:
 
-- Domainmodellen, protocollen, prompts, pipeline-instellingen en het
+- Domainmodellen, protocols, prompts, pipeline-instellingen en het
   frontend-typecontract bewust nog niet neergezet. Die ontstaan in de stap
   waar ze horen. Ik probeer op die manier bewust vroeg drift en dode code te voorkomen.
 - Geen apart beslisdocument. De motivering staat in de README en hier.
@@ -40,19 +40,19 @@ Wat ik heb laten vallen of uitgesteld:
 Wat ik deed:
 
 - Login via Spotify met PKCE en cookie-sessies: tokens blijven server-side, de browser krijgt alleen een opaque HttpOnly cookie.
-- Dunne async client op de Spotify Web API met per-endpoint retrybeleid:
+- Dunne async client op de Spotify Web API met per-endpoint retry policy:
   leesacties herhalen maximaal 1 keer en alleen binnen een grens
   (Retry-After), schrijfacties op playlists nooit.
 - Token-refresh is single-flight: parallelle requests delen 1 refresh in
   plaats van er allemaal zelf een te starten.
 - Mapping van Spotify-JSON naar eigen modellen op 1 plek; kapotte items
   vallen weg in plaats van dat ze de app breken.
-- Getypeerde fouten en 12 transport- en routetests op een mock transport.
+- Getypeerde errors en 12 transport- en routetests op een mock transport.
 - Na een eerste review de login-flow uit de routes getrokken naar een eigen
-  module (routes zijn nu dunne doorgeefluiken) en het retrybeleid herschreven
+  module (routes zijn nu dunne passthroughs) en de retry policy herschreven
   naar een lineaire keten van losse regels in plaats van een loop met flags;
-  foutdetails uit de Spotify-body worden meegenomen in de getypeerde fouten
-  en quota-uitputting wordt apart herkend en nooit opnieuw geprobeerd.
+  foutdetails uit de Spotify-body worden meegenomen in de getypeerde errors
+  en quota exhaustion (QUOTA_EXCEEDED) wordt apart herkend en nooit opnieuw geprobeerd.
 - Daarna het API-contract vastgelegd: request-schema en de gestreamde
   events (metadata / track / warning / error / done), gespiegeld in
   TypeScript.
@@ -60,7 +60,7 @@ Wat ik deed:
 Waarom:
 
 - Schrijfacties blind herhalen kan dubbele playlist-items opleveren; dat
-  risico sluit ik structureel uit in het retrybeleid.
+  risico sluit ik structureel uit in de retry policy.
 - Het contract eerst bevriezen maakt parallel werken aan frontend en
   pipeline mogelijk zonder elkaar te breken.
 
@@ -80,15 +80,19 @@ Wat ik deed:
   Spotify-smaakprofiel naar prompttekst plus een set bekende track-ids,
   prompts als data in een eigen module, en alle instelbare waarden
   gesectioneerd in de config met per waarde het waarom.
-- Twee LLM-aanroepen achter een eigen interface: aanroep 1 interpreteert de
+- Twee LLM-calls achter een eigen interface: call 1 interpreteert de
   vraag (stemming, activiteit, taal, bekendheid) en stelt 30-40 echte
-  nummers voor als gestructureerde output; aanroep 2 herordent uitsluitend
+  nummers voor als gestructureerde output; call 2 herordent uitsluitend
   geverifieerde nummers en streamt per nummer een eerlijke onderbouwing.
   Elke output wordt gevalideerd, met hooguit 1 herstelpoging.
-- Grounding: begrensde parallelle zoekslag met vroege stop, een deadline,
+- Grounding: begrensde parallelle search fan-out met early stop, een deadline,
   een naam-naar-id cache en twee aparte metrieken: niet gevonden versus
-  wel gevonden maar afgekeurd door de controle. Een track-id dat niet in
+  wel gevonden maar afgekeurd door de match-check. Een track-id dat niet in
   de geverifieerde pool zit kan nooit bij de gebruiker terechtkomen.
+- Na review de orkestratie herschreven: de stream-functie leest nu als de
+  pipeline-stappen zelf, en de selectie-logica (alleen pool-ids, geen
+  duplicaten, begrensd aantal, ranking) zit in 1 kleine klasse die zowel
+  het normale pad als de fallback bedient.
 
 Waarom:
 
@@ -96,13 +100,13 @@ Waarom:
   deterministische muren: alles wat hij ziet is echte data, alles wat de
   gebruiker ziet is geverifieerd op Spotify. Een verzonnen nummer valt
   stilletjes af en verschijnt nooit.
-- Zoeken geeft maximaal 10 resultaten per aanroep, dus resolutie is per
+- Zoeken geeft maximaal 10 resultaten per call, dus resolutie is per
   definitie een fan-out; liever een kandidaat laten vallen dan het
   verkeerde nummer aanbevelen.
 
 Wat ik heb laten vallen of uitgesteld:
 
-- Verfijnvragen doen geen nieuwe zoekslag: turn 2 herordent de bestaande
-  geverifieerde pool. Sneller en consistent, maar een verfijning haalt
+- Refinements doen geen nieuwe search-ronde: turn 2 herordent de bestaande
+  geverifieerde pool. Sneller en consistent, maar een refinement haalt
   geen nieuwe nummers op. Dit is een bewuste afweging, mocht er tijd over 
   zijn is dit 1 van de uitbreidingen die ik op zou kunnen pakken.