Merge pull request 'Add Media as the eleventh domain, with its words (ADR 0302)' (#319) from feat/302-media-domain into main

00-META/glossary.md

@@ -563,6 +563,38 @@ asking, never the act. **Decided by** ADR 0152, 0175, 0234, 0259, 0272.
   prevent it. A lesson is `proposed`, `accepted` or `declined`; an accepted lesson is a personal rule, and a
   proposed one is never read as one (ADR 0273).
 
+## Media — what a person watches, listens to and reads
+
+**Purpose.** To find, fetch and file copies of the works a person watches, listens to and reads, each in
+the library its kind names. **Recorded by** the `media-importer` module's settings and its memory of what
+it was told, and the servarr apps' own libraries. **Upstream of** nothing. **Decided by** ADR 0295, 0296,
+0302.
+**Uses:** module, seat, setting (Module).
+
+- **content** — a work a person watches, listens to or reads: a film, an album and its tracks, an
+  episode, a book, a session of a sport event. It is known by an identity from a catalogue outside the
+  mesh, never by a file's name, and a work with no copy anywhere is still content (ADR 0302).
+- **kind** — a kind of content, declared as configuration, never code: its parts, the metadata fields
+  that identify a work, the file extensions of its copies, and its folder and file templates. The first
+  are music, movie, series, audiobook, ebook and sport event.
+- **media release** — one copy of a work an engine can fetch, such as an NZB or a video. Downloaded, it
+  sits in the downloads folder, not yet filed. ADR 0302 says *release*.
+- **library** — one folder of one kind, filed by one importer: the media-importer's, named in its
+  settings, or a servarr app's. Several libraries may hold one kind, as TV Shows and Anime both hold
+  series.
+- **media file** — a file on disk together with its metadata: its kind, the fields that identify the
+  work, and what part of the work the file is. It is what the media-importer takes.
+- **media-importer** — the module that files a media file into its library at the place its kind's
+  templates make of its metadata. It files only the downloads it was told about, and never into a
+  servarr app's library (ADR 0302).
+- **download client** — a module that fetches a media release into the downloads folder and emits
+  `download.added` and `download.completed` naming the download's id, its category and the path of its
+  files: `nzbget`, `qbittorrent`, `youtube`.
+- **engine** — a module that searches for media releases: the holder of `usenet-search` (`nzbgeek`,
+  ADR 0295) or of `youtube-search` (`youtube`, ADR 0296).
+- **grab** — an engine handing one media release to a download client. It names the work it is for, so
+  the media-importer knows where the copy belongs.
+
 ## The record — how this repository works
 
 Not a domain of the mesh but of the way it is built, listed because its words meet the mesh's.
@@ -637,6 +669,7 @@ renaming one sense, the old sense moves to a *Not:* line and becomes mechanical.
 | | a phone notification | **push notification** | Operator and conversation |
 | release | a person letting a held delivery go on | **release** | Change and delivery |
 | | taking a consumer off a licence | **unbind** (verb `release`, to rename) | Identity and access |
+| | a copy of a work an engine can fetch | **media release** | Media |
 | gate | the judgement on a delivery's first node | **first-node gate** | Change and delivery |
 | | the pull request status | **merge gate** | Change and delivery |
 | | a failed step stopping its module's later steps (ADR 0136) | *a failed step holds its module* | Placement |

03-DESIGN/01-to-be/49-the-mesh-in-domains.md

@@ -2,19 +2,20 @@
 layer: to-be
 status: in-progress
 code: [hq 00-META/checks/words.py, mesh-catalog merge-check.sh]
-updated: 2026-10-07
+updated: 2026-10-11
 decisions:
   - "ADR 0244"
   - "ADR 0006"
   - "ADR 0008"
+  - "ADR 0302"
 ---
 
 # 49 — The mesh in domains
 
-**Every concept of the mesh belongs to one of ten domains, which owns its one word. The glossary is
+**Every concept of the mesh belongs to one of eleven domains, which owns its one word. The glossary is
 organised by them and is the authority; a word it retires is named in the entry that replaced it, with
 where it is retired; and two checks hold the documents and the tools' descriptions to it.**
-(ADR 0244.)
+(ADR 0244; the eleventh, Media, ADR 0302.)
 
 A **domain** is an area of the mesh that owns a set of concepts: inside it each concept has one word,
 and the domain decides what that word means. The glossary
@@ -35,6 +36,7 @@ shape — what each is for, where its records live, and how they depend on one a
 | **Data** | to know every item of data a module holds, how precious it is, and keep it recoverable | the manifests' data declarations, and every node's `node-backup` seat |
 | **Connectivity** | to make every node and module reachable by name where it should be, and unreachable where it should not | the controller |
 | **Operator and conversation** | to let the mesh and its operator tell, ask and answer, and act only on an answer it can trust | the router, and the controller for authorising asks |
+| **Media** | to find, fetch and file copies of the works a person watches, listens to and reads, each in the library its kind names | the `media-importer` module's settings and memory, and the servarr apps' own libraries |
 
 Beside them, **the record** is this repository's own vocabulary — research, decisions, designs,
 issues, playbooks, checks — listed because its words meet the mesh's.
@@ -65,6 +67,9 @@ a change of meaning upstream ripples down, never up. Arrows point downstream.
                      (a held delivery waits for a person's word)
 ```
 
+Media stands beside the diagram, below Module alone: its words are about what a person watches, not
+about the mesh's machinery, and no other domain reads them.
+
 Change and delivery sits low because it reads health and data; in time it runs first, and asks Placement
 to send. An authorising answer acts in whichever domain asked, through that domain's own verb: the
 conversation owns the asking, never the act.

03-DESIGN/01-to-be/README.md

@@ -48,7 +48,7 @@ document is written and this one's status becomes `implemented`.
 | [`45-a-core-that-cannot-fail-silently.md`](45-a-core-that-cannot-fail-silently.md) | **Designed.** The core says when it is wrong, refuses what is stale or unreadable, heals what it knows, upgrades one machine at a time with a witness that rolls it back, and is checked against the real mesh before merge: the writers and signals tables, the condition store, `doctor`, the minimal output channel, healers, the lease and report order, staged upgrades, the facts snapshot and replays, in six phases | ADR 0227, ADR 0224, ADR 0218 |
 | [`46-the-conversation-with-the-operator.md`](46-the-conversation-with-the-operator.md) | **Designed.** The mesh tells and asks its operator over channels that are holders of two kinded benches, `channel` and `intake`, declaring capabilities from a fixed vocabulary; the router orders them by work context and never lowers the bar; an answer that performs an action is checked and performed by the controller, on a TOTP code or a verified Telegram sender, never on a desk click alone; operator messages addressed or answered by the mesh's responder, untrusted input kept as data, references for what words may not carry, and a recoverable factor; Telegram first, in six phases | ADR 0234, ADR 0227 |
 | [`47-delivery-from-commit-to-delivered.md`](47-delivery-from-commit-to-delivered.md) | **Designed.** A delivery is one commit in one repository, from its pull request's head to every machine; a delivery group is deliveries sharing a branch name, ordered and checked as one future state; both owned by the `mesh-delivery` module with one state table, its state on the bus, every transition said, noted on the commit and shown on the pull request; the controller keeps the planner, the gate, sending and the walk, and the core's own updates never wait for the module | ADR 0239, ADR 0238, ADR 0236 |
-| [`49-the-mesh-in-domains.md`](49-the-mesh-in-domains.md) | **In progress.** Every concept belongs to one of ten domains, which owns its one word; the glossary is organised by them and is the authority, a retired word is named on its replacement's line with its scope, and two checks hold this repository's documents and the catalogue's tool descriptions to it | ADR 0244, ADR 0006, ADR 0008 |
+| [`49-the-mesh-in-domains.md`](49-the-mesh-in-domains.md) | **In progress.** Every concept belongs to one of eleven domains, which owns its one word; the glossary is organised by them and is the authority, a retired word is named on its replacement's line with its scope, and two checks hold this repository's documents and the catalogue's tool descriptions to it | ADR 0244, ADR 0006, ADR 0008, ADR 0302 |
 | [`50-split-dns-on-a-machine-with-a-vpn-client.md`](50-split-dns-on-a-machine-with-a-vpn-client.md) | **In progress.** A machine whose VPN client pushes servers of its own runs a resolver of its own, on a node seat, that routes the VPN's domains over its link and every other name to the mesh's resolvers; the VPN client's module carries the adapter | ADR 0247, ADR 0223 |
 | [`51-the-registries-keep-what-is-named.md`](51-the-registries-keep-what-is-named.md) | **In progress.** The artifact store, the package registry and each machine's container runtime get tools that say what they hold, what names each thing and what could go; every removal is a dry run unless a person asks and says why, and what decides is always a record | ADR 0251, ADR 0189 |
 | [`52-shares-and-mounts.md`](52-shares-and-mounts.md) | **In progress.** A node shares one folder at a time through `nfs-server`, which provides it as a provision to the private network only, mapping every client to the folder's owner; a node that asks mounts it through `mounts`, a mount unit and an automount per share, so nothing mounts or fails at boot; a device that comes and goes is an occasional source whose absence is a state | ADR 0263, ADR 0051, ADR 0092 |