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.ID]*catalogs.Builder) []sources.Observation
• func NewMockSource(sourceType sources.ID, catalog *catalogs.Builder) sources.Observation
• type AuthorityStrategy
  • func NewAuthorityStrategy(authorities authority.Authority) *AuthorityStrategy
  • func (s *AuthorityStrategy) ResolveConflict(field string, values map[sources.ID]any) (any, sources.ID, string)
  • func (s *AuthorityStrategy) ResolveResourceConflict(resourceType sources.ResourceType, field string, values map[sources.ID]any) (any, sources.ID, string)
• 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)
  • func (r *Reconciler) Sources(ctx context.Context, primary sources.ID, srcs []sources.Observation) (*Result, 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 NewSourceOrderStrategy(priorityOrder []sources.ID) *SourceOrderStrategy
  • func (s *SourceOrderStrategy) ResolveConflict(_ string, values map[sources.ID]any) (any, sources.ID, string)
  • func (s *SourceOrderStrategy) ResolveResourceConflict(_ sources.ResourceType, _ string, values map[sources.ID]any) (any, sources.ID, string)
• 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.ID]*catalogs.Builder) []sources.Observation

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

func NewMockSource

func NewMockSource(sourceType sources.ID, catalog *catalogs.Builder) sources.Observation

NewMockSource creates a direct observation for testing.

type AuthorityStrategy

AuthorityStrategy uses field authorities to resolve conflicts.

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

func NewAuthorityStrategy

func NewAuthorityStrategy(authorities authority.Authority) *AuthorityStrategy

NewAuthorityStrategy creates a new authority-based strategy.

func (*AuthorityStrategy) ResolveConflict

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

ResolveConflict uses authorities to resolve conflicts.

func (*AuthorityStrategy) ResolveResourceConflict

func (s *AuthorityStrategy) ResolveResourceConflict(resourceType sources.ResourceType, field string, values map[sources.ID]any) (any, sources.ID, string)

ResolveResourceConflict uses resource-specific authorities to resolve conflicts.

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 combines data from multiple sources into a canonical catalog. It is concrete because this package has one reconciliation engine; extension points are accepted through the narrow Strategy, Authority, Source, and Enhancer interfaces.

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

func New

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

New creates a new Reconciler with options.

func (*Reconciler) Sources

func (r *Reconciler) Sources(ctx context.Context, primary sources.ID, srcs []sources.Observation) (*Result, error)

Sources performs reconciliation with clean step-by-step flow.

type Result

Result represents the outcome of a reconciliation operation.

type Result struct {
    // Core data
    Catalog        *catalogs.Builder
    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.ID

    // 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 NewSourceOrderStrategy

func NewSourceOrderStrategy(priorityOrder []sources.ID) *SourceOrderStrategy

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

func (*SourceOrderStrategy) ResolveConflict

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

ResolveConflict uses source priority order to resolve conflicts.

func (*SourceOrderStrategy) ResolveResourceConflict

func (s *SourceOrderStrategy) ResolveResourceConflict(_ sources.ResourceType, _ string, values map[sources.ID]any) (any, sources.ID, string)

ResolveResourceConflict resolves conflicts by source order; resource type does not affect this strategy.

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.ID]any) (any, sources.ID, string)

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

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

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