85 lines
4.3 KiB
Markdown
85 lines
4.3 KiB
Markdown
# ADR 0008: Delegate effective configuration comparison to owning libraries
|
|
|
|
## Status
|
|
|
|
Accepted.
|
|
|
|
## Date
|
|
|
|
2026-10-06; revised 2026-10-11.
|
|
|
|
## Context
|
|
|
|
ConfigKit provides a native configuration comparison capability. Exposing it
|
|
through CommandKit gives applications a consistent operator interface and reduces
|
|
repeated command, selection, and reporting infrastructure. ConfigKit remains the
|
|
authority for the meaning and disclosure of its comparison results.
|
|
|
|
## Decision
|
|
|
|
### Comparison ownership
|
|
|
|
For ConfigKit-backed scopes declaring comparison support, `config diff` exposes
|
|
ConfigKit's native comparison API. CommandKit checks capability availability before
|
|
acquisition and coordinates selection, acquisition, adaptation, presentation,
|
|
and invocation outcomes.
|
|
|
|
Integrations delegate comparison to their owning libraries' supported public
|
|
APIs. ConfigKit owns its comparison semantics and disclosure rules. CommandKit
|
|
follows the public contract of the ConfigKit version it adopts. When an adopted
|
|
upstream revision changes those semantics, the changes flow through to
|
|
CommandKit's integration. Upstream remains authoritative as the capability evolves.
|
|
|
|
Application-supplied providers retain ownership of their implementation and
|
|
loading effects. [ADR 0012](0012-typed-configuration-comparison-pairs.md) governs
|
|
paired selections, provider contracts, and typed input/shared-state lifetimes.
|
|
|
|
### Safe disclosure and presentation
|
|
|
|
Adapt and present native comparison results in accordance with the adopted
|
|
upstream API's disclosure contract. The integration carries the upstream results
|
|
and relevant metadata through its public provider boundary.
|
|
|
|
CommandKit owns report presentation and may summarize or transform the returned
|
|
safe comparison data for different operator needs. Reports may vary in format,
|
|
organization, and detail while respecting safe disclosure and the evidence
|
|
provided by the comparison. Each report's documented meaning defines the
|
|
conclusions an operator can draw from it.
|
|
|
|
Report formats, schemas, and rendering choices belong in the
|
|
[CLI reference](../cli.md) when implemented. They can evolve independently of
|
|
this ownership decision under the [release policy](../policy/release.md).
|
|
|
|
### Invocation outcomes
|
|
|
|
A completed comparison returns success regardless of whether differences are
|
|
reported. Load, comparison, and writer
|
|
failures use the operational failure classification in
|
|
[ADR 0005](0005-invocation-outcomes.md). Applications may use comparison results
|
|
to make their own domain decisions.
|
|
|
|
## Alternatives considered
|
|
|
|
| Alternative | Analysis |
|
|
| --- | --- |
|
|
| Compare safe snapshots in CommandKit | Gives CommandKit direct control over comparison, but requires it to maintain equality and sensitivity logic and account for values already withheld from snapshots. Native comparison keeps those responsibilities with the owning library. |
|
|
| Compare rendered configuration text | Reuses existing output, but formatting and masking affect the apparent differences. Native comparison supplies evidence grounded in the library's effective-value model. |
|
|
| Leave comparison commands entirely to applications | Preserves application flexibility, but repeats selection, acquisition coordination, and presentation infrastructure across consumers. Integration providers retain application control within the common command system. |
|
|
| Return a distinct status when differences are found | Supports assertion-oriented scripts, but couples successful inspection with a policy judgment about the result. The selected outcome model leaves that judgment to consumers. |
|
|
|
|
## Consequences
|
|
|
|
CommandKit supplies consistent comparison commands while relying on owning
|
|
libraries for comparison semantics and safe disclosure. Dependency adoption
|
|
includes adapting the integration and its documentation to upstream changes.
|
|
New library integrations
|
|
are assessed through their supported comparison contracts; each scope can expose
|
|
its available capabilities independently under
|
|
[ADR 0009](0009-configuration-scopes.md).
|
|
|
|
Reports can serve different operator needs using the same native comparison
|
|
data. Their level of detail may differ, and sensitivity rules may limit what
|
|
can be shown. Maintaining the boundary between comparison evidence and report
|
|
presentation allows those reports to evolve while preserving library ownership
|
|
and consumer control.
|