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.
87 lines
3.8 KiB
Markdown
87 lines
3.8 KiB
Markdown
---
|
|
layer: as-is
|
|
status: implemented
|
|
code: [hal]
|
|
updated: 2026-08-23
|
|
decisions:
|
|
- adr/0004-managed-files-are-generated-never-edited.md
|
|
- adr/0005-capabilities-are-provisioned-on-declaration.md
|
|
---
|
|
|
|
# Configuration and secrets
|
|
|
|
Every value a module reads at runtime comes from a file on a node's disk. Every one of those
|
|
files is **generated**.
|
|
|
|
## The rule
|
|
|
|
A managed file is derived from the mesh database. A synchroniser rewrites it when the values
|
|
behind it change. The write path is the mesh operation that owns the value; the file is an
|
|
output ([ADR 0004](../../adr/0004-managed-files-are-generated-never-edited.md)).
|
|
|
|
An edit to a managed file survives until the next synchronisation and is then overwritten
|
|
silently, taking whatever it was fixing with it — bringing back the bug the edit had removed,
|
|
with a delay, and with no error to connect the two events.
|
|
|
|
There is a way to ask whether a given file is managed. That question has to be asked, because
|
|
the answer is not visible from the file.
|
|
|
|
## What is managed
|
|
|
|
Generated environment files for each module, service definitions in each module's runtime
|
|
directory, managed configuration files a module declares, and node-level settings. The list is
|
|
not a category — it is whatever a synchroniser claims, which is why the question is asked of
|
|
the tooling rather than answered from a rule.
|
|
|
|
## How a value is decided
|
|
|
|
Values resolve by precedence, highest first:
|
|
|
|
1. **A database override** — set deliberately, or written by a provisioner.
|
|
2. **The value already in the generated file** — preserved for anything without an override.
|
|
3. **A generated value** — a random secret, a template composed from other variables, or a
|
|
value pulled from the node's own record.
|
|
4. **The manifest default.**
|
|
|
|
Two consequences follow, and both are subtle enough to have caused confusion.
|
|
|
|
The second rule is what keeps a generated password **stable** across regenerations. It is not
|
|
an oversight; without it every regeneration would issue a new secret and break whatever holds
|
|
the old one.
|
|
|
|
The same rule means that **changing a manifest's default does not change anything already
|
|
using it**. The existing file's value wins. The new default reaches only installations that
|
|
never had one.
|
|
|
|
Removing a declaration is worse than changing it: the old override row and the file it produced
|
|
are both left behind. Configuration is additive in practice, whatever the manifest says.
|
|
|
|
## Secrets
|
|
|
|
Generated secrets are produced by the mesh, never authored. Provisioned credentials arrive as
|
|
database overrides written by the provisioner and are marked as such, so they can be
|
|
distinguished from a deliberate override and cleaned up when the grant is removed
|
|
([ADR 0005](../../adr/0005-capabilities-are-provisioned-on-declaration.md)).
|
|
|
|
Nothing in the repository contains a credential. The repository has no per-node content at all,
|
|
which is what makes that guarantee structural rather than a matter of care.
|
|
|
|
Two known weaknesses, both recorded rather than resolved:
|
|
|
|
**Generated environment files were world-readable.** The mode passed at write time only applies
|
|
when the file is created, so regeneration left the previous mode in place. The class of bug is
|
|
worth remembering beyond the instance: a permission set at creation is not a permission
|
|
maintained.
|
|
|
|
**Rotation is not a mesh operation.** Secrets can be generated and granted; there is no
|
|
mechanism that rotates one and informs everything holding it. Where a rotation has been done,
|
|
it has been done by hand, and doing it wrong has taken services down.
|
|
|
|
## Node-level and mesh-level values
|
|
|
|
A node-level value applies to everything on one node. A mesh-level value applies everywhere and
|
|
is read by every node — the broker's location is the canonical example, and a wrong one is how
|
|
a mesh fails to form.
|
|
|
|
Neither is a file that anyone edits. Both are database records that produce files.
|