78 lines
3.9 KiB
Markdown
78 lines
3.9 KiB
Markdown
# 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 remain proposals in the
|
|
[CLI roadmap](../roadmap/01-cli-plan.md#config-diff).
|
|
|
|
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).
|
|
|
|
## 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](0004-standard-inspection-surface.md).
|
|
|
|
Applications can use the successful report as input to domain decisions or future
|
|
assertion workflows.
|