jochen
6e3373c879
0113 — the plaintext claim was false under its own mechanism: handing a provider's answer to the controller puts every secret on the broker and in the controller in the clear. The provider now seals each secret field itself, to the consumer node's public key the mesh hands it, and the controller carries sealed fields it cannot open. That is stricter than today, where the controller holds every minted credential in the clear. Option 3 (plaintext to the controller) is recorded and rejected. The foundation exception now covers root-secret rotation (0085) and forms like the broker admin's hash, so no phase claims to remove the broker's bootstrap step. To-be 24 and 13 are named among what it amends. 27 — resolution is consistent with 0110: co-location and the only provider apply only where no seat delivers the provision, so an unheld seat is refused even with one provider. The secret-field rule now matches 0086 exactly (a declared env-file, never a container environment value). The seat placeholder is the controller's, and the one module reading it moves to a host port. Contracts are held by the controller and written down in phase 1, so they can be checked; every rule has a check. An operator's secret is still the operator's, with the vault as custodian. Which seats a module holds is listed as not settled. 0110 — the unheld-seat-with-one-provider case and the one-answer-for-everyone rule have checks; the claim about moved manifests is corrected. 26 — the table governs and the code catches up, not the reverse; scope and capacity agree with the glossary; moving a seat is described as it really is today. 0112 — aligned with 27, and lists 0049 and 26 among what it changes. Issue 118 is renumbered 119: another branch took 118 first. 'Control-plane' is gone from 0110 and 0111.
15 KiB
layer, status, code, updated, decisions
| layer | status | code | updated | decisions | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| to-be | proposed | 2026-09-25 |
|
27 — A module requires, the mesh resolves
One concept for everything a module needs. A module definition states what it requires. Each requirement has a contract and a kind of provider. Installing the module on a node resolves every requirement, or refuses and says why. Nothing else reaches a module: no path it chose, no setting beside the model, no literal it carries.
This replaces six mechanisms that grew separately: provisions read through bindings, settings, assigned ports, machine facts, minted or accepted secrets, and literals in the definition. Each resolved, validated and failed in its own way (ADR 0112, issue 119).
A requirement
A requirement has three parts:
| part | is |
|---|---|
| name | what the module calls it, unique within the module |
| contract | the fields the module may read, and what each promises: a type, whether it is secret, and anything the provider must honour |
| provider kind | which of the four kinds of provider answers it |
A contract is shared, not per module. A database's contract is the database's, whoever requires it. The controller holds every contract, one per provision name, declared where the provision is defined in the catalogue. Today contracts are implicit in each provider's served fields; the first phase below makes them explicit, because nothing can be checked against a contract that is not written down. A provider is checked against the contract it claims to answer. A module's own specification may narrow a contract (a password of at least this length, a directory owned by this user) and never widen it.
The four kinds of provider
The set is closed, like the seats. A fifth kind is a decision, because each kind is a place an answer can come from and a reviewer has to know every one.
| provider | answers | resolved by | replaces |
|---|---|---|---|
| a module | a database, a bucket, a vhost, a route, a secret | the rule below | provisions and bindings |
| the node's host | a directory, a port, a fact about the machine | always the module's own node | resource paths, assigned ports, machine placeholders, facts |
| the mesh | the module's identity and names, and the delivery of every answer | the controller | derived logins and generated names; the controller's delivery |
| the operator | a value a person chooses | the assignment, else the requirement's default | settings, carried literals |
A module provider
Which module answers, in order:
- a pin: the assignment names a provider, because this consumer is coupled to that provider's contents (ADR 0084);
- the holder of a seat that delivers the provision, where one does. Co-location does not apply to these: the seat is the mesh's one answer for everyone (ADR 0110, 26 — The seats);
- for a provision no seat delivers, the provider on the consumer's own node;
- for a provision no seat delivers, the only provider in the mesh;
- otherwise refused: naming the unheld seat, for a provision a seat delivers, even when exactly one provider exists; naming the candidates otherwise.
The provider makes what it provides and answers with its contract's fields. The mesh carries the
answer back to the consumer, sealing every secret field to the consumer's node
(ADR 0113). The vault
is a module provider like any other: it holds the mesh-vault seat and generates the secrets it
provides.
The node's host
The host answers what only a machine can: where a directory is, which port is free, what the machine is. It is always the module's own node, because none of these means anything elsewhere.
A directory. The contract is an owner and a mode, and the owner the image expects where it has one. There is no persistence flag. A directory is kept while it holds anything, and data that may be lost is a named volume, not a directory (ADR 0030, ADR 0107).
Where a directory is on the machine is the assignment's:
- a node's default layout, a root per node with one directory per instance beneath it, used when the assignment says nothing;
- a placement, where the assignment puts one directory elsewhere: on a second disk, or where an adopted machine's data already is (ADR 0100).
An operator's shared data is an access, as before (ADR 0051): never created, owned or removed by the mesh. The module requires read or read-write access. Where the data is, is an operator value on the assignment.
A port is what ADR 0038 already decided: the module says which port its software uses, and the host answers with where the machine put it.
A fact is something the machine knows: its name on the private network, the names of the mesh's machines. Each fact has a contract like anything else.
The mesh
The mesh answers who the module is: its login, its broker account, the names it is known by. These are derived by the mesh so every party agrees by construction, and no provider may make them (ADR 0049).
The operator
A value a person chooses: a public name for an endpoint, a greeting, how many workers to run.
It must stay cheap. An operator requirement's contract is a type and, optionally, a default. It needs no provider module, no grant and no credential. If asking a person for a value took more than that, module authors would route around it, and the literals this replaces would come back.
A secret operator value, such as an external API key, is still an operator requirement: its provider is the operator. What differs is where it is kept. The vault holds it as an operator-delivered value (ADR 0092), never as a setting, because anything secret belongs in one place that can seal and audit it. The vault is its custodian, not its provider.
An endpoint is an operator value inside a route requirement: the public name is chosen on the assignment, and the route provider answers. A public name already held by another assignment is refused, like any other singular thing.
How a definition reads what was resolved
One form, naming a requirement and a field of its contract. A definition that needs the database's host in an environment variable, the directory's location on the host side of a mount, or the public name in a configuration file writes the same thing: the requirement's name and the field. The controller fills it at resolution.
This one form replaces the placeholders that exist today, one per mechanism: bound values, secrets, ports and machine facts.
The seat placeholder stays, for the controller alone. The controller composes its own declaration and reaches the store and broker it made before any module existed, so it cannot be their consumer. One module reads the placeholder today: the store module, to find its own server's port. That is its own port, so it becomes a host port requirement in phase 3, and after that no module uses the seat placeholder.
A secret field reaches a process as a file, as ADR 0086 decided. The one exception 0086 allows is a declared env-file with its reason; a secret field as a value in a container's environment is refused when the definition is parsed, with no exception.
An instance
An assignment has an identity: an instance name, which defaults to the module's name. Everything keyed by the module's name today is keyed by the instance: directories, containers, the login it presents, its broker account, the seats it holds, its settings and its identity as a provider.
So a module may run twice on one node, under two instance names. What must stay singular stays so: by a seat, or by an operator value colliding, as with a public name.
A login still has to fit the tightest backend, which is twenty characters today (ADR 0049). A node name and an instance name will not fit in full. The instance therefore gets a short form alongside the module's slug, under the same rules as a slug. This has to be settled before a second instance is allowed.
Genesis
The one exception. Before any provider exists, genesis answers the foundation's own requirements itself: the store's and broker's credentials, the vault's own access, and the root secrets. It seals them to the operator key as it does now (ADR 0085). After genesis, nothing is answered except by a provider.
Refusing
Installation refuses when any requirement is unresolved, and says everything at once. For each requirement it names what is missing and what would answer it:
- an unheld seat, and which modules could hold it;
- no provider, and which modules could provide it;
- an operator value with no default, and that the assignment must give it;
- a provider that has not answered yet, and which one.
The last one is a state, not a failure. A consumer waiting for its provider is shown as waiting, and nothing is delivered until the answer arrives (ADR 0113).
What this retires
| mechanism | becomes |
|---|---|
| provisions read through bindings | a module requirement; its answer is the contract's fields |
| settings on an assignment (ADR 0046) | operator requirements, addressed to an instance |
| a port the mesh assigns | a host requirement |
| machine facts and machine placeholders | host requirements |
| a secret the controller mints | a secret the vault makes (ADR 0113) |
| paths in resources, mounts, bindings, secrets and received files | host directory requirements, placed by the assignment |
| literals carried in a definition | operator requirements with defaults |
Each is retired only once nothing uses it. Until then both are accepted, and a catalogue test lists the definitions still using the old form. That list shrinks to empty, and then the old form is removed from the parser.
Phases
Each phase ends at a check that holds, so none of them leaves a mechanism half-replaced.
- Contracts, resolution and the new form. Every provision's contract is written down and held by the controller. The controller resolves requirements from the four providers, refuses as above, and fills the one form. Old mechanisms keep working beside it. Ends when a definition written entirely in the new form installs on a lab machine.
- Providers answer. The SDK harness answers with contract fields and seals the secret ones, the controller carries answers back, and the vault holds its seat and generates. Ends when the analytics and DNS providers answer their consumers, and a module's own secret is generated by the vault and rotated by it.
- Definitions move. Every catalogue definition is rewritten, adopted and running assignments placed where their data already is. Ends when the list of definitions using an old form is empty, and the old forms are removed.
- Instances. The instance name and its short form, and everything keyed by it. Ends when one module runs twice on one lab machine with two public names.
How it is checked
| Rule | Checked by |
|---|---|
| Every requirement has one of the four provider kinds | The parser refuses any other. |
| A definition names no host path, node or mesh | The catalogue tests of ADR 0112. |
| A module provider is chosen by pin, seat, co-location, only one, refusal | Resolution tests for each step; for a second provider on a consumer's own machine when a seat delivers the provision; and for an unheld seat with exactly one provider, refused. |
| A provider answers within its contract | A controller test: an answer carrying a field its contract does not name, or missing one it does, is refused and not delivered. |
| A module narrows a contract and never widens it | The parser refuses a module specification that loosens a contract's field. |
| A host requirement is answered on its own node | A resolution test placing one elsewhere: refused. |
| An operator value needs no provider module | A resolution test: a requirement with a default resolves with no module assigned anywhere. |
| A secret field reaches a process as a file | The parser refuses a secret field as a container environment value, and accepts it in a file or a declared env-file with its reason. |
| A public name already held is refused | A resolution test: a second instance asking for a public name the first holds is refused, naming the first. |
| Everything keyed by a module is keyed by its instance | A resolution test: two instances of one module on one node get two directories, two containers, two logins and separate settings. |
| A consumer waits for its provider | A resolution test with a provider that has not answered: shown as waiting, and nothing delivered. |
| Refusal names everything at once | A resolution test with three unresolved requirements of different kinds: one refusal naming all three. |
| The old forms retire | The catalogue test listing definitions still using one. It must be empty before a form is removed. |
Not settled here
- The exact spelling of the one form. It must name a requirement and a field and nothing else.
- The layout a node's default root uses beneath it, beyond one directory per instance.
- Whether a module provider's answer can change without the provider being asked, for example a provider moving. The rule so far is that it cannot, and moving is re-resolving.
- Which seats a module holds. Today a claim is part of the definition, so moving a seat is a definition change (26 — The seats). By this document's own logic it belongs to the assignment: a definition says which seats a module can hold, and the assignment says which it does. That changes ADR 0110, and is its own decision.