feat(filters): scopes + episode fields — the engine becomes the single query system (item 3.1)

The qf tree gains an optional top-level `scope` ("books" default |
"episodes" — absent = books, so every existing saved tree and legacy
client stays valid). The row head is scope-aware AND this closes a
real leak: the composed engine's head had NO podcasts exclusion, so
episodes already surfaced on All-Books qf queries (plan §9 violation —
the sqlc flat head excluded them, the composed head didn't). Books
scope now says library_type_name <> 'podcasts'; episodes scope is
source = 'podcast_episode'.

The registry fields declare their scopes (the plan's "reusable
template with conditionals" = scope-driven rendering in 3.3): episode
fields declare exactly the episodes scope and the books scope REJECTS
them at parse (the "hide podcasts from the rules on the all books
page" rule enforced server-side); books fields inside episodes trees
are allowed and honestly no-op on NULLs.

New fields (the item-2.4 rule vocabulary expressed in SQL):
- feed — KindIdentifier over podcast_feeds (RLS-governed suggestion
  source and match; unsubscribed feeds match nothing, by the engine)
- downloaded — is_true/is_false on download_state = 'downloaded'
- played — THE canonical finished predicate (viewer progress >= 0.999,
  the hide_finished definition shared with item 2.4), reading_progress
  join per viewer
- published_date — clauseDateFactory like added_at, within_days
  default op (the published_within rule's SQL form)

Engine hygiene: the stray ComposedSearch SQL debug printf is gone.

Pinned by TestFilterScopeValidation (unit: scope grammar, books×
episode-field 400s, legacy no-scope trees) and
TestFilterScopesAndEpisodeFields (integration: books head excludes
podcasts including the 404-no-results contract, episodes head is
episodes only, feed-in/downloaded/played/published-date evaluate in
SQL against a subscribed-feed fixture with a played viewer).

cmd/server/tests/filter_builder_test.go

@@ -295,6 +295,115 @@ func TestFilterComposedSemantics(t *testing.T) {
 	assert.Equal(t, []string{"Sem Tide"}, got, "published_year at_least")
 }
 
+// TestFilterScopesAndEpisodeFields pins item 3.1: the books scope
+// excludes podcasts (the leak the composed head used to have), the
+// episodes scope is episodes only, episode fields evaluate in SQL
+// (feed-in, downloaded, played, published-date-within), and episode
+// fields are 400s in books trees.
+func TestFilterScopesAndEpisodeFields(t *testing.T) {
+	setup := setupTestServer(t)
+	t.Cleanup(func() { _ = setup.Close() })
+
+	regUUID := getRegularUserID(t, setup.DB)
+	builderFixtureLib(t, setup, regUUID, "Scope")
+
+	// Podcasts library + a subscribed feed with three downloaded
+	// episodes: two fresh/unplayed, one played (~finished) — the
+	// played-rule fixture.
+	feedLib, _ := createPodcastsLibrary(t, setup, "test Scope Podcasts")
+	feed, err := setup.DB.CreatePodcastFeed(adminSeedCtx(t, setup), database.CreatePodcastFeedParams{
+		LibraryID: feedLib.ID,
+		FeedUrl:   "https://feed.invalid/scope-probe.xml",
+		Title:     "Scope Probe Feed",
+	})
+	require.NoError(t, err)
+	epFresh := upsertTestEpisode(t, setup, feed, "scope-fresh", "Scope Fresh Episode", 1)
+	epPlayed := upsertTestEpisode(t, setup, feed, "scope-played", "Scope Played Episode", 2)
+	upsertTestEpisode(t, setup, feed, "scope-pending", "Scope Pending Episode", 3)
+	subscribeRaw(t, setup, regUUID, feed.ID)
+	adminScopeExec(t, setup, adminCtxValue(t, setup), `
+		UPDATE media_items SET download_state = 'downloaded', file_size = 1000,
+		       date_published = CURRENT_DATE WHERE id IN ($1, $2)`, epFresh.ID, epPlayed.ID)
+	adminScopeExec(t, setup, adminCtxValue(t, setup), `
+		INSERT INTO reading_progress (media_item_id, user_id, percentage)
+		VALUES ($1, $2, 1.0) ON CONFLICT (media_item_id, user_id)
+		DO UPDATE SET percentage = 1.0`, epPlayed.ID, regUUID)
+
+	feedID := uuid.UUID(feed.ID.Bytes).String()
+
+	qfScoped := func(scope string, children ...map[string]interface{}) url.Values {
+		b, _ := json.Marshal(map[string]interface{}{"scope": scope, "mode": "all", "children": children})
+		return url.Values{"qf": {string(b)}}
+	}
+	const booksScope = "books"
+	const episodesScope = "episodes"
+
+	search := func(p url.Values) []string {
+		rows := p
+		status, body := qfSearch(t, setup, setup.RegularToken, rows)
+		// 404 is the endpoint's pinned no-results contract — an empty set.
+		require.Contains(t, []int{http.StatusOK, http.StatusNotFound}, status, "qf must parse: %v", rows)
+		return qfTitles(t, body)
+	}
+
+	t.Run("books_scope_excludes_podcasts", func(t *testing.T) {
+		// An exact-ish title hits BOTH a book fixture ("Scope Tide") and
+		// the episode fixture if the head leaks; books scope must return
+		// the book, never the episodes.
+		got := search(qfScoped(booksScope, qfRule("title", "is", "Scope Tide")))
+		assert.Equal(t, []string{"Scope Tide"}, got, "books scope returns the book")
+		got = search(qfScoped(booksScope, qfRule("title", "is", "Scope Fresh Episode")))
+		assert.Empty(t, got,
+			"books scope must never return podcast episodes (the composed-head leak is CLOSED)")
+	})
+
+	t.Run("episodes_scope_is_episodes_only", func(t *testing.T) {
+		got := search(qfScoped(episodesScope, qfRule("title", "is", "Scope Fresh Episode")))
+		assert.Equal(t, []string{"Scope Fresh Episode"}, got,
+			"episodes scope: only episodes — books drop")
+	})
+
+	t.Run("episode_rules_evaluate_in_sql", func(t *testing.T) {
+		got := search(qfScoped(episodesScope,
+			qfRule("feed", "in", feedID)))
+		assert.ElementsMatch(t, []string{"Scope Fresh Episode", "Scope Played Episode", "Scope Pending Episode"},
+			got, "feed-in matches every episode of the feed (download state is a separate rule)")
+
+		got = search(qfScoped(episodesScope,
+			qfRule("downloaded", "is_true")))
+		assert.ElementsMatch(t, []string{"Scope Fresh Episode", "Scope Played Episode"},
+			got, "downloaded:true drops the pending episode")
+
+		got = search(qfScoped(episodesScope,
+			qfRule("played", "is_false"),
+			qfRule("downloaded", "is_true")))
+		assert.ElementsMatch(t, []string{"Scope Fresh Episode"}, got,
+			"played:false + downloaded = the unplayed playable episode (viewer progress)")
+
+		got = search(qfScoped(episodesScope,
+			qfRule("played", "is_true")))
+		assert.ElementsMatch(t, []string{"Scope Played Episode"}, got,
+			"played:true matches the finished episode")
+
+		got = search(qfScoped(episodesScope,
+			qfRule("published_date", "within_days", "7"),
+			qfRule("downloaded", "is_true")))
+		assert.ElementsMatch(t, []string{"Scope Fresh Episode", "Scope Played Episode"},
+			got, "published-within includes the dated episodes")
+	})
+
+	t.Run("episode_fields_are_400_in_books_scope", func(t *testing.T) {
+		p := qfScoped(booksScope, qfRule("played", "is_true"))
+		req, _ := http.NewRequest("GET", setup.Server.URL+"/api/media-items/search?"+p.Encode(), nil)
+		req.Header.Set("Authorization", "Bearer "+setup.RegularToken)
+		resp, err := http.DefaultClient.Do(req)
+		require.NoError(t, err)
+		defer func() { _ = resp.Body.Close() }()
+		assert.Equal(t, http.StatusBadRequest, resp.StatusCode,
+			"episode-only fields are rejected in books trees at parse time")
+	})
+}
+
 func TestFilterUserRelativeFields(t *testing.T) {
 	setup := setupTestServer(t)
 	t.Cleanup(func() { _ = setup.Close() })