What the wire carries that the companion does not read

Status: Register · Measured 28 September 2026, against the companion at dab906bd and the core at 950df25b

The stack publishes sixty-two envelopes and serves fifty-seven. The companion app follows thirty-nine of them. This is the other twenty-three, written down so that what fills them is a decision somebody made rather than whatever the next person happened to notice.

Five of the sixty-two are published and not served. They are not envelopes the app has not got to; they are envelopes it cannot reach. Three have a heading of their own below, setup is marked so under Guided setup, and the fifth, pull, is a line of the command line’s own, said in the next section.

It is a register of facts, not of requirements. No row here proposes a screen. N1-R17 is the rule that matters: a field wants a requirement before it wants a surface, and a surface built because the wire happens to carry a field is a surface nobody asked for. Every row is an invitation to decide, and no requirement asks for this remains a complete answer.

How it was measured

Reproducible, from the companion’s checkout:

ls vendor/lemonfiber/sdk-php/src/Generated/*Envelope.php | wc -l                 # 62
Tests\Support\WhatTheReadersRead::envelopes()                                    # 39
git grep -lw '<Name>Envelope' -- app-modules bridge/src ':!*/tests/*'            # 40 of the 62 names

The companion measures the same thing and states it. Its tests/Feature/EveryActionTheStackOffersTest.php puts every kind the SDK ships in one of three lists: OFFERED, held to exactly the envelopes WhatTheReadersRead::envelopes() answers with, which is thirty-nine; ELSEWHERE, Setup and Wizard, each excused by N1-R4; and NOT_YET, the other twenty-one. Its .docs/requirements/what-a-screen-owes.md says 62, 39, 21 and 2, and that test holds the page to what the lists come to. This register counts the same way and agrees with it: named means named in a file under app-modules or bridge/src outside a tests directory.

The grep answers forty names rather than forty-one, because Log is followed without being named: a log window arrives through the SDK’s LogWindow, held in its envelopes, and WhatTheReadersRead seats the reads on it all the same. Three of the twenty-one are named by tests and by nothing the app ships: Start and Wiring by the app’s root test suite, and Word by a test of the development stand-in, under app-modules/dx/tests.

Admission and Pull are the two named without being followed. The app reads admission through Admitted rather than through the envelope, and its code names AdmissionEnvelope only in the development stand-in that answers for a stack. Pull carries a bare string, and is named in that stand-in’s comments. Word is what /api/explain answers with when one word is asked for: the app asks for the whole glossary, which answers with Glossary. Word has a row below; Admission and Pull have none, and these sentences are their entry.

From the core’s checkout, contract/web-api/ publishes sixty-two kinds. Fifty-three are the variants of Outcome, in crates/lemonfiber-core/src/app/outcome.rs, each written by the command that produces it; the other nine are written with Envelope::new where they arise. A kind is served when crates/lemonfiber-api answers with it: through a command its reads (read/table.rs), its actions (actions/named.rs) or setup’s endpoints (setup.rs) build, or an envelope it writes itself — admission, error, job and log, and on the event stream dashboard, start and step.

plugins, wiring and substitution are not served because no read, action or endpoint builds Command::Plugins or Command::Wiring. pull and setup are written only by the command line, in crates/lemonfiber/src/engine.rs and crates/lemonfiber/src/setup.rs; the HTTP crate names both only to describe them in the contract, and setup’s endpoints answer with wizard.

pull is the command line’s alone. Its bare strings are the lines docker compose pull prints, which the command line writes under that kind as they arrive. No read, action or event produces it over HTTP: the pull action answers with a job whose outcome is lifecycle, and nothing is said on the event stream while it runs. N2-R24 asks the app to offer the fetch, and N2 records the progress that does not reach it.

What the thirty-nine answer

Each is followed by a reader in app-modules/sdk. The requirements are the rows in the companion’s .docs/requirements/ that name the envelope, its reader, or what that reader builds. The last column counts the envelope’s rows in WhatTheContractCarriesThatNothingReadsTest: each is a path the app has decided not to read, with the reason.

Held is the shelf a member sees, drawn by the household module’s WhatYouCanWatch. The one row that names it is N3-R14, which it does not answer: that requirement is about a player, and the companion records the player as not built.

Error is read as the kernel’s Problem — code, severity, state, meaning and remedies — and a severity outside the four G4-R2 defines is refused rather than read. Its detail, cause and each remedy’s detail are the three unread rows.

Bandwidth’s eleven are applied, which a reading that never writes always answers the same way; clients, a surface of its own; metered, which belongs beside the cap with its exclusions said; respite and respite_says, the override’s countdown; rhythm and zone, the household’s hours, which are a setting; and per direction limit and resolved, which the says sentence already carries.

Alerts’ two are changed and rehearsed. Only a call that changes the setting answers them otherwise, and this app makes none, which is also why N10-R9, a rehearsed alert, is not drawn.

Hosting’s three are caveat, and per command definition and runs.

History does not answer N11-R4, the reason a change was made: the envelope carries no such field, because the stack’s journal records none, and because is why putting a change back stops short rather than why it was made.

Config, Doctor and Outbound carry the same origin on each setting, each finding and each service: bundled, operator, a named plugin, a named plugin’s override with the value it replaced, a value a removed plugin left, or unknown with the stack’s reason. Its eight paths on each of the three are read, into one type, and shown. A setting says its origin on every row. A check or a service says it only where it is not the stack’s own, with one line under the list saying what an unmarked row is, which is how the stack’s own terminal draws them. An origin that cannot be read refuses the reading rather than defaulting to bundled (F7-R11).

What watches the envelopes

The companion has a machine-checked register for unread fields, WhatTheContractCarriesThatNothingReadsTest, and its rule is that every path on an envelope the app reads is either followed to a reader or listed with a reason. A hundred and forty-three rows, over the one thousand and twenty-seven paths the contract declares on the thirty-nine envelopes the app reads.

It cannot see any of the twenty-three, and the reason is one line of its own scaffolding:

foreach (WhatTheReadersRead::envelopes() as $envelope) {

It walks the envelopes a reader already reads. An envelope nothing touches contributes no paths, so it can never be flagged — the blind spot is exactly the shape of the gap. The rule watches fields arriving on envelopes the app already knows about.

Whole envelopes are held by EveryActionTheStackOffersTest, which names every kind in one of its three lists, so a kind the stack adds fails there as unclassified. NOT_YET claims only that somebody looked: it carries no reason and no account of what the envelope holds. This register is that account.

---

Connecting it together

The surface that lets an operator wire the stack up. The app draws none of it. Its kernel holds the types a wiring would be read into, recorded in the companion’s connecting-the-stack.md.

Three of these are not served at all. wiring, substitution and plugins are published in the contract and generated into the SDK, and no HTTP route or action produces any of them. Nothing under lemonfiber-api’s src names any of them. Its read table, read/table.rs, declares every read it serves, with catalogue, forms and alerts among them and none of these three. The single action route accepts only the names in actions/named.rs’s OFFERED — forty of them, and not one is a plugin, wiring or substitute verb — so an action outside that list is refused before a command is built. Recorded in lemonfiber#731, which is open.

The kind exists because the command line produces it, which is why the generated surface lists it. contract/web-api-surface/index.json maps every kind to its type, including these three, and that file is not evidence of a route. Outcome::Plugins is produced by Command::Plugins, which the core and the command line run; nothing on the HTTP surface asks for it. A register that read the surface map would call this served, and be wrong.

The plugin lifecycle plugins reports on is built at the command line: installing, rehearsing, updating and removing are plain subcommands (F6-R13), and an unmet capability is refused by name (F6-R10). wiring and substitution each have a settled report in the core, and Command::Wiring produces Outcome::Wiring from the command line. What all three lack is a route.

Serving them is required, and scheduled. F6-R14 requires what is installed to be a read of the web API, F6-R15 requires installing, updating and removing a plugin to be actions of it, and F6-R16 requires each of those to be rehearsable there. F4-R26 requires the wiring to be a read, F4-R27 requires choosing which service fills a capability to be an action, and F4-R28 requires that choice to be rehearsable. 0.18.0, which is planned, locks all six as goals, with F4-R29, which gives the choice an optional reason on both surfaces.

So they are a different kind of row from everything else here. Every other envelope in this register is a decision waiting to be made, or, for setup and wizard, one N1-R4 has made; these three have no decision about the companion that can reach them while no route serves them. The companion records the same for N5: N5-R2, N5-R4, N5-R7, N5-R10, N5-R11 and N5-R13 cannot be answered there until a read exists.

The wiring row names a choice nothing can make. The core will not resolve a contested capability — the command line says nothing wires to it until the operator chooses, and lemonfiber does not choose by install order. The contract models that choice, down to whose: 'operator'.

There is nowhere in the companion to make that choice, and nowhere on the wire to read that it is waiting. F4-R26 requires the read that says it is waiting, and F4-R27 the action that makes it: for a contested capability too, recorded and journalled as the command records it, and read back as the operator’s, with their reason where they gave one (F4-R29).

Guided setup

The companion excuses setup and wizard under N1-R4: setup is performed at the machine, and the app says so rather than offering it.

Putting things back

Copies are read: archives, backup and restore, above. These two put the stack back without one.

Moving in

The survey of what is already on the machine, migration, is read, drawn by WhatIsAlreadyOnThisMachine. These are the acts, and the companion records N7-R1 to N7-R4, carrying out a mode, and N7-R7 to N7-R10 and N7-R15 to N7-R17, the seed action, as asked for and not drawn.

A service’s life

Household and access