From 56b7a9084a5fb79bfafc8f8bab051a675778b29a Mon Sep 17 00:00:00 2001 From: jochen Date: Sun, 11 Oct 2026 21:32:15 +0200 Subject: [PATCH] Add Media as the eleventh domain, with its words (ADR 0302) ADR 0302 made Media a domain: content, kind, media release, library, media file, media-importer, download client, engine and grab now have one meaning each. Release already meant two things, so the Media sense is qualified in the homonyms. --- 00-META/glossary.md | 33 ++++++++++++++++++++ 03-DESIGN/01-to-be/49-the-mesh-in-domains.md | 11 +++++-- 03-DESIGN/01-to-be/README.md | 2 +- 3 files changed, 42 insertions(+), 4 deletions(-) diff --git a/00-META/glossary.md b/00-META/glossary.md index 0d5e09ea..04bd1286 100644 --- a/00-META/glossary.md +++ b/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 | diff --git a/03-DESIGN/01-to-be/49-the-mesh-in-domains.md b/03-DESIGN/01-to-be/49-the-mesh-in-domains.md index fde66dec..01a93f91 100644 --- a/03-DESIGN/01-to-be/49-the-mesh-in-domains.md +++ b/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. diff --git a/03-DESIGN/01-to-be/README.md b/03-DESIGN/01-to-be/README.md index 4d0dbf95..163fea68 100644 --- a/03-DESIGN/01-to-be/README.md +++ b/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 |