Shipped on branch wt/recs, 2026-09-20. The engine is pure and thoroughly tested in src/recs/; the nightly jobs that run it are covered in Nightly jobs.

What each button means

Dwell is meant to measure active watching only — a paused or backgrounded tab should not accrue duration. watch_history.duration_seconds (supabase/migrations/20260920090000_recommendations.sql) is the column that carries it; the taste module (src/recs/taste.ts) already computes the dwell factor from it, defaulting to a neutral 1.0 for any row where it is still null.

The taste vector

src/recs/taste.ts folds every one of a user’s signals into one Taste vector — the same Probabilities shape the taxonomy vectors use — by weighting each signal (heart/like/dislike undecayed, watch decayed by age with a 30-day half-life) and summing into the channel’s category vector.

Channel similarity

scripts/build-channel-similar.ts runs nightly and fills channel_similar, which op=similar serves. It reads the native catalogue slice the catalog-slices workflow publishes, because that slice holds every channel a viewer can tune along with its streams and census desk. For each channel, src/recs/similar.ts ranks the playable channels of its primary category with rankPeers from src/catalog/recommend.ts, the same function the device runs when op=similar has nothing, and keeps the top 40. The ranking, highest first:
  1. the tuned channel’s first language (spellings folded, so fre is fra);
  2. its census desk (pathChild);
  3. how many of its other categories the peer shares (top-news, for example);
  4. a stream no territory limits;
  5. watches in the last seven days, in doubling steps (only the job has them);
  6. how many services carry a playable stream of the channel;
  7. the same country.
Catalogue order breaks what is left. Then each RT and CGTN channel, in every variant, moves 8 places down the list, or to the end of a shorter one, and everything else keeps its order (an editorial choice, STATE_MEDIA and STATE_MEDIA_DEMOTE in src/catalog/recommend.ts): they still show, just not first. No family of numbered or format variants (ABC News Live 1 to 10, BBC News HD and BBC News HEVC) holds more than two of the first 12 places, and the tuned channel counts as one of its own family. The job writes channel_similar and nothing else. Both its columns reference public.channels, which pnpm sync:catalog writes by hand and which lags the catalogue, so a channel the table lacks gets no rows and is no one’s peer, and the run logs how many it skipped. For such a channel (NHK World-Japan’s famelack id, for one) op=similar answers with nothing and the device ranks You might like itself, with the same rankPeers.

Candidates → prescore → Jev blend

src/recs/candidates.ts builds a pool of channel candidates per user (seeded by taste categories, saved/liked channels, and trending); src/recs/blend.ts turns that pool into ranked RecRows. In full mode, each candidate’s code-only prescore is blended with a Noul score returned by one Jev call per user (src/recs/questions.ts shapes that request as a viewer state block — ranked category names, channel names, languages, words only, never numbers — plus one question per candidate). A candidate missing from the returned noulScores map falls back to prescore-only for that one channel, even inside an otherwise-full run.

Row lineup (Watch screen)

  1. Top picks for you — user_recs row top-picks, signed-in users with 3 or more signals
  2. Continue watching
  3. Your channels
  4. Because you liked/saved — user_recs row because:<channel_id>, up to 2 seeds (most-recent heart, else like)
  5. You might like — channel_similar neighbors, filtered against reactions and hidden channels; the same ranking on the device when op=similar has nothing for the channel
  6. Trending on Bytestream — works for anonymous viewers too
  7. Catalog shelves

The degradation ladder

Jev is a bonus, never a dependency.
1

full

A TYPESAFE_API_KEY is set and Jev answers: prescore blended with the per-user Noul score.
2

vectors-only

No key, no credits, or a Jev call exhausted its retries: falls back to the channel_paths.probabilities cosine vectors already in the database — no extra call needed.
3

tags-only

No classification row exists for a channel at all: falls back to a one-hot vector rolled up from the channel’s publisher tags to their parent taxonomy keys.
The run always exits 0. user_recs.reason records which mode built each row for later inspection, but the mode is never surfaced in the UI — a viewer never sees which rung of the ladder their picks came from.
A 402/403 from Jev, or one user’s call exhausting its retries, flips a run-level demoted flag: that user and every user processed after them in the same run score prescore-only for the rest of the run. Rows already blended before the flag flipped are kept as-is.

What’s next

Phase 2 (designed, deferred): an “On now for you” row, programme-aware Jev scoring, and dayparting. Translation was explicitly considered and rejected — the taxonomy vectors are already language-agnostic, so there’s nothing for a translation layer to fix.