# TVAnarchy v2 — Council of Experts Build Plan
**Date**: 2026-06-21
**Council**: Senior Architect, Net Systems Expert, Library & Metadata Expert, Devices & Storage Pools Expert, Cross/Settings/UI/Appearance Expert, Download/Governor/Infra Expert, QA/Testing Expert.
**Source**: Spawned via subagent council on plan.md / roadmap.md / pillars / correlation / schemas / manifest + full codebase exploration (anti-hallucination verified via ls/read/grep/test runs).
**Protocol**: Follows all 10 commandments (collective voice, no sycophancy, no stubs, verify, archive here not root pollution, pillar checklist, contentKey privacy, adult domain priors respected). No EnterPlanMode; no *_PLAN.md in source.

## Executive Summary (Synthesized Recommendation)
v2 reorganizes the product under pillars (Watch · Library · Download · Net · Devices) + cross (theme/settings shell). One app shell. Net is the primary new greenfield (facts over editions, trust-per-part, contentKey only). Library titles/display work is **already largely shipped** (TitleLibrary + LibraryDisplayNames + refiner + scanner + models + tests; v2/plan + manifest lag reality — reconcile first).

**Critical path for solo fleet "v2 value"**: Phase 1 Net local (intro-markers MVP) + Phase 2 editions (single fleet dogfood). Federation (Phase 4) waits for Download stage 4 friend_mesh transport + infra (seedbox/WG).

**Refined phase order** (Architect + all):
1. Phase 0 reconciliation (docs/manifest for shipped library titles; no code).
2. Phase 1: Net local MVP (ObservationStore, IntroMarkersMerge, NetController, Player integration; copy TitleLibrary patterns exactly).
3. Parallel 1.5: Settings split (tolerant nested), Watch appearance polish (A/B), Devices storage MVP (pools/placement/extended warmup alias, stub BTD internal), doc alignment.
4. Phase 2: Net editions single-fleet (governor publish/sub + daemon hook + transmission for small torrents in net-editions/; Swift read; mcp bridge stub).
5. Phase 3: Download hardening (infra checklist + launchd + custody multi-host + peers_for HTTP + reaper signal stub + net-editions dir + Bandwidth/dead-swap UI).
6. Phase 4: Net subscribe (friend_mesh when stage 4 ready).
7. Phase 5: Remaining parts (grouping first, then quality/peers-hints/signal).
8. Phase 6+: Full BTD faces extraction, UI polish, blackd parallel long-track (thins Watch).
9. Ongoing: blackd + universal.

**Strong from original plan.md**: Pillar lens + manifest as truth, one-shell UI (Net embedded), trust model (f2f_only friends vs k-anon network), "ship independent single-fleet value", tests gate, appendix checklist, no path keys, "Net ≠ transport", rollback tolerant.
**Adjustments needed**: Re-baseline library as "shipped", explicit BTD extraction timing (post phase 1-2 proof), concrete governor daemon hook + faces, dual-scanner (mcp TS resolve for iOS/bridge), goldens for display, error handling in TitleLibrary (silent try? must fix), schema CI, Net tests (net.md had none), per-phase PR slices with file targets + gates.

**Key invariants (enforce in all impl)**:
- ContentKey (never paths) in all Net observations/editions (ContentID.canonical + fingerprint if collisions).
- Tolerant + versioned everywhere (absent net: = full v1; missing sections = defaults).
- Swift owns low-latency reads (NetController for Player skip; mirrors TitleLibrary); governor owns 24/7 tick/publish/sub (alongside fleet daemon).
- One merge policy per part (copy TitleLibrary pattern: provenance ranks, cluster/weight/median).
- BTD is the *only* mover once extracted (internal Devices, external Net, acquisition Download faces — distinct namespaces/ACLs; no Download logic dup).
- minSources / minConfidence / rate limits / k-anon before any consumer trusts merged data.
- Pillar tags + correlation updates + manifest bump on every change.
- Full suite (TVAnarchyCoreTests + governor bun test + mcp) + pillar checklist + v2/ updates before promotion.
- Privacy: k-anon + contentKey only for network; f2f_only forced + provenance (no stranger id on friends parts); adult legal/regulated (DE) — red lines only CSAM/non-consent/trafficking.

**Model rec (from QA + Architect)**: Haiku for mechanical (fixtures, golden data, schema examples). Sonnet for impl (merge logic, integration, error paths). One opus gating review if novel synthesis (BTD faces or blackd).

