feat: fresh refinement

docs/FRESH.md

@@ -0,0 +1,79 @@
+# Fresh discovery
+
+Fresh intersects release evidence from one authenticated numeric autobrr filter
+with deterministic TMDB identity and downstream discovery policy. It is not
+request, acquisition, download, Jellyfin availability, or permanent tracker
+state.
+
+## Identity and admission
+
+- A movie identity is `(movie, tmdbId)`. Its first selected-filter observation
+  may qualify inside the configured movie window or the fixed 14-day
+  first-observation grace. Digital observations prefer TMDB Digital dates;
+  Blu-ray/UHD observations prefer Physical dates. Fallbacks are deterministic
+  and never invent a date.
+- An ordinary TV identity is `(tv, tmdbId, seasonNumber)`. Admission uses the
+  latest episode aired by the observation time (with the bounded one-day date
+  tolerance), then a trustworthy season date when episode dates are absent.
+  Parent-series age is not admission evidence.
+- An explicit special is `(tv, tmdbId, special, episodeNumber)` and uses the
+  exact special episode's air date. A bare or uncorroborated season zero remains
+  unknown.
+- Public TV presentation remains one canonical series card. When more than one
+  season/special is currently visible, the newest immutable admission controls
+  ordering; the individual histories remain independently durable.
+- Canonical identity is always the typed pair `(mediaType, tmdbId)`. Numeric
+  TMDB IDs are not globally unique across Movie and TV namespaces.
+
+An admitted Movie, Season, or Special has one irreversible Fresh clock.
+Additional episodes, packs, PROPER/REPACK/REMUX releases, qualities, title
+punctuation variants, source-generation changes, and rebuilds may add evidence
+but cannot reset `firstFreshAt` or `visibleUntil`.
+
+## Automatic and human state
+
+Fresh preserves source/parsed evidence, automatic typed resolution, automatic
+admission and content-policy reasons, optional typed manual resolution, optional
+admission override, and effective presentation as separate concepts.
+
+- **Resolve** validates the administrator-selected Movie/TV namespace and TMDB
+  ID server-side. The durable decision is bound to versioned sanitized source
+  evidence and can correct both type and ID without rewriting parsed evidence.
+- **Reset resolution** deactivates that human mapping and restores the current
+  automatic result. It does not erase source evidence or discovery history.
+- **Admit to Fresh** overrides a stable automatic policy exclusion only after a
+  typed identity and Movie/Season/Special identity exist. It cannot override No
+  Match, Ambiguous, transient provider failure, unknown TV season, an already
+  active item, or expired history.
+- **Remove override** restores automatic policy. Re-adding an override reuses
+  the original history and cannot create a new Fresh clock.
+
+All mutations are administrator-only, revision-bound, and serialized with sync,
+reconciliation, and rebuild operations. Candidate Diagnostics is the durable
+work queue; transient Pipeline decisions are operational telemetry.
+
+## Rebuild and continuity
+
+**Rebuild Fresh Data** clears and reconstructs only source-derived observations,
+candidates, checkpoint state, and the current source projection. It preserves:
+
+- typed canonical media metadata;
+- irreversible Movie/Season/Special histories;
+- typed manual resolutions and provenance;
+- admission overrides and provenance.
+
+Evidence already pruned by autobrr cannot be recovered. A missing authenticated
+checkpoint must remain `GAP_PRESERVED`; use the explicit Fresh reconciliation
+operation after backing up the isolated runtime. Reconciliation establishes a
+new source generation from retained history without claiming the missing source
+interval was observed. Old-generation evidence cannot activate current cards,
+while matching durable histories and human decisions remain available.
+
+## Data minimization
+
+Fresh persists bounded, sanitized observation evidence and durable identity /
+decision history. It must never persist or expose autobrr tokens, credentials,
+download URLs, tracker/private URLs, passkeys, cookies, raw action payloads,
+Axios objects, raw provider errors, or full TMDB responses. Public `/fresh`
+returns the paginated effective media projection only; candidate evidence and
+mutation endpoints remain administrator-only.

docs/SEERR_DOWNSTREAM_ROADMAP.md

@@ -29,7 +29,8 @@ downstream home.
 - `origin/downstream-main`: `f74657aa501e1fc28bf314673a0cedde167d47e6`.
 - Current infrastructure branch: `chore/downstream-image-publication`.
 - Upstream queue-sync contribution: [seerr-team/seerr#3535](https://github.com/seerr-team/seerr/pull/3535), open against `develop`.
-- Fresh discovery: merged into `downstream-main` and released as `custom-v1.0.7`.
+- Fresh discovery: merged into `downstream-main`; current architecture and
+  operating invariants are documented in [Fresh discovery](FRESH.md).
 - Local integration harness: the separate `seerr-harness` workspace.
 
 ## Phase 1 — safe downstream foundation
@@ -49,6 +50,10 @@ downstream home.
 ## Phase 2 — downstream features and repeatable upkeep
 
 - [x] Deliver persistent Fresh discovery with focused tests and downstream release validation.
+- [x] Refine Fresh with irreversible Movie/Season/Special history, typed manual
+  correction, admission overrides, and an administrator work queue.
+- [ ] Add administrator shortcuts from Fresh/Discover to Fresh Settings.
+- [ ] Improve validation performance without weakening exact-tree evidence.
 - [ ] Evaluate direct/on-demand Download Sync refresh as a separate downstream feature.
 - [ ] Add automated upstream change detection.
 - [ ] Add reusable upstream sync-PR generation if manual sync becomes costly.

docs/SEERR_HANDOFF.md

@@ -54,9 +54,11 @@ maintenance branch.
 ### Fresh
 
 Fresh is merged into `downstream-main` and maintained in this repository. The
-authoritative released implementation is `custom-v1.0.7`; the earlier isolated
-prototype checkout has been retired. Continue Fresh maintenance from the primary
-Seerr checkout and preserve its persistent incremental architecture.
+earlier isolated prototype checkout has been retired. Continue Fresh maintenance
+from the primary Seerr checkout and preserve its persistent incremental
+architecture. The durable Movie/Season/Special identity, irreversible-history,
+typed correction, override, rebuild, and GAP-recovery contract is documented in
+[Fresh discovery](FRESH.md).
 
 ### Local harness