reconciler

reconcile

Package reconcile provides complex multi-source data reconciliation with field-level authority and provenance tracking.

reconciler

import "github.com/agentstation/starmap/pkg/reconciler"

Package reconciler provides catalog synchronization and reconciliation capabilities. It handles merging data from multiple sources, detecting changes, and applying updates while respecting data authorities and merge strategies.

Index

• func ConvertCatalogsMapToSources(srcs map[sources.Type]catalogs.Catalog) []sources.Source
• func NewMockSource(sourceType sources.Type, catalog catalogs.Catalog) sources.Source
• type AuthorityStrategy
  • func (s *AuthorityStrategy) ResolveConflict(field string, values map[sources.Type]any) (any, sources.Type, string)
• type Merger
• type Option
  • func WithAuthorities(authorities authority.Authority) Option
  • func WithBaseline(catalog catalogs.Catalog) Option
  • func WithEnhancers(enhancers ...enhancer.Enhancer) Option
  • func WithProvenance(enabled bool) Option
  • func WithStrategy(strategy Strategy) Option
• type Reconciler
  • func New(opts ...Option) (Reconciler, error)
• type Result
  • func NewResult() *Result
  • func (r *Result) Finalize()
  • func (r *Result) HasChanges() bool
  • func (r *Result) IsSuccess() bool
  • func (r *Result) Summary() string
  • func (r *Result) WasApplied() bool
• type ResultMetadata
• type ResultStatistics
• type SourceOrderStrategy
  • func (s *SourceOrderStrategy) ResolveConflict(_ string, values map[sources.Type]any) (any, sources.Type, string)
• type Strategy
  • func NewAuthorityStrategy(authorities authority.Authority) Strategy
  • func NewSourceOrderStrategy(priorityOrder []sources.Type) Strategy
• type StrategyType
  • func (s StrategyType) Name() string
  • func (s StrategyType) String() string
• type ValidationError
• type ValidationResult
  • func (v *ValidationResult) HasWarnings() bool
  • func (v *ValidationResult) IsValid() bool
  • func (v *ValidationResult) String() string
• type ValidationWarning

func ConvertCatalogsMapToSources

func ConvertCatalogsMapToSources(srcs map[sources.Type]catalogs.Catalog) []sources.Source

ConvertCatalogsMapToSources converts the old map format to sources slice for testing.

func NewMockSource

func NewMockSource(sourceType sources.Type, catalog catalogs.Catalog) sources.Source

NewMockSource creates a new mock source for testing.

type AuthorityStrategy

AuthorityStrategy uses field authorities to resolve conflicts.

type AuthorityStrategy struct {
    // contains filtered or unexported fields
}

func (*AuthorityStrategy) ResolveConflict

func (s *AuthorityStrategy) ResolveConflict(field string, values map[sources.Type]any) (any, sources.Type, string)

ResolveConflict uses authorities to resolve conflicts.

type Merger

Merger performs the actual merging of resources.

type Merger interface {
    // Models merges models from multiple sources
    Models(sources map[sources.Type][]catalogs.Model) ([]catalogs.Model, provenance.Map, error)

    // Providers merges providers from multiple sources
    Providers(sources map[sources.Type][]catalogs.Provider) ([]catalogs.Provider, provenance.Map, error)
}

type Option

Option is a function that configures a Reconciler.

type Option func(*options) error

func WithAuthorities

func WithAuthorities(authorities authority.Authority) Option

WithAuthorities sets the field authorities.

func WithBaseline

func WithBaseline(catalog catalogs.Catalog) Option

WithBaseline sets an existing catalog to compare against for change detection.

func WithEnhancers

func WithEnhancers(enhancers ...enhancer.Enhancer) Option

WithEnhancers adds model enhancers to the pipeline.

func WithProvenance

func WithProvenance(enabled bool) Option

WithProvenance enables field-level tracking.

func WithStrategy

func WithStrategy(strategy Strategy) Option

WithStrategy sets the merge strategy.

type Reconciler

Reconciler is the main interface for reconciling data from multiple sources.

type Reconciler interface {
    // Sources reconciles multiple catalogs from different sources
    // The primary source determines which models exist; other sources provide enrichment only
    Sources(ctx context.Context, primary sources.Type, srcs []sources.Source) (*Result, error)
}

func New

func New(opts ...Option) (Reconciler, error)

New creates a new Reconciler with options.

type Result

Result represents the outcome of a reconciliation operation.

type Result struct {
    // Core data
    Catalog        catalogs.Catalog
    Changeset      *differ.Changeset
    AppliedChanges *differ.Changeset

    // Tracking maps
    ProviderAPICounts map[catalogs.ProviderID]int
    ModelProviderMap  map[string]catalogs.ProviderID

    // Metadata
    Metadata ResultMetadata

    // Provenance tracking
    Provenance provenance.Map

    // Issues
    Errors   []error
    Warnings []string
}

