Every payload kind

kind says which payload an envelope carries, so a consumer can branch before parsing data. The contract artefact describes eighty-four of them, and each entry is the whole envelope with that kind’s payload in place rather than the payload alone — a generator wants the shape it will actually parse.

The set is closed. A kind is named in one place in the source and nowhere else, it cannot be constructed outside that place, and the contract is generated from the same list — so a kind that reaches the wire without a schema, or a schema for a kind nobody emits, fails the build rather than reaching a client.

Kind	In one line
admission	A session opened, and the moment it stops being one.
adoption	What adopting a setup already here came to, or would come to.
alert	One interruption: what happened, which way, and how much it matters.
alerts	What the operator will be told about, and what changing it came to.
archives	The archives this machine has kept.
askable	One page of what a member's search found, under their limits.
asked	What asking for one title came to, or would come to under a rehearsal.
backup	What a capture produced.
bandwidth	How the line is shared, and what that costs.
beside	What standing lemonfiber beside an existing setup came to, or would come to.
bundle	What a support request said: what a bundle holds, and where it is if it exists.
capabilities	Every capability this stack has, by the path its request is served at.
catalogue	What this stack holds, and what it used to.
certificate	What asking for the certificate to be replaced came to.
clients	The guidance in full, for a surface that shows all of it.
config	The answer to a configuration command.
credentials	The whole answer to a question about credentials.
dashboard	Everything the dashboard shows at one moment.
device-challenge	A challenge, as the phone is handed it to sign.
device-key	A device key registered.
device-keys	Every device key this machine has registered, and what became of a revoke.
doctor	What a diagnostic run found, and what it amounts to.
error	Something that went wrong, in the form an operator can act on.
forms	Every form this stack declares.
front-door	The household's one front door: which service it is, where it stands, and what else they can reach that is not it.
glossary	Every word this product explains, for somebody who asked what there is to ask about.
grant	A grant to play on a member's own account, the token the device plays with, and how long it lasts.
handoff	Where one person's hand-off stands, and what to hand them.
held	What one member can watch, and who they are.
history	Everything lemonfiber changed, most recent first.
hosting	What this machine keeps running on lemonfiber's behalf.
household	Who is in the household, what each may watch, and what each has asked for.
import	What copying an operator's own records across came to, or would come to.
invitation	One invitation, as it was just made.
job	Work that outlives the request that started it: its name, and what it was.
key-claim	A key minted as a claim: the link that collects it, and no secret.
keys	Every key this machine has minted, and what became of a revoke.
lifecycle	What a lifecycle command did, or would have done.
log	One line of output from one service, and how bad it says it is.
migration	What is already on this machine, before anything is proposed.
minted-key	A key minted, with everything a client on another machine needs to use it.
music	What choosing an audio format for music did: the choice, whether it was recorded or only rehearsed, and — once recorded — what became of applying it to the music service.
news	The newest of each kind, by what names them and nothing else.
news-items	What a surface can mark as new, newest first within each kind.
outbound	Everything that leaves this machine: lemonfiber's own requests, those it makes on an installed plugin's behalf, and the stack's.
pairing	Pairing material, and what the operator is told beside it.
part-way	What one member was part-way through, most recent first.
pausing	What pausing or resuming every download client came to.
playing	What is playing now, and whose sessions were asked about.
plugins	What is installed, and what installing one came to.
preview	What will be run, and what was left out.
provenance	Where every service in this stack comes from.
pull
quality	The operator's quality choice, what each preset means, and what the command did with it.
removal	What removing somebody costs, and what it did.
repair	What a repairing run offered, and what it did.
replacement	What standing in place of a setup already here came to, or would come to.
reset	What a full reset did, or — until it is confirmed — would do: the operator edits it reverts back to lemonfiber's own state, and whether it was carried out or only shown.
restore	What a restore said: what it would overwrite, and whether it did.
seed	What a seed pass amounted to.
self-update	Where this copy of lemonfiber stands, and what moving it would come to.
settings	Every setting and secret the stack's services read, and what changing a setting came to.
setup	What a setup run came to, and what it settled on.
space	Where the disk stands, what is on it, and what could be got back.
start
status	What each service is doing, and what that adds up to.
step	One narrated line: a step, and what was specifically true of it.
stop-seeding	One completed download, what letting it go would cost, and what became of it.
stored	Everything lemonfiber keeps on this machine, and what became of it.
stuck	The items whose downloads are stuck, across the curators — the landing point for "N items stuck" that queue health reports, each entry naming the item so the operator goes straight to its per-item trace rather than to a count to investigate.
substitution	What substituting one service for another would come to.
title	One title, as the member it was asked for may see it.
trace	Where one item is in the pipeline: how far it got, why it stopped if it did, and the stages it passed through — the answer to "where is my show?".
undo	What putting a run back came to.
uninstall	A removal, before or after it happened.
update	What updating the stack would change, or what a run of it came to.
upgrade	What upgrading existing content did, or — unconfirmed — would do.
version	What versions are in play: the binary, the stack it operates, and what changed.
walkthrough	What a first-content walkthrough did — the whole of it, narrated line by line as it happened and gathered here so the ending can be rendered, serialised and exited on.
watch	What a watch saw, once the data root it was guarding was lost.
watched	A player's report of how far a member got, as the media server now holds it.
wiring	What this stack wires to what.
wizard	Where a setup run stands, and what it is still asking for.
word	A word this product uses, and what somebody meeting it needs to know.

