# Changelog All notable changes to Alfred are documented here. The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Alfred is not yet on SemVer — entries are grouped by **dated work blocks** instead of release numbers. Granularity targets behavioral or API-visible changes; refer to `git log` for commit-level detail. Sections used per block: **Added** / **Changed** / **Deprecated** / **Removed** / **Fixed** / **Internal** (for tech-debt and refactor noise that doesn't affect callers). --- ## [Unreleased] ### Added - **`.alfred` v2 — Phase 4: v2-shaped `rescan_show` + new `rescan_movie` + index anchor-warning + `tmdb_cache_ttl_days` setting.** Fourth and final structural phase of `specs/dot_alfred_v2.md` on branch `refactor/dot-alfred-v2`. The TV + movie rescan orchestrators now write v2 release aggregates (`SeriesRelease` / `MovieRelease`) via the concrete v2 repositories; the library index keeps auto-healing from the new sidecars on its next read (no TMDB call from rescan — that stays Phase 5). - **`rescan_show`** moves from `alfred/application/library/` to `alfred/application/tv_shows/` (symmetry with the new `alfred/application/movies/`). New signature: `(show_root, *, tmdb_id: TmdbId, imdb_id: ImdbId | None = None, series_repo, scanner, prober, kb) -> SeriesRelease`. - **`rescan_movie`** (new — `alfred/application/movies/rescan.py`) locates the main video via `find_video_file`, runs `inspect_release` once, and writes the per-movie `.alfred` sidecar. `added_at = datetime.now(UTC)` on every rescan (the sidecar records reconciliation time, not filesystem mtime). Raises `MovieRescanFailed` when no video is found in the folder. - **PACK semantics in `rescan_show`**: a single-video + no-episode season becomes `SeasonRelease(mode=PACK, folder=…, episodes=())`. The slot map stays empty until the Phase 5 TMDB sync supplies `episode_count` — no fabricated `EpisodeRange` lands in the sidecar. *(Superseded by Phase 4b — see Fixed.)* - **`Settings.tmdb_cache_ttl_days: int = 14`** — placeholder for the Phase 5 TTL policy on library-index entries (`fetched_at + TTL` drives refresh decisions). - **Library-index anchor-mismatch warning** — both `DotAlfredTVShowLibraryIndex` and `DotAlfredMovieLibraryIndex` now cross-check each entry's `metadata.path` against the on-disk folder layout right after a successful parse. Drift is logged as a `WARNING` (one per missing folder, with `tmdb_id`); the heal path stays silent by construction (it always synthesizes from real folder names). - **`.alfred` v2 — Phase 5: TMDB sync orchestrators.** Fifth phase of `specs/dot_alfred_v2.md` on branch `refactor/dot-alfred-v2`. Two new orchestrators refresh the library-root index's TMDB-cached fields from on-disk truth + a single TMDB call: - **`sync_show`** (`alfred/application/tv_shows/sync.py`) calls `TMDBClient.get_tv_show_info`, loads the release via `DotAlfredSeriesReleaseRepository.load_by_tmdb_id`, and upserts the result into `DotAlfredTVShowLibraryIndex`. Honors `Settings.tmdb_cache_ttl_days`; placeholder entries (auto-healed, `status == "unknown"`) always refresh; `force=True` overrides both gates. Raises `ShowNotFoundInLibrary` when neither index nor sidecar carry `tmdb_id`. Indexed shows with a missing per-show sidecar still get a fresh TMDB pass — slot map clears until rescan repopulates it. - **`sync_movie`** (`alfred/application/movies/sync.py`) is the movie-side parallel. Placeholder signature is `name == metadata.path` (auto-heal copies the folder name into `name`; the sidecar schema requires `name` non-empty so we can't use `name == ""`). When the per-movie sidecar is gone but the index entry remains, sync warns and returns the existing entry unchanged (no upsert possible without a release). - **`TmdbMovieInfo` DTO + `TMDBClient.get_movie_info`** — symmetric to the existing `TmdbShowInfo` / `get_tv_show_info` pair. Carries `tmdb_id`, `imdb_id`, `title`, and `release_year` (parsed from TMDB's `release_date`). - **`load_by_tmdb_id` on the v2 release repositories.** The series repo returns `(SeriesRelease, show_folder_name)` so the sync orchestrator can feed `DotAlfredTVShowLibraryIndex.upsert(..., path=...)`; the movie repo returns `MovieRelease` alone (folder is on `release.folder` already) and is provided as a semantic alias of `find_by_tmdb_id` for symmetry. - **`alfred/application/exceptions.py`** — new module for the two shared `*NotFoundInLibrary` exceptions raised by the sync orchestrators (`ShowNotFoundInLibrary`, `MovieNotFoundInLibrary`). ### Fixed - **PACK vs EPISODIC classification (Phase 4b).** The Phase 4 walker + `rescan_show` logic classified seasons by parser output (does the filename carry `Exx`?), but PACK vs EPISODIC is a *structural* distinction: - **PACK** = season folder with N flat `SxxEyy` videos. - **EPISODIC** = season folder with N subfolders, each holding one video. The walker now descends two levels under `show_root` and classifies per season folder. Mixed (flat + subfolders) is malformed — warn and skip. `rescan_show` trusts the walker's mode and stops conflating "single un-numbered video" with PACK (that case is now skipped as malformed too). Tests rewritten against the real model. Supersedes the PACK-semantics bullet above in Added. ### Removed - **v1 dot_alfred stack and its abstract domain ports.** Deleted `alfred/infrastructure/persistence/dot_alfred/{bridge,repository, serializer,sidecar}.py`, plus the `alfred/domain/{tv_shows,movies}/repositories.py` ABCs (`TVShowRepository` / `MovieRepository`) — zero callers after Phase 4. `dot_alfred/__init__.py` is rewritten as a v2-only re-export (four concrete repositories + `ShowFolderUnknown`). - **`alfred/application/library/` package** (rescan + walker moved to `alfred/application/tv_shows/`). - The two Phase 3 module-level test skips (`test_repository.py`, `test_serializer.py`) are lifted by deleting the quarantined files. - **`MediaWithTracks` mixin + `track_lang_matches` helper** in `alfred.domain.shared.media`. Parked in Phase 4 pending a Phase 5 decision; zero callers across `alfred/` and `tests/` after the v2 aggregates landed, so both go. ### Internal - **Suite**: 1233 → 1277 passing; 10 → 8 skips (only LLM-not-running skips remain — the Phase 3 quarantines are gone with their files). - Phase 5 cleanup sweep returns zero hits for `MediaWithTracks`, v1 dot_alfred symbols, v1 sidecar names, and `alfred.application. library` — the v2 surface is the only one left. ### Changed - **`.alfred` v2 — Phase 3: `TVShow` / `Movie` aggregates become TMDB-only.** Third phase of `specs/dot_alfred_v2.md` on branch `refactor/dot-alfred-v2`. Filesystem-side concerns (file paths, tracks, quality, mode, `added_at`) move to the `releases/` domain added in Phase 1; the TMDB aggregates now carry only identity + TMDB catalog facts. - **`TVShow`** — `tmdb_id: TmdbId` is now the **required primary key**; `imdb_id: ImdbId | None` is the optional secondary anchor. Added `status: str = "unknown"` (raw TMDB string, default matches the v2 library-index auto-heal placeholder). `episode_count` aggregates the TMDB-cached counts on each `Season` (was: sum of materialized `Episode` objects). - **`Season`** — added `episode_count: int = 0` (TMDB-cached, authoritative). **Removed**: `audio_tracks`, `subtitle_tracks`, and the `mode` property (release mode now lives only on `SeasonRelease.mode` — single source of truth). - **`Episode`** — slimmed to identity + title. **Removed**: `file_path`, `file_size`, `audio_tracks`, `subtitle_tracks`. The `MediaWithTracks` mixin is no longer in `Episode`'s MRO; on-disk facts live on the matching `EpisodeRelease` keyed by `(season_number, episode_number)`. - **`Movie`** — `tmdb_id: TmdbId` required, `imdb_id` optional. **Removed**: `file_path`, `file_size`, `quality`, `added_at`, `audio_tracks`, `subtitle_tracks`. `get_filename()` now returns `"Title.Year"` (quality lives on `MovieRelease` and is appended by a release-aware caller — Phase 4 wires this through `MediaOrganizer`). - **`TVShowBuilder` / `SeasonBuilder`** — constructor requires `tmdb_id: TmdbId`; `imdb_id` and `status` are optional. `SeasonBuilder.set_episode_count(int)` replaces the old `set_audio_tracks` / `set_subtitle_tracks` (tracks no longer persisted on `Season`). - **`MovieRelease` carries `added_at: datetime`** (required). Bumped `dot_alfred/v2` `SCHEMA_VERSION` from `1` → `2` to add `added_at: datetime` to `MovieReleaseSidecar`. Round-trip via Pydantic `mode="json"` (datetime ↔ ISO 8601 string). No migration code shipped — no v2.1 sidecars exist in the wild yet. - **No-coercion `TmdbId` contract.** `TVShow(tmdb_id=1396)` now raises — callers pass `TmdbId(1396)`. Same for `imdb_id: ImdbId | None` on `TVShow`/`Movie`. Honest type contract, no ergonomic shim. ### Removed - `Season.mode` property (derive from `SeasonRelease.mode` instead). - `Episode.file_path` / `file_size` / `audio_tracks` / `subtitle_tracks`. - `Movie.file_path` / `file_size` / `quality` / `added_at` / `audio_tracks` / `subtitle_tracks`. ### Internal - v1 dot_alfred package (`bridge.py`, `repository.py`, `serializer.py`, `sidecar.py`), the abstract `TVShowRepository` / `MovieRepository` ports typed against the pre-Phase-3 aggregates, and `alfred/application/library/rescan.py` are **intentionally left in tree as a known-red island**. Their tests (`tests/infrastructure/persistence/dot_alfred/test_repository.py`, `test_serializer.py`, `tests/application/library/test_rescan.py`) are module-level skipped with a Phase 4 reference. Phase 4 rewrites `rescan_show` / introduces `rescan_movie` on top of the v2 release repositories + library index, then deletes the v1 stack + the abstract ports + the quarantined tests in one swing. - Test suite: 1216 passed, 11 skipped (8 pre-existing + 3 Phase-3 quarantines), 4 xfailed. v2 round-trip tests now reference `SCHEMA_VERSION` instead of hard-coded `1` for future-proofing. ### Added - **`.alfred` v2 — Phase 2: new persistence package + TMDB client extensions.** Second phase of `specs/dot_alfred_v2.md` on branch `refactor/dot-alfred-v2`. The new `alfred/infrastructure/persistence/dot_alfred/v2/` package ships the full v2 sidecar stack while leaving v1 (and the existing `TVShow` aggregate) untouched — Phase 3 is the cutover. - **Pydantic DTOs** — `SeriesReleaseSidecar` / `MovieReleaseSidecar` (per-item), `TVShowLibraryIndexSidecar` / `MovieLibraryIndexSidecar` (library-root index). All built on a common `_Strict` base (`extra="forbid"`, `frozen=True`) with a `@model_validator` enforcing `schema_version == 1`. - **Track entries** — `AudioTrackEntry` / `SubtitleEntry` (sidecar cache shape, slimmed from the domain track types). `SubtitleEntry` carries `is_forced` + `is_sdh` as explicit booleans (v1's `type: "sdh"` overload is gone). - **Serializer** — `read_yaml` / `atomic_write_yaml` helpers centralize YAML I/O and atomic writes (`.tmp + os.replace`). `SidecarSchemaError` wraps both YAML parse errors and Pydantic validation errors for uniform catch-and-skip semantics. - **Bridge** — lossless `domain ↔ sidecar` conversion for `SeriesRelease` / `MovieRelease` (round-trippable, including multi-episode ranges and `is_sdh` subtitles); one-way projection for library-index entries (`show_index_entry_from`, `movie_index_entry_from`) that flattens multi-episode files into per-TMDB-slot maps in `seasons[*].episodes`. - **Repositories** — `DotAlfredSeriesReleaseRepository` / `DotAlfredMovieReleaseRepository` walk `library_root/*/` with log+skip on corruption; **`DotAlfredTVShowLibraryIndex`** / **`DotAlfredMovieLibraryIndex`** auto-heal silently on missing or corrupt index files by rebuilding from the per-item sidecars (healed entries keep TMDB-cached fields as placeholders until the next sync repopulates them). Writes are atomic and never auto-heal (read paths handle that). - **TMDB client extensions** — `TmdbSeasonInfo` / `TmdbShowInfo` DTOs + `TMDBClient.get_tv_show_info(tmdb_id)` aggregating `/tv/{id}` + `/tv/{id}/external_ids`. The parsing logic is a pure function (`parse_tv_show_info`) testable without HTTP, with an injectable reference date for deterministic `aired` flag tests. - **`is_sdh` flag on `SubtitleTrack`.** Added to `alfred/domain/shared/media.py::SubtitleTrack` to mirror ffprobe's `hearing_impaired` disposition. Wired through the ffprobe layer (`ffprobe_prober.py`) and the v2 sidecar bridge so SDH information round-trips end-to-end. Defaults to `False` — backwards-compatible for every existing caller. - **37 v2 integration tests** on `tmp_path` covering round-trips (domain ↔ sidecar ↔ YAML ↔ domain), atomic writes (no `.tmp` leftovers), per-item log+skip on corruption / schema mismatch, movie anchor-mismatch warning, full upsert / find / delete on both library indexes, and the auto-heal path on missing / corrupt / schema-mismatched index files. **16 TMDB DTO tests** for the new `parse_tv_show_info` pure function. - **`.alfred` v2 — Phase 1: new `releases/` domain.** First step of `specs/dot_alfred_v2.md` on branch `refactor/dot-alfred-v2`. The new `alfred/domain/releases/` package introduces a filesystem-only bounded context separated from TMDB identity (the existing `tv_shows` / `movies` domains). It hosts: - **`EpisodeRange` VO** — covers single-episode files (`EpisodeRange(E02, E02)`) and multi-episode files (`EpisodeRange(E02, E04)` for `SxxE02E03E04.mkv`), with `count()` / `numbers()` / `is_single()` helpers. - **`ReleaseMode` enum** — `PACK` (N video files directly in the season folder) vs `EPISODIC` (N sub-folders, one episode each); classified by the walker, never re-derived. - **Aggregates** — `TrackProfile`, `EpisodeRelease`, `SeasonRelease` (with `episode_count()` summing each file's range), `SeriesRelease`, `MovieRelease`. All frozen dataclasses; mutation via `SeasonReleaseBuilder` / `SeriesReleaseBuilder` (mirror the v1 `TVShowBuilder` pattern, including `from_existing()` round-trip). - **Abstract ports** — `SeriesReleaseRepository`, `MovieReleaseRepository` (concrete `DotAlfred*` arrive in Phase 2). - **`TmdbId` VO** added to `alfred/domain/shared/value_objects.py` (positive int, rejects bool/str/float — symmetry with `ImdbId`). - 73 unit tests covering VO validation, entity invariants, builder sort + overlap detection, and `from_existing()` round-trips. v1 code paths untouched at this stage; new domain coexists. - **`rescan_show` orchestrator (`alfred/application/library/rescan.py`).** Step 4 of the `specs/dot_alfred.md` plan. Walks an Alfred-managed show folder, runs the existing `inspect_release` pipeline on every video file it finds, and assembles a frozen `TVShow` aggregate persisted via the injected `TVShowRepository`. Reuses the release parser + ffprobe path verbatim — no duplicated parse/probe logic at the library layer. PACK vs EPISODIC inferred per season folder from the on-disk file count + parser output: a single video whose name carries no `Exx` token becomes a PACK season (tracks lifted to the season-level `audio_tracks` / `subtitle_tracks`), anything else becomes EPISODIC (one `Episode` per file). Episode paths are stored relative to the show root for portability. Files that fail to parse a season/episode number, or seasons with mixed numbers, are logged and skipped — the orchestrator never raises. Embedded subtitle tracks are captured from `ffprobe`; adjacent `.srt` files, multi-episode entries (`S01E01E02`), and TMDB-driven PACK detection are tracked as tech debt for a dedicated subtitles / ShowTracker session. 7 integration tests on `tmp_path` with the Foundation layout (S01 EPISODIC + S02 PACK) cover the round-trip through the real `.alfred` repository. - **Show tree walker (`alfred/application/library/walker.py`).** Step 4a foundation. `walk_show(show_root, scanner, kb)` returns a `ShowTree(show_root, season_folders=tuple[SeasonFolder, ...])` — pure structural snapshot, no parsing, no probing. Season folders are detected by a `\bS\d{1,2}\b` token anywhere in the directory name (release-style naming, no Plex `Season 01` / `Specials` conventions). Video files are filtered against `kb.video_extensions`; no recursion into sub-sub-folders. 11 unit tests on `tmp_path` cover detection (case-insensitive, in-word rejection), filtering (subs, NFO, sample files), and edge cases (empty / missing show root). - **Season-level audio/subtitle tracks (`alfred/domain/tv_shows/entities.py`, `alfred/domain/tv_shows/builders.py`).** `Season` now inherits from `MediaWithTracks` and carries `audio_tracks` / `subtitle_tracks` tuples (empty by default). Populated only in PACK mode (the single release covering the whole season); empty in EPISODIC mode where tracks live per-episode. `SeasonBuilder` gains `set_audio_tracks()` / `set_subtitle_tracks()` and forwards them through `from_existing()`. The bridge writes / reads them in the PACK branch via shared `_synth_audio_tracks` / `_synth_subtitle_tracks` helpers used for episodes too. - **`DotAlfredTVShowRepository` — filesystem-backed implementation of the `TVShowRepository` port (`alfred/infrastructure/persistence/dot_alfred/repository.py`).** Step 3 of the `specs/dot_alfred.md` plan. Reads and writes one `.alfred` YAML file per show under a configurable `library_root`. `save(show)` writes atomically (`.alfred.tmp` + `os.replace`) into a folder that **must already exist** — the repository never invents a folder name (the upstream `MediaOrganizer` is in charge of placing files; the repo writes the sidecar next to them). `find_by_imdb_id` / `find_all` walk `library_root/*/`, loading each readable sidecar; folders without a sidecar return `None` / are skipped (no implicit cold scan — that is the job of the upcoming `rescan_show` tool). Corrupted YAML and schema violations are logged and skipped, never raised, so a single bad folder does not break the rest of the library. The repo keeps a tiny in-memory `imdb_id → folder_name` index populated on every successful read/save, so subsequent saves find the right destination without re-walking — useful when the show folder name diverges from `show.get_folder_name()` (custom 1080p / 4K variants). 20 integration tests on `tmp_path` cover the round-trip, cold folder / unknown id returns, multi-show `find_all`, corrupted / wrong-schema skipping, atomic write (no `.alfred.tmp` left behind), overwrite, and folder-name fallbacks. - **Sidecar ↔ TVShow bridge (`alfred/infrastructure/persistence/dot_alfred/bridge.py`).** `to_sidecar(show, folder_paths=...)` summarizes the rich domain `AudioTrack` / `SubtitleTrack` to the sidecar's compact form (unique audio languages in track order; subtitle entries derived from `is_forced` and assumed `source="embedded"`). `from_sidecar(sidecar, title=...)` reconstructs the domain `TVShow` with synthesized tracks — one `AudioTrack` per language, one `SubtitleTrack` per entry, with ffprobe-only fields (`codec`, `channels`, `channel_layout`) left as `None`. The bridge is intentionally lossy on probe minutiae the sidecar does not store; this is the documented trade-off from the factual-only spec. - **`.alfred` sidecar serializer (`alfred/infrastructure/persistence/dot_alfred/`).** Implements step 2 of the `specs/dot_alfred.md` plan. Pure-dict in/out (`serialize(sidecar) -> dict`, `deserialize(data) -> ShowSidecar`) — YAML I/O lives in the repository layer (step 3) and is kept out for trivial testability. Ships the DTOs that mirror the YAML schema field-for-field (`ShowSidecar`, `SeasonSidecar`, `EpisodeSidecar`, `SubtitleEntry`). The sidecar acts as a **scan cache**: it stores only what is genuinely costly to recompute — folder/file paths (skipping the FS walk) and probed track metadata (skipping ffprobe). Release identifiers (group, source, quality, codec) live in folder and file names and are derived on demand by the parser — they are deliberately absent from the schema and rejected on deserialize. The serializer is **strict on schema**: unknown keys at any level raise `SidecarSchemaError`, missing required fields raise clearly, and `bool` cannot sneak in as a season/episode number. Optional fields (`tmdb_id`, empty `audio`/`subtitles`/`episodes`) are omitted from the output rather than emitted as `null` / `[]`. Tests cover round-trip equivalence (DTO → dict → DTO and DTO → YAML text → DTO), the Foundation S01 PACK case (real-world fixture with mixed sub types — superset captured at season scope), and a Breaking Bad S05 EPISODIC case. An on-disk `tmp_path` fixture recreates the Foundation folder structure with placeholder files, ready to be reused by the upcoming repository walk tests in step 3. - **`TVShowBuilder` / `SeasonBuilder` — sole construction surface for the TVShow aggregate** (`alfred/domain/tv_shows/builders.py`). The aggregate is now fully frozen; building goes through a mutable scratchpad that emits an immutable `TVShow` via `build()`. Both builders offer a `from_existing()` classmethod to seed from a current frozen aggregate and apply modifications. Episodes are emitted sorted by number within a season, seasons sorted by number within the show. - **`SeasonMode` enum** (`PACK` / `EPISODIC`) in `alfred/domain/tv_shows/value_objects.py`. Computed at read time from the season's structural shape (`Season.mode` property): a season with no explicit episodes is `PACK` (a single release covering the whole season), a season with episodes is `EPISODIC` (currently airing, one release per episode). Never stored — the YAML sidecar encodes the mode via the presence/absence of the `episodes:` block. ### Changed - **TVShow aggregate is now frozen all the way down.** `TVShow`, `Season` and `Episode` are all `@dataclass(frozen=True)`. Children are stored as ordered tuples (`tuple[Season, ...]`, `tuple[Episode, ...]`) sorted by their respective numbers, replacing the previous mutable dicts. Lookup helpers `TVShow.get_season(n)` and `Season.get_episode(n)` traverse the tuple lazily via `next()`. The former `add_episode` / `add_season` mutation methods are gone — all construction goes through `TVShowBuilder` / `SeasonBuilder`. ### Removed - **ShowTracker-territory fields stripped from the TVShow aggregate.** The aggregate now models only what the `.alfred` sidecar stores (filesystem-observable facts + immutable identity). Dropped from the domain: - `TVShow.status` (`ShowStatus`) and the `ShowStatus` enum entirely, along with its TMDB string mapping (`from_string`). - `TVShow.expected_seasons`, `Season.expected_episodes`, `Season.aired_episodes`, `Season.name`. - `TVShow.collection_status()`, `is_complete_series()`, `missing_episodes()`, `is_ongoing()`, `is_ended()` and the `CollectionStatus` enum. - `Season.is_complete()`, `is_fully_aired()`, `missing_episodes()` and the `aired ≤ expected` validation. - `TVShow.add_episode()` / `TVShow.add_season()` / `Season.add_episode()` — replaced by the builder API. These concerns will reappear in a dedicated `ShowTracker` layer (to be designed) that combines the `.alfred` sidecar with live TMDB data to answer questions like "is this show complete?" or "are new episodes out?". Keeping volatile/derived state out of the aggregate matches the factuel-only philosophy locked in `specs/dot_alfred.md`. ### Internal - **Test suite rewritten for the new aggregate shape.** `tests/domain/test_tv_shows.py` now covers frozen invariants, builder ordering, last-write-wins on duplicates, `from_existing` round-trip, and `SeasonMode` derivation. `tests/infrastructure/test_filesystem_extras.py` helper simplified (no more `ShowStatus.ENDED` / `expected_seasons` on test shows). 1078 tests still green. - **Design doc for `.alfred/` sidecar persistence (`specs/dot_alfred.md`).** First entry in the new `specs/` directory. Specifies a per-show `.alfred/` directory holding a `show.yaml` and one `season_NN.yaml` per season, used by the upcoming concrete `TVShowRepository` to cache parse/probe results and avoid full rescans on every library read. Covers schema, naming conventions, cache invalidation strategy (size + mtime), self-healing on drift, atomicity (`os.replace`), edge cases (legacy folders, corrupted sidecars, manual file removal), and a phased implementation plan. No code yet — spec only. ### Internal - **`specs/` is now tracked.** The repo-level `.gitignore` had a blanket `*.md` rule with only `CHANGELOG.md` allow-listed. Added explicit exceptions for `/README.md` (root only — avoids unintentionally exposing fixture READMEs) and `specs/**/*.md` so the new design-doc directory ships with the project. Also added an explicit `/.claude/` ignore line for the private dev-docs sub-repo that sits inside the working tree but is versioned separately. ### Fixed - **Multi-episode chain (e.g. `S14E09E10E11`) now collapses to a full range.** The parser previously captured `episode=9, episode_end=10` and dropped E11+. It now returns `episode=first, episode_end=last`, with intermediate values implied. Fixture `shitty/archer_multi_episode/` updated from anti-regression-of-bug to anti-regression-of-fix. - **Apostrophes in titles no longer push the release through the AI fallback.** `Honey.Don't.2025.2160p.WEBRip.DSNP.DV.HDR.x265-Amen` previously parsed with `parse_path="ai"` and everything UNKNOWN because `'` is in the forbidden-chars list. Apostrophes are now pre-stripped before the well-formed check, so the parse completes normally (`title=Honey.Dont, year=2025, quality=2160p, ...`); only the title text loses its apostrophe. `parse_path` becomes `sanitized` to surface the cleanup. Side win: PoP fixture `the_prodigy_full_chaos/` also moves from total failure to a partially-correct parse (year, source, codec extracted). - **Season-range markers (`Sxx-yy`) are now recognized as `tv_complete`.** `Der.Tatortreiniger.S01-06.GERMAN...` previously parsed as `media_type=movie` with `S01-06` glued onto the title. The parser now recognizes the range, sets `season=first`, `media_type=tv_complete`, and removes the marker from the title. `is_season_pack` flips to `true`. - **Pure-punctuation TITLE tokens are dropped at assembly.** Releases with surrounding ` - ` separators (`Vinyl - 1x01 - FHD`) previously produced `title="Vinyl.-"`. Such tokens (a stray dash, a wide pipe `｜`, …) carry no title content and are now filtered out. Side effect: PoP fixture `khruangbin_yt_wide_pipe/` also benefits — the YouTube wide-pipe no longer leaks into the title. ### Added - **Fullwidth vertical bar `｜` (U+FF5C) is now a recognized release-name token separator.** Added to `alfred/knowledge/release/separators.yaml` so CJK release names (and the occasional decorative YouTube-style use) tokenize cleanly instead of leaving the wide pipe glued onto an adjacent token. The tokenizer in `alfred/domain/release/parser/pipeline.py` already iterates the separator list as plain strings (no regex), so a multi-byte UTF-8 separator works without any code change. - **`InspectedResult.recommended_action` property** — derived hint that collapses the orchestrator's go / wait / skip decision into a single value (``"process"`` / ``"ask_user"`` / ``"skip"``). Centralizes the exclusion logic that was previously dispersed across road / media_type / main_video checks at each call site. Ordering is part of the contract: ``skip`` (no main video, or media_type == ``"other"``) wins over ``ask_user`` (media_type == ``"unknown"`` or road == ``"path_of_pain"``) which wins over ``process``. Surfaced through the ``analyze_release`` tool so the LLM can route on it directly. 6 new tests in ``tests/application/test_inspect.py`` cover the four branches and the precedence rules. - **`LanguageRepository` port** in `alfred.domain.shared.ports`. Structural Protocol covering `from_iso`, `from_any`, `all`, `__contains__`, `__len__` — the surface previously coupled to the concrete `LanguageRegistry`. Mirrors the `MediaProber` / `FilesystemScanner` pattern: domain code depends on the Protocol, infrastructure provides the YAML-backed adapter. Tests in `tests/infrastructure/test_language_registry.py`. ### Changed - **`Movie` and `Episode` are now frozen dataclasses.** Both entities hold their track collections as `tuple[AudioTrack, ...]` and `tuple[SubtitleTrack, ...]` instead of mutable lists, and are `@dataclass(frozen=True, eq=False)` (identity-based equality preserved via `__eq__`/`__hash__`). `__post_init__` coercion uses `object.__setattr__` for the `imdb_id` / `title` / `season_number` / `episode_number` normalizations. To project enrichment results (probe output, file metadata) callers now rebuild via `dataclasses.replace(...)`. Pattern aligned with the recent `ParsedRelease` freeze. `MediaWithTracks` mixin contract updated to `tuple` accordingly. `Season` and `TVShow` remain mutable for now — freezing the aggregate root would cascade a full reconstruction on every `add_episode`, deferred. - **`SubtitleCandidate` renamed to `SubtitleScanResult`.** The old name conflated "this might become a placed subtitle" with "this is what a scan pass produced". The class is the output of a scan/identify pass — language/format may still be `None`, confidence reflects how sure the classifier is, and `raw_tokens` holds the filename fragments under analysis. `SubtitleScanResult` says that directly. Pure rename with a refreshed docstring in `alfred/domain/subtitles/entities.py`; no behavior change. Touches the domain entity + `__init__` export, the matcher / identifier / utils services, the manage_subtitles use case, the placer, the metadata store, the shared-media cross-ref comment, and the seven test modules that imported the type. - **`ParsedRelease` is now frozen; enrichment passes return new instances.** The VO was mutable so `detect_media_type` and `enrich_from_probe` could patch fields in place — a code smell in a value object whose identity *is* its content. `ParsedRelease` is now `@dataclass(frozen=True)`; `languages` is a `tuple[str, ...]` instead of a `list[str]`. `enrich_from_probe` returns a new `ParsedRelease` via `dataclasses.replace` (only allocates when at least one field actually changed). `inspect_release` rebinds `parsed` after both `detect_media_type` (wrapped in `MediaTypeToken` to satisfy the strict isinstance check that now also runs on replace) and `enrich_from_probe`. Parser pipeline now packs `languages` as a tuple in the assemble dict. Callers updated: `inspect_release`, `testing/recognize_folders_in_downloads.py`, and the enrichment tests (22 call sites + language assertions switched to tuple literals). - **`resolve_destination` use cases take `kb` / `prober` as required params; module-level singletons gone.** The four `resolve_{season,episode,movie,series}_destination` use cases now accept `kb: ReleaseKnowledge` and `prober: MediaProber` as required arguments, matching the shape of `inspect_release`. The module-level `_KB = YamlReleaseKnowledge()` and `_PROBER = FfprobeMediaProber()` singletons that previously lived in `alfred/application/filesystem/resolve_destination.py` are removed — the application layer no longer reaches into infrastructure. The singletons now live at the agent-tools frontier (`alfred/agent/tools/filesystem.py`), where the LLM-facing wrappers instantiate them once and thread them through. `analyze_release` no longer needs the dirty `from ... import _KB` indirection. Tests inject their own stubs by keyword (`prober=_StubProber(...)`) instead of monkeypatching a module attribute. - **`ParsePath` enum renamed to `TokenizationRoute`.** The old name collided with `pathlib.Path` in code-reading mental models, and was one letter from `parse_path` (the field that holds the value) — making it harder than it needed to be to spot the type vs the attribute. ``TokenizationRoute`` says what it actually captures (DIRECT / SANITIZED / AI = how the name reached the tokenizer), and the class docstring now spells out the orthogonality with ``Road`` (EASY / SHITTY / PATH_OF_PAIN, which captures parser confidence on ``ParseReport``). The ``parse_path`` field name stays unchanged — string values too — so YAML fixtures, the ``analyze_release`` tool spec, and any external consumer are untouched. - **`enrich_from_probe` codec mappings moved to YAML.** The three hard-coded module dicts (`_VIDEO_CODEC_MAP`, `_AUDIO_CODEC_MAP`, `_CHANNEL_MAP`) translating ffprobe output to scene tokens (`hevc → x265`, `eac3 → EAC3`, `8 → "7.1"`, …) now live in `alfred/knowledge/release/probe_mappings.yaml` and are loaded into `ReleaseKnowledge.probe_mappings` (new port field, populated by `YamlReleaseKnowledge`). `enrich_from_probe` gains a third `kb` parameter and reads the maps from there. Aligns with the CLAUDE.md rule that lookup tables of domain knowledge belong in YAML, not in Python — and opens the door to a future "learn new codec" pass. Callers updated: `inspect_release`, `testing/recognize_folders_in_downloads.py`, and all 22 sites in `tests/application/test_enrich_from_probe.py`. - **`ParsedRelease.tech_string` is now a derived `@property`** (`alfred/domain/release/value_objects.py`). It computes `quality.source.codec` joined by dots on every access, so it stays in sync with the underlying fields by construction. The stored field is gone from the dataclass, the dict returned by `assemble()` no longer carries the key, `parse_release`'s malformed-name fallback drops the `tech_string=""` kwarg, and `enrich_from_probe` no longer re-derives it after filling `quality`/`source`/`codec`. Closes the parser/enrichment double-source-of-truth that `e79ca46` had to fix reactively. The fixtures runner now injects `tech_string` alongside `is_season_pack` since `asdict()` skips properties. - **`RuleScope.level` is now an enum (`RuleScopeLevel`).** The set of valid levels (global, release_group, movie, show, season, episode) was documented only in a docstring comment and validated nowhere. `RuleScopeLevel(str, Enum)` keeps wire compatibility (YAML serialization, `.value` access) while making the closed set explicit to type-checkers and IDEs. `to_dict()` emits `.value` strings so YAML output is unchanged. - **`FilePath` VO uses `__post_init__` instead of a hand-rolled `__init__`.** Same public API (accepts `str | Path`), same behavior, but the dataclass-generated `__init__` is no longer bypassed. One less smell in the shared VOs. - **`Language` VO is strict by default; `Language.from_raw()` factory for normalization.** The previous `__post_init__` mutated `iso` and `aliases` via `object.__setattr__` on a frozen dataclass — a code smell hiding behind the dataclass facade. Split: the direct constructor now rejects un-normalized input (uppercase iso, whitespace in aliases, etc.), and `Language.from_raw()` handles arbitrary YAML/user input. Only one caller (LanguageRegistry loading the ISO YAML) needed migration. - **`ParsedRelease.normalised` renamed to `clean`.** The field name promised "dots instead of spaces" but in practice held `raw - site_tag - apostrophes` — only used by `season_folder_name()`. Renamed and docstring corrected. - **`ParsedRelease.media_type` / `parse_path` are strict enums.** The fields were already typed as `MediaTypeToken` / `ParsePath`, but a tolerant `__post_init__` coerced raw strings. With both classes being `(str, Enum)`, the coercion served no purpose. Strict constructor; `.value` no longer passed at call sites; dropped the unused `_VALID_MEDIA_TYPES` / `_VALID_PARSE_PATHS` lookup tables. ### Removed - **`settings.min_movie_size_bytes`** — orphan Pydantic field + validator. Its only consumer (`MovieService.validate_movie_file`) had been removed during an earlier refactor. The "real movie vs sample" rule now lives in extension-based exclusion (`application/release/supported_media.py`) and PoP. If a size threshold is ever needed, it'll go in a knowledge YAML, not in `settings`. ### Internal - **Flattened `alfred.domain.shared.media/` package into a single `media.py` module.** The 6-file package (audio, video, subtitle, info, matching, tracks_mixin + `__init__`) collapsed into one ~250 LoC module. All 12 import sites continue to resolve unchanged (`from alfred.domain.shared.media import AudioTrack, MediaInfo, …`) since Python treats `media.py` and `media/__init__.py` interchangeably for import paths. Easier to scan when the whole bounded-context fits on one screen. - **`SubtitleKnowledgeBase` types `language_registry` against the `LanguageRepository` port** instead of the concrete `LanguageRegistry` class. The default constructor still instantiates the concrete adapter when no repository is injected — behaviour is unchanged for existing callers. Opens the door to in-memory fakes in future tests without loading the full ISO 639 YAML. - **Moved `detect_media_type` and `enrich_from_probe` from `alfred.application.filesystem` to `alfred.application.release`**. They are inspection-pipeline helpers — their natural home is next to `inspect_release`, not next to the filesystem use cases. The move also eliminates a circular-import workaround in `resolve_destination.py`: `inspect_release` can now be imported at module top instead of lazily inside `_resolve_parsed`. Public surface is unchanged for callers that imported the helpers from their full module paths (the only call sites — `inspect.py`, two tests, one testing script — were updated in this commit). ### Added - **`resolve_*_destination` use cases now consume `inspect_release`**. `resolve_episode_destination` and `resolve_movie_destination` reuse their existing `source_file` parameter as the inspection target; `resolve_season_destination` and `resolve_series_destination` gain a new **optional** `source_path` parameter (also threaded through the tool wrappers and YAML specs). When the path exists, ffprobe data fills tokens missing from the release name (e.g. quality) and refreshes `tech_string`, so the destination folder / file names end up more accurate. When the path is missing or absent (back-compat callers), the use cases fall back to parse-only — same behavior as before. ### Fixed - **`enrich_from_probe` now refreshes `tech_string`** after filling `quality` / `source` / `codec`. Previously the field stayed at its parser-time value, so filename builders saw stale tech tokens even after a successful probe. New `TestTechString` class in `tests/application/test_enrich_from_probe.py` locks the behavior. ### Added - **`inspect_release` orchestrator + `InspectedResult` VO** (`alfred/application/release/inspect.py`). Single composition of the four inspection layers: `parse_release` → `detect_media_type` (patches `parsed.media_type`) → `find_main_video` (top-level scan) → `prober.probe` + `enrich_from_probe` when a video exists and the refined media type isn't in `{"unknown", "other"}`. Returns a frozen `InspectedResult(parsed, report, source_path, main_video, media_info, probe_used)` that downstream callers consume directly instead of rebuilding the same chain. `kb` and `prober` are injected — no module-level singletons. Never raises. ### Changed - **`analyze_release` tool now delegates to `inspect_release`** — same output shape, plus two new fields: `confidence` (0–100) and `road` (`"easy"` / `"shitty"` / `"path_of_pain"`) surfaced from the parser's `ParseReport`. The tool spec (`specs/analyze_release.yaml`) documents both fields so the LLM can route releases by confidence. - **`MediaProber` port now covers full media probing**: added `probe(video) -> MediaInfo | None` alongside the existing `list_subtitle_streams`. `FfprobeMediaProber` (in `alfred/infrastructure/probe/`) implements both methods and is now the single adapter shelling out to `ffprobe`. The standalone `alfred/infrastructure/filesystem/ffprobe.py` module was removed — all callers (tools, testing scripts) instantiate `FfprobeMediaProber` instead. Unblocks the upcoming `inspect_release` orchestrator, which depends on the port. ### Removed - `alfred/infrastructure/filesystem/ffprobe.py` (folded into the `FfprobeMediaProber` adapter). --- ## [2026-05-20] — Release parser confidence scoring + exclusion ### Added - **Pre-pipeline exclusion helpers** (`alfred/application/release/supported_media.py`): `is_supported_video(path, kb)` (extension-only check against `kb.video_extensions`) and `find_main_video(folder, kb)` (top-level scan, lexicographically-first eligible file, returns `None` when no video qualifies; accepts a bare file as folder for single-file releases). No size threshold, no filename heuristics — PATH_OF_PAIN handles the exotic cases. Foundation for the future `inspect_release` orchestrator. - **Release parser — parse-confidence scoring** (`alfred/domain/release/parser/scoring.py`, `alfred/knowledge/release/scoring.yaml`). `parse_release` now returns `(ParsedRelease, ParseReport)`. The new `ParseReport` frozen VO carries a 0–100 `confidence`, a `road` (`"easy"` / `"shitty"` / `"path_of_pain"`), the residual UNKNOWN tokens, and the missing critical fields. EASY is decided structurally (a group schema matched); SHITTY vs PATH_OF_PAIN is decided by score against a YAML-configurable cutoff (default 60). Weights and penalties also live in `scoring.yaml` — title 30, media_type 20, year 15, season 10, episode 5, tech 5 each; penalty 5 per UNKNOWN token capped at -30. `Road` is a new enum, distinct from `ParsePath` (which records the tokenization route, not the confidence tier). `ReleaseKnowledge` port gains a `scoring: dict` field. ### Changed - **`parse_release` signature** is now `(name, kb) → tuple[ParsedRelease, ParseReport]` instead of returning a bare `ParsedRelease`. Call sites updated in `application/filesystem/resolve_destination.py` and `agent/tools/filesystem.py`. Tests updated accordingly. --- ## [2026-05-20] — Release parser v2 (EASY + SHITTY) ### Added - **Release parser v2 — EASY path live** (`alfred/domain/release/parser/`): new annotate-based pipeline (tokenize → annotate → assemble) drives releases from known groups. Exposes `Token` (frozen VO with `index` + `role` + `extra`), `TokenRole` enum (structural/technical/meta families), and `GroupSchema` / `SchemaChunk` value objects. - `pipeline.tokenize`: string-ops separator split (no regex), strips a `[site.tag]` prefix/suffix first. - `pipeline.annotate`: detects the trailing group right-to-left (priority to `codec-GROUP` shape, fallback to any non-source dashed token), looks up its `GroupSchema`, then walks tokens and schema chunks in lockstep — optional chunks that don't match are skipped, mandatory mismatches abort EASY and return `None` so the caller can fall back to SHITTY. - `pipeline.assemble`: folds annotated tokens into a `ParsedRelease`-compatible dict. - `parse_release` (in `release.services`) tries the v2 EASY path first and falls through to the legacy SHITTY heuristic on `None`. Legacy SHITTY/PATH OF PAIN behavior is unchanged. - Knowledge: `alfred/knowledge/release/release_groups/{kontrast,elite, rarbg}.yaml` declare the canonical chunk order per group, loaded via new `ReleaseKnowledge.group_schema(name)` port method. - Tests in `tests/domain/release/test_parser_v2_{scaffolding,easy}.py` cover token VOs, site-tag stripping, group detection, schema-driven annotation (movie, TV episode, season pack with optional source), and field assembly. - **Release parser v2 — enricher pass** completes the EASY pipeline. The structural schema walk now tolerates non-positional tokens between chunks (instead of aborting on leftover tokens), and a second pass tags them with audio / video-meta / edition / language roles. Multi-token sequences from `audio.yaml`, `video.yaml`, `editions.yaml` (e.g. `DTS.HD.MA`, `DV.HDR10`, `TrueHD.Atmos`, `DIRECTORS.CUT`) are matched before single tokens. Channel layouts like `5.1` and `7.1` (split into two tokens by the `.` separator) are detected as consecutive pairs. Sequence members carry an `extra["sequence_member"]` marker so `assemble` extracts the canonical value only from the primary token. KONTRAST releases with audio / HDR / edition / language metadata now produce a fully populated `ParsedRelease`. - **Streaming distributor as a separate dimension** from encoding source. New `alfred/knowledge/release/distributors.yaml` (NF, AMZN, DSNP, HMAX, ATVP, HULU, PCOK, PMTP, CR) feeds a new `ReleaseKnowledge.distributors` port field, a `TokenRole.DISTRIBUTOR` annotation, and a `ParsedRelease.distributor` field. `WEB-DL` stays the source; the platform that produced the release is now recorded distinctly. The five entries (NF, AMZN, DSNP, HMAX, ATVP) were correspondingly removed from `sources.yaml`. - **Real-world release fixtures** under `tests/fixtures/releases/{easy,shitty,path_of_pain}/`, each documenting an expected `ParsedRelease` plus the future `routing` (library / torrents / seed_hardlinks) for the upcoming `organize_media` refactor. EASY bucket seeded with 5 cases (movie, single-episode, season pack, movie + noise, YTS bracket-heavy). SHITTY bucket seeded with 15 anti-regression cases covering: 3-level INTEGRALE hierarchy (Angel), French custom titles (Buffy, La Nuit au Musée, Chérie j'ai agrandi), multi-episode chain `S14E09E10E11` (Archer, captures E11 loss), lowercase `s01e01` (Notre Planète), `NxNN` with ` - ` separators (Vinyl, captures dash artifact), title-with-year-suffix (Deutschland.83), season-range `S01-06` (Tatortreiniger, captures movie misclassification), bare folder name (Jurassic Park, media_type=unknown), apostrophe-in-name (Honey Don't, captures full AI-path degeneration), SUBS-tag movie (Hook), space separators (Predator Badlands, captures group=UNKNOWN), subs-only release (Westworld S04). PATH OF PAIN bucket seeded with 10 worst-case fixtures covering: UTF-8 wide pipe yt-dlp slug (Khruangbin), 3-show franchise box-set with double season range and parens-wrapped tech (Deutschland 83-86-89, captures `group=S03` misdetection), accented chars in title (Chérie BéBé with VFF), 8-word stand-up comedy title (Jimmy Carr), site-tag prefix + XviD (OxTorrent), episode title + air-date silently lost (Prodiges), full-chaos apostrophe + spaces + Blu-ray dash + 1080i + multi-word audio codec (The Prodigy, full AI-path degeneration), yt-dlp YouTube ID glued to year (Sleaford Mods), bilingual `[FR-EN]` tag mistaken for group (Super Mario Bros), COMPLETE + S01-S07 range + REPACK + HEVC (Gilmore Girls, the well-behaved exception). Parametrized over `tests/domain/test_release_fixtures.py` for anti-regression. - **`NxNN` alt season/episode form supported** by `parse_release`. Releases like `Show.1x05.720p.HDTV.x264-GRP` and `Show.2x07x08.1080p.WEB.x265-GRP` (multi-ep alt form) now parse as TV shows. - **`alfred/knowledge/release/separators.yaml`** declares the token separators used by the release-name tokenizer (`.`, ` `, `[`, `]`, `(`, `)`, `_`). New conventions can be added without code changes. The canonical `.` is always present even if missing from YAML. ### Changed - **Release parser v2 — SHITTY simplified to dict-driven tagging**. The legacy ~480-line heuristic block in `release/services.py` is gone; `pipeline._annotate_shitty` does a single pass that looks each token up in the kb buckets (resolutions / sources / codecs / distributors / year / `SxxExx`) with first-match-wins semantics, and the leftmost contiguous UNKNOWN run becomes the title. `annotate()` no longer returns `None` — SHITTY is the always-on fallback when no group schema matches. `services.py` shrunk from ~525 to ~85 lines. Four fixtures (`deutschland_franchise_box`, `sleaford_yt_slug`, `super_mario_bilingual`, `predator_space_separators` — the last one moved from `shitty/` → `path_of_pain/`) are now marked `pytest.mark.xfail(strict=False)` documenting PoP-grade pathologies that SHITTY intentionally won't handle. `ReleaseFixture` grows an `xfail_reason` field; the parametrized suite wires the xfail mark automatically. - **`parse_release` tokenizer is now data-driven**: it splits on any character listed in `separators.yaml` (regex character class) instead of `name.split(".")`. This makes YTS-style releases (`The Father (2020) [1080p] [WEBRip] [5.1] [YTS.MX]`), space-separated names (`Inception 2010 1080p BluRay x264-GROUP`), and underscore-separated names parse correctly via the direct path — no more fallback through sanitization. - **`parse_release` flow simplified**: site-tag extraction always runs first (so `parse_path == "sanitized"` now reliably indicates a stripped `[tag]`), then well-formedness is checked only against truly forbidden chars (anything not in the configured separator set). - **ISO 639-2/B is now the canonical language code project-wide** (was a mix of 639-1 and 639-2/T): - `SubtitlePreferences.languages` default is now `["fre", "eng"]` (was `["fr", "en"]`). Old LTM files are not auto-migrated — delete `data/memory/ltm.json` to regenerate with the new defaults. - Subtitle output filenames are now `{iso639_2b}.srt` (e.g. `fre.srt`, `fre.sdh.srt`). Existing `fr.srt` files are still **read** correctly (recognized as French via alias) but new files are written canonically. - `Language` value object docstring corrected: it has always stored 639-2/B (matching what ffprobe emits), not 639-2/T as previously documented. - **`MovieService.validate_movie_file` minimum size is now configurable** via `settings.min_movie_size_bytes` (default unchanged: 100 MB). Constructor accepts an optional `min_movie_size_bytes` override for tests. - **`SubtitleKnowledgeBase` delegates language lookup to `LanguageRegistry`** rather than duplicating tokens. `subtitles.yaml` now only declares subtitle-specific tokens (e.g. `vostfr`, `vf`, `vff`) under a new `language_tokens` section. ### Removed - **`alfred/domain/tv_shows/services.py`** and **`alfred/domain/movies/services.py`** deleted entirely. They held fossil parsers (`parse_episode_filename`, `extract_movie_metadata`, …) with zero production callers — superseded by `parse_release` as the single source of truth for release-name parsing. Associated tests (`tests/domain/test_movies.py`, `tests/domain/test_tv_shows_service.py`) removed as well. - `_sanitize` and `_normalize` helpers in `alfred/domain/release/services.py` — the new tokenizer makes them redundant. - `_LANG_KEYWORDS`, `_SDH_TOKENS`, `_FORCED_TOKENS`, `SUBTITLE_EXTENSIONS` hardcoded dicts in `alfred/domain/subtitles/scanner.py` — all knowledge now lives in YAML (CLAUDE.md compliance). - `_MIN_MOVIE_SIZE_BYTES` module-level constant in `alfred/domain/movies/services.py` — replaced by the new setting. - Top-level `languages:` block in `subtitles.yaml` — superseded by `language_tokens:` (subtitle-specific only) since iso_languages.yaml is the canonical source. ### Fixed - **`hi` token no longer marks a subtitle as SDH** (it conflicted with the ISO 639-1 alias for Hindi). SDH is now detected only via `sdh`, `cc`, and `hearing` tokens. - `SubtitleKnowledgeBase` default rules used `"fra"` while `iso_languages.yaml` exposes French as `"fre"` — preferred languages defaults now match the canonical form. ### Internal - **Domain I/O extraction** (`refactor/domain-io-extraction`): the domain layer no longer performs subprocess calls, filesystem scans, or YAML loading. Achieved in a series of focused commits: - **Knowledge YAML loaders moved to infrastructure**: `alfred/domain/release/knowledge.py`, `alfred/domain/shared/knowledge/language_registry.py`, and `alfred/domain/subtitles/knowledge/{base,loader}.py` relocated to `alfred/infrastructure/knowledge/`. Re-exports were dropped — callers import directly from the new location. - **`MediaProber` and `FilesystemScanner` Protocol ports** introduced at `alfred/domain/shared/ports/` with frozen-dataclass DTOs (`SubtitleStreamInfo`, `FileEntry`). `SubtitleIdentifier` and `PatternDetector` are now constructor-injected with concrete adapters (`FfprobeMediaProber` wrapping `subprocess.run(ffprobe)` and `PathlibFilesystemScanner` wrapping `pathlib`). No more direct `subprocess`/`pathlib` usage from the subtitle domain services. - **Live filesystem methods removed from VOs and entities**: `FilePath.exists()` / `.is_file()` / `.is_dir()` deleted — `FilePath` is now a pure address VO. `Movie.has_file()` and `Episode.is_downloaded()` dropped. Callers either rely on a prior detection step or use try/except over pre-checks (eliminates TOCTOU races). - **`SubtitlePlacer` moved to the application layer** at `alfred/application/subtitles/placer.py` — it performs `os.link` I/O, which doesn't belong in the domain. Pre-checks replaced with try/except for `FileNotFoundError`/`FileExistsError`. - **`SubtitleRuleSet.resolve()` no longer reaches into the knowledge base**: the implicit `DEFAULT_RULES()` helper is gone, replaced by an explicit `default_rules: SubtitleMatchingRules` parameter. The `ManageSubtitles` use case loads defaults from the KB once and passes them in. - **`SubtitleKnowledge` Protocol port** at `alfred/domain/subtitles/ports/knowledge.py` declares the read-only query surface domain services consume (7 methods: `known_extensions`, `format_for_extension`, `language_for_token`, `is_known_lang_token`, `type_for_token`, `is_known_type_token`, `patterns`). `SubtitleIdentifier` and `PatternDetector` depend on this Protocol instead of the concrete `SubtitleKnowledgeBase` from infrastructure — `domain/subtitles/` now has zero imports from `infrastructure/`. The remaining domain → infra leak (`domain/release/` loading separator YAML at import-time) is documented in tech-debt and scheduled for its own branch. - **`to_dot_folder_name(title)` helper** in `alfred/domain/shared/value_objects.py` — extracts the `re.sub(r"[^\w\s\.\-]", "", title).replace(" ", ".")` pattern that was duplicated between `MovieTitle.normalized()` and `TVShow.get_folder_name()`. - **`ParsedRelease.languages` uses `field(default_factory=list)`** instead of a manual `__post_init__` that assigned `[]` via `object.__setattr__`. - **`file_extensions.yaml` splits subtitle sidecars (`.srt`, `.sub`, `.idx`, `.ass`, `.ssa`) into a dedicated `subtitle:` category** instead of lumping them under `metadata:`. The `_METADATA_EXTENSIONS` set used by `detect_media_type` remains the union of both (same behavior — subtitles are still ignored when deciding the media type of a folder), but a new `load_subtitle_extensions()` loader is now available for the subtitles domain. Sematic clarity, no functional change. - **`tv_shows/entities.py` module docstring** now shows the aggregate ownership as an ASCII tree before the rule text — quicker visual scan of the DDD structure. - Removed backward-compat shims `_sanitise_for_fs` / `_strip_episode_from_normalised` from `domain/release/value_objects.py` (zero callers). - Cleaned ruff warnings across the codebase: `subprocess.run` calls now pass explicit `check=False` (PLW1510); lazy imports promoted to module top where there was no cycle (PLC0415 in `manage_subtitles.py`, `placer.py`, `qbittorrent/client.py`, `file_manager.py`); fixed module-level import ordering (E402) in `language_registry.py` and `subtitles/knowledge/loader.py`; removed unused locals (F841 / B007); replaced unnecessary set comprehension with `set()` in `release/knowledge.py` (C416). - Ruff config: ignore `PLR0911` / `PLR0912` (too-many-returns / too-many-branches) globally — noisy on parser mappers and orchestrator use-cases where early-return validation is essential complexity. Ignore `PLW0603` for the documented memory singleton (`infrastructure/persistence/context.py`). - **Release-knowledge DDD purification** (`refactor/domain-release-knowledge`): the last domain → infrastructure leak (`domain/release/value_objects.py` loading YAML at import-time) is gone. Achieved via: - **`ReleaseKnowledge` Protocol port** at `alfred/domain/release/ports/knowledge.py` declares the read-only query surface release parsing needs (token sets for resolutions, sources, codecs, languages, hdr extras; structured dicts for audio, video_meta, editions, media_type_tokens; separators list; file-extension sets used by application/infra callers; `sanitize_for_fs(text)` method). - **`YamlReleaseKnowledge` adapter** at `alfred/infrastructure/knowledge/release_kb.py` loads every YAML constant once at construction. Builds an immutable `str.maketrans` translation table for filesystem sanitization. - **`parse_release(name, kb)`** takes the knowledge as an explicit parameter — no more module-level YAML loading inside the domain. Every internal helper (`_tokenize`, `_extract_tech`, `_extract_languages`, `_extract_audio`, `_extract_video_meta`, `_extract_edition`, `_extract_title`, `_infer_media_type`, `_is_well_formed`) takes `kb`. - **`ParsedRelease` Option B**: sanitization happens once at parse time and is stored on a new `title_sanitized: str` field. Builder methods (`show_folder_name`, `season_folder_name`, `episode_filename`, `movie_folder_name`, `movie_filename`) are now pure — they accept already-sanitized `tmdb_title_safe` / `tmdb_episode_title_safe` arguments. Callers at the use-case boundary sanitize TMDB strings via `kb.sanitize_for_fs(...)` before passing them in. - **All domain-knowledge constants removed from `value_objects.py`**: `_RESOLUTIONS`, `_SOURCES`, `_CODECS`, `_AUDIO`, `_VIDEO_META`, `_EDITIONS`, `_HDR_EXTRA`, `_MEDIA_TYPE_TOKENS`, `_LANGUAGE_TOKENS`, `_FORBIDDEN_CHARS`, `_VIDEO_EXTENSIONS`, `_NON_VIDEO_EXTENSIONS`, `_SUBTITLE_EXTENSIONS`, `_METADATA_EXTENSIONS`, `_WIN_FORBIDDEN_TABLE`, and the `_sanitize_for_fs` helper. The domain module is now pure. - **Application-layer KB singleton**: `resolve_destination.py` instantiates a module-level `_KB: ReleaseKnowledge = YamlReleaseKnowledge()` and threads it through every `parse_release(...)` call. The local `_sanitize` helper and `_WIN_FORBIDDEN` regex were dropped in favor of `_KB.sanitize_for_fs(...)`. - **`detect_media_type(parsed, source_path, kb)` and `find_video_file(path, kb)`** now take the knowledge explicitly instead of importing `_*_EXTENSIONS` constants from the domain. `agent/tools/filesystem.py::analyze_release` imports the application KB singleton and passes it through. --- ## [2026-05-17] — TVShow & Movie aggregate refactor Multi-phase refonte of the TV show domain into a real DDD aggregate, with matching parity work on `Movie`, a language knowledge system, and the `shared/media` restructure that supports both. ### Added - **Language knowledge system** (`alfred/knowledge/iso_languages.yaml` + 42 languages including `und` for undetermined). - `Language` value object (frozen dataclass) with `iso`, `english_name`, `native_name`, `aliases`, and a `matches(raw)` cross-format helper. - `LanguageRegistry` loader (`alfred/domain/shared/knowledge/`) merging builtin + learned YAML. Not a singleton — the application layer instantiates it. - ISO 639-2/B is the canonical key; aliases cover 639-1, 639-2/T, English name, native name, and common spellings. - **`VideoTrack`** dataclass (`alfred/domain/shared/media/video.py`) with a `resolution` property using width-priority bucket detection (handles cinema/scope crops like 1920×960 → 1080p). - **`shared/media/matching.py`** — `track_lang_matches` helper shared by `Episode` and `Movie`. Implements the **"C+" contract** for language helpers: - `Language` query → cross-format match via `Language.matches()` - `str` query → case-insensitive direct comparison (no normalization) - **TVShow aggregate composition**: - `TVShow.seasons: dict[SeasonNumber, Season]` - `Season.episodes: dict[EpisodeNumber, Episode]` - `Season.expected_episodes` / `Season.aired_episodes` (split so collection state can compare "owned vs aired today" without confusing in-flight seasons with future ones) - **Aggregate methods on `TVShow`**: - `add_episode(ep)` — sole sanctioned mutation entry point (creates the season if missing) - `add_season(season)` — replaces a season wholesale - `collection_status()` → `CollectionStatus.{EMPTY, PARTIAL, COMPLETE}` - `is_complete_series()` — true iff `ENDED + COMPLETE` - `missing_episodes()` — flat list of all aired-but-not-owned `(season, episode)` pairs - **`CollectionStatus`** enum (orthogonal to `ShowStatus`). - **Episode track helpers** (`has_audio_in`, `has_subtitles_in`, `has_forced_subs`, `audio_languages`, `subtitle_languages`), driven by `Episode.audio_tracks` / `Episode.subtitle_tracks`. - **Movie aggregate parity** — `Movie` now carries `audio_tracks` / `subtitle_tracks` and exposes the same helpers as `Episode` (same C+ contract). - **`CHANGELOG.md`** (this file). ### Changed - **`shared/media_info.py` exploded into `shared/media/{audio,video,subtitle,info,matching}.py`.** `MediaInfo` is now symmetric: every stream type is a `list[Track]`. Flat accessors (`width`, `height`, `video_codec`, `resolution`) remain as properties that read the first video track. - **`MediaInfo.duration_seconds` / `bitrate_kbps`** moved from `VideoTrack` to `MediaInfo` (file-level — they come from the ffprobe `format` block, not a stream). Files without a video stream now correctly expose duration. - **`ShowStatus.from_string`** extended to map TMDB strings (`Returning Series`, `In Production`, `Pilot`, `Planned`, `Canceled`, `Cancelled`). Comparison is whitespace-trimmed and case-insensitive. - **`Season` / `Episode`** dropped their `show_imdb_id` back-references. They are owned by `TVShow` and reached only through it. - **`TVShow.seasons_count` and `episode_count`** are now `@property` (computed from the dict) instead of stored ints. - **`TVShowService.parse_episode_from_filename`** rewritten in string operations (no regex). Supports `S01E05` / `s1e5` and `1x05` / `01x5` forms. - **`TVShowService.find_next_episode`** now drives off `show.missing_episodes()` instead of the hardcoded "max 50 episodes per season" heuristic. - **`TVShowService` constructor** no longer takes `season_repository` / `episode_repository` — the aggregate persists in one block via `TVShowRepository` only. - **`SubtitleTrack` in `alfred.domain.subtitles.entities` renamed to `SubtitleCandidate`.** Coexists with the `shared.media.SubtitleTrack` ffprobe-view dataclass (different bounded contexts, kept separate intentionally). - **`tv_shows/services.py` `_VIDEO_EXTENSIONS`** now loaded from `knowledge/release/file_extensions.yaml` via `load_video_extensions()` (single source of truth). - **`CLAUDE.md`** updated with three new policy sections: - "Tests" — small updates OK during normal work, no mass-update sprees - "Backwards-compatibility shims" — prefer clean migration over shims - "Regex" — not forbidden, use judgment when string ops would be fragile ### Removed - **Legacy `Season N Episode N` filename form** in `TVShowService.parse_episode_from_filename`. It never appears in the release names Alfred handles, and supporting it forced a regex. - **`SeasonRepository` and `EpisodeRepository`** — only the aggregate root has a repository (DDD rule: one repo per aggregate). - **`shared/media_info.py`** compatibility shim — callers updated. - **`SubtitleTrack` compatibility alias** in `subtitles.entities` — callers updated to `SubtitleCandidate`. ### Fixed - **`MediaInfo.duration_seconds` returns `None` on audio-only files** instead of crashing through `primary_video.duration_seconds` (see the duration/bitrate move under **Changed**). - **`MediaOrganizer`** (`infrastructure/filesystem/organizer.py`) no longer passes the removed `show_imdb_id` / `episode_count` kwargs when constructing a `Season` for folder-name generation. ### Internal - Test suite rewritten where the aggregate redesign broke fixtures: `tests/domain/test_tv_shows.py` (69 tests), `tests/domain/test_media_info.py` (rewritten for `VideoTrack`), `tests/application/test_enrich_from_probe.py` (helper added), `tests/infrastructure/test_filesystem_extras.py` (fixtures), `tests/domain/test_tv_shows_service.py` (find_next_episode driven by real aggregate state). - Subtitle services internal migration: `matcher.py`, `utils.py`, `placer.py`, `identifier.py` updated to import `SubtitleCandidate`. - Suite status at end of block: **1066 passed, 8 skipped, 0 failed**.