jschoubben
f1b1cd9aa0
A sweep for claims overtaken by the last few days. Annotated rather than rewritten, following the pattern already in 0049 -- what changed and why is the useful part, and an accepted record should not quietly become something else. 0057's init section was wrong on all three of its claims. It said the host needs FOUR things from an init; 0061 reduced that to one. It said every machine the mesh targets already has systemd; Alpine does not, and it is the intended first node. It said there is no second init to abstract over; there is now, and the answer is still not an abstraction -- it is a four-line file per system. What survives is the part that was always right: an init is not a dependency in 0041's sense, because it is not installed, it is what the machine already is. 0048 named Docker as the container runtime. It is now docker or podman, detected rather than chosen -- because adoption keeps what a machine already has, so naming one contradicted a rule already decided. That row is the only one of the five that names two, and the record now says why. 0060 claimed the bundle is portable across operating systems. Its mechanism is; its contents are not -- package names, unit names, service names all differ, so an Arch host embeds an Arch bundle. That was my error, and it is the exact confusion behind the question that found it. The design layer had the same drift: 07 and 09 said "Docker" where they meant a container runtime, 09 said systemd restarts the host after an upgrade when the launcher does, and both install snippets assumed Arch. They now show Alpine and Arch side by side, which makes the point better than prose did -- step 1 differs per system, step 2 never does. Checked and NOT changed: 0047's "the vocabulary grows by one shape" is a claim about the rate, not the count, and is still true. 0037 lists docker among tools the host manages, which it does. 0041 says nothing about either.
107 lines
6.1 KiB
Markdown
107 lines
6.1 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-08-27
|
|
deciders: jochen
|
|
reconstructed: false
|
|
extends: 0030-the-repository-structure.md
|
|
---
|
|
|
|
# 48. The substrate is named
|
|
|
|
## Context
|
|
|
|
[The substrate](../03-DESIGN/01-to-be/07-the-substrate.md) is defined by a test — *what the
|
|
control plane consumes and cannot grant itself* — and the design layer describes its members
|
|
entirely by role: a relational store, a message bus, an object store, an image registry.
|
|
|
|
**No design document names a product.** Postgres appears in zero of them. The names occur only
|
|
in the as-is layer and in research, describing what already runs.
|
|
|
|
That is a gap rather than a discipline. The rule it came from —
|
|
[`01-RESEARCH`](../01-RESEARCH/README.md)'s *research never identifies the mesh it observed* —
|
|
is about node names and domains, not about software. Nothing is protected by declining to write
|
|
*Postgres* in a public repository, and something is lost: a design that never names a product
|
|
does not record that the choice was made.
|
|
|
|
Two costs, both already accrued:
|
|
|
|
- **`substrate.lock` cannot be written from the design.** It pins images by digest, and a digest
|
|
belongs to a named image.
|
|
- **A reader cannot tell a settled choice from an unexamined one.** "A relational store" reads
|
|
the same whether the store was chosen deliberately or never considered.
|
|
|
|
## Decision
|
|
|
|
**The substrate is named, and the names are these:**
|
|
|
|
| Role | Product | Why |
|
|
|---|---|---|
|
|
| relational store | **PostgreSQL** | In use, understood, and the provisioning model already assumes its notions of database, role and schema. |
|
|
| message bus | **LavinMQ** | In use, speaks AMQP, which is what [ADR 0001](0001-nodes-communicate-over-a-broker.md) assumes. Interchangeable with other AMQP brokers at the protocol level, which is what makes it a safe choice rather than a locked-in one. |
|
|
| object store | **MinIO** | In use, speaks the S3 protocol, which is the closest thing to a portable object-store interface. |
|
|
| image registry | **the OCI distribution registry** | In use, and the format is the standard rather than a vendor's. |
|
|
| container runtime | **Docker or Podman** — *detected, not chosen* | See below. The other four rows name one product; this one names two, and the difference is the point. |
|
|
|
|
### Outside the substrate
|
|
|
|
The gap is not only the substrate's. The design layer names roles for these too, and the same
|
|
correction applies — a role is a legitimate abstraction, but the product belongs beside it:
|
|
|
|
| Role, as the design says it | Product | Tier |
|
|
|---|---|---|
|
|
| **the forge** | **Gitea** | a hosted workload — the mesh builds from it but does not need it to run |
|
|
| **the coordinator** | the mesh's own pipeline | tier 2 — part of the control plane, not a product |
|
|
| **ingress** — *exposure*, *certificates* | **Traefik** | not substrate — [ADR 0049](0049-a-route-is-a-grant.md) |
|
|
|
|
**Ingress was a real gap rather than a naming one**, and it is closed by
|
|
[ADR 0049](0049-a-route-is-a-grant.md): applying the same test shows it is **not** substrate, and
|
|
a route is an ordinary grant. Recorded here because finding it was the point — naming the
|
|
products is what made the unnamed role visible.
|
|
|
|
**The container runtime is the one row that is not a choice at all**, and it stopped being one
|
|
after this record was written ([ADR 0060](0060-the-host-is-built-per-operating-system.md)). The
|
|
host detects what the machine has and uses it, because adoption keeps a machine's existing
|
|
configuration rather than replacing it — so naming a single runtime here contradicted a rule
|
|
already decided. Both are supported, checked against a real podman: only the version probe
|
|
differs, and one behavioural difference (podman has no daemon, so containers do not return after
|
|
a reboot unless `podman-restart.service` is enabled) belongs in the declaration rather than the
|
|
host.
|
|
|
|
**Identity is deliberately absent.** Whether an identity provider is substrate at all depends on
|
|
whether the control plane delegates authentication, which is undecided
|
|
([`07-the-substrate.md`](../03-DESIGN/01-to-be/07-the-substrate.md)). Naming a product before
|
|
deciding whether the role exists would be the mistake this record is correcting, in reverse.
|
|
|
|
**The role and the product are both written.** A design says *the relational store (PostgreSQL)*
|
|
rather than one or the other. The role is what the argument turns on; the product is what gets
|
|
installed, and a reader needs both.
|
|
|
|
## Consequences
|
|
|
|
- **`substrate.lock` becomes writable.** It pins named images by digest, which was impossible
|
|
while the design refused to say which images.
|
|
- **Continuity is the argument, and it is a real one.** Every choice here is what already runs.
|
|
Nothing was re-litigated, because nothing about the new shape gives a reason to — and changing
|
|
a substrate service is a migration of the mesh's own state, which is not a cost to pay for
|
|
novelty.
|
|
- **Protocols, not products, are what the design depends on.** The bus is reached over AMQP, the
|
|
object store over S3, the registry over the OCI protocol. Replacing a product is then a
|
|
substrate migration rather than a redesign — which is the property that makes naming them safe
|
|
rather than a commitment that cannot be revisited.
|
|
- **The relational store is the exception**, and it should be said. The provisioning model uses
|
|
databases, roles and schemas as Postgres means them, and
|
|
[ADR 0044](0044-a-module-declares-presence-instantiation-and-exclusion.md) already records that
|
|
two stores from different vendors are not substitutable for a consumer. Replacing it is not a
|
|
swap.
|
|
- **The rule that caused this is narrowed, not repealed.** Research still does not identify the
|
|
mesh it observed — node names, domains, addresses. Product names were never in scope, and the
|
|
over-application cost the design layer its concreteness.
|
|
|
|
## References
|
|
|
|
- [`07-the-substrate.md`](../03-DESIGN/01-to-be/07-the-substrate.md) — the test these satisfy.
|
|
- [ADR 0001](0001-nodes-communicate-over-a-broker.md) — why the bus speaks AMQP.
|
|
- [ADR 0046](0046-the-installer-fetches-what-it-pins.md) — pinning by digest, which needs a name.
|
|
- [ADR 0044](0044-a-module-declares-presence-instantiation-and-exclusion.md) — why the store is
|
|
the one that cannot simply be swapped.
|