feat(node): V8–V11 — show-branch ladder, year-aware _best_match, wider sequel_variants

V8: the TV/show branch of _tmdb_search used the old "first candidate over
0.6 wins" shape. It now shares one _tmdb_ladder helper with the movie
branch — score every candidate query, keep the best, fast-path a
confident primary hit. A year lifted off the show's folder name
(title_parse.year_in, e.g. "Some.Show.2022.S01") rescues a sub-0.6 hit
that lands on the exact year. title_parse.clean_query de-dots a
folder-derived title without naive_title's extension-stripping trap.

V9: _best_match gains an optional `year`. When the top result is not a
confident textual hit (ratio < 0.6) and a year was requested, a
different result of that exact release year is preferred — TMDB already
year-filtered the search, so this is a hard corroboration, not the fuzzy
re-rank §3.3 warns against. A confident top hit is never overridden.
search_movie/search_tv forward the year.

V10: sequel_variants widened — trailing Roman→digit as well as
digit→Roman, spelled-out indices (one..twelve / un..douze / ordinals),
and a "Part N" / "Chapitre N" wrapper. Still empty for a trailing word
that is not an index or a 4-digit year.

V11: when the primary hit is already decent (>= 0.6) and there is nothing
more specific to try (no alternative_title, no sequel variant — only a
punctuation restatement left), the ladder returns without the extra
requests. The clean-title common case is back to one call.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018BMLQjqFGCize2KtNBT79v

1 files changed, 53 insertions, 0 deletions

diff --git a/packages/meshbay-node/tests/test_tmdb.py b/packages/meshbay-node/tests/test_tmdb.py
index fcbc2a2..ab452ce 100644
--- a/packages/meshbay-node/tests/test_tmdb.py
+++ b/packages/meshbay-node/tests/test_tmdb.py
@@ -40,6 +40,59 @@ async def test_search_movie_returns_top_result_and_confidence():
     await client.close()
 
 
+# ── §10.1/V9: year-exact preference, only when the top hit is weak ──────────
+
+@pytest.mark.asyncio
+async def test_year_exact_result_wins_when_the_top_hit_is_low_confidence():
+    # results[0] is TMDB's popularity #1 but a poor textual match for the
+    # query; results[2] is the exact requested year.
+    body = {"results": [
+        {"id": 1, "title": "Franchise vs. The Doctor", "release_date": "1962-10-05"},
+        {"id": 2, "title": "Franchise: Goldfinger", "release_date": "1964-09-17"},
+        {"id": 3, "title": "Second Errand", "release_date": "2002-11-20"},
+    ]}
+    client = TmdbClient(
+        roster=FakeRoster(),
+        transport=httpx.MockTransport(_handler({"search/movie": body})),
+    )
+    result, _ = await client.search_movie("The Franchise", 2002)
+
+    assert result["id"] == 3
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_year_is_ignored_when_the_top_hit_is_already_confident():
+    body = {"results": [
+        {"id": 1, "title": "The Franchise", "release_date": "1999-01-01"},
+        {"id": 2, "title": "Unrelated", "release_date": "2002-01-01"},
+    ]}
+    client = TmdbClient(
+        roster=FakeRoster(),
+        transport=httpx.MockTransport(_handler({"search/movie": body})),
+    )
+    result, ratio = await client.search_movie("The Franchise", 2002)
+
+    assert result["id"] == 1 and ratio > 0.9
+    await client.close()
+
+
+@pytest.mark.asyncio
+async def test_no_year_match_leaves_the_top_result_in_place():
+    body = {"results": [
+        {"id": 1, "title": "Something Else Entirely", "release_date": "1990-01-01"},
+        {"id": 2, "title": "Also Not It", "release_date": "1991-01-01"},
+    ]}
+    client = TmdbClient(
+        roster=FakeRoster(),
+        transport=httpx.MockTransport(_handler({"search/movie": body})),
+    )
+    result, _ = await client.search_movie("The Franchise", 2002)
+
+    assert result["id"] == 1
+    await client.close()
+
+
 @pytest.mark.asyncio
 async def test_search_tv_returns_top_result():
     body = {"results": [{"id": 7, "name": "Some Show"}]}