container-runtime-policies seeded and validated config.ContainerConfig directly,
the last resource in the registry whose document was the internal config struct
(archie-core-1171). encoding/json fell back to that struct's Go field names --
Image, MaxConcurrency, LegacyEnabled, Profiles -- the only Go-cased keys the Web
UI still rendered, and case-insensitive matching let a lowercase misspelling
("maxconcurrency") decode as the field while "max_concurrency" was read back
half-applied.
Define the document here instead: containerRuntimePolicies with explicit
snake_case tags and agentProfile at the profile nesting level, the same shape
267d21a2 gave the channel document. The two durations stay config.Duration,
which already writes the string the file accepts; this leak was the keys only.
The mapping to config.ContainerConfig is one function the validator and the
runtime layering share.
Reading a legacy document is deliberate, so it stays strict about everything
else: DecodeRenamingLegacyKeys renames the seven Go-cased keys an existing store
holds (and the four at the profile level), drops LegacyEnabled -- the removed
containers.enabled switch, which had no runtime consumer and no current
counterpart -- and keeps DisallowUnknownFields, because swallowing an unknown
key decodes as unset and an unset image is a broken worker. A misspelling is
refused.
normalizeContainerPolicies, through the Definition.Normalize hook the channel
document already uses, rewrites a legacy document into the current shape on
write, so a stored document converges the next time it is saved. The layering
keeps its profile semantics -- a document that omits profiles (one stored before
they existed) inherits the file's, one that carries them replaces the file's --
and now checks both spellings of the key.
docs/development/control-plane.md's 'adding a database-owned field' still
instructed the untagged practice this class of issue removes; it now names the
wire-shape rule, the legacy-key tolerance and the Normalize hook instead.
4.7 KiB
4.7 KiB
Control plane and settings
Authority: docs/architecture/configuration.md. The wiring matrix, the
decoded-but-unwired ledger and the three shapes an unwired field takes are in
.agents/skills/archie-config-and-flags.
A field that parses is not a field that works. Before adding one, name the code that reads it and the path the value takes to get there.
Decide what kind of setting it is
- Bootstrap-only (read once at process start:
database_url,state_dir,work_dir). It stays in the file, is checked byvalidateBootstrapininternal/infrastructure/configuration/validate.go, and the runtime overlay refuses changes to it. - Database-owned (repository policies, scheduling, tools, plugins,
channels, containers). The file only seeds it. Once the State Store holds the
control-plane resource, the stored document is layered over the file
(
controlplane.Client.RuntimeConfig) and the file key stops mattering. It is checked byvalidateDatabaseOwnedand by the resource's validator. - Worker-carried. A value the agent container needs travels in
config.TaskConfig(Config.ForTask) or ontaskrun.Request. Never pass it as an environment variable the daemon did not already define, and never carry a secret this way.
Adding a database-owned field
- Add it to the wire-shape type the resource's
Documentnames — a dedicated struct ininternal/app/controlplane/with explicit snake_case json tags (channel_settings.go,tool_settings.go,container_settings.goare the precedents), never the internal config struct itself. A struct fed straight into the document falls back to Go field names (Window,MaxRequests), and a baretime.Durationmarshals as nanoseconds — both render unusable in the Web UI. The resource's JSON schema and the dashboard's Advanced settings editor are generated from that type, so no UI work is needed for the editor itself. - Map to and from the internal config type at the resource boundary (
Seed, the layering inruntime_config.go, and the validator all use the same mapping). Durations in the document are a string-marshalling type (config.Durationor a document-local one), never a baretime.Duration. - A document stored before the shape existed carries Go-cased keys. Read them
with
controlplanerpc.DecodeRenamingLegacyKeys(anUnmarshalJSONon the wire type) while keepingDisallowUnknownFields— dropping unknown keys would decode a misspelling as "unset" — and register aNormalizeon theDefinitionthat re-encodes the document, so a legacy document converges the next time it is written. A map or a nested struct needs its layering checked: a stored map replaces the file's, not merges into it, and a field the stored document omits keeps the file's value. Add a case tointernal/app/controlplane/runtime_config_test.gofor both. - Validate it in one function both sides call, and add a case to
TestResourceValidatorsRejectWhatEffectiveValidationRejectsinvalidators_agree_test.go, so the file and the resource cannot disagree. - Decide whether it reloads: it does only if every consumer re-reads it from
config.Holder. The allowlist isinternal/app/archied/reload.go; anything not on it requires a restart. - If the settings page shows it as a plain field, add it to
internal/webui/config_schema.goand the view inapi_config.go. - A generic catalog resource (
replacecommand, not domain-managed, no query service) is watched once per archie-ui process bywebui.RunLive, then published to every browser through/api/stream. Do not add an EventSource per resource to a settings store or a gRPC Watch per HTTP client. The control-plane server pollsResourceevery 250ms per upstream Watch; verify watch count is independent of client count and that late clients get the hub's current value (internal/webui/live_hub_test.go, real server over bufconn). Reopens resume after the last delivered version and charge failed attempts; accepting a gRPC stream does not establish its health.
Every new field
- Test through the layering: build the effective config the way boot does, not by setting the field on the consumer.
- Add a commented example to
config.example.toml. Touchdeployments/*.tomlonly when a profile there needs a value different from the default. - Update the wiring matrix in
.agents/skills/archie-config-and-flags. - Secrets are
SecretRefs resolved through the secret registry. Never inspect a resolved value, even in a test. - Reject a configuration that sets a field with no consumer rather than
accepting and ignoring it (per-identity
forge.intakeis the precedent).