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

Review of the to-be layer: check what the documents claim against what runs

Browse Source 
First pass of a design review, done by reading documents against code
and against a raised mesh rather than against each other. Every error
below was invisible to a proofread.

**Statuses were stale, and nothing checked them.** Ten to-be documents
said `designed` while naming working, lab-proven code — several with a
*What was built* or *Raised, and observed* section. Added a
`status-vs-code` check: naming a file is a claim that the file
implements this, so a document that points at one has stopped being
merely designed. It failed on all ten before it passed, per the rule
this folder sets for its own checks.

**The bundle carries three images, not two.** 07 reasoned about which
substrate services go in and overlooked that the control plane is in
there too — it is what the substrate exists to start, and there is
nothing to fetch it with yet. Counted, not deduced.

**The bootstrap uses four shapes, not six.** It listed `file` and
`directory`, which substrate-first-node.lock never asks for. The claim
that mattered — nothing is blocked on the host — was true either way,
which is why the wrong count survived.

**The eight capabilities were documented nowhere.** Implemented in
internal/profile/detectors.go and enumerated in no document, including
the one about the host that detects them. A vocabulary modules write
against, readable only by reading the code. Now written down, with the
seat/graphical-session distinction that is wrong in both directions if
collapsed.

**MinIO swept out of the to-be layer** per 0028.

The gate now fails on one thing left deliberately: ADR 0024 is
`proposed` while two documents rest on it and the feature it decides is
built and lab-proven. Accepting a decision is not mine to do.
This commit is contained in:
jschoubben
2026-08-31 17:20:47 +02:00
parent cbcbba8099
commit 1b5308c9cc
13 changed files with 100 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files
03-DESIGN/01-to-be/07-the-substrate.md
+23 -15
View File
@@ -1,6 +1,6 @@
---
layer: to-be
status: designed
status: in-progress
code:
- mesh-host examples/substrate-first-node.lock
- mesh-host internal/apply
@@ -117,15 +117,20 @@ Being substrate and being in the bundle are two different questions:
|---|---|---|
| PostgreSQL | yes — the control plane's own state lives in it | **yes** — there is nowhere to put that state otherwise |
| LavinMQ | yes — it cannot grant itself a virtual host | **yes** — the control plane reaches a node only over the link, and the link is the broker ([ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)) |
| MinIO | yes — it cannot grant itself a bucket | no — nothing is delivered before the mesh exists |
| the OCI registry | yes — it cannot grant itself a repository | no — the first node fetches upstream ([ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md)) |
The two on the bottom rows are **substrate by role and ordinary by delivery**: by the time they
are wanted there is a control plane, and it provisions them the way it provisions anything.
That keeps the bundle to two images rather than four, which is what makes it small enough for the
review [ADR 0005](../../02-DECISIONS/0005-the-node-host.md) requires. It was one until
[ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md) established that the broker has
to precede the control plane.
The registry is **substrate by role and ordinary by delivery**: by the time it is wanted there is
a control plane, and it provisions it the way it provisions anything. That keeps the bundle small
enough for the review [ADR 0005](../../02-DECISIONS/0005-the-node-host.md) requires — one
substrate image until
[ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md) established that the
broker has to precede the control plane, and two since.
*Corrected 2026-08-31, from counting what the bundle holds rather than reasoning about it.* **It
carries three images, not two** — PostgreSQL, LavinMQ, and the control plane itself, which the
sentence above had overlooked by counting only substrate services. The control plane is what the
substrate exists to start, and it is in the bundle for the same reason they are: there is nothing
to fetch it with yet. It also carries seven actions, a package and a service.
**Why pinned:** the bundle is applied when no mesh exists, so nothing can resolve a version, ask
a registry, or check a constraint. What the host carries must already be exact.
@@ -150,8 +155,8 @@ The order, from [research 011](../../01-RESEARCH/011-the-module-graph/worked-pro
5 a virtual host, a credential, and actions, run locally
a self-signed certificate
6 the control plane starts and only now is there a mesh
7 MinIO, the registry, and everything the ordinary path
else are provisioned
7 the registry, and everything else the ordinary path
are provisioned
```
**Steps 4 and 5 are why the bundle is not one image**
@@ -185,10 +190,13 @@ what it is called differs per system. It is:
- a package, which needs the machine's own package manager and a network — both permitted by
[ADR 0006](../../02-DECISIONS/0006-the-substrate-and-the-control-plane.md).
So the host's bootstrap vocabulary is six shapes: **package**, **container**, **file**,
**directory**, **service**, and **action**. **All six are built**
([`05-the-node-host.md`](05-the-node-host.md) stage 2), so nothing in this bootstrap is
blocked on the host any longer.
So the bootstrap uses four shapes: **package**, **container**, **service** and **action** —
*counted from `substrate-first-node.lock`, which is the only bundle there is*. It had said six,
adding `file` and `directory`, which this bootstrap never asks for.
All four are built, as are the host's other four
([`05-the-node-host.md`](05-the-node-host.md) stage 2), so nothing in this bootstrap is blocked
on the host any longer — which is the claim that mattered, and it was true either way.
**Steps 2 and 3 happen before there is a mesh to do them**, which is why provisioning is part of
the bootstrap rather than a service consumers use later. They are **actions** the bundle
@@ -220,7 +228,7 @@ host's vocabulary grows by one shape rather than by one resource type per substr
question was whether the host must learn what a database is, and it must not. The bundle
declares an **action**; the host runs it and verifies it, and what a database means stays with
the module that provides one.
- **Whether one host can raise all four.** The claim under stage 2 of
- **Whether one host can raise all three.** The claim under stage 2 of
[the node host](05-the-node-host.md), never proved. If it is false, the tier boundary moves.
- **How the substrate is updated once a mesh exists.** Pinned by hand at bootstrap; afterwards
the control plane could deliver it like anything else, and nothing says whether it does.