novox/hq
3
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Design pass: address the review

Browse Source 
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.
This commit is contained in:
jochen
2026-09-25 22:46:10 +02:00
parent aad92ea8fe
commit 6e3373c879
7 changed files with 128 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/26-the-seats.md
+19 -9
View File
@@ -28,7 +28,7 @@ A seat has four properties, fixed by the mesh rather than by any module:
| property | is |
|---|---|
| name | what a manifest claims, and what a person reads in the list |
| scope | node, site or mesh: where there may be only one holder |
| scope | node, site or mesh: where its capacity applies. Every seat in the set has a capacity of one, so one holder per scope. A bench, a seat with several holders, is a word the glossary keeps and no seat uses yet |
| delivers | the provision its holder answers for, or nothing |
| decision | the record that made it a seat |
@@ -63,8 +63,10 @@ argued for is an entry nobody can explain.
| `the-showcase` | node | — | the showcase module |
The controller holds this set in code, and a test asserts both its size and that every entry names
the record that made it a seat. This document follows the code, not the reverse. If the two disagree,
the test has been changed without this table, and the table is what is wrong.
the record that made it a seat. **This table and [ADR 0110](../../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md)
govern, and code that disagrees is what is wrong.** The implementation in progress predates two
things here: the `mesh-vault` seat, and the rule that `mesh-store` and `mesh-broker` deliver
nothing. It is brought to this table before it merges.
## A seat that delivers a provision
@@ -89,14 +91,22 @@ one is the mesh's, and co-location answering first would let any second provider
machine take over for that consumer, silently. So a second provider can run beside the holder and
harm nothing. The forge holds
`npm-package-registry`. An npm proxy may provide the same provision on another machine, and a module
requiring an npm registry is still served by the forge, without anybody pinning it. Moving the role
to the proxy is moving the seat: unassign the claim from one, assign it to the other, and every
consumer follows.
requiring an npm registry is still served by the forge, without anybody pinning it.
**Moving the role is changing which module claims the seat, and today that is a definition change.**
A claim is part of a module's definition, so the proxy's definition must claim the seat and the
forge's must stop. The forge cannot simply be unassigned, because it holds `git` as well. Every
consumer follows once the claim moves. Making *which* seats a module holds the assignment's choice,
with the definition saying only which seats it *can* hold, is the consistent answer, and
[27 — A module requires, the mesh resolves](27-a-module-requires-the-mesh-resolves.md) lists it as
not yet settled.
**What a consumer receives is a grant**, the same as for any provision: where the provider answers,
what it serves, and a credential where one is minted. A consumer never reads the seat directly. The
one exception is the controller itself, which reaches the store and the broker through a narrow
seat placeholder because it made them before any module existed and cannot be their consumer.
what it serves, and a credential. A consumer never reads the seat directly. The one exception is the
controller itself, which reaches the store and the broker through a narrow seat placeholder,
because it made them before any module existed and cannot be their consumer. One foundation module
also reads it today, to find its own server's port. [27](27-a-module-requires-the-mesh-resolves.md)
moves that to a host port requirement.
## A seat that delivers nothing
03-DESIGN/01-to-be/27-a-module-requires-the-mesh-resolves.md
+47 -27
View File
@@ -23,7 +23,7 @@ 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](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md),
[issue 118](../../04-ISSUES/118-a-module-definition-decides-where-its-files-live/00-report.md)).
[issue 119](../../04-ISSUES/119-a-module-definition-decides-where-its-files-live/00-report.md)).
## A requirement
@@ -36,9 +36,12 @@ A requirement has three parts:
| 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 mesh knows each contract, and a provider is checked against the one 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.
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
@@ -49,7 +52,7 @@ can come from and a reviewer has to know every one.
|---|---|---|---|
| **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 | the controller | derived logins, generated names |
| **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
@@ -61,9 +64,10 @@ Which module answers, in order:
2. **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](../../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md),
[26 — The seats](26-the-seats.md));
3. **the provider on the consumer's own node**, for a provision no seat delivers;
4. **the only provider** in the mesh;
5. otherwise **refused**, naming the candidates, or the unheld seat.
3. for a provision no seat delivers, **the provider on the consumer's own node**;
4. for a provision no seat delivers, **the only provider** in the mesh;
5. 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
@@ -112,9 +116,11 @@ A value a person chooses: a public name for an endpoint, a greeting, how many wo
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 held by the vault as an
**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](../../02-DECISIONS/0092-an-operator-delivers-a-pair-credential.md)),
never stored as a setting.
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
@@ -128,13 +134,17 @@ name in a configuration file writes the same thing: the requirement's name and t
controller fills it at resolution.
This one form replaces the placeholders that exist today, one per mechanism: bound values, secrets,
ports, machine facts and seats. The seat placeholder the controller uses to reach its own foundation
stays, because the controller cannot be a consumer of a foundation it made before any module
existed. It is the controller's own and no module uses it.
ports and machine facts.
**A secret field reaches a process as a file**, as today ([ADR 0086](../../02-DECISIONS/0086-a-secret-reaches-a-process-as-a-file.md)).
Reading one into a plain value, such as an environment variable, is refused when the definition is
parsed, unless the definition declares the exception 0086 allows, with its reason.
**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](../../02-DECISIONS/0086-a-secret-reaches-a-process-as-a-file.md)
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
@@ -190,12 +200,14 @@ removed from the parser.
Each phase ends at a check that holds, so none of them leaves a mechanism half-replaced.
1. **Resolution and the new form.** 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.
2. **Providers answer.** The SDK harness answers with contract fields, the controller carries answers
back and seals them, and the vault holds its seat and generates. *Ends when* the analytics and DNS
providers answer their consumers and the broker's bootstrap step is removed.
1. **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.
2. **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.
3. **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.
@@ -208,10 +220,15 @@ Each phase ends at a check that holds, so none of them leaves a mechanism half-r
|---|---|
| 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](../../02-DECISIONS/0112-a-module-definition-names-no-node-mesh-or-path.md). |
| A module provider is chosen by pin, seat, co-location, only one, refusal | Resolution tests for each step, and for a second provider on a consumer's own machine when a seat delivers the provision. |
| 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 | 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 read into a plain value, unless the definition declares the 0086 exception with a reason. |
| 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. |
@@ -221,5 +238,8 @@ Each phase ends at a check that holds, so none of them leaves a mechanism half-r
- 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.
- A contract registry: where contracts live, and how a new provision gets one. Today contracts are
implicit in each provider's served fields.
- **Which seats a module holds.** Today a claim is part of the definition, so moving a seat is a
definition change ([26 — The seats](26-the-seats.md)). 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](../../02-DECISIONS/0110-a-seat-is-a-module-assignment-from-a-closed-set.md),
and is its own decision.