Contract: bundle.toml

Status: Accepted

The interface between lemonfiber and the default bundle lemonfiber-plugins keeps. Everything lemonfiber knows about the stack it ships comes from this file and the plugin trees it pins: which profiles and forms there are, which first-party plugin fills each capability by default, where each part sits, and the choices the stack makes on its own behalf.

Satisfies: B1-R1, B1-R2, B1-R3, B1-R12, B1-R15, F2-R13, F2-R14, F9-R4, F14-R7, F14-R19

---

Why this file exists

Every bundled part is a first-party plugin in a repository of its own (ADR-0041), and the bundle is what pins them and what the binary embeds (ADR-0042). A plugin manifest describes one part, in the vocabulary every author shares (ADR-0043 §2). What is about the whole stack has no place in any one part: the profiles, the forms, the services the catalogue no longer carries, which of two claimants the stack chooses, and the links that are genuinely about one service. The bundle declares those, and pins each part by the tree it was reviewed at (ADR-0045).

A part enters the bundle before its adapter exists. Such a part is assembled: lemonfiber builds the stack it ships from the bundle and the parts’ copies, and an assembled part’s one service is a stack service in every respect, its in-process adapter included. A part whose adapter has shipped is installed through the plugin path, moving in place of the stack service it replaces (ADR-0042 §4). The bundle says which, per part.

File location

bundle/bundle.toml in lemonfiber-plugins, which the core pins as a submodule and compiles in. Beside it, bundle/plugins/<id>/ holds each pinned plugin’s tree, copied byte for byte from its origin at the pinned revision.

The stack lemonfiber ships is assembled from these and from nothing else (ARCH-R263). It carries no stack.toml, no include list and no services/ file, and lemonfiber materialises none for it. The stack manifest is the form the assembly produces inside lemonfiber, and the format of a stack directory an operator names with --stack-dir (F1-R3).

Top-level structure

schema = 2

[[profile]]  # one per profile
[[form]]     # one per form
[[wiring]]   # a choice of filler, or a link by name
[[removed]]  # one per service the catalogue no longer carries
[[plugin]]   # one per first-party plugin, ordered by id

schema names the format generation. schema = 1 is the bundle of plugins alone, each copy one manifest at bundle/plugins/<id>.toml and each pin naming a release. lemonfiber reads 1 and 2, and refuses any other, naming both (ARCH-R265).

[[profile]]

[[profile]]
id          = "tv"
name        = "Television"
description = "Automated television acquisition"

[[profile]]
id          = "torrent"
name        = "Torrents"
description = "Torrent downloading, VPN-isolated"
protocol    = "torrent"

protocol — what makes the intersection possible

B1-R4 requires a closure to be intersected with the operator’s configured protocols before anything starts, and B1-R15 requires the profiles it applies to to be declared rather than recognised by name. protocol is that declaration. A profile that declares one cannot run unless the operator has configured that provider; a profile that declares none is never narrowed away.

The consequence of getting this wrong is not cosmetic. A torrent profile started without a configured VPN brings up the tunnel container with no credentials, and the failure mode of a VPN that is not protecting anything is the one failure in this product with consequences outside the machine.

[[form]]

[[form]]
id          = "tv"
name        = "TV"
description = "Search, download and automate television"
profiles    = ["search", "usenet", "torrent", "tv", "subs"]
composable  = true

A form’s profiles list is the complete closure, written out. Dependencies are not inferred: tv names search explicitly rather than lemonfiber deducing that Sonarr needs indexers, because inference would require lemonfiber to understand each service’s semantics (ADR-0002).

[[removed]]

[[removed]]
id          = "readarr"
removed_in  = "0.1.0"
reason      = "Discontinued upstream in 2025. Its repository is archived, so the pin could only ever age."
replaced_by = "bindery"

[[wiring]] — a choice of filler, or a link by name

[[wiring]]
by        = "bindery"
asks      = "indexer.search"
filled_by = "prowlarr"
why       = "Two services here answer as an indexer and one of them has to be the one this asks."

[[wiring]]
by  = "decline"
to  = "jellyfin"
why = "It makes three of Jellyfin's own calls, with a key lemonfiber minted for it alone."

An ask is the asker’s: a part asks for a capability in its own manifest’s [[ask]], with each where it reaches every filler, as any plugin does. A bundle wiring is one of the two things no manifest may say (F14-R9, F14-R22):

provides says what a service can do, and an ask says what a service needs. F4-R1’s second clause is that the wiring asks for a capability rather than naming a service, and F9-R4 is that clause applied to the stack this project ships.

filled_by — a choice, recorded, rather than a rule

Where two parts claim one capability and a part asks for one of them, somebody has to choose. F4-R8 says who: not install order, not precedence, not recency, but an operator, and their choice is recorded.

filled_by is the stack making that choice for the stack it ships, in a file the operator can read and with the reason beside it. It is a default, not a rule: the operator substitutes by choosing another claimant, that change is journalled like any other (F4-R10), and it can be put back. A plugin’s ask of the same capability is settled by the same choice where the operator made none (F14-R23).

It is why-bearing for the same reason to is. A choice with no reason beside it is indistinguishable from a rule somebody encoded, which is the thing F4-R8 refuses.

to — by name, and shown as by name

