Extract shared RecommendationScoringCoordinator across recommendation-scoring view models

[jubishop]

Problem

Three view models each hand-rolled a similar recommendation-scoring orchestration:

• EpisodesListViewModel — ScoredInputsKey, a $scoringRevision observation, a cancel-and-restart scoring task.
• EpisodeDetailViewModel — RecommendationScoringSnapshot, a $scoringRevision observation, a 400ms debounce, a cancel-and-restart fetch task.
• PodcastRecommendationScorer — RecommendationScoringSnapshot (with entries), a $scoringRevision observation, a cancel-and-restart scoring task.

Each re-implemented a similar shape:

1. Observe recommendationEngine.$scoringRevision.stream().dropFirst().
2. Build an Equatable snapshot/key that embeds scoringRevision.
3. Skip — or post-hoc drop — a redundant pass using that key.
4. Run the pass in a .utility Task, cancel-and-restart.

Why it matters

Because each view model builds its own $scoringRevision observation and snapshot key, each can independently get the set of scoring inputs wrong. A future scoring input added the wrong way would silently break in three places.

Resolution (PR #326)

Extracted a shared, generic RecommendationScoringCoordinator<Snapshot, Result> that owns:

• the $scoringRevision observation,
• the snapshot-keyed skip,
• the cancel-and-restart task machinery,
• score-cache retention across teardown.

Each view model supplies only its snapshot shape, a "score these" closure, and an "apply" closure. This single-sources the "what triggers a re-score" contract (engine scoringRevision ↔ coordinator) and makes it structurally unable to drift per view model.

Scope — amended from the original proposal

The original proposal called for converging the three surfaces' debounce + in-flight coalescing + generation-guard machinery. That became obsolete before this work started (see comments below): PRs #315 and #321 removed EpisodesListViewModel's debounce/generation machinery and PodcastRecommendationScorer's runningDirty tristate, leaving both on plain cancel-and-restart. So the extraction is reduced-scope:

• Uniform cancel-and-restart. No per-trigger .coalesce/.restart policy parameter — no surface debounces anymore, so there is nothing to flatten.
• The scoring backend is still not uniform (recommendations(for:) vs. local embed + similarityScore(forEmbedding:)) and result shape is still per-surface — handled by the generic Result and each surface's own score closure.

Behavior changes

All deliberate; none is a correctness regression — every existing per-view-model scoring suite stays green.

1. EpisodeDetailViewModel's 400ms scoringRevision debounce is removed, converging it onto cancel-and-restart. $scoringRevision is already a low-frequency, upstream-coalesced signal (engine cacheDebounce + settings changes), so a per-surface debounce bought nothing.
2. A transient candidate-observation failure in EpisodesListViewModel no longer forces a recompute on the next reappear. The old skip-check was gated on recommendationScoresState == .loaded, so a .failed fell through to a re-score. The coordinator's skip is keyed purely on the snapshot, and the retained score is still valid for unchanged inputs — so reappear recovers by re-applying it.
3. EpisodeDetailViewModel gains the snapshot-keyed skip it previously lacked — it used to re-fetch on every trigger and drop stale writes post-hoc. The skip only elides redundant identical-input fetches.

New direct RecommendationScoringCoordinatorTests cover the shared machinery; three existing per-view-model cases were updated to assert the post-change observable behavior.

SearchRecommendationCollector (#284) was evaluated and is not a client of this coordinator — it is a structurally different pattern (external-ranking fan-out with a per-source debounce; it does not observe $scoringRevision).

[jubishop]

Sequencing — land #293 first

#293 (PodcastDetail observation storm) should be fixed before this refactor.
They touch different layers and do not conflict in code — #293 debounces the
podcastSeriesDetail DB observation in observePodcastSeries; this issue
extracts the $scoringRevision-driven scoring orchestration — but the order
matters:

• This refactor rewrites a currently load-bearing coalescer.
  PodcastRecommendationScorer's 400ms recommendationScoresDebounce is today
  what keeps a storm of stateDidChange() calls (one per storm transition,
  ~178/s in the worst incident) from spawning a score pass each. Refactoring
  that coalescing machinery while the storm still feeds it is strictly riskier:
  any regression in the new coordinator's coalescing re-pegs the app, and it is
  hard to distinguish a refactor regression from the pre-existing storm. With
  PodcastDetail observation storm — Observatory.podcastSeriesDetail re-fires on every episode-row write #293 fixed, the storm is capped at the observation layer and the coordinator
  is refactored under sane input rates.
• Constraint 1's deliberate latency trade-off assumes normal frequency.
  Converting runningDirty's immediate re-loop to a trailing debounce is an
  "acceptable, bounded" change only at normal stateDidChange() frequency;
  with the storm live the analysis is muddier.

Caveat once #293 is in

After #293 there are two stacked debounces from a DB write to a re-score:
the #293 observation debounce → transition → stateDidChange() → the
coordinator's debounce. Implications for this refactor:

• Do not drop the coordinator's debounce assuming "the storm is gone
  upstream." PodcastDetail observation storm — Observatory.podcastSeriesDetail re-fires on every episode-row write #293 removes only the transition-storm load. The coordinator
  still must coalesce the $scoringRevision path, which is engine-driven
  and unaffected by PodcastDetail observation storm — Observatory.podcastSeriesDetail re-fires on every episode-row write #293.
• Do not add a third redundant debounce — the stateDidChange() path
  already sits behind an upstream observation debounce once PodcastDetail observation storm — Observatory.podcastSeriesDetail re-fires on every episode-row write #293 lands.

[jubishop]

this may be no longer worth doing after #310 and #311 lands which will change the pattern for EpisodesListView and PodcastDetailView significantly. altho perhaps they could still use this coordinator but only during the times that the sorting selection was set to sort by recommendation scores.