Simplify ADRs and relax premature constraints

This commit is contained in:
2026-10-07 02:45:09 +00:00
parent 984d159676
commit 7e453a2df2
9 changed files with 165 additions and 310 deletions

View File

@@ -23,37 +23,13 @@ value semantics while making limited coverage visible to operators.
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.
before acquisition. Providers supply captured results through the owning
libraries' supported public inspection APIs.
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.
compared recursively; ordered sequences are compared as whole values.
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
@@ -67,9 +43,12 @@ 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
schema belongs in the CLI reference when implemented. Selection syntax,
inheritance rules, and detailed change records remain proposals in the
[CLI roadmap](../roadmap/01-cli-plan.md#config-diff).
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
@@ -81,14 +60,13 @@ writer failures use the operational failure classification in
| 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.
where sensitivity limits comparison. Whole-sequence comparison keeps
implementation scope focused at the cost of less detailed collection changes.
Diff support depends on safe snapshots preserving value semantics and sensitivity.
CommandKit applies this comparison policy to scopes declaring that capability.
@@ -96,6 +74,4 @@ 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.
assertion workflows.