5.6 KiB
ADR 0008: Compare semantic snapshots with explicit sensitivity gaps
Status
Proposed
Date
2026-10-06
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.
Decision
For a scope declaring safe comparison support, config diff compares two
independently resolved effective configurations. CommandKit checks that capability
before acquisition. Registered root, overlay, context, and override selectors
define the left side where applicable. The initial application-root/ConfigKit
integration uses --against-config PATH, --against-overlay NAME, or both to
select the right side. Other comparison
source models can declare applicable paired selectors through the input extension
contract under ADR 0010.
Unspecified right selectors inherit the resolved left selection. Discovery is
resolved for the left selection once. An omitted right overlay inherits the left
overlay; the explicit overlay name default selects the base. Domain selectors
and typed overrides apply identically to both sides for the initial operation.
CommandKit requests each resolved side through the inspection provider under
ADR 0008. The provider supplies the captured result
according to its public loading and validation contract.
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. A container replacement produces one change at the replaced path.
Changes are classified as added, removed, or changed and sorted by JSON
Pointer configuration paths, consistent with the ConfigKit integration. Reports
contain safe before/after snapshots and resolved selection metadata. Presentation
and source identity retain their own metadata roles, while value comparison
operates on the effective semantic representation.
CommandKit's comparison provider contract accepts effective values and sensitivity metadata through supported public inspection APIs. The comparison handler consumes inspection-safe data and uses supplied redaction classifications. Secret resolution remains part of the upstream or callback loading lifecycle.
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.
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.
Text and YAML reports include differences and coverage gaps. The exact report schema belongs in the CLI reference when implemented. A completed comparison returns success whether it finds differences or gaps; load, comparison, and writer failures use the operational failure classification in ADR 0005.
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. |
| Independent domain selectors for each side | Supports broader context comparison. The operation acquires duplicated selector sets and pairing rules. |
| A distinct status for observed differences | Supports assertion-oriented scripts. Inspection completion and change detection share an outcome signal. |
Consequences
Operators receive meaningful effective-value changes with explicit uncertainty where sensitivity limits comparison. Stable path ordering and whole-sequence comparison keep reports understandable and implementation scope focused.
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.
Applications can use the successful report as input to domain decisions or future assertion workflows. Separate left/right loading and safe union classification need evidence for presence, container replacement, sensitivity changes, and coverage gaps.