hq/02-DECISIONS/0048-the-substrate-is-named.md

status, date, deciders, reconstructed, extends

status	date	deciders	reconstructed	extends
accepted	2026-08-27	jochen	false	0019-how-this-repository-works.md

48. The substrate is named

Context

The substrate 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'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 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

Ingress was a real gap rather than a naming one, and it is closed by ADR 0049: 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). 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). 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 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 — the test these satisfy.
• ADR 0001 — why the bus speaks AMQP.
• ADR 0046 — pinning by digest, which needs a name.
• ADR 0044 — why the store is the one that cannot simply be swapped.