tv-anarchy/docs/roadmap.md

Status & Roadmap

Where the project is and the de-risked path to the full vision. Architecture is in architecture.md; the mesh design origin is ../.project/history/20260608_fleet-manager-mesh-design.md.

Status at a glance

Area	Status	Note
App — playback (VLC / mpv / QuickTime)	✅ Shipped	blacktv retired → mpv; no NFS — local players play downloads, else route to black
App — library browser	✅ Shipped	black index fast-path + local MEDIA_ROOTS walk + registry fallback (no NFS)
App — downloads (search + transmission)	✅ Shipped	via mcp CLI; search needs FlareSolverr
App — metadata enrichment + artwork	✅ Shipped	regex parse + TMDB/IMDb/keyless + ffmpeg frame-grab
App — all UI (Home/Player/Library/Search/Downloads/Metadata/Adult/Devices/Logs/Settings)	✅ Shipped	wired, no TODO/FIXME/fatalError debt
App — device registry (Devices tab)	✅ Shipped (registry only)	DeviceConfig: type→services presets mapping to fleet classes, per-device load badge; duty engine still unbuilt (see fleet below)
App — adult content tab	✅ Shipped	porn-rotation.py ported to PornCollectionService; ENABLE_ADULT compile flag + runtime pornFeature setting, concealed by default
App — VPN subsystem	✅ Shipped	OVPN profile/credential stores (Keychain), controller, settings UI
App — offline cache + Now Playing/media keys	✅ Shipped	OfflineCacheController, NowPlayingController, bandwidth policy
iOS app (TVAnarchyiOS)	✅ Shipped (companion)	VLCKit player, library, downloads, remote control via HTTP bridge (default :8787); the bridge server is not in this repo's mcp/ tree
Distribution (release/update)	✅ Shipped	tools/release.sh → Forgejo on forge.black; tools/update.sh installs/updates any node without a toolchain
governor (portable-net-tv)	✅ Shipped (single-host)	watch tracking + prefetch buffer
mcp (plum-control-mcp)	✅ Shipped	VLC / black-tv / transmission / display tools
recommender	✅ Shipped	enrichment + local recs
MLX title refiner	✅ Shipped	LocalLLMTitleRefiner → media_rec/title_refiner.py (MLX Qwen); cached, self-disabling, wired at app startup
governor → fleet orchestrator (stage 1)	✅ Shipped	governor/src/fleet/: registry ingest, duty assignment, custody floor-check, zombie reaper, re-pin actuation (fleet repin --apply: rsync holder→target + recorded holdings), capacity probes (fleet probe: ssh df + EWMA uptime), periodic daemon (fleet daemon), research feed into mcp search
peers_for / custodians_of (stage 3 core)	✅ Shipped (single-fleet)	source model + both policy gates enforced; unions fleet ∪ seedbox ∪ live DHT, provenance-tagged; served over HTTP by fleet serve (/peers_for/<hash>, bearer-token) — runnable on any node until a real broadcast host exists
Fleet WireGuard fabric (plane 1)	❌ Designed	blocked on the 10.9.0.4 open question + root on each node
Seedbox source + off-home face	❌ Blocked external	engine supports the class/duty today; needs an actual provisioned seedbox
Friend-mesh / F2F relay (stage 4)	❌ Designed	needs other fleets to exist
Private-tracker source (stage 5)	❌ Designed	gates already enforced in peers.ts; ships last, after F2F is battle-tested
Discord planes	❌ Designed	control/QA/announce + availability bot; needs bot tokens/servers
Multi-identity / cross-fleet	❌ Designed	single-fleet foundation must land first

Verdict: the media-client layer is complete and production-grade. The fleet/mesh layer now has its single-fleet core (registry → duties → custody → reaper → peers_for) implemented and tested in the governor; what remains is actuation (cross-host copies), the WG fabric, and every stage that requires infrastructure outside this repo (seedbox, friends, Discord).

Repo-state note

The PlumTV → TVAnarchy rename and the helper subsystems (governor/, mcp/, recommender/, search/, fleet/, tools/) were committed to main on 2026-06-09 as a series of atomic commits (41afc1c…b44b5a2). Stage 0 (hygiene) below is done.

Remaining work — detail

MLX title refiner — ✅ done 2026-06-09

LocalLLMTitleRefiner (Swift) shells into media_rec/title_refiner.py (MLX Qwen 1.5B, same model as the show grouper), consulted only for degenerate (<2-char) regex titles. Results are disk-cached (~/.local/state/tv-anarchy/title-refinements.json); two consecutive subprocess failures disable it for the session so a scan never pays repeated timeouts when MLX is absent. Wired at app startup. (The seam itself had a wiring bug — the raw-name fallback ran before the refiner check, making it unreachable — fixed in the same change.)

governor → fleet orchestrator — ✅ engine + read-only actuation done 2026-06-09

governor/src/fleet/ implements stage 1: registry ingest (the app-side fleet.json array is authoritative, devices.json the fallback), deterministic duty assignment with the spec's invariants, the N-copy custody floor-check with rolling-baton custodianship + re-pin planning, and the zombie reaper (healthy | stalled | dead, mesh-first recovery, public re-search fallback). CLI: portable-net-tv fleet status|duties|custody|repin|reaper|peers|probe|daemon|serve (all --json). reaper --apply performs only safe idempotent transmission nudges (reannounce/verify).

