103 lines
5.5 KiB
Markdown
103 lines
5.5 KiB
Markdown
# ADR 0009: Select named configuration scopes with declared inspection capabilities
|
|
|
|
## Status
|
|
|
|
Proposed
|
|
|
|
## Date
|
|
|
|
2026-10-06
|
|
|
|
## Context
|
|
|
|
An application can expose its own configuration, PromptKit engine configuration,
|
|
and other independently meaningful configurations through the `config` family.
|
|
A scope identifies the configuration targeted by an operation. Different
|
|
providers may support different inspection operations.
|
|
|
|
Configuration scopes and command families are distinct: a future `feedkit`
|
|
family can inspect feeds through its own verbs, independently of whether FeedKit
|
|
configuration is also exposed as a configuration scope.
|
|
|
|
[ADR 0004](0004-standard-inspection-surface.md) defines initial operation purposes.
|
|
[ADR 0001](0001-command-dispatch-and-inputs.md) records
|
|
installation from declared capabilities.
|
|
|
|
## Decision
|
|
|
|
Use stable semantic scope identifiers. The `app` scope describes application
|
|
configuration; an optional `promptkit` scope describes captured engine
|
|
configuration. Registration also accepts additional independently meaningful
|
|
configuration scopes with unique identifiers.
|
|
|
|
Each scope declares its available inspection operations and their providers.
|
|
Capabilities can include validation, native effective YAML, source inventory,
|
|
path explanation, and safe semantic comparison data. Scope metadata describes
|
|
identity, supported operations, applicable selectors, and dependencies.
|
|
CommandKit checks the wiring needed by each declared capability. Additional
|
|
operations can be supported as their upstream data becomes available.
|
|
|
|
Expose scope operations through CommandKit-owned public provider contracts.
|
|
Adapters preserve supported upstream values, provenance, and confidentiality.
|
|
Exact Go declarations remain API design work under
|
|
[ADR 0003](0003-public-facade.md). Separate capability contracts allow new
|
|
operations to evolve independently of existing provider implementations.
|
|
|
|
`--scope NAME` selects one configuration. `all` denotes all registered scopes for
|
|
`config validate` and `config show`; `sources`, `explain`, and `diff` select one.
|
|
An aggregate selection retains its all-scope meaning. CommandKit checks operation
|
|
availability across the requested selection before acquiring views. An unavailable
|
|
operation yields a usage diagnostic identifying the scope and available choices,
|
|
so an aggregate result accurately describes the requested coverage.
|
|
|
|
`show`, `sources`, `explain`, and `diff` default to `app`; `validate` defaults to
|
|
`all`. Explicit selection remains available for narrower validation. These
|
|
selection defaults operate against the registered inventory and capabilities.
|
|
|
|
Scope order is `app` first when registered, `promptkit` next when registered,
|
|
then additional scopes sorted by identifier. `config scopes` and combined YAML
|
|
show use that order. The inventory reports identity, description, supported
|
|
operations, and selection defaults entirely from metadata. Discovery is available
|
|
independently of file loading.
|
|
|
|
CommandKit validates scope collisions, operation wiring, selector applicability,
|
|
and supported selections. It registers the standard operations supplied by at
|
|
least one scope, alongside metadata discovery. Help identifies their applicable
|
|
scopes; selection of an unsupported scope-operation pair yields a usage diagnostic.
|
|
|
|
Declared dependencies are coordinated under
|
|
[ADR 0008](0008-inspection-lifecycle.md). An inspection operation acquires its
|
|
selected scope and required prerequisites through that provider boundary.
|
|
|
|
A command family defines its own resources, supported verbs, and data contracts.
|
|
The configuration provider contract applies to configuration inspection. FeedKit
|
|
resource listing or display, for example, can use separate capabilities with
|
|
meanings consistent with shared verbs. A library integration can expose a command
|
|
family, configuration scope, or both, according to the provided capabilities.
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| Require every configuration inspection operation per scope | Gives one capability set. Missing comparison or provenance blocks other useful inspection operations. |
|
|
| A separate command tree for each configuration | Makes the target part of the path. Repeats common operations and help. |
|
|
| One verb set for every library family | Gives a uniform inventory. Resource domains acquire operations with little useful meaning. |
|
|
| Executable names as scope identifiers | Relates scopes to application branding. Shared scripts need application-specific identifiers. |
|
|
| Every operation defaults to `app` | Gives one selection default. Integrated validation becomes an explicit aggregate request. |
|
|
| Skip unsupported scopes during aggregate inspection | Produces available reports. The meaning and coverage of `all` become less apparent. |
|
|
| Public upstream result types as the provider API | Simplifies direct wiring. CommandKit acquires those type identities and release dependencies. |
|
|
|
|
## Consequences
|
|
|
|
A shared configuration family serves multiple configurations while help and
|
|
inventory make operation availability explicit. Individual capabilities can be
|
|
integrated before other upstream inspection APIs exist. Default and ordering
|
|
rules remain observable CommandKit behavior.
|
|
|
|
Scoped operations validate availability before loading. An `all` request can
|
|
report unsupported coverage; an explicit supported scope remains available.
|
|
The same verb purpose can serve different families with different operation sets.
|
|
|
|
[Selection inputs](0010-configuration-selection.md) define parsing and propagation;
|
|
[native YAML reporting](0007-native-yaml-reports.md) defines combined presentation.
|