pull and start are the two whose data is not an object. Both are a single string: one line the container engine wrote, emitted as it was written, because a pull that takes ten minutes has to say something before it ends.

Six of them are set out field by field below — the ones a client meets first, and the ones whose payloads are small enough to read as a table. The other seventy-eight are in the artefact in full, and every SDK generates a type for each kind in their own copy of it, so nothing here is the only place their shapes are written down. Every table below is rendered from that artefact at the revision this site pins, so a field here is a field on the wire.

error

Something that went wrong, in the form an operator can act on. This is the kind a failed run emits on the error stream. cause is a problem of the same shape, so a symptom can name the root it came from without a second type existing to say so.

A code is stable on purpose: an operator who searches for one should find the same answer a year later. Codes are declared beside the code that raises them and are never recycled. Severity has four levels, deliberately: more would not be applied consistently, and inconsistent severity is worse than coarse severity.

Problem

Something that went wrong, in the form an operator can act on.

Field	Type	Required	What it is
cause	Problemornull	no	The problem that produced this one, where several share a root.
code	Code	yes	The stable identifier for this kind of problem.
detail	stringornull	no	The underlying technical detail, available but never leading.
meaning	string	yes	What it means for the operator.
remedies	array ofRemedy	yes	What to do, most likely first.
severity	ProblemSeverity	yes	How much it matters.
state	ProblemState	yes	Where it stands with respect to being fixed.
steps	array ofProblemStep	no	Every step a run declares, with what each came to, where the problem ended a run of steps part-way; absent from every other problem. Data beside the detail rather than in it, so a client reads what changed somewhere going back cannot reach without parsing a sentence written for a person.
summary	string	yes	What happened, in one plain sentence.

Code

A stable identifier for a kind of problem.

Stability is the whole point: an operator who searches for a code should find the same answer a year later. Every code is declared in the error crate's codes module, and a code is never recycled.

It is string

Remedy

One thing the operator can do about a problem.

Field	Type	Required	What it is
action	string	yes	The action, phrased as something to do rather than something to know.
detail	stringornull	no	Where to look, when that helps.

ProblemSeverity

How much a problem matters.

Four levels, deliberately. More would not be applied consistently, and inconsistent severity is worse than coarse severity.

One of these:

• "advisory"

  Informational; nothing is required.

• "warning"

  Degraded or risky, still working.

• "error"

  Something is broken.

• "critical"

  Consequences outside the machine, or data at risk.

ProblemState

Where a problem stands with respect to being fixed.

One of these:

• "actionable"

  A remedy is available here.

• "guided"

  The operator must act, somewhere else.

• "remediable"

  lemonfiber can fix this itself.

• "unknown"

  No known remedy; escalation is offered instead.

• "suppressed"

  Acknowledged, and not re-shown until it recurs.

ProblemStep

What one step of a run that stopped part-way came to.