Completed 2026-06-09 (later, parallel agent team): the actuation layer — fleet repin --apply executes re-pin plans (rsync on the target pulling from the holder, recorded holdings feed back into the floor-check), fleet probe measures disk/uptime over ssh (EWMA score; feeds custody disk-eligibility), fleet daemon runs the duties→floor→reaper tick periodically for launchd, and fleet serve exposes /registry /custody /reaper /peers_for/<hash> over HTTP with optional bearer auth (the broadcast-host service, runnable on any node). Research actions build real mcp search invocations (fleet repin/reaper plans name them; execution behind apply flags). Remaining inside stage 1: nothing — what's left is infrastructure (targets need ssh + mediaRoot in fleet.json for repin to have somewhere to copy to) and the launchd plist itself.

fleet WireGuard fabric (plane 1) — blocked on a decision

The spec promotes a scoped fleet WG mesh (tva0, fleet-subnet-only AllowedIPs, collision-probe) to a foundational stage, but its design is explicitly blocked on the open question of what 10.9.0.4 is today (general overlay vs ad-hoc tv-anarchy overlay), and bring-up needs root on every node. Decide, then build.

stages 2/4/5 + Discord — blocked on external infrastructure

The engine already models seedboxes (class, duty preference, source defaults) and enforces the private-tracker gates; what doesn't exist is the infrastructure: a provisioned seedbox, friends' fleets for F2F, private-tracker credentials, Discord bots/servers. None of this is code in this repo until those exist.

Roku dev channel — planned milestone

The living-room display has a Roku Streaming Stick 4K (10.0.0.233, ECP) alongside black's HDMI input. ECP transport control is done (HostKind .roku / RokuTarget — pause/jump-back/exit/now-playing from the Devices tab). The channel itself — a couch-native TVAnarchy UI on the Roku — needs:

1. HTTP media plane on black — Roku only plays HTTP(S) streams; today the media is NFS/ssh. A file server plus on-demand ffmpeg remux/transcode→HLS for the incompatible tail (mkv with FLAC/Opus audio, PGS subs). This is the heavy piece and is useful beyond Roku (any future web/TV client).
2. BrightScript/SceneGraph client — library browse (black index over HTTP)
   • Video node playback. New codebase, no Swift reuse.
3. Release pipeline — TVAnarchy-<tag>-roku.zip asset + a push-deploy step (dev channels are uploaded TO the stick: curl --digest -u rokudev:<pass> -F archive=@channel.zip http://10.0.0.233/plugin_install). One dev-channel slot, persists indefinitely; dev mode enable = ECP keypress sequence.

Store publishing is out: Roku killed non-certified channels (2024) and certification would reject the torrent surfaces regardless of ENABLE_ADULT. Sideload-only, which the forge model already fits.

Build order (de-risked; each stage independently shippable)

From the design spec. Each stage ships on its own; later stages depend on earlier.

0. Hygiene (prerequisite) — ✅ done 2026-06-09: the PlumTV → TVAnarchy rename and the helper subsystems are committed on main.
1. Host registry + duty assignment, single fleet — ✅ done 2026-06-09 (engine): app-side registry (Devices tab, fleet.json) + governor-side duty engine, custody floor-check, and reaper (governor/src/fleet/). Remaining inside stage 1: re-pin actuation (cross-host copy execution) and running fleet duties/reaper under launchd instead of on demand.
2. Seedbox source + public_swarm_face duty. Adds an always-on custodian; proves the source model on the zero-risk source first. ("Add a seedbox" is the single most important onboarding step for non-power-users — most multi-device fleets have zero always-on nodes otherwise.)
3. peers_for() over local sources — ✅ core done 2026-06-09: fleet peers <infohash|title> unions fleet holders ∪ seedbox ∪ live DHT peers, provenance-tagged, with both private-tracker policy gates enforced (search_only default-closed; f2f_only forced un-overridably). Remaining: a broadcast host to serve peers_for to other devices (today it's a local CLI query).
4. Friend-mesh source + F2F relay. Federates; the custody floor goes cross-fleet. Multi-identity lands here.
5. Private-tracker source, default-closed. LAST and highest-consequence: swarm_isolation forced to f2f_only, un-overridable; content share is an account-killer for the source user. Ship only once F2F isolation is battle-tested on safe sources.

Parallel, any time: MLX TitleRefiner — ✅ done 2026-06-09. After a working mesh: the Discord planes — control/ops + QA/community + release announcements (project home server) and content/availability (private mesh

• a bot inside users' own servers, never the public home server). Discord is a surface you notify, not a backbone you route through: custody/reaper/F2F run over WireGuard regardless, and a Discord ban must not take the mesh down.

Non-goals / explicitly deferred (not defects)

• BlackTVTarget removed. Intentional — auto-migrated at runtime to MpvTarget with CommandsConfig.blackTVDefaults(bin:). Black-TV control still works.
• No ratio enforcement. Resolved decision (2026-06-08): ship gift-economy, build the custody_capacity knob, leave it off. First lever is visibility, not enforcement; hard ratio is a per-group last resort. Ratio anxiety is the pain being sold against — "minus the ratio police."
• No fingerprint-stripping on private shares. Resolved decision: warn hard, strip never by default. Stripping re-encodes and destroys the quality that makes a private release valuable; the friend is protected structurally by f2f_only, the source by the explicit warning. Strip is a per-release opt-in only, never auto.
• App doesn't link governor or call the MCP server directly. By design — it shells out to the mcp CLI and recommender as subprocesses; governor runs independently under launchd.
• Black-TV watch state not on plum. Intentional — black-local, read over SSH, never written across NFS.
• Watch parties (if built) = synchronized local playback; Discord carries only voice + timestamps, never streamed copyrighted video.