102 lines
5.6 KiB
Markdown
102 lines
5.6 KiB
Markdown
# 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](0010-configuration-selection.md).
|
|
|
|
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](0008-inspection-lifecycle.md). 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](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. |
|
|
| 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](0004-standard-inspection-surface.md).
|
|
|
|
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.
|