Field	Type	Required	What it is
came	StepCame	yes	What it came to.
landed	boolean	yes	Whether it reached somewhere other than the plugin's own services, which going back cannot undo.
recipe	string	yes	The recipe the step belongs to.
step	string	yes	The step's id within it.

StepCame

What one step of a recipe came to.

One of these:

• "answered"

  It was answered with what it should be, and took what it captures.

• "skipped"

  Its guard did not hold, so it was not made.

• "not-reached"

  An earlier step did not come to what it should, so this one was not made.

• "unreachable"

  Nothing answered it.

• "refused"

  It was not sent: its host stands for an address not out on the internet, or could not be resolved.

• "withheld"

  It was not sent: a value it carries may not go where it was going.

• "unexpected"

  It was answered with something other than what it expects.

• "uncaptured"

  Its answer held nothing where a capture reads.

• "oversized"

  Its answer was larger than any answer a recipe reads.

log

One line of output from one service. A log stream emits one envelope of this kind per line.

at is kept verbatim and unparsed. Containers disagree with the host clock and with each other, and the only defensible ordering is each container’s own account of itself — which a reader can apply only if it is carried rather than replaced by an arrival time.

LogLine

One line of output from one service, and how bad it says it is.

What a machine-readable surface hands on, rather than the engine's line alone, so a consumer can mark the lines that say they failed, or find the first of them, without reading the text for itself — a second reading of severity would be a second answer, and the two would disagree about some service's spelling.

Field	Type	Required	What it is
at	stringornull	no	When the container itself says it wrote the line, where it said so. Kept verbatim and unparsed. Containers disagree with the host clock and with each other, and the only defensible ordering is each container's own account of itself — which a reader can only apply if it is carried rather than replaced by an arrival time.
level	LogLevelornull	no	How bad the line says it is, in one lowercase word. Absent where the line says nothing about itself. It is never guessed from the stream the line arrived on or from the words in it: most of this stack writes ordinary progress to standard error, and a line saying it could not find something is often a routine miss.
line	string	yes	The line, without its trailing newline.
service	string	yes	The Compose service it came from.
stream	Stream	yes	Which stream it arrived on.

LogLevel

How bad a line says it is.

Ordered, so a filter can ask for "warnings and worse" without a table of which level outranks which. Deliberately coarse: these six are what services agree on, and a seventh that only one of them writes would be a level nobody could filter by across the stack.

One of these:

• "trace"

  Detail a developer asked for.

• "debug"

  Detail beyond the ordinary account of what happened.

• "info"

  The ordinary account of what happened.

• "warn"

  Something the operator may want to know about, that did not stop the service.

• "error"

  Something that failed.

• "fatal"

  Something that failed and stopped the service.

Stream

Which stream a log line arrived on.

One of these:

• "stdout"

  Standard output.

• "stderr"

  Standard error.

setup

What a setup run came to, and what it settled on.

This report is deliberately not the settings themselves. Setup writes an indexer key and a service password among them, and a report a script can read is a report a script can log — into a file, a CI transcript, somebody’s terminal history. So it says what was decided and never what was entered, and its fields are chosen one at a time rather than by serialising a struct that might later gain a secret.

SetupReport

What a setup run came to, and what it settled on.

Deliberately not the settings themselves. Setup writes an indexer key and a service password among them, and a report a script can read is a report a script can log — into a file, a CI transcript, somebody's terminal history. So this says what was decided and never what was entered, and the fields are chosen one at a time rather than by serialising a struct that might later gain a secret.

The indexer's address is left out for that reason rather than because it is itself a secret: it is entered beside its key, and the two travel together in every place an operator copies them from.

Field	Type	Required	What it is
data_root	stringornull	no	Where the library was put, where a location was chosen.
outcome	SetupOutcome	yes	How the run ended.
protocols	Protocols	yes	Which ways of downloading the stack was set up for.
service_user	stringornull	no	The user the services run as, as uid:gid, where one was set.

SetupOutcome

How a setup run ended.

One of these:

• "applied"

  The reviewed answers were written.

• "abandoned"

  The plan was seen and not applied; nothing was written.

• "already-set-up"

  Nothing was asked, because this machine was already set up.

Protocols

Which download protocols the operator actually has accounts for.