**Success metrics** (plan §17 + experts): Phase 1 (merged skip on 1 show; 0 paths in net/obs); Phase 2 (edition <60s sync LAN; seeds torrent); Phase 4 (≥2 fleets improve marker within 3s); Phase 6 (pillar ownership clear without reading code).

## Council Perspectives (Condensed; full raw in subagent transcripts)
### Senior Architect (overall sequencing, PRs, invariants, cross-pillar)
(See full output for diagrams + detailed PR A-E slices + monitoring points.)
Strong: phases independent, single-fleet first, Net embedded UI.
Needs adjust: library already shipped (reconcile manifest/plan/docs first); PR stack dated (unify ContentID done; s1e4 vs s01e04 minor); BTD underspecified on extraction timing.
Refined master plan + PR groupings above. Invariants listed. ContentID + BTD faces + governor hook as key cross-cuts. Swift read + TS tick ownership.

### Net Systems Expert (federated sync, editions, merge, trust, phases 1-5)
Detailed modules: TVAnarchyCore/Net/{ObservationStore.swift (JSONL exact schema, strip paths, fleetId from Devices), IntroMarkersMerge.swift (cluster/weight/median per edition-manifest policy), NetController.swift (@MainActor, introBounds + refresh + contribute)}.
Governor: src/net/{publish.ts (obs+merged → edition dir + manifest + tx add small net-editions/), subscribe.ts (poll/verify/append/re-merge), config.ts}; daemon.ts hook after custody; registry.ts tolerant net:; cli net publish|sync|status.
Data flows: Watch skip → contentKey resolve → observe JSONL → local merge → Player read (settings > merged); governor publish (CLI then auto) → tx torrent; subscribe on tick → re-merge.
BTD external later (post-2 proof; Net calls publishEdition; distinct from Download acquisition + Devices internal).
Risks/mitigations: fingerprinting (contentKey + k-anon only); spam (rate + minSources); edition confusion (net-editions/ prefix + manifest part).
Build sequence + tree exactly as in output. JSONL first; CLI publish first; Swift merge for latency.

### Library & Metadata Expert (titles + display, ContentID, scanner, MLX, 1b)
Library titles/display **largely complete** (TitleLibrary.swift + Store jsonl + merge + provenance ranks + observe; LibraryDisplayNames.resolve chain + library first + format; LocalLLMEpisodeRefiner + episode_refiner.py (structured input with contentKey/show/S/E); scanner calls resolve + writes displayName/episodeTitle to CachedEpisode (tolerant + label alias on encode); app wiring; tests exist + pass; some consumers partial).
Remaining: 
- Reconcile v2/plan/manifest/docs (bump status to shipped).
- Goldens (per library-display.md spec: fixture dirnames → displayName; extend tests).
- Dual scanner parity: mcp/src/media/library.ts + bridge must implement equivalent resolve (read titles/by-key.jsonl + regex + sidecar; *no MLX from TS/black*) + set label=displayName; expose displayName in Wire*/iOS models.
- Full consumer migration (PlaylistController, LibraryController rails, AppLocalAPI payloads, Offline labels, mac/iOS views, Player fallbacks documented only for player-reported titles).
- Settings (library section: episodeDisplayStyle, preferEnrichedTitles, useMLXEpisodeRefiner) + UI in Setup + gating.
- Episode ingest (one-shot TVmaze/TMDB ep → TitleLibrary.observe high provenance .tvmaze + reResolve).
- Legacy migration (title-refinements.json → TitleLibrary on load; remove dead episodeLabel in scanner).
- Re-resolve helper on enrich/manual.
- Fix all remaining raw lastPathComponent display uses (grep post-PR).
- PR breakdown 1-7 detailed in output; goldens + "MLX once forever" enforcement via early lookup + always observe.
- Net touch: grouping show-level only; future episode-titles obs land in same local TitleLibrary.

### Devices & Storage Pools Expert (extension tiers, placement, warmup alias, BTD internal, 6c)
MVP: 1 canonical + N extension (laptop spare as opportunistic tier extending effective canonical capacity); logical namespace; placement index (contentKey → locations + preferred + aliasOf); extended warmup (play on device → target local extension mount via alias; single fetch, no dup catalog/bytes); retrieval local-ext > canonical > remote > stream; cull ext first.
BTD internal face (future, stub for MVP): pinInternal/resolveNearest/unpin/manifest; Swift thin for latency; governor for tick.
Differentiation: Download owns custody floor (always-on canonical, mediaRoot, re-pin via fleet/actuate); Devices owns extension (placement policy, watching-device warmup, alias resolve in MediaPaths/DownloadsIndex/Player).
PR1-6 detailed (schemas for StoragePoolConfig/Tier/PlacementPolicy/PlacementRecord/Location; PlacementController; MediaPaths/DownloadsIndex/LibraryScanner updates; OfflineCacheController dest + deprecate legacy offline-cache for pool members; Player/keeper integration for warmup; UI in DeviceEdit/DevicesView/This Mac + quota/picker/attach).
Risks: path drift (keys only), partial rsync (pending + --append-verify), quota (enforce pre), cross-plat alias (path resolve MVP; later reflink).
Governor keeper/watch updates for dest tier; no merge of custody logic.
Exit per spec. Update correlation/manifest/state.