func NewResult

func NewResult() *Result

NewResult creates a new result with defaults.

func (*Result) Finalize

func (r *Result) Finalize()

Finalize calculates duration and marks completion.

func (*Result) HasChanges

func (r *Result) HasChanges() bool

HasChanges returns true if any changes were detected.

func (*Result) IsSuccess

func (r *Result) IsSuccess() bool

IsSuccess returns true if the reconciliation was successful.

func (*Result) Summary

func (r *Result) Summary() string

Summary returns a human-readable summary of the result.

func (*Result) WasApplied

func (r *Result) WasApplied() bool

WasApplied returns true if changes were applied.

type ResultMetadata

ResultMetadata contains metadata about the reconciliation process.

type ResultMetadata struct {
    // StartTime when reconciliation started
    StartTime time.Time

    // EndTime when reconciliation completed
    EndTime time.Time

    // Duration of the reconciliation
    Duration time.Duration

    // Sources that were reconciled
    Sources []sources.Type

    // Strategy used for reconciliation
    Strategy Strategy

    // DryRun indicates if this was a dry-run
    DryRun bool

    // Statistics about the reconciliation
    Stats ResultStatistics
}

type ResultStatistics

ResultStatistics contains statistics about the reconciliation.

type ResultStatistics struct {
    ModelsProcessed    int
    ProvidersProcessed int
    ConflictsResolved  int
    ResourcesSkipped   int
    TotalTimeMs        int64
}

type SourceOrderStrategy

SourceOrderStrategy resolves conflicts using a fixed source precedence order. Sources earlier in the priority slice have higher precedence than sources later in the slice.

type SourceOrderStrategy struct {
    // contains filtered or unexported fields
}

func (*SourceOrderStrategy) ResolveConflict

func (s *SourceOrderStrategy) ResolveConflict(_ string, values map[sources.Type]any) (any, sources.Type, string)

ResolveConflict uses source priority order to resolve conflicts.

type Strategy

Strategy defines how reconciliation should be performed.

type Strategy interface {
    // Type returns the strategy type
    Type() StrategyType

    // Description returns a human-readable description
    Description() string

    // ShouldMerge determines if resources should be merged
    ShouldMerge(resourceType sources.ResourceType) bool

    // ResolveConflict determines how to resolve conflicts
    ResolveConflict(field string, values map[sources.Type]any) (any, sources.Type, string)

    // ValidateResult validates the reconciliation result
    ValidateResult(result *Result) error

    // ApplyStrategy returns how changes should be applied
    ApplyStrategy() differ.ApplyStrategy
}

func NewAuthorityStrategy

func NewAuthorityStrategy(authorities authority.Authority) Strategy

NewAuthorityStrategy creates a new authority-based strategy.

func NewSourceOrderStrategy

func NewSourceOrderStrategy(priorityOrder []sources.Type) Strategy

NewSourceOrderStrategy creates a new source priority order strategy. The priorityOrder slice determines precedence: earlier elements have higher priority.

type StrategyType

StrategyType represents the type of reconciliation strategy.

type StrategyType string

const (
    // StrategyTypeFieldAuthority uses field-specific authority scores to resolve conflicts.
    StrategyTypeFieldAuthority StrategyType = "field-authority"
    // StrategyTypeSourceOrder uses source ordering to resolve conflicts.
    StrategyTypeSourceOrder StrategyType = "source-order"
)

func (StrategyType) Name

func (s StrategyType) Name() string

Name returns the name of the strategy type.

func (StrategyType) String

func (s StrategyType) String() string

String returns the string representation of a strategy type.

type ValidationError

ValidationError represents a validation error.

type ValidationError struct {
    ResourceType sources.ResourceType
    ResourceID   string
    Field        string
    Message      string
}

type ValidationResult

ValidationResult represents the result of validating a catalog or changeset.

type ValidationResult struct {
    Valid    bool
    Errors   []ValidationError
    Warnings []ValidationWarning
}

func (*ValidationResult) HasWarnings

func (v *ValidationResult) HasWarnings() bool

HasWarnings returns true if there are warnings.

func (*ValidationResult) IsValid

func (v *ValidationResult) IsValid() bool

IsValid returns true if validation passed.

func (*ValidationResult) String

func (v *ValidationResult) String() string

String returns a string representation of the validation result.

type ValidationWarning

ValidationWarning represents a validation warning.

type ValidationWarning struct {
    ResourceType sources.ResourceType
    ResourceID   string
    Field        string
    Message      string
}

Generated by gomarkdoc