Files
archie/docs/development/control-plane.md
T
sam 67c5447ebc fix(controlplane): refresh a stale seeded resource and re-seed a removed one
A seed was consulted only for a resource kind the store did not hold, so a
document that changed in the build never reached a database an earlier
release had seeded. For workflow-definitions that is not a stale setting but
a total outage: the collection validates as one document, so a stored step
type this build no longer has fails every task's pin, whatever workflow the
task names. The seed's request ID was stable per kind and the store answers a
known request ID from resource_history, which outlives the resource, so the
documented recovery -- remove the resource and restart -- wrote nothing
either.

Seeds now carry one identity the reader can name, and a kind the store holds
is refreshed only when the seed itself wrote the newest revision: a
file-derived value stays the store's, and an operator's replacement is never
undone. The request ID is derived from the value, so an idempotent replay is
still one revision without making a second, changed document impossible. A
replay whose resource is gone re-creates it from the ledger's revision.

The shipped-vs-file-derived distinction is the seed's to make, so it is a
property of the definition (Defaults is set exactly for the kinds that ship a
document) rather than a check at each consumer.
2026-09-29 14:27:57 +10:00

5.0 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 by validateBootstrap in internal/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 by validateDatabaseOwned and by the resource's validator. A stored value is refreshed from the file only when the store has no value for the kind at all; a kind that ships a document of its own (workflow definitions, personas) is refreshed whenever the seed itself wrote the stored copy, since that copy is a previous release's document rather than an operator's (controlplane.Server.seedKind).
  • Worker-carried. A value the agent container needs travels in config.TaskConfig (Config.ForTask) or on taskrun.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

  1. Add it to the wire-shape type the resource's Document names — a dedicated struct in internal/app/controlplane/ with explicit snake_case json tags (channel_settings.go, tool_settings.go, container_settings.go are 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 bare time.Duration marshals 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.
  2. Map to and from the internal config type at the resource boundary (Seed, the layering in runtime_config.go, and the validator all use the same mapping). Durations in the document are a string-marshalling type (config.Duration or a document-local one), never a bare time.Duration.
  3. A document stored before the shape existed carries Go-cased keys. Read them with controlplanerpc.DecodeRenamingLegacyKeys (an UnmarshalJSON on the wire type) while keeping DisallowUnknownFields — dropping unknown keys would decode a misspelling as "unset" — and register a Normalize on the Definition that 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 to internal/app/controlplane/runtime_config_test.go for both.
  4. Validate it in one function both sides call, and add a case to TestResourceValidatorsRejectWhatEffectiveValidationRejects in validators_agree_test.go, so the file and the resource cannot disagree.
  5. Decide whether it reloads: it does only if every consumer re-reads it from config.Holder. The allowlist is internal/app/archied/reload.go; anything not on it requires a restart.
  6. If the settings page shows it as a plain field, add it to internal/webui/config_schema.go and the view in api_config.go.
  7. A generic catalog resource (replace command, not domain-managed, no query service) is watched once per archie-ui process by webui.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 polls Resource every 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. Touch deployments/*.toml only 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.intake is the precedent).