Simplify ADRs and relax premature constraints
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user