base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Finalize native comparison ADRs and clarify declaration contracts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-11 18:59:57 +00:00
parent fbee871731
commit 21c2fde8d5
6 changed files with 280 additions and 180 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
docs/adr/0008-semantic-configuration-diff.md
View File

@@ -1,4 +1,4 @@
# ADR 0008: Compare semantic snapshots with explicit sensitivity gaps
# ADR 0008: Delegate effective configuration comparison to owning libraries
## Status
@@ -6,72 +6,79 @@ Accepted.
## Date
2026-10-06
2026-10-06; revised 2026-10-11.
## Context
Configuration comparison helps operators understand changes in final effective
values across roots and overlays. Formatting, authored file layout, and provenance
identifiers are different properties from effective-value equality. Sensitivity
classification also limits the values available for inspection.
Meaningful comparison requires structured effective snapshots with per-path
sensitivity data from the owning libraries. The comparison policy must preserve
value semantics while making limited coverage visible to operators.
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
For a scope declaring safe comparison support, `config diff` compares two
independently resolved effective configurations. CommandKit checks that capability
before acquisition. Providers supply captured results through the owning
libraries' supported public inspection APIs.
### Comparison ownership
Compare values using the owning library's safe structured inspection semantics,
including defaults and recorded domain resolution. Preserve the distinctions
among absent values, null, empty mappings, and empty sequences. Mappings are
compared recursively; ordered sequences are compared as whole values.
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.
For each path, use the union of the two sides' sensitivity classifications to
protect both before and after presentation. A value classified on either side
receives the corresponding safe treatment in both snapshots. Hidden values
produce explicit comparison gaps with their paths and supported reasons.
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.
Equality conclusions cover the comparable data. A comparison with gaps reports
its limited coverage alongside observed differences. A complete comparison with
an empty difference set supports an equality conclusion for the inspected
selection. Redaction masks are presentation data; classification metadata
determines comparison coverage.
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.
Text and YAML reports include differences and coverage gaps. The exact report
schema belongs in the [CLI reference](../cli.md) when implemented. Selection
syntax, inheritance rules, and detailed change records are outside the scope
of this decision.
### Safe disclosure and presentation
A completed comparison returns success whether it finds differences or gaps;
load, comparison, and writer failures use the operational failure classification in
[ADR 0005](0005-invocation-outcomes.md).
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 |
| --- | --- |
| Rendered YAML line comparison | Reuses native display output. Formatting and masking become part of change interpretation. |
| Compare masks as literal strings | Uses visible snapshot bytes directly. Equal masks express equal presentation while hidden values remain uncertain. |
| Use one side's sensitivity policy | Simplifies classification selection. A value's disclosure treatment depends on which snapshot supplies that policy. |
| Fetch secret values for comparison | Gives access to additional equality evidence. Comparison acquires sensitive material and additional confidentiality responsibilities. |
| Element-by-element sequence diff | Gives detailed collection changes. Stable element identity and alignment need another comparison contract. |
| A distinct status for observed differences | Supports assertion-oriented scripts. Inspection completion and change detection share an outcome signal. |
| 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
Operators receive meaningful effective-value changes with explicit uncertainty
where sensitivity limits comparison. Whole-sequence comparison keeps
implementation scope focused at the cost of less detailed collection changes.
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).
Diff support depends on safe snapshots preserving value semantics and sensitivity.
CommandKit applies this comparison policy to scopes declaring that capability.
Other operations and families can be integrated independently under
[ADR 0004](0004-standard-inspection-surface.md).
Applications can use the successful report as input to domain decisions or future
assertion workflows.
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.