Natalie 9875e53ec0 docs(@applications/tv-anarchy): 📝 add technical glossary definitions

Co-Authored-By: Lilith Autocommit <noreply@atlilith.com>

2026-06-08 22:14:11 -07:00

Glossary

Domain terms used across the docs and the design spec.

Hosts & fleets

Fleet — the atomic unit: one Discord identity plus its typed devices. A single fleet (e.g. black + apricot) already contains its own seeder floor, so the system works for one user with zero friends; the mesh is the same code with more identities.
Identity — a person, represented by one discord_id. Owns one or more fleets.
Host class — what a device is: server | roamer | consumer | seedbox | broadcast. Class is fixed; duty is assigned.
Roamer — a non-always-on device that seeds with a TTL while in use (e.g. plum).
Consumer — a pure sink (e.g. a phone); never receives any duty.
Broadcast node — the most-reachable always-on node (seedbox/vps-0). Anchors F2F rendezvous, holds the aggregated peer registry, runs the Discord bridge, and is optionally the only node touching public swarms.
always_on / on_home_ip — host flags. on_home_ip = true means public-swarm traffic from it exposes the home connection (so it's avoided as the swarm face).
uptime_score — a rolling [0,1] reliability measure feeding capacity math.
custody_capacity — Σ (disk_free × uptime_score) over a fleet's always-on hosts; says whether the fleet can hold a floor or is a net consumer.

Duty — what the manager tells a host to do: custody_floor | public_swarm_face | f2f_relay | broadcast. Assigned deterministically from capabilities on registry change, never hardcoded.
custody_floor — the obligation to keep ≥N complete copies of a wanted title.
public_swarm_face — the node that touches public swarms; prefers off-home-IP so home connections stay dark.
f2f_relay — an always-on node that relays friend-to-friend requests/bytes.
broadcast — exactly one per fleet; the rendezvous/registry/bridge anchor.

Custody floor — the replication guarantee: every wanted title keeps ≥N complete copies; dropping to N−1 triggers a re-pin from a surviving seeder before the last copy vanishes.
Rolling baton — custodianship rotates: the newest downloader joins the floor, the oldest is released (demoted to voluntary). A custodian reclaiming disk must floor-check + hand off before dropping.
Watch = auto-seed with TTL — every viewing adds a seeder; content heals as it's used.
Zombie — a torrent with no live seeders (a dead magnet / "corpse").
Reaper — the governor's cron classifier (healthy | stalled | dead); for dead-but-wanted titles it recovers from the mesh first, public re-search as fallback. The mesh prevents future zombies; the reaper resurrects already-dead ones.

Custody graph — narrow, trust-bounded (1° friends + always-on nodes); holds the seeder floor.
Discovery/signal graph — wide, six-degrees, anonymized + aggregated; carries popularity signal and relays F2F requests.
F2F (friend-to-friend / darknet routing) — you peer directly only with people you trust; requests and bytes relay hop-by-hop until a holder is reached (Freenet/RetroShare model). Six-degrees reach, local trust, never peer a stranger.
Trust gradient — 1° = full custodian peer; 2° = rate-limited pull via relay; 3°+ = signal only unless vouched.
k-anonymity — suppress discovery signal for titles below K≈5 distinct watchers; load-bearing because a single-watcher leak fingerprints someone (adult content is in scope).
per-fleet dedup — one person watching on plum then phone counts as one watch.

Source — a place peers come from: dht | public_tracker | private_tracker | friend_mesh | fleet_host | seedbox.
share_policy — search_only (share the infohash) vs content (serve bytes). Private trackers default to search_only (default-closed).
swarm_isolation — f2f_only vs open. Forced to f2f_only and un-overridable for private sources, so a friend never announces to the private tracker.
passkey — the per-user secret embedded in a private .torrent; if a friend's client announces it, the source user is banned for passkey sharing. The reason f2f_only isolation exists.
served_via — how a peer is reachable: public | wireguard. Lets the UI show the transport behind each peer.
Meta-tracker — the holistic, user-owned seeder list produced by peers_for, unioning privates ∪ fleet ∪ friends' fleets ∪ seedbox ∪ DHT/public — a union no single tracker can assemble.

PlayerTarget — the protocol every playback backend implements; capability sub-protocols add launch/enqueue/track-selection/quality/stats.
Command template — argv array (with {query}/{path}/… tokens) that delegates an operation a generic mpv host can't do over IPC to a helper binary.
TitleRefiner — the (unwired) MLX seam for cleaning filenames regex can't parse; see roadmap.md.