docs: record the config-field trap (a field that parses is not a field that works)

Three defects in one session landed the same way: a map field the file overlay
dropped (xrux), a field missing from the control-plane projection
(parallel_tool_calls), and per-identity forge.intake - accepted TOML that no
consumer reads, and which is not even validated. The entry names the shape,
gives the live example with file:line, and points at
docs/architecture/configuration.md as the config authority.
This commit is contained in:
sam committed 2026-09-22 03:21:27 +10:00
1 parent 1fe4691bd6
commit 27d7c08049
1 file changed
+14
+14
View File
@@ -161,6 +161,20 @@ structures found in legacy packages.
## Per-Package Invariants & Traps
- **Config fields (cross-cutting): a field that parses is not a field that works.**
Adding a knob to a struct the extensible surface reuses makes it *parse*
everywhere without taking effect anywhere. `Forge` is the live example:
`IdentityConfig` embeds it (`internal/config/config.go:573`), so
`[identities.forge].intake`, `.webhook_secret` and `.webhook_addr` are
accepted TOML, while every read is the root block
(`validate.go:257-268`, `defaults.go:278-279`, `bootstrap.go:1330-1344`) - so
they are silently ignored and not even validated. Three defects landed this
way in one session: a map field the file overlay dropped, a field missing from
the control-plane projection, and per-identity `forge.intake`. Before adding
or reusing a config field, name its consumer; with none, reject the
configuration rather than accept it. `docs/architecture/configuration.md` is
the authority on the config model and its reloadability criterion.
- **`internal/channels/telegram/`:**
- The long-polling worker must call `dropPendingUpdates(ctx, b)` before
`b.Start(ctx)` and on `/restart`.