98 lines
5.2 KiB
Markdown
98 lines
5.2 KiB
Markdown
# 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.
|
||
|
||
## Duties
|
||
|
||
- **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 & healing
|
||
|
||
- **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.
|
||
|
||
## Graphs & routing
|
||
|
||
- **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.
|
||
|
||
## Sources & sharing
|
||
|
||
- **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.
|
||
|
||
## Derived outputs
|
||
|
||
- **`peers_for(infohash) → Peer[]`** — the holistic seeder list / meta-tracker.
|
||
- **`custodians_of(title) → Host[]`** — who is obligated to keep a title alive.
|
||
|
||
## App-side terms
|
||
|
||
- **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](./roadmap.md).
|