3.9 KiB
ADR 0008: Compare semantic snapshots with explicit sensitivity gaps
Status
Accepted.
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. Providers supply captured results through the owning
libraries' supported public inspection APIs.
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 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. Selection syntax, inheritance rules, and detailed change records are outside the scope of this decision.
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. |
| 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. Whole-sequence comparison keeps implementation scope focused at the cost of less detailed collection changes.
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.