99 lines
5.0 KiB
Markdown
99 lines
5.0 KiB
Markdown
# ADR 0010: Compare Frozen Effective Configuration Snapshots
|
|
|
|
## Status
|
|
|
|
Accepted. The [feature roadmap](../roadmap/diff.md) owns the target
|
|
contract and implementation status; the
|
|
[implementation plan](../roadmap/implementation.md) owns execution order.
|
|
|
|
## Date
|
|
|
|
2026-10-09
|
|
|
|
## Context
|
|
|
|
Applications need to inspect how two completed configurations differ, including
|
|
the effective impact of an overlay after defaults and application resolution.
|
|
ConfigKit already retains canonical typed inspection snapshots, semantic paths,
|
|
presence information, and sensitivity classification for successful loads.
|
|
|
|
Extending this inspection model lets applications share configuration comparison
|
|
and safe disclosure while keeping their presentation and domain interpretation.
|
|
The operation should follow ConfigKit's existing equality, ownership, and secret
|
|
boundaries so consumers can reason about loading and inspection consistently.
|
|
|
|
## Decision
|
|
|
|
Provide structured effective-value comparison between successful results of the
|
|
same configuration type. Compare their retained canonical inspection snapshots
|
|
through the root-owned public facade. Each comparison uses the completed load
|
|
state and returns detached records with a semantic path and safe left and right
|
|
value snapshots.
|
|
|
|
Use canonical value equality and the existing structural comparison rules.
|
|
Mappings compare recursively, sequences report atomic changes, and scalar or
|
|
kind replacements report the affected region. Presence distinguishes additions
|
|
and removals from explicit null. Equal effective values produce an empty diff;
|
|
source attribution, explicit-input status, and history remain separately
|
|
inspectable through each result. Canonical pointer ordering makes reporting
|
|
deterministic.
|
|
|
|
Detect changes before masking values. Apply sensitivity from both loads to both
|
|
returned sides, including historical and dependency-derived classification.
|
|
Preserve public content where the shapes permit corresponding sensitive regions
|
|
to be identified. When a structural replacement prevents safe correspondence,
|
|
mask the complete reported replacement region on both present sides. Absence
|
|
retains its own representation.
|
|
|
|
Keep masking and hidden-change information distinct. Each record indicates
|
|
whether an actual change is withheld by redaction, allowing applications to
|
|
display a changed-sensitive-value indicator even when safe snapshots render
|
|
identically. Public-only changes alongside unchanged masked content retain that
|
|
distinction.
|
|
|
|
Typed secret references participate through their configured environment names.
|
|
Resolved credential bytes remain behind the existing explicit secret accessor.
|
|
The comparison uses the same frozen inspection boundary as effective rendering
|
|
and explanation.
|
|
|
|
ConfigKit owns comparison and paired safe disclosure. Applications own labels,
|
|
layout, and rendering of the returned changed regions. Reusing the existing
|
|
snapshot representation and engine boundary keeps the extension consistent with
|
|
the library's established inspection model.
|
|
|
|
## Alternatives considered
|
|
|
|
- **Compare input text or separately rendered YAML.** Supports familiar textual
|
|
displays, but input text precedes composition and resolution, and independently
|
|
redacted output can hide changes or apply different disclosure rules. Canonical
|
|
comparison with paired masking represents the completed configuration.
|
|
- **Leave comparison to applications using returned Go values.** Offers direct
|
|
access to application types, but duplicates structural and redaction machinery
|
|
and observes caller mutation. Retained inspection snapshots preserve the
|
|
completed load's values and established ownership boundary.
|
|
- **Align sequence elements and return context-rich rendering data.** Enables
|
|
finer-grained displays, but requires additional correspondence and disclosure
|
|
rules. Atomic sequence records and existing value snapshots satisfy the
|
|
selected changed-region workflows with a smaller public model.
|
|
- **Compare resolved credentials or retain credential-derived tokens.** Could
|
|
detect rotation behind an unchanged reference, but expands retained sensitive
|
|
state and introduces a separate trusted comparison mechanism. Reference-name
|
|
comparison preserves the existing inspection boundary.
|
|
|
|
## Consequences
|
|
|
|
Applications can compare independently loaded configurations using ConfigKit's
|
|
shared equality, presence, and disclosure rules. Existing composition and load
|
|
semantics continue to determine the values being compared. Caller mutation of a
|
|
returned configuration leaves its retained comparison snapshot unchanged.
|
|
|
|
Paired redaction can conceal public content within a structurally incompatible
|
|
replacement. The changed region and hidden-change indicator still communicate
|
|
its effective impact. Credential rotation behind an unchanged environment name
|
|
produces equal reference values for comparison.
|
|
|
|
The implementation requires operation-local disclosure preparation and focused
|
|
coverage for presence, shape changes, historical sensitivity, and detached
|
|
results. Applications retain control of presentation; changed-region records
|
|
supply the safe data needed for that responsibility.
|