Add configuration comparison capability contract

integrations/ckconfig/contracts.go

@@ -29,6 +29,8 @@ const (
 	Sources Operation = "sources"
 	// Explain reports the history and provenance of a selected path.
 	Explain Operation = "explain"
+	// Diff compares two selections of the same configuration scope.
+	Diff Operation = "diff"
 )
 
 // Request describes one configuration operation and its selected inputs.
@@ -39,6 +41,24 @@ type Request struct {
 	Selection Selection
 }
 
+// ComparisonSide groups one configuration selection with its independently
+// prepared typed input.
+type ComparisonSide[I any] struct {
+	// Selection carries the explicit config and overlay inputs for this side.
+	Selection Selection
+	// Input is initialized and checked for this side before comparison.
+	Input I
+}
+
+// ComparisonRequest carries the earlier and later selections supplied to a
+// scope's comparison callback.
+type ComparisonRequest[I any] struct {
+	// Left is the earlier configuration selection.
+	Left ComparisonSide[I]
+	// Right is the later configuration selection.
+	Right ComparisonSide[I]
+}
+
 // EffectiveWriter writes a configuration's native effective representation.
 type EffectiveWriter interface {
 	WriteEffective(io.Writer) error
@@ -63,9 +83,11 @@ type View struct {
 	Explanation ExplanationReader
 }
 
-// Scope declares the operations and acquisition callback for one named
-// configuration. Construction issues are retained privately until family
-// assembly attaches them to its command declaration.
+// Scope declares the operations and providers for one named configuration.
+// Ordinary inspection operations use Acquire; Diff uses Compare and does not
+// require Acquire unless an ordinary operation is also declared. Construction
+// issues are retained privately until family assembly attaches them to its
+// command declaration.
 type Scope[I, S any] struct {
 	// Name identifies the scope in CLI selection and reports.
 	Name string
@@ -73,8 +95,12 @@ type Scope[I, S any] struct {
 	Summary string
 	// Operations selects the standard handlers exposed for this scope.
 	Operations []Operation
-	// Acquire loads the selected configuration for one inspection invocation.
+	// Acquire loads the selected configuration for one ordinary inspection
+	// 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.
+	Compare func(context.Context, ComparisonRequest[I], S) (commandkit.Acquired[[]configkit.Difference], error)
 
 	issues []error
 }