Contract: the web API

Status: Accepted

The interface between lemonfiber, which serves it, and lemonfiber-web, which draws it.

Satisfies: G1-R1, G1-R2, G1-R7, G1-R12, C6-R9, C6-R10, C6-R11, C6-R12

---

Why this is a contract

ADR-0011 put the web surface in its own repo, which means the boundary between it and the core is a published shape rather than a compiler check. That is the whole point: G1-R2 says no surface may implement behaviour independently, and a client that can only ask and draw cannot break it by construction.

The risk a contract carries is drift, so this one is built to make drift structurally hard rather than merely discouraged.

It is the envelope that already exists

Machine-readable output is already a stable interface (ARCH-R9, versioning):

{ "api_version": 1, "kind": "status", "data": { … } }

The web API does not introduce a second shape. Every endpoint answers with the identical envelope the equivalent command emits under --json, byte for byte. A script piping lemonfiber status --json and the web app fetching /api/status receive the same document.

This is the load-bearing decision in the contract, and it is worth being explicit about why. A separate “web shape” would be a second serialisation of the same domain — two places to change when a field is added, two sets of tests, and eventually two answers to the same question, which is exactly what G1-R2 exists to prevent. One shape means the surface adds no vocabulary of its own.

Reading

Each command that supports --json has one endpoint, named for the command, returning that command’s envelope:

GET /api/forms         GET /api/status         GET /api/services
GET /api/checks        GET /api/storage        GET /api/logs?…
GET /api/requests      GET /api/trace?…        GET /api/stuck
GET /api/version       GET /api/config?…       GET /api/quality
GET /api/explain?…     GET /api/backups        GET /api/bundle/{name}
GET /api/front-door    GET /api/provenance    GET /api/catalogue
GET /api/outbound      GET /api/stored       GET /api/clients
GET /api/credentials   GET /api/alerts
GET /api/space         GET /api/bandwidth
GET /api/hosting      GET /api/uninstall
GET /api/migration    GET /api/held?…        GET /api/held/{id}?…
GET /api/held/{id}/poster?…                   GET /api/held/{id}/backdrop?…
GET /api/history
GET /api/update?…
GET /api/news
GET /api/plugins       GET /api/wiring       GET /api/settings
GET /api/playing       GET /api/watching?…
GET /api/askable?…      GET /api/askable/{id}/poster?…

Query parameters mirror what the command takes, flag or argument. A command that gains one gains a parameter; one that gains an endpoint gained a command first.

/api/held/{id} is one title on a member’s shelf, named in the path by the id the shelf lists it under: what it is, a series’ seasons and episodes, and where each is served at the guarded front door beside the fingerprint the door presents (D11). It is read as the member whose shelf it is, so a title outside their limits is answered as absent, the same answer a title the household does not hold gets. /api/watching is what a member was part-way through and how far, located the same way.

