jschoubben
702efca6bb
HQ held only the to-be. Every reader had to already know the system the decisions were about, and an as-is claim had nowhere to live except inside an intention. Adds 02-DESIGN/00-as-is — eleven documents written from the implementation and the operational record, not from intent, including the parts nobody would choose again. The two existing designs move under 01-to-be. Layers are declared in frontmatter and never mix: a design that ships does not move, its as-is counterpart is written, and both stand. Back-fills adr/0001-0014 for decisions taken in implementation and never recorded — the broker, the module abstraction, the mesh database, managed files, provisioning, migrations, the workspace removal, failing loudly, the constitution, application placement, linking, the employee model, the artifact, the three silos. Each marked reconstructed, dated from the history, and citing the evidence it was recovered from. The two existing records renumber to 0015 and 0016 so the ledger runs oldest first; 0017 extends 0015 to modules outside the core, principle only — the domain list is deliberately not invented here. how-we-build.md becomes the source of the mesh constitution, with a sync playbook, so the enforced copy stops being the only one that is true. Process becomes explicit: five playbooks, eight thin skills that defer to them, a repository map, and AGENTS.md with CLAUDE.md as its include. The five Observations become 04-ISSUES 001-005 where they can be owned and closed. 006 is new and uncomfortable: HQ is not indexed into the knowledge base. That claim is what decision 27 rests on, it was never checked, and the README now says so instead of repeating it. Also corrects the ADR index into something generated, the "02-DESIGN is empty" claim, the VISION.md pointer that did not survive the repo split, and a note asserting the symlink rule was contradicted — it was a misreading; the rule forbids hand-made links, the installer links by design.
68 lines
3.1 KiB
Markdown
68 lines
3.1 KiB
Markdown
---
|
|
status: accepted
|
|
date: 2026-04-06
|
|
deciders: jochen
|
|
reconstructed: true
|
|
---
|
|
|
|
# 5. Capabilities are provisioned on declaration, not configured by hand
|
|
|
|
> Reconstructed after the fact from the evidence cited below.
|
|
|
|
## Context
|
|
|
|
Most modules need something another module holds — a database, a cache, a bucket, a message
|
|
vhost, an identity client. Wiring that by hand means creating the resource, creating a user,
|
|
generating a credential, putting it in the consumer's configuration, and repeating all of it
|
|
on every node the consumer runs on.
|
|
|
|
Every step is a place to make a mistake that surfaces much later, and the credential ends up
|
|
written somewhere it can be read.
|
|
|
|
## Considered options
|
|
|
|
1. **Manual setup, documented.** Rejected. Documentation of a manual procedure is a
|
|
description of the mistakes people will make.
|
|
2. **A shared credential per resource type**, distributed to all consumers. Rejected: no
|
|
isolation, and rotation becomes a mesh-wide outage.
|
|
3. **Declared requirements, satisfied by the provider module.** Chosen.
|
|
|
|
## Decision
|
|
|
|
A module declares what it **provides** and what it **requires**. A requirement names the
|
|
provider, the resource type, optionally a name and a target node, and a mapping from the
|
|
resource's connection fields to the consumer's environment variables.
|
|
|
|
The mesh satisfies it: a provisioner belonging to the provider creates the resource and its
|
|
credential, records the grant, and writes the mapped values as database overrides. The
|
|
synchroniser from [ADR 0004](0004-managed-files-are-generated-never-edited.md) then
|
|
materialises them. Neither the credential nor the topology is ever written by hand.
|
|
|
|
A requirement may name a provider on another node. The grant records consumer and provider
|
|
nodes separately, so cross-node wiring is the same declaration.
|
|
|
|
## Consequences
|
|
|
|
- **Provisioning becomes a core concern of the mesh, not plumbing.** A module asks for a
|
|
capability; where it lives is the mesh's problem. This is the property
|
|
[ADR 0015](0015-mesh-brokers-nodes-host-agents-think.md) later builds the whole domain model
|
|
around.
|
|
- Credentials are never authored, so they are never authored badly, and they are never in the
|
|
repository.
|
|
- Each consumer gets its own credential, so revocation is per-consumer.
|
|
- Rotation is where this bites. A shared secret rotated for a new consumer invalidates the
|
|
peers holding the old one, and this has taken the mesh down. The declaration model makes
|
|
granting easy and says nothing about fan-out.
|
|
- A module with no requirements skips the stage entirely, which is correct and also means the
|
|
absence of provisioning is indistinguishable from provisioning that did not run.
|
|
|
|
## References
|
|
|
|
- `Remove shell/ helper library; split brain into independent workspaces`, 2026-04-06 — the
|
|
provisioner daemon becomes its own component.
|
|
- `Coordinator refactor: centralize pipeline orchestration`, 2026-04-04 — the provision-then-
|
|
environment-then-start sequence becomes the coordinator's.
|
|
- Knowledge base: `provisioning`, `provisioning/requires`.
|
|
- The rotation failure: `troubleshooting/provision-rotation-invalidates-peers`,
|
|
`troubleshooting/provision-adoption-rotates-live-credential`.
|