F4-R12 keeps by-name wiring available and makes it visible as the exception it is. to names a service, carries the reason, and anything that lists the stack’s wiring shows it as by-name rather than as an ask that happened to resolve to one candidate. A link by name joins the service whose id it names, the first-party service holding that reserved id once the part has moved in place (ARCH-R301), and never a service filling the same capability under another id (ARCH-R242).

Each by-name link says why: it is a service configured in another’s own terms, or making another’s own calls, so it is about that service. Everything else asks.

The torrent client’s link to the tunnel is not here. It is network.via on the client’s own service, an ask of network.egress-guard, so a substitute egress guard takes the client inside its own network.

[[plugin]] — each part, pinned

[[plugin]]
id           = "sabnzbd"
origin       = "https://github.com/lemonfiber/plugin-sabnzbd"
revision     = "4c1d0a7e9b2f3c5d6e8f0a1b2c3d4e5f6a7b8c9d"
manifest     = "sha256:2b9e…"
tree         = "sha256:7f04…"
fills        = ["download.usenet"]
stage        = "assembled"
profile      = "usenet"
last_release = "2026-09-30"

[[plugin]]
id           = "jellyfin"
origin       = "https://github.com/lemonfiber/plugin-jellyfin"
release      = "0.18.0"
revision     = "9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b"
manifest     = "sha256:c310…"
tree         = "sha256:5ad2…"
fills        = ["media.serve", "identity.source"]
stage        = "installed"
profile      = "media"
last_release = "2026-10-02"

A plugin builds an image where one of its services runs an image under ghcr.io/lemonfiber/, where lemonfiber publishes the images it builds and nothing else (ADR-0033). Only such a plugin is tagged by the train, and where release is named every image it builds is tagged at that release (REPO-R92).

The id is the service’s because every name the stack already gives a part follows from it: the container, the configuration directory ./config/<id>, the settings and secret namespaces, the materialised files and the journal’s history. A part becoming a plugin renames none of them.

stage — assembled, or installed

The release whose bundle moves a part from assembled to installed is the release that deletes its in-process adapter from the core. The move is one of the steps lemonfiber update stack rehearses and shows, and the confirmed update takes it. Until an update is confirmed, the stack keeps running the part’s own service, assembled from the pin’s copy, what the deleted adapter filled stands unfilled, and up and the doctor name the move as not yet taken.

The media server is pinned installed before its move can be made: the move takes the stack’s own service out of the Compose project, which only the generated project can, and the stack runs from the generated project only from the compose cutover. Until the release that moves it, the stack keeps the media server’s service, claims and recordings as the media stack held them at the source switch, the one part not read from the bundle (ARCH-R263), with its in-process adapter.

Profiles and forms for a part

Every service of a pinned plugin sits in the profile its [[plugin]] names, whatever the stage (ARCH-R96). A plugin manifest has no profile field, so a substitute and the part it stands in for are declared in the same vocabulary, and the bundle is the one place a profile is assigned. The plugin’s [plugin].forms names exactly the forms whose closure holds that profile, so what the manifest says it joins and what the bundle starts agree.

The tree — what a pin covers

A plugin’s tree is every file the binary carries from it, at the paths its repository holds them:

• plugin.toml;
• each service’s starting files, under config/<service id>/ (starting files);
• every recording the manifest names, a claim’s, a proof’s or a contributed check’s;
• conformance/, where the plugin speaks a contract.

tree is the SHA-256 of a listing of those files, one line per file, sorted by path bytewise: the file’s SHA-256 in lowercase hex, two spaces, its path relative to the repository root with / between segments, and a line feed. The listing is what sha256sum prints for the same files in that order, so any reader reproduces the digest with standard tools (ARCH-R267).

manifest is the digest of plugin.toml alone. Both are pinned: manifest is what the catalogue’s signed index already names, and tree is what the binary carries.

The copy at bundle/plugins/<id>/ is that tree, each file at its path in the plugin’s repository. A first-party plugin keeps its starting files at config/<id>/ and its recordings at recordings/<id>/, the paths the media stack held them at, so every materialised file and every fixture keeps its path when a part’s source moves.

The reserved register

The ids, the published ports and the proxy hostnames of every service a pinned plugin declares, of either stage, are reserved, and so is every hostname the proxy’s configuration in its copy answers on (ARCH-R269). A service of any other plugin taking one is refused, naming it and the part that holds it, except the first-party service whose replaces names that id (replaces, ARCH-R222). Reading both stages is what keeps a part’s port reserved through its move: an installed part is still the bundle’s.

Validation

Validation reports every violation in one pass, each naming its location (F1-R9).

Published schema

Each release of lemonfiber carries a JSON schema of bundle.toml, contract/bundle.schema.json, generated from the types lemonfiber reads it into (ARCH-R172).

Requirements

Related

• ADR-0045 — the decision this contract implements
• ADR-0046 — an assembled part’s secrets, and when the environment file is filed
• ADR-0042 — the bundle, pinned and embedded
• ADR-0002 Profiles and forms
• plugin-manifest — what each pinned plugin declares
• stack-manifest — the form the bundle is assembled into, and a --stack-dir stack’s format
• lemonfiber-plugins — where the bundle lives, and the CI that holds each copy to its origin
• releasing — OPS-R86, which plugins the train tags and which it pins by revision alone
• B1 Forms · F9 Capabilities of the bundled services