6.1 KiB
Example-config and generated-config drift — decision
Status: Approved
Date: 2026-09-15
Closes: the checked-in-config half of audit findings config-1 and
repo-root-deployment-2; strengthens doc-drift findings generally.
Authority: extends docs/architecture/generated-documentation.md and
docs/prds/config-schema.md; does not replace either.
Question
Should config.example.toml and deployments/*.toml be generated, so they
cannot drift from the config code?
Decision
No — do not generate them. Gate them instead. Neither file is a projection of the schema, and generating either would destroy the thing that makes it useful. Three verified reasons, in order of weight:
config.example.toml's value is its comments. It documents 137 keys (measured: active and commented-out), and those hand-written comments are the file's purpose —docs/architecture/configuration.mdstates outright that "config.example.tomlcarries documentation users are meant to hand-edit". TOML round-tripping does not preserve comments, which is exactly whytomlwritedoes line-oriented edits rather than decode/encode. A generator would emit a correct file with the documentation deleted.docs/prds/config-schema.mdforbids building onconfig.Config. That PRD rejects "a reflection-based schema overconfig.Config" because the struct is "scheduled for dissolution". A generator deriving the example from its struct tags would build on a foundation this repo has already decided to remove.docs/architecture/generated-documentation.mdprohibits it. "Adding another hardcoded type list todocsgenis prohibited" — so any generator must consume a domain-owned registry, which does not exist for configuration yet. Creating one is the config-domain migration's job, not this change's.
The deployment profiles are also not a projection: they set 3-46 keys against the example's 137, and they are curated overlays ("a complete config, not an overlay", per their own headers), not near-duplicates. Generating them would add machinery to remove duplication that largely is not there.
The gap that is real
Unknown config keys are silently ignored. Verified at
internal/infrastructure/configuration/decode.go:
if _, err := toml.DecodeFile(path, target); err != nil {
There is no MetaData.Undecoded() check, so a typo — max_concurrancy = 4 —
parses clean, validates clean, and does nothing. That is the same failure shape
this repo's audit found repeatedly: a setting that looks applied and is not. It
is also detectable without any hand-maintained list, because BurntSushi/toml
reports exactly which keys the target did not consume.
Note the second, separate gap already admitted in writing:
generated-documentation.md — "task check does not run docs:check, so
generated drift is ungated."
What to build
1. Unknown-key detection at the loader (behaviour). Decode with metadata and
collect Undecoded(). Report it as a warning at startup listing the offending
keys, and expose it so tests can assert emptiness.
Deliberately a warning, not a fatal error. configuration.md's settled
startup policy is "a missing credential disables a capability; only an invalid
config stops the daemon". A stray key is far more likely to be an operator typo
in a file they are otherwise happy with than a reason to refuse to boot, and
[web] is documented as landing in a different binary
(internal/app/archieui), so a key unknown to one process is legitimately known
to another. Failing closed here would break working deployments on upgrade.
2. A checked-in-config contract test (gate). Load config.example.toml and
every deployments/*.toml through the real loader and assert Undecoded() is
empty, with an explicit allowlist for keys another binary owns. This is the
mechanism that would have caught a renamed key left behind in an example, and it
needs no inventory.
3. Gate generated data in task check. Done. task docs:check runs in the
gate, closing the admitted "generated drift is ungated" hole. The
check mode did not exist when this was written; it was added for issue #855,
which also made the check non-destructive so the gate can never rewrite the
artifact it is judging.
4. Explicitly NOT now: a generated key inventory. configuration.md's
completion criteria want "generated documentation lists every external key,
default, constraint, mutability class, owner". That is a real target and it is
the config domain's, once a domain-owned registry exists — the prohibition above
means it cannot be bootstrapped from a list inside docsgen. Recorded as
deferred, not rejected.
Non-goals
- No generation of
config.example.tomlordeployments/*.toml. - No reflection-based schema over
config.Config. - No new type list inside
docsgen. - No change to
archied setup's template:configtemplate.Examplestays the verbatim embedded example, hand-maintained, andsetupcontinues to edit it viatomlwriterather than regenerate it.
A withdrawn premise, recorded so it is not reused
An earlier measurement claimed 17 keys were "set by a profile but documented
by no example", and used it to argue for generation. It was an
artifact: the extractor stripped comment markers and tracked a single table
variable, so commented blocks were mis-attributed. Re-checking refuted it —
providers.<name>.api_key_env is a real, documented backwards-compatible field
(internal/config/config.go, config.example.toml) and [[identities]]
is documented at config.example.toml. The decision above does not rest on
that measurement.
Acceptance criteria
- A config file containing an unknown key surfaces those keys to the operator at startup, and the daemon still starts.
config.example.tomland everydeployments/*.tomlare loaded by a test that fails if any key is undecoded, except keys explicitly attributed to another binary.task checkfails when committed generated data is stale.- Introducing a renamed key into
config.example.tomlfails the gate (prove it by doing it, not by asserting it).