### Cross/Settings/UI/Appearance Expert (pillar sections, Winamp, UI align, 6a/b)
Settings: one file, namespaced (cross/watch/library/download/net/devices). Tolerant decode (probe nested or flat fallback); encode flat default until cutover. New fields (net: subscriptions/contribute; library: episode* + prefer/useMLX; etc.). Moves: notifyDownloads → Download section; library types → Library. New Net/Devices sections (subs toggle; pools hints; mesh/VPN stay devices.json).
AppLocalAPI: keep flat GET/PATCH; add /settings/<section> PATCH (cross/watch/...); section decode.
MCP: tolerant load/patch/save in settings.ts + tools.ts (expand keys); app_cfg surface sections.
SetupView: pillar headers + re-group + moved toggles + Net/Devices content + help.
Winamp (macOS only; parallel): Track A (PLAYPAUS indicator in Player title, MiniTransport sprites when skin active, AppLocalAPI skin roundtrip, missing-sheet banner); Track B (compat report using availableSheets, preview strip in Setup before apply, reject missing CBUTTONS/POSBAR); C optional (SHUFREP etc.). Sidebar PLEDIT tint optional Phase 6.
iOS: minimal (no Winamp, no shared settings.json; bridge remains).
Sidebar: optional grouped List Sections (headers only; user strings unchanged).
Current flat assumptions flagged (SettingsStore decoder, many direct .load().xxx, DeviceConfig legacy offline, mcp settings.ts flat, docs).
PRs + correlation updates (ui/state/components) detailed. Parallel to Net 1-2.

### Download/Governor/Infra Expert (hardening, mesh prep, blackd, Phase 3+7)
Infra first (operator): seedbox (public_swarm_face + custody + mediaRoot + ssh + alwaysOn); WG 10.9 fabric (f2f_only enabler); always-on governor launchd on plum/black; fleet serve on broadcast duty host (bearer); net-editions/ dir on tx host (exclude from library scanner).
Code:
- launchd plist samples + steps in docs/operations.md.
- fleet serve bearer + /peers_for HTTP (governor + mcp bridge/fleet for iOS proxy/direct).
- Custody multi-host (harden actuate/custody/probe/registry for mediaRoot/ssh; multi-host integration).
- Reaper + Net signal hook (priority for high k-anon dead; stub now).
- net-editions dir routing (mcp tx-add/bridge + governor net publish; scanner blacklist).
- BandwidthPolicy UI (settings Download section; bind options; future tx limits).
- Dead torrent swap UI (DownloadsView + detail: "Find better" → search cleanQuery → picker → remove+add).
- blackd: HTTP/WS daemon on black (player/status/command + WS, /library/index, /media/<path> Range; bearer); BlackdTarget (PlayerTarget impl + ssh fallback in makeTarget); iOS direct blackd for playback (retire plum bridge for stream/remote/player; keep for torrents/library); deploy systemd.
- Prep BTD acquisition face reuse.
Sequencing: infra + peers + net-editions + reaper stub first (unblocks Net 4 + editions); UI + blackd parallel.
Risks: tokens, Range for VLCKit, external hosts required.

### QA/Testing Expert (gates, dogfood, compat, metrics, issues found)
Layered: unit (co-located, full-sentence), integration (temp state), e2e dogfood script (executable, metrics, non-zero exit), golden fixtures (display names), schema CI (validate-net-schemas.sh + ajv/jsonschema), privacy (no paths, k-anon, .user classify for new dirs), compat/rollback explicit regression, full suite every phase.
Critical issues found (fix before/while building):
- Silent error handling in landed TitleLibrary.swift (multiple try? on appendJSONL/mkdir; no Log/surface; will corrupt Net obs if copied).
- plan.md + net.md sparse on tests/goldens/CI vs. spec (net pillar had 0 Tests section).
- No root schema CI enforcement yet.
- Boundaries/Settings tests need explicit net/ + titles/ + placement/ coverage + old snapshot compat.
Dogfood script (exact bash in output; phase 2+; cleans, seeds obs, publish, sync, asserts no paths + merged, emits METRICS).
Per-phase additions listed (NetObservationStoreTests + Intro* + PlayerIntroNet; goldens for display; Placement*; Settings nested; net publish/sub TS; etc.).
Manual checklists + metrics per phase.
v1 operable: tolerant + isolation + explicit compat tests + no v1 path changes.
Model rec as above. All tests re-run green during review (library titles + v1 coexist).