A form names both, because a form describes what it does rather than what this operator has paid for. Narrowing happens afterwards, so a tunnel is never started with credentials that were never supplied.

Field	Type	Required	What it is
torrent	boolean	yes	A VPN and torrent client are configured.
usenet	boolean	yes	A Usenet provider is configured.

walkthrough

What a first-content walkthrough did: the whole of it, narrated line by line as it happened.

WalkthroughReport

What a first-content walkthrough did — the whole of it, narrated line by line as it happened and gathered here so the ending can be rendered, serialised and exited on.

Field	Type	Required	What it is
already_here	boolean	yes	Whether what was asked for was already here, and so was not acquired again.
handover	Handoverornull	no	Where it leaves the operator, where it worked.
in_background	boolean	yes	Whether the download was handed to the background rather than waited out.
item	stringornull	no	What it walked, where it got as far as choosing something.
lines	array ofLine	yes	Every line it said, in order — the same lines the operator watched arrive, kept so a machine-readable run is not a silent one.
link	Linkornull	no	What the import did with the file, where it got that far.
proves	string	yes	What it set out to prove, said so the operator knows what they watched.
shape	Shape	yes	Which walk this was.
state	WalkthroughState	yes	Where it ended up.
stopped	Stoppedornull	no	Where and why it stopped, where it did.
suggestions	array ofstring	yes	What could have been walked instead, where nothing was chosen — the safe first attempts, so an operator with an empty library is not left guessing.

Handover

Where a finished walkthrough leaves the operator.

Field	Type	Required	What it is
next	array ofNext	yes	What to do next, in order.

Line

One narrated line: a step, and what was specifically true of it.

Field	Type	Required	What it is
detail	string	yes	What was specifically true — the evidence that makes the line worth reading rather than a spinner. Empty where there is nothing particular to say.
said	string	yes	What it is doing, in plain language.
step	WalkthroughStep	yes	The step being narrated.

Link

What the import did with the finished download — the difference between one copy of a file and two.

One of these:

• "hardlinked"

  The library entry and the download are the same file under two names, which is what a correctly-shared volume allows and what costs no extra disk.

• "copied"

  The file was copied, so it now exists twice. Works, but every import costs its own size again and seeding a torrent holds the second copy for as long as it seeds.

Shape

Which walkthrough this stack is offered.

One of these:

• "pipeline"

  The full walk: search, grab, download, import, and see it in the library.

• "library-only"

  The walk for a stack that acquires nothing: point at media already on disk and confirm the media server can see it.

WalkthroughState

What has become of a walkthrough.

One of these:

• "offered"

  Presented at the end of setup, not yet answered.

• "skipped"

  Declined. Available later, and carrying no penalty — a stack that was set up is set up whether or not anyone watched it fetch something.

• "searching"

  Looking for releases.

• "grabbing"

  Sending a release to the download client.

• "downloading"

  The download is running.

• "importing"

  Moving the finished download into the library.

• "complete"

  It is in the library and playable.

• "failed"

  Stopped at a named step, with a diagnosis.

• "abandoned"

  The operator left part-way. Whatever was in flight stays in flight.

Stopped

A walkthrough that stopped: where, why, what the services were saying, and what to do.

Field	Type	Required	What it is
logs	array ofstring	yes	What the services involved were saying at the time, shown inline rather than left for the operator to go and find — a fault report they have to research is a fault report they abandon.
reason	Reason	yes	Why.
remedy	string	yes	The one thing to try.
step	WalkthroughStep	yes	The step it stopped at.

Next

One thing to do next.

One of these:

• "more-content"

  Add more content, now that the shape of it is understood.

• "household"

  Let the rest of the household ask for things themselves.

• "client-apps"

  Watch it somewhere other than the machine it is running on.

WalkthroughStep

One step of the walk, ordered from picking something to watching it play.

One of these:

• "choosing"

  Picking something to add, and confirming it is not already here.

• "searching"

  The indexers are being searched for releases.

• "grabbing"

  A release is being sent to the download client.

• "downloading"

  The download is running.

• "importing"

  The curator is moving the finished download into the library.

• "scanning"

  The media server is being told to look at what arrived.