/api/held/{id}/poster and /api/held/{id}/backdrop are the two reads that answer bytes rather than an envelope: the title’s picture, read as the member and passed on as an image/* body of at most 2 MiB, marked Cache-Control: private (D11-R9). They exist for a browser, which can neither present a session to the guarded front door nor pin its certificate, so it fetches the picture here with its own token and draws it from memory. A title outside the member’s limits, and a picture the media server does not hold, are answered as absent.

/api/clients takes none either, and for a different reason: what to watch on is the same answer on every machine, because the client landscape belongs to the platforms rather than to a stack. It reads nothing and asks nothing of the engine, so it answers where nothing is set up yet — which is when somebody deciding what to tell the house is most likely to ask. Naming a device would let a surface show one row and call it the answer, and the row most worth reading is the one saying a device is poorly served and what to do instead.

/api/credentials takes none, and it is half a word on purpose. What it answers with is every credential the stack holds — what each is, what authenticates with it, where the value lives and where it stands, and each grant letting it cross to a third-party plugin (ARCH-R325) — and no value, because the shape it is built from has no field one could go in. The two things that can be asked of a line of it are not offered here at all: printing a credential over this door would put it through a browser’s cache, whatever proxy is between and the log each of them keeps, and replacing one is a write a request could be forged into making against the credential the stack is currently working on. Both are the terminal’s, in front of the person who typed the confirmation. A parameter narrowing the list would be a way to ask about one credential rather than the set, and the answer worth reading is the set — the credential worth knowing about is usually the one somebody had forgotten was there.

/api/space takes none, and the absence is the point. What it answers with is the account of where the disk went and an offer of what could be got back; there is no parameter choosing what to reclaim, because that choice is never a caller’s to make. A torrent still seeding is named with what removing it costs and left with the operator, and something the operator has already asked to be left alone is not on offer at any level of fullness — so a narrowing parameter would be a way to ask for exactly the two things nothing here will take.

The space action that answers the offer can be narrowed, and only within it: only names categories of what the offer says costs nothing, so an operator agrees to each one apart and never to a set chosen for them; anything the offer did not name is refused (ARCH-R289).

/api/bandwidth takes none, and the absence draws the same line the disk’s does. What it answers with is the account of the line: what it was measured to carry, what the stack is being held to, which side of the household’s day each download client says it is on, and whether each is actually keeping to what it was given. Declaring a limit is the action of the same name, at the door changes are asked for — a read that could set one would be a read that changes what everybody in the house experiences, which is the distinction the two doors exist to draw.

/api/uninstall takes one, and it is required in spirit rather than in shape: which of the four removals is being read. Naming none reads the one that removes nothing, because that is the safe reading and the one a browser opening the page has not chosen anything by; a word that names none of the four is refused rather than read as whichever the shape would default to, since on this subject the default that would hurt is the one that reaches the library. It is a read and never a removal — what it answers with is the listing every container, image and path a removal would take, and the action of the same name is where an answer to that listing goes. The two are one command read the same way twice, so what a browser agrees to is what it was shown.

/api/update takes one too, and it names the object rather than narrowing the answer: which of the two things that can be moved forward is being read — the services the stack runs, or lemonfiber itself. They are one command because moving something forward is one word an operator reaches for, and the object is the whole of what tells them apart; what=stack answers with what each service would move to, how large the step is, and which of the steps migrate state and so cannot be walked back, while what=self answers with where this copy stands and the exact command for whichever tool owns it. Naming none is refused rather than answered, and this is where it parts company with the removal above: that one has a reading that takes nothing, and here neither object is the smaller case of the other — a page that asked about the stack and was handed the binary has been answered a question it did not ask, and the two answers do not even resemble each other. Both are reads whichever is named. Nothing here replaces the binary at all, and moving the services is the action of the same name, where an answer to what the read listed goes.

/api/hosting takes none, because what is hosted is a property of the machine rather than of the caller. It answers with every long-running command that could be handed to this machine’s service manager and what became of each — installed or not, running or not, and where the words of a command with no terminal are being written. Naming one would let a surface show a single row and call it the answer, and the row worth reading is the one saying a guarantee the operator believes is in force is not.

/api/front-door takes none, because the question takes none: which one address the household is given is derived from what the stack runs rather than asked for, so a parameter here would be a way for one surface to be told a different door from another.

/api/requests answers with the household and what each member has asked for, the same document lemonfiber household --json writes. Each request carries what a member’s own screen needs to show it without asking anything else: the kind of title it is, the year that title came out, when it arrived on the media server, and the identifier the media server holds it under, which is the identifier /api/held names it by, so a request that has arrived can be found on the shelf. A value that cannot be known is left out rather than written as an empty one: the year until a request has been handed to the service that files it, and the arrival and the identifier until the title is on the media server (ARCH-R161).

/api/news takes none, because what is new is decided by whoever reads it rather than by the stack. It answers with the items a surface can mark as new, newest first within each kind: the releases in the stack’s record, each by its version; the household’s requests, each by its number; and the checks found wrong, each by its check and its onset (C1-R17). Each carries the stack’s own words for it. The stack keeps no record of what anybody has seen, because what one phone has seen is not what another has, and a stack that kept it would be keeping a person’s reading habits. lemonfiber news --json is the same document.

/api/bundle/{name} is the one read that does not answer with an envelope. It answers with the bundle itself, because a browser has no path on the host to be told and handing the file over is the only form --out can take on a screen. The name is resolved beneath the bundles directory rather than followed, so one carrying a path, or climbing out of that directory, is refused by name.

What is playing

GET /api/playing       GET /api/watching?…

The playing envelope lemonfiber playing --json prints: every session the media server is playing now, each naming the member watching and what they are watching, so how many are playing is read off the list rather than kept beside it. The operator, and a read or act key, are answered with every session. A member, and a key scoped to one, are answered with their own sessions and nobody else’s (ARCH-R156).

The narrowing is the command’s, not the reply’s. What runs names the member who asked, whatever the request named, as it does for the household row and the held shelf, so there is no path on which another member’s session is read and then left out.

What a member may ask for

GET /api/askable?…       GET /api/askable/{id}/poster?…       POST /api/actions/ask

/api/askable is a member’s search for titles the house does not hold yet, answered by the core under that member’s limits (D4-R15), as lemonfiber household search --json answers. It takes term, the words searched for, two to a hundred characters once trimmed and refused outside that as WISH-1; after, the place a previous page said the next one begins at, refused as WISH-2 where it is not one a page answered; and member, which the operator names and a member’s own request has replaced with themselves, as the held shelf does. A member, the operator and a key scoped to a member are answered; a read or an act key is not, because every search is a live question to the request service and to the catalogue behind it.

• Where the titles come from. The core asks whatever fills request.intake, over the contract where it speaks it and through the bundled adapter otherwise. The client asks the core and nothing else.
• Which kinds. The kinds a running curator can deliver now, decided by the core and named in the answer’s kinds (D4-R4, D4-R18). Nothing to fetch with is refused as WISH-4.
• Under whose limits. A title with no certification is looked up for the country the media server’s own rating table is named for, which identity.source answers as country; one still uncertified is held to the member’s unrated policy and is never let through by default (D4-R19, D8-R5). A title outside the member’s limits is left out, never shown as unavailable (D8-R9).
• One page at a time. A page holds the titles in the request service’s order and next, the place the following page begins, absent on the last; no title is on two pages of one search (D4-R17).
• What each title says. Its id, kind, title, year where known, and where it stands: here, partly-here, on-its-way or askable (D4-R5, D4-R10). No title carries the location of its artwork; the core serves that itself (D11-R10).
• What the member may ask for. Beside the titles, asking: what their period allows and has left of each kind and when it next frees up, as the household read says it, and approval, a household sentence saying whether what they ask for waits for whoever runs the house.

/api/askable/{id}/poster is the poster of a title a page offered, named by its id in the path and its kind as a parameter, with member as the search takes it and answered to the same callers. It answers bytes rather than an envelope, as the held shelf’s pictures do: an image/* body of at most 2 MiB marked Cache-Control: private (D11-R10). The core fetches it from the location the request service gave for that title, and only where that location lies beneath the one catalogue address the account of what leaves this machine names, over HTTPS, with no credentials, its host resolved and refused where it stands for a loopback, private or link-local address, and no redirect followed; the member’s client is never sent to the catalogue. A title outside the member’s limits is refused as WISH-3, as an ask is; one with no poster, a poster that is not a raster image or is larger, and an operator who switched posters off (LEMONFIBER_REACH_POSTERS, G8-R5) are answered as WISH-13.

ask takes id and kind, as a page of /api/askable named the title, seasons for a series (none names every season not already here or on its way, D4-R11), name, which the operator names and a member’s own request has replaced with themselves, and dry_run. It answers now, never with a job, in the asked envelope lemonfiber household ask --json writes (D4-R16, D4-R20):

• The rehearsal comes first. Under dry_run it checks everything the ask would and sends nothing, answering what the ask would leave of the member’s allowance in titles of each kind, never as a size (D7-R15), and whether it would wait for approval.
• The limits and the allowance are checked before the request service is asked. An id the member’s search could not have offered them, outside their limits or unknown, is refused as WISH-3, the same answer for both, so an ask reveals nothing a search would hide (D8-R9).
• One ask per title. A title already on its way is answered on-its-way and nothing is created (D4-R10); one already here is refused as WISH-5 (D4-R5). A title not out yet is asked for and says it will arrive once it is (D4-R6).
• What it answers. outcome is asked, waiting or on-its-way; leaves is what is left of each kind afterwards, absent for a kind nothing limits; said is the household sentence for all of it.
• Sent once. A client sends every ask with an Idempotency-Key, so an ask retried after no answer is carried out once (ARCH-R165).

Every refusal of any of the three carries a household sentence and a remedy beside its code, and names no service, size, address or state of the stack (G4-R16):

When a request is refused

The body of every refusal is the error envelope, the same one --json renders, and its problem’s code names why the request was refused. The status says which kind of refusal it is:

A status groups refusals; the code tells them apart. Four different facts share 403:

• The request carried nothing this run admits. Signing in again helps.
• It said it came from somewhere this server is not.
• The caller proved who they are, and this is not theirs.
• The media server could not say whether the caller is still anybody.

Each of these has its own remedy, and a client that read them from the status alone would offer one remedy for all four. So a client decides what a refusal means from its code. It never decides from the sentence, which is written for a person and may be reworded.

That sentence is plain text, and so is every other sentence the core sends a client: a refusal’s summary and remedy, a reason, a report, and the meaning and remedy each code carries in the registry. None carries markup. A name is written as the name, with no backticks or emphasis around it, so a client shows the sentence exactly as it arrives and no client has to render a markup language to be read correctly. A capability contract’s refusals and reasons are held to the same rule, because the core passes them on.

A code is one of the core’s problem codes. It is stable, never recycled, and listed with every other code the core raises. The artefact lists every code a refusal may carry, with the status each is answered with (the refusals it lists), so an SDK generates the list rather than copying it. A refusal carrying no code, or a code the client does not know, is read by its status alone. That is what a client meeting an older or a newer server can still rely on.

The line between the first two is what the request was for. A word this product does not explain is absent — the word is the whole of what /api/explain was asked for, and there is no entry — while a parameter left out, given twice, or given a value the surface does not offer is a request that could never have been answered as it stands. It is the same line the write surface already draws between an action name nothing answers to and an argument it cannot take, and the same reading ARCH-R72 makes of a job name this run never issued.

500 is reserved rather than incidental. A client told the machine failed will retry, and a client told that about a word with no entry retries forever; worse, one that cannot tell the two apart has to word a single message that is true of both, which is how “no entry” and “no answer” reach an operator as the same sentence.

Live state

GET /api/events        text/event-stream

The SSE event name is the envelope’s kind, and the payload is the envelope. Three properties are required rather than incidental:

It is the same gather. G1-R12 requires concurrent surfaces to agree, and two independent gathers are two chances to disagree — so the stream is fed by the gather that already serves the dashboard, not a second one built for the web.

A silent stream is distinguishable from a broken one. Without a heartbeat, “nothing has changed” and “the connection died twenty minutes ago” look identical to a client, which is the same confusion Reading::Stale exists to prevent one layer down.

A resumed stream does not lie about what it missed. On reconnect a client may hold values gathered before the gap. Those are Stale by definition, and must be presented as such rather than as current.

What is newest rides the stream, and the items do not. A news event names the newest few identifiers of each kind /api/news lists, when any of them changes and when a client connects. A surface that marks what is new can then say whether anything is, and how much, from the stream it already holds, and reads /api/news only on the screen that lists the items — rather than reading three answers for every stack on every frame of every screen to draw a mark on a tab.

An alert rides the stream as it happens. An alert event is sent when an alert starts and again when it resolves, carrying what the dashboard’s alert says: what happened, what it means for the household, what to do, how much it matters and which way it went. It also carries an identity that names the alert rather than the event, the same on an onset and on the resolution that ends it and different for the next time the same thing goes wrong, so a client can close what it opened without comparing sentences. A client connecting is not sent the alerts already said; the dashboard’s own list is where those are (ARCH-R162).

An alert names its notification kind, from a closed list. Beside its event kind, which is open and grows with every check, an alert carries notification: one of problem, completion, update, backup, request or member, the list the artefact publishes as a closed union. A new kind is a contract change. GET /api/alerts carries kinds, the ones this stack raises, so a client offers a switch for each of those and for nothing else (ARCH-R279, ARCH-R280, ADR-0047).

A resumed stream replays the alerts it missed. A stream opened with Last-Event-ID is sent every alert event raised after that id, oldest first, from the last 24 hours and at most the last 200, before anything else, so a phone the platform woke an hour later hears what was said while it slept. An id older than that is answered from the oldest kept, and the replay says partial so the client knows it missed some (ARCH-R281).

A phone can ask to be woken. A phone that cannot hold the stream while it is closed registers a UnifiedPush endpoint, and the core sends it a WebPush message, encrypted to the phone, on every alert’s onset and resolution, carrying nothing but that the stack has something to say. The phone then reads the stream over its own connection, so the distributor learns when a stack spoke and never what it said. The endpoints are the operator’s to see and remove, at the command line as here (ARCH-R282):

POST /api/push-endpoints        GET /api/push-endpoints        DELETE /api/push-endpoints/{name}

What is playing rides the stream. A playing event carries every session the media server is playing now, in the envelope GET /api/playing answers the same credential with, and it is sent again every 5 seconds, the pace a member’s stream sends what they are playing at. A client that shows what is playing, a home automation’s sensor among them, follows it from the stream it already holds rather than polling the read (ARCH-R178).

A line names the work that said it. A start, pull or step event said by work an accepting reply named carries that name as job, at the top of the envelope beside kind and data, and an event no job said carries none — a run at a terminal, the server starting:

{ "api_version": 1, "kind": "pull", "job": "9f2c1a7e04b3d815", "data": "Pulling sonarr" }

The name sits on the envelope rather than in data, so what a kind carries is the same whoever said it, and a client ties each line to the start, fetch or walk it asked for by the name the accepting reply gave it (B2-R19, D3-R14). The lines the container engine writes while pulling images are pull events, for a fetch and for a start that pulls, and the command line’s --json says them under the same kind (B2-R18, ARCH-R48). A start fetches the images it lacks before it starts anything and then starts with nothing left to fetch, so its pull lines all come before its start lines and a fetch that failed is said before anything was started. A pull line is state, as a start line is: a client connecting is given the newest, because the line says where the work has got to and a fetch says hundreds of them. A step is a record, because a step missed is a hole in the walk.

A member’s stream

The stream above is the operator’s view: the dashboard, the log lines, what setup is doing. None of it is narrowed to anybody, so it is never handed to a member. A member, and a key scoped to one, are admitted to a stream of their own instead. It carries their household row, their held shelf and what they are playing, each as the read that answers it answers that member, and nothing gathered for the operator (ARCH-R157).

It is the same stream in every other respect. It beats at the same interval, it resumes from the same event id, and a value gathered before a gap is stale on it as on the operator’s. It ends when the member is removed or their key is revoked, as the operator’s ends when the operator’s credential does (ARCH-R158).

Getting in

How a caller is admitted, by the per-run token, a session or an integration key, and the limit wrong answers meet, is on its own page.

Writing

POST /api/actions/<name>

Arguments mirror the command’s. G1-R1 requires every action to be available from every surface, and this contract adds the converse: the web API exposes nothing the CLI cannot do. An action that exists only here would be a behaviour implemented by a surface.

Long-running actions return a job identifier and report progress on the event stream, so a browser tab that closes mid-repair does not orphan the work. The identifier is redeemable — see a job’s outcome — because a name that cannot be turned back into an outcome makes the reply an acknowledgement rather than an answer.

Rehearsing

--dry-run is one flag over every command, and the core decides for each command how it answers it: a read runs as it always does, a command that changes something reports what it would do and changes nothing, and a command whose effect cannot be known without producing it refuses the flag with its reason — a walkthrough, a searching trace and the disruptive checks. An action takes the same request as the argument dry_run and answers it as its command does. A rehearsal writes nothing and answers with the envelope the command’s rehearsal renders, and that envelope says it was a rehearsal; an action whose command refuses the flag refuses the argument with the same reason (ARCH-R131).

The statement is required because nothing else on the wire can stand in for it. Several actions answer an unconfirmed request with a reading of what they would do, and that reading carries confirmed: false. So does a rehearsal of the same action. A client that inferred one from the other would label a rehearsal as a cost waiting to be agreed to, or a reading as something that had been tried and written nothing, and each is a different sentence to show somebody.

A plugin, and what fills a capability

POST /api/actions/plugin-install    POST /api/actions/plugin-update
POST /api/actions/plugin-remove     POST /api/actions/plugin-run
POST /api/actions/plugin-prove      POST /api/actions/wiring-fill
POST /api/actions/credentials-revoke

What is installed and what the stack wires to what are read as their commands answer them, GET /api/plugins and GET /api/wiring. A record or a wiring that cannot be read is refused with a code the artefact lists, and is never answered with an empty list: an empty list says nothing is installed, which is a different sentence from this could not be read (ARCH-R145).

The seven writes take what their commands take (ADR-0031):

The yes is the offer. Each rehearsal answers an offer built from what it read, and the write takes that offer, builds it again from what is there now, and refuses where the two differ, naming what moved. A bare confirm is no yes to any of the seven (ARCH-R146).

credentials-revoke ends one grant a third-party plugin holds, as lemonfiber credentials revoke does: the credential stops crossing to the plugin, whose services that read it restart, and the plugin stays installed (ARCH-R324). It is a write over a grant, not over a credential: it prints no value and replaces none, so it stays on this door while revealing and rotating a credential stay at the terminal. A grant is given only by the install or update offer that names it, through approved, as <setting>@<plugin> (ARCH-R323).

plugin-prove runs the plugin’s live proof again, as lemonfiber plugin prove does: a pass clears every nonconforming record the plugin holds, and a failure keeps them and names each case that failed (F14-R16, ARCH-R215).

A source is any the command takes: a catalogue name, a git repository or a path on the machine (ADR-0036). A git source is fetched over https from a public host; a name resolving to any address not out on the internet, as the plugin manifest contract classes addresses, is refused, every address it answers with checked when the fetch is made, the fetch connecting only to those, and no redirect followed (ARCH-R152). The rehearsal names the revision it fetched, and the offer is built from it.

A recipe runs on install or on demand, as its manifest says. An install recipe runs inside plugin-install and plugin-update; a demand recipe runs only through plugin-run, which names the plugin and the recipe. inputs carries each value a recipe asks the operator for, as name=value, on plugin-install, plugin-update and plugin-run alike. Until every one is given the act is refused as PLUGIN-34, naming each input missing, so a client can ask the operator for exactly those; one no recipe of that act asks for is refused the same way, naming it. An input is never part of the offer and is never repeated back.

What a recipe would send is agreed to as itself. A rehearsal whose recipe would carry a value to an external host lists each pair: the value’s name, where it comes from, and the destination by name, never a resolved address. The write takes the approval of each pair in approved, apart from offer, and refuses where one is missing; the offer still covers the list, so a pair that changed is refused as a moved offer (ARCH-R147). A pair releasing a value a service of the stack answered with is agreed to the same way, and the rehearsal lists it with its release, the sentence the manifest gives for carrying the value away from that service, and its from, the service it was read from (F8-R18). Any other pair to a service in the stack is listed too and carries no approval: what it carries neither leaves the machine nor leaves the service it came from, so there is nothing to agree to, and an approval written for it is refused as one no pair asks for. An approval is given to the act that carries it and to no other: a pair approved at install is asked for again by a demand recipe that carries it, and by each run of it. The rehearsal lists the recipe’s steps in order and names each adapter as lemonfiber’s (ARCH-R148), and a call refused because an external name answered from inside the network ends with a code of its own, apart from a network that failed (ARCH-R149). Every recipe, pair, destination and adapter field is present on a rehearsal and on the record, an empty list where there is none, so none is never confused with not read; a pair’s approval is present exactly where the pair leaves the machine or carries a release, and its release and from exactly where it carries one (ARCH-R150).

The installed plugins and the wiring each ride the event stream as their envelope: a plugins event and a wiring event, sent when a client connects and whenever either changes, an install that leaves a capability contested included (ARCH-R151).

Browsing what the catalogue offers is GET /api/plugins/catalogue, answered from the verified index as lemonfiber plugin catalogue --json answers it, and listing nothing the index’s signature does not cover (ARCH-R153).

Settings

POST /api/actions/settings-set      POST /api/actions/settings-clear

A setting is a value a service’s environment reads from the operator rather than from its manifest: one the core publishes for every service, such as the operator’s domain, or one in a plugin’s own namespace, such as the countries an egress guard may exit from (plugin-manifest). The settings live in the core’s settings store, and GET /api/settings reads them as lemonfiber settings --json does. Each setting carries its name; whose it is, the core’s or a plugin’s; each service that reads it and the variable it is read into; the default its manifest declares; and the operator’s value where one is recorded, so a value still at its default is told apart from one somebody set to the same text (ARCH-R254).

The same read lists each secret a service’s environment names, with whose it is, the services that read it, where its value came from (the operator, a recipe or a granted credential) and whether one is held. It never carries the value: the shape it is built from has no field one could go in, as the credentials read has none (ARCH-R256).

Only the operator is answered. A member, a key scoped to one, and a read or an act key are refused, because a setting is how the machine is run and the household never sees it.

The core’s own settings are a closed list, and this is it. Beside the settings a service’s environment reads, the settings store holds the ones the core itself reads, each read back as the core’s:

Every other LEMONFIBER_* key is lemonfiber config’s, read by GET /api/config. Each command refuses the other’s names, naming the command that takes the name, so one name has one writer (ARCH-R278).

The two writes take what lemonfiber settings set and lemonfiber settings clear take:

settings-clear takes the operator’s value away, so the declared default is written again. Each rehearsal names every entry the change regenerates and every service it restarts, and answers an offer; the write takes that offer and refuses where what it would change moved since, naming what moved, as the plugin writes do (ARCH-R146). Each write is journalled (ARCH-R255). A value is written as exactly itself: nothing in it is substituted (ARCH-R230).

A secret is not written here. A secret a manifest names is entered as an input of the install or update that first needs it, never repeated back, and is replaced afterwards at the terminal, as every credential is (ADR-0031). Naming a secret to either write is refused, naming it (ARCH-R256).

The settings ride the operator’s event stream as their envelope, a settings event, sent when a client connects and whenever one changes, and only to the operator, by the per-run token or an operator session: never on a member’s stream and never to a key of any scope, so the stream tells nobody what the read refuses them (ARCH-R257).

Setting up

GET  /api/setup            POST /api/setup/answer     POST /api/setup/next
POST /api/setup/back       POST /api/setup/apply      POST /api/setup/recover

Named for the walk rather than for a command, because a wizard is one request read many times: what it is standing on, an answer to that, and the movement between. apply is where it stops asking and writes, and recover is what an apply that stopped part-way is answered with — offered after the report has named what that apply had already written, so the choice is made by somebody who has seen it.

These are writes and sit behind the same guard as the actions above. They are named here because the first-run walk is where credentials are entered, and an endpoint that takes one and is written down nowhere is the one nobody audits.

What a stack says it can do

GET /api/capabilities

Every other surface runs on the machine the stack runs on, so it is the same version by construction and never has to ask. A client on a phone is the first that can be older or newer than what it is talking to, and the first that can hold several stacks at once, each at a different version (N1-R11).

A version number does not answer the question. GET /api/version says which binary is running; turning that into what this stack can do means a client carrying a table of which release added which feature — a second copy of the changelog, on a different release cadence, in a different repository. It goes wrong quietly: a client meeting a version its table does not know either offers an action that fails when pressed, or hides one that works.

So the stack declares what it can do, and the client reads it rather than deduces it.

The payload is kind: "capabilities", whose data maps a capability name to its state:

{ "api_version": 1, "kind": "capabilities",
  "data": { "capabilities": {
      "/api/plugins":             "available",
      "/api/actions/wiring-fill": "available",
      "/api/actions/pull":        "unconfigured",
      "/api/actions/invite":      "unpermitted" } } }

A capability’s name is the path the surface serves the request at: /api/actions/<name> for an action and /api/<name> for a read. The set is generated from the lists the surface routes by, so a request the surface gains is a capability it declares with nothing else to keep in step, and a client already holds these names, because they are what it calls. A read and an action may share a word, and they are two requests — reading what an uninstall would take is not taking it — so each has a key of its own. What a client shows for one is its own words and not the stack’s.

Four answers, and the difference between them is the whole point — each is a different sentence to show somebody:

Absence is the answer for a stack that is too old, and it needs no coordination: a stack that has never heard of a capability cannot name it, so a client meeting an older stack sees the same thing it would see if the capability were removed. That is why the shape is a map of what is rather than a list of flags, and why a client must treat an unknown key as something it does not understand rather than as an error.

The set is scoped to the credential, not only to the stack. What a household member may do is already the core’s answer (D6, N3-R2), so a capability set that ignored who was asking would be a second permission model — the thing N3-R2 exists to prevent. unpermitted is how that answer arrives, and it is deliberately distinguishable from unconfigured, because “you may not” and “nobody has set this up” are not the same news.

It says which stack is answering. Beside the capabilities the data carries stack, the stack’s own identifier: the one pairing material carries (N1-R62), minted once and kept, the same across a change of address and a replacement of the certificate. A client holding several stacks, or meeting one again at a new address, tells them apart by it. Neither the address nor the certificate’s fingerprint can serve, because each changes in exactly the cases a client most needs to recognise the machine, and the envelope’s host names the machine an answer is about rather than the stack giving it. It is carried to every credential that may read the capabilities, a member’s key included, because recognising a stack is not something a credential’s scope can make anybody unentitled to (ARCH-R163).

It says whose credential asked. The data carries scope: operator, read, act or member. A client that words itself for the household, or decides what to offer, reads the scope from it rather than inferring it from which reads came back permitted, because a read permitted to two scopes says nothing about which one is asking, and the set of reads a scope admits can grow (ARCH-R179).

It is read, not pushed, and it can change under a client. Configuring storage turns snapshots from unconfigured to available without the session ending. So it is an ordinary read: it carries the age every other reading carries (N1-R9), a client may retain it and paint from it (ADR-0019), and a client that has not re-read it lately is holding an opinion rather than a fact.

A capability is not a promise the action will succeed. It says the action is offerable. A repair may still be refused on its own terms, and that refusal is G4’s business, not this endpoint’s.

What guards it

A writable API on loopback is reachable from any page the operator happens to visit — a page cannot read a cross-origin response, but it can send a request the server acts on, and DNS rebinding defeats a naive origin check. The CLI never had this exposure; nothing a web page does reaches argv.

The token travels in a header. Never a query parameter: URLs reach logs, history and referrers, and a credential that leaks into any of those has leaked.

Version skew

The client declares the api_version it speaks. Because the built app is embedded from a pinned submodule (ADR-0012), build.rs validates that declaration against the binary at compile time — the same protection ARCH-R6 already gives the embedded stack’s schema_version. A mismatched pair cannot be released.

The runtime check remains, because a browser may hold a cached older app. A mismatch there refuses plainly and says which versions are involved, rather than rendering a page whose fields have quietly changed meaning.

The details two clients must agree on

The particulars two clients must agree on to talk to the same server — the token’s header, the address, the heartbeat, resuming the stream, a job’s outcome, an action sent again, the payload’s type and how an instant is written — are on their own page.

Requirements

The artefact

The shapes the surface exchanges are generated from the server’s own types into one artefact every SDK consumes. What it carries, the refusals it lists and how it reaches an SDK are on their own page.

Related

• web-api-artefact — the generated artefact, and how it reaches an SDK
• web-api-getting-in — how a caller is admitted
• web-api-wire — the particulars two clients must agree on, instants included
• sdk-ts — the TypeScript client implementing this contract
• versioning.md — api_version and the envelope it belongs to
• design-tokens.md — the other contract lemonfiber-web consumes
• ADR-0011 — why the boundary is a contract
• ADR-0012 — how the built client reaches a machine
• C6 — the security policy this sits inside