feat: score trend samples by percentile and sample recent uploads

[devhims]

Stacked on #67. Base retargets to main once that merges.

Why

The Trend Lab's numbers were internally consistent but answered the wrong question. Three specific failures, all visible in a real Claude Code scan:

1. Scores came from fitted curves against the sample median (50 + 22 * log2(v / median), exp(-ageHours / 504), engagementRate * 12). The median for that query moved from 276 to 112 views/hour between two scans hours apart, so a score of 58 meant different things each time, and nobody can say why 22.
2. An estimated video carries 0.55 weight on lifetime views divided by age, so a four month old hit outranked a genuinely accelerating new video and could be banded Breakout on the strength of an average.
3. Relevance search returns a topic's greatest hits. That sample held one video from the last seven days out of eight, and seven of eight were 20 minutes or longer, which is where the plan's 28 minute length recommendation came from.

What changed

Percentile scoring. Velocity, freshness, channel performance, engagement and acceleration are now percentile ranks inside the sample. Weights are unchanged, so 50 is still the middle, but the number reads as a position and survives the divisor moving. A missing signal scores 50 so it neither helps nor hurts. methodologyVersion goes to 3.0, and each video exposes percentiles, velocityRank and effectiveViewsPerHour.

Breakout requires measurement. It now needs signalSource: observed and at least 5 enriched videos. confidence.reasons says how many videos were withheld and why.

Recency reservation. The candidate pool reads deeper (4 pages or 4x the limit) and up to half the enrichment budget goes to videos published inside a 14 day window. The per-channel cap of 3 is only relaxed to avoid returning a short sample. New window block and summary.medianRecentViewsPerHour / summary.recentVelocityLift; length advice comes from recent uploads when the window holds at least two.

searchRank is now the relevance position rather than the enrichment position, and is absent for a video only the recency pass found.

Dashboard. Charts, leaderboard and scatter were showing lifetime averages even where measured growth existed. They now show the velocity the score used, labelled measured or estimated. The cumulative-views tile is replaced by recent versus established.

Effect on the real sample

Same eight videos, scored both ways:

before	after	video
58 Rising (listed 1st)	65 Rising (2nd)	Anthropic's own "What is Claude Code?", 4 months old
58 Rising (2nd)	69 Rising (1st)	Mikey No Code, 3 days old, small channel
28 Steady	26 Steady	Nick Saraev, 2.5M views, measured growth of 0/h

The new top row is the one a creator can act on. Breakout count is 0, honestly, because nothing leads on every axis.

Not included

Date-filtered search. SearchFilters declares dateFrom, dateTo and sort: 'date', but packages/all-things-youtube/src/youtube-client.ts implements none of them: only type, channelId, minViews, duration, live, captionsOnly and sort: 'views' do anything. An exact window needs a library release plus a processor lockfile bump, so the window is derived from each candidate's published-age text instead. That cannot see recent uploads ranking too poorly to appear at all, and the report says so in confidence.reasons.

Two follow-ups this exposes, both out of scope here: the agent's search_youtube tool advertises those same unimplemented filters to the model, and a cold scan still sheds videos (This YouTube processor is at capacity.) because enrichment fans out 6 videos, which is 12 concurrent container calls.

Also deferred from the design discussion: topic-level rollups in D1 so scans produce week-over-week deltas (needs a migration), and subscriber tiers for a "can a small channel win here" signal (needs one getChannel per unique channel).

Testing

• platform: 669 tests pass, 10 in trends.test.ts covering percentile midpoints, the Breakout gate on both estimated momentum and thin samples, the recency reservation against the channel cap, and neutral ranks for missing signals.
• web: 54 tests pass.
• tsc --noEmit clean in both packages; npm run docs:check clean after regenerating docs/api-reference/openapi.json.
• The before/after table above came from running the real API response through buildTrendReport in a throwaway test, since the scoring change cannot be verified against production until this deploys.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
video2ctx-web	Ready	Preview	Sep 21, 2026 9:54pm UTC