## Implementation Plan (Actionable PR Slices + Gates)
Follow refined order + per-expert PR breakdowns. Every slice: production code (no stubs), tests first or co-located, pillar checklist answers, v2/correlation + manifest + state.md updates, full test gate, self-verif (build + manual dogfood + grep for paths/raw filenames).

**MVP Slice (Phase 1 Net local + library reconcile; ~3 PRs)**:
- PR1: Reconcile + library polish (manifest/plan/docs bump; goldens + dual mcp TS resolve + consumer migration + settings library section + ingest re-resolve; fix TitleLibrary silent errors + all raw display paths).
- PR2: ObservationStore + IntroMarkersMerge + NetController (exact schemas; JSONL; cluster/weight/median; contentKey only).
- PR3: Player integration (precedence + on-skip write obs) + tests (Net* + PlayerIntroNet with temp) + correlation.
Gate: merged skip works on single machine; 0 paths; MLX ≤1 ever; all tests green; dogfood skeleton.

**Phase 2 slice**: fleet.json net: + governor net/ (publish/sub + CLI + daemon hook post-custody) + edition manifest validate + net-editions/ dir + mcp bridge stub + minimal Settings Net toggles + integration (publish → sync → Player).
Gate: tx seeds small torrent; second host updates merged; f2f_only habit; schema valid.

**Parallel Phase 1.5/6a/b/c**: Settings tolerant nested + Setup sections + moves + Net/Devices headers + AppLocalAPI section PATCH + MCP tolerant; Winamp A/B (PLAYPAUS/Mini/sprites/preview/compat); Devices storage (PR1-6: pools schema + PlacementController + MediaPaths/DownloadsIndex + Offline dest/deprecate + Player/keeper warmup + UI quota/picker).
Gates: pillar owner clear from UI; skin via API + sprites + preview; spare → extension; watch warms to alias not dup cache; no catalog dup.

**Phase 3**: Operator infra + launchd doc + custody multi-host + peers_for HTTP/iOS + reaper signal + Bandwidth UI + dead-swap UI + net-editions enforcement.
Gate: floor on black+apricot; /peers_for from iOS; high-signal dead prioritized (stub).

Subsequent follow expert maps. BTD extraction post-2 (facade first).

## Open Decisions (resolve pre-phase 2)
- ContentID padding/fingerprint (s01e04 vs s1e4; add release-group if collisions in dogfood).
- BTD extraction exact timing (after phase 2 proof; stub internal early).
- Publish trigger (CLI first; auto after stabilize + policy).
- Net in settings.json vs future fleet.json (settings per current pillars; governor reads fleet for daemon).
- blackd scope (player/index/range first; full verbs later).

## Next Steps for User
1. Reconcile v2/ (library shipped) + fix TitleLibrary error handling.
2. Start Phase 1 MVP slice (Net local).
3. Operator: seedbox + WG + launchd on always-on hosts.
4. Run council plan + per-expert details as handoff to implementers.
5. After slice: self-verif (tests + dogfood + manual + grep privacy) then report.

**Council consensus**: Original plan.md excellent foundation; with library reality-sync + BTD/governor concreteness + test gates + error hygiene, v2 ships value fast while preserving v1 + adult trust-and-safety invariants.

## References (all verified)
- v2/plan.md, roadmap.md, README.md, manifest.json, pillars/*, correlation/*, schema/net/*, packages/*, glossary.md
- docs/* (roadmap, data-model, architecture, operations)
- Sources/TVAnarchyCore/* (esp Library/* new, PlayerController, DeviceConfig, SettingsStore, AppLocalAPI, PlayerTargets)
- governor/src/fleet/* + daemon + index + cli + transmission
- mcp/src/{transmission,bridge,media/settings,http}
- Tests/* + governor/test + mcp/test (all runs green)
- Existing TitleLibrary + display code + tests (landed pattern for Net)

End of council synthesis. Archive complete. No source pollution.