Document configuration comparison behavior

integrations/ckconfig/contracts.go

@@ -17,7 +17,7 @@ type Selection struct {
 	Overlay commandkit.Supplied[string]
 }
 
-// Operation identifies a supported configuration inspection operation.
+// Operation identifies a supported standard configuration operation.
 type Operation string
 
 const (
@@ -42,7 +42,8 @@ type Request struct {
 }
 
 // ComparisonSide groups one configuration selection with its independently
-// prepared typed input.
+// initialized and checked typed input. The supplied-state fields of Selection
+// are preserved for the scope's loader.
 type ComparisonSide[I any] struct {
 	// Selection carries the explicit config and overlay inputs for this side.
 	Selection Selection
@@ -51,7 +52,8 @@ type ComparisonSide[I any] struct {
 }
 
 // ComparisonRequest carries the earlier and later selections supplied to a
-// scope's comparison callback.
+// scope's comparison callback. Each side has a separately prepared input; the
+// callback receives shared invocation state separately.
 type ComparisonRequest[I any] struct {
 	// Left is the earlier configuration selection.
 	Left ComparisonSide[I]
@@ -99,7 +101,9 @@ type Scope[I, S any] struct {
 	// invocation.
 	Acquire func(context.Context, Request, I, S) (commandkit.Acquired[View], error)
 	// Compare compares two selections for this scope using one shared state.
-	// It is required when Diff is declared in Operations.
+	// Its Acquired result carries native difference records and diagnostics;
+	// returned errors retain their supported cause identity. It is required when
+	// Diff is declared in Operations.
 	Compare func(context.Context, ComparisonRequest[I], S) (commandkit.Acquired[[]configkit.Difference], error)
 
 	issues []error
@@ -116,24 +120,28 @@ type Selector[I any] struct {
 // Suite declares the typed input, shared state, selectors, and configuration
 // scopes used to assemble configuration commands.
 //
-// Input initialization is separate for each selected scope; state is shared
-// by that invocation's acquisitions. Factory results and callback effects remain
+// Input initialization is separate for each selected ordinary scope and each
+// reached comparison side; state is shared by the invocation's acquisitions or
+// comparison callback. Factory results and callback effects remain
 // caller-owned: Command does not deep-copy arbitrary objects or repair aliases
 // returned by factories. Core-owned repeated flag collections are copied when
 // applied to separate inputs. Factories are not invoked during construction,
 // installation, help, version, or scope discovery, and need not run after failure.
 type Suite[I, S any] struct {
-	// NewInput is called once for each selected scope reached after operation
-	// preflight, before applying its selectors and calling CheckInput.
+	// NewInput is called once for each selected ordinary scope, or once for each
+	// reached side of a comparison, after operation preflight and before applying
+	// selectors and calling CheckInput.
 	// If nil, input is the zero value of I, including nil for pointer types.
 	NewInput func() I
-	// NewState is called once when acquisition is reached, after all selected
-	// inputs pass their checks. The result is shared by selected acquisitions.
+	// NewState is called once when provider execution is reached, after all
+	// selected inputs pass their checks. The result is shared by selected
+	// acquisitions or the comparison callback.
 	// If nil, state is the zero value of S, including nil for pointer types.
 	NewState func() S
 	// Selectors declares typed flags and their applicable scopes.
 	Selectors []Selector[I]
-	// CheckInput validates one initialized scope input after applicable values are applied.
+	// CheckInput validates one initialized scope input after applicable values
+	// are applied. Comparison sides are checked separately with their selection.
 	CheckInput func(scope string, selection Selection, input I) error
 	// Scopes declares the configuration scopes assembled by Command.
 	Scopes []Scope[I, S]