5.0 KiB
ADR 0010: Compare Frozen Effective Configuration Snapshots
Status
Accepted. The feature roadmap owns the target contract and implementation status; the implementation plan 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.