commandkit/docs/adr/0008-semantic-configuration-diff.md

# 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.