2026-11-07 02:42:54 +00:00
|
|
|
# ADR 0003: Expose configuration scopes through declared capabilities
|
|
|
|
|
|
|
|
|
|
## Status
|
|
|
|
|
|
2026-11-07 02:49:13 +00:00
|
|
|
Accepted.
|
2026-11-07 02:42:54 +00:00
|
|
|
|
|
|
|
|
## Date
|
|
|
|
|
|
|
|
|
|
2026-11-07; consolidates decisions made on 2026-10-06.
|
|
|
|
|
|
|
|
|
|
## Context
|
|
|
|
|
|
|
|
|
|
An application may expose its own configuration and configurations belonging to
|
|
|
|
|
integrated libraries. Repeating a configuration command tree for each one would
|
|
|
|
|
duplicate operator mechanics. Requiring identical inspection capabilities would
|
|
|
|
|
exclude useful integrations whose upstream APIs provide only a subset.
|
|
|
|
|
|
|
|
|
|
## Decision
|
|
|
|
|
|
|
|
|
|
Expose independently meaningful configurations as named scopes through a shared
|
|
|
|
|
configuration command family. A scope identifies the configuration being
|
|
|
|
|
inspected; a command family defines operations on its resources. An integration
|
|
|
|
|
may expose either or both without requiring the other.
|
|
|
|
|
|
|
|
|
|
Each scope declares its supported operations and providers. Assemble standard
|
|
|
|
|
commands from the available capabilities and describe actual availability through
|
|
|
|
|
metadata-driven help and discovery. An unavailable capability does not prevent
|
|
|
|
|
using the scope's other operations.
|
|
|
|
|
|
|
|
|
|
Validate required provider wiring against declared capabilities. Check selected
|
|
|
|
|
operation availability before acquisition. Aggregate inspection must account for
|
|
|
|
|
its requested coverage rather than silently dropping unsupported scopes.
|
|
|
|
|
|
|
|
|
|
Use narrow integration contracts, reusing upstream public types where useful.
|
|
|
|
|
Applications supply acquisition and domain context; integrations adapt supported
|
|
|
|
|
inspection APIs under [ADR 0004](0004-optional-integration-modules.md). Scope and
|
|
|
|
|
comparison inputs follow the input/state separation in
|
|
|
|
|
[ADR 0001](0001-command-dispatch-and-inputs.md).
|
|
|
|
|
|
|
|
|
|
## Alternatives considered
|
|
|
|
|
|
|
|
|
|
- A separate command tree per configuration would make the target part of the
|
|
|
|
|
path but repeat shared operations and help.
|
|
|
|
|
- Requiring every operation for every scope would make one missing capability
|
|
|
|
|
block otherwise useful inspection.
|
|
|
|
|
- One universal operation set across library families would assign operations
|
|
|
|
|
to resources for which they have little meaning.
|
|
|
|
|
|
|
|
|
|
## Consequences
|
|
|
|
|
|
|
|
|
|
Operators use a common configuration family while providers can expose supported
|
|
|
|
|
features incrementally. Capability declarations and help must describe actual
|
|
|
|
|
coverage, and provider abstractions must remain proportionate to integration
|
|
|
|
|
needs.
|
|
|
|
|
|
|
|
|
|
The [CLI reference](../cli.md#configuration-scopes) owns command inventory, scope
|
|
|
|
|
names and defaults, selector syntax, aggregate applicability, and report ordering.
|
|
|
|
|
The [consumer guide](../consumers/guide.md#configkit-scopes) and
|
|
|
|
|
[GoDoc](../../integrations/ckconfig/contracts.go) own provider wiring and precise
|
|
|
|
|
input/acquisition lifetimes. Those details do not require separate ADRs merely
|
|
|
|
|
because they are public contracts.
|