• "available"

  It is in the library and playable.

Reason

Why a walkthrough could not go on.

One of these:

• "no-indexers"

  No indexer is configured, so there is nothing to search. Not a failure of the walk — a reason not to offer it at all.

• "indexers-failed"

  The search could not be run: the indexers, or the service holding them, would not answer.

• "nothing-matched"

  The search ran cleanly and matched nothing. An entirely different problem from the one above, and the one operators most often mistake for it.

• "none-met-the-preset"

  Releases exist, but none meets the chosen quality preset. The stack is working; the preset and what is out there disagree.

• "tunnel-down"

  Torrents are in play and the tunnel is not verified up. Nothing is grabbed.

• "not-grabbed"

  The release was never handed to a download client.

• "stalled"

  The download stopped making progress.

• "import-failed"

  The download finished and the library manager would not take it.

• "no-media-server"

  There is no media server in the running form to make it playable.

• "not-visible"

  It was imported, the media server was told, and it still cannot be found there.

watch

What a watch saw, once the data root it was guarding was lost.

SupervisionReport

What a watch saw, once the data root it was guarding was lost.

Field	Type	Required	What it is
forms	array ofstring	yes	The forms that were being watched, and are now stopped.
reason	string	yes	Why the watch ended: the data root vanished, or a different volume took its place — or, on a run that only said what a watch would do, that nothing was watched at all.
rehearsed	boolean	yes	Whether this was a rehearsal: what would have happened, with none of it done. Said in a field of its own so that a rehearsal is never told from the real run by its wording alone.
stopped	boolean	yes	Whether stopping the services succeeded.
would	Vigilornull	no	The watch this run would have kept, where it only said what it would do. A guard is the one command with no ending of its own, so a rehearsal of it cannot be the command with its last step left out — it would hold until the drive was pulled. What it answers with is this instead, and the fields above then describe a watch that never began: nothing ended, and nothing was stopped. Absent on every watch that actually ran.

Vigil

The watch a run would keep, and what it would do at the end of it.

Field	Type	Required	What it is
command	array ofstring	yes	The invocation it would run the moment that location went, word for word. Built by the same path a real watch stops the services through, rather than described beside it: an argv reported from a second reckoning is one nobody runs, and the one nobody runs is the one that stops being right.
every	integeruint64, ≥ 0	yes	How often it would look, in seconds.
root	string	yes	The data location it would hold.

word

A word this product uses, and what somebody meeting it needs to know. short is enough to act on: somebody who reads only that should not be stuck. also_called exists because the services do not agree on words, and an operator moving between their screens should not have to work out that two of them are one.

Term

A word this product uses, and what somebody meeting it needs to know.

Field	Type	Required	What it is
also_called	array ofstring	yes	What other services in this stack call the same thing. A curator and a Usenet client do not agree on words, and an operator moving between their screens should not have to work out that two of them are one.
deep	stringornull	no	More, for somebody who asks — never needed in order to act.
forms	array ofstring	yes	The other forms this product itself writes the word in, where a state or a stage is named by one — grabbed for grab, seeding for seed. Apart from [Self::also_called], which is another service's word and one this product must never write as its own. These are this product's own words, and a surface explaining a word it was sent looks for the word it was sent here, so that nothing on the far side has to guess which term an inflection belongs to.
short	string	yes	One sentence: what it is for and what it costs or gains. Enough to act on. Somebody who reads only this should not be stuck.
word	string	yes	The word as it appears in the interface.

The other seventy-eight

Every kind in the table above is in the contract artefact with its full schema, including the seventy-eight not expanded here. Their payloads are larger — a dashboard carries twelve panels, each with its own shape; a lifecycle report carries seventeen fields — and transcribing them into this page would create a second place their shapes are written down, which is the one thing the artefact exists to prevent.

Read them from contract/web-api/, or let a generated client do it: the TypeScript SDK, the PHP SDK and the Python SDK each emit one type per kind from that contract, so the shapes arrive typed rather than transcribed.

Where to go next

The wrapper these sit inside is the envelope. To read them from code without transcribing any of the above, use the TypeScript SDK, the PHP SDK or the Python SDK, each of which generates one type per kind. Error codes have their own reference in every error by code.