From 3697a511242d60c860549f09f02b75d1eb2fe660 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 9 Oct 2026 12:10:56 +0000 Subject: [PATCH] Accept the effective configuration diff decision --- docs/adr/0010-effective-configuration-diff.md | 98 +++++++++++++++++++ 1 file changed, 98 insertions(+) create mode 100644 docs/adr/0010-effective-configuration-diff.md diff --git a/docs/adr/0010-effective-configuration-diff.md b/docs/adr/0010-effective-configuration-diff.md new file mode 100644 index 0000000..876f550 --- /dev/null +++ b/docs/adr/0010-effective-configuration-diff.md @@ -0,0 +1,98 @@ +# 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.