2.7 KiB
ADR 0003: Expose configuration scopes through declared capabilities
Status
Accepted. Consolidated during the alpha ADR cleanup.
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. Scope and comparison inputs follow the input/state separation in ADR 0001.
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 owns command inventory, scope names and defaults, selector syntax, aggregate applicability, and report ordering. The consumer guide and GoDoc own provider wiring and precise input/acquisition lifetimes. Those details do not require separate ADRs merely because they are public contracts.