sync

type DependencyDecision uint8

type DependencyDecisionHandler func(context.Context, sources.ID, sources.Dependency, bool) (DependencyDecision, error)

type Option func(*Options)

type Options struct {
	// Orchestration control
	DryRun  bool          // Show changes without applying them
	Timeout time.Duration // Timeout for the entire sync operation

	// Source selection
	Sources    []sources.ID         // Which external/human sources to use; verified embedded always participates.
	ProviderID *catalogs.ProviderID // Filter for specific provider

	// Human workspace used for both local observation and materialization.
	CatalogPath string

	// Source behavior control
	Fresh              bool   // Delete existing models and fetch fresh from APIs (destructive)
	CleanModelsDevRepo bool   // Remove temporary models.dev repository after update
	Reformat           bool   // Reformat providers.yaml file even without changes
	SourcesDir         string // Directory for external source data (models.dev cache/git)
	ModelsDevGitCommit string // Exact models.dev commit required by Git verification

	// Dependency control
	AutoInstallDeps   bool // Automatically install missing dependencies without prompting
	SkipDepPrompts    bool // Skip dependency prompts and continue without optional dependencies
	RequireAllSources bool // Require every configured source to return a complete, successful, nonempty observation

	// DependencyDecisionHandler is supplied by an interactive adapter. It is nil
	// for library, server, scheduler, and other noninteractive callers.
	DependencyDecisionHandler DependencyDecisionHandler
}

type ProjectionResult = projection.Result

type ProjectionStatus = projection.Status

type ProviderResult struct {
	ProviderID catalogs.ProviderID  // The provider that was synced
	Added      []catalogs.Model     // New models not in catalog
	Updated    []differ.ModelUpdate // Existing models with changes
	Removed    []catalogs.Model     // Models in catalog but not in API (informational only)

	// Summary counts
	AddedCount   int // Number of models added
	UpdatedCount int // Number of models updated
	RemovedCount int // Number of models removed from API (not deleted from catalog)

	// Metadata
	APIModelsCount      int // Total models fetched from API
	ExistingModelsCount int // Total models that existed in catalog
	EnhancedCount       int // Number of models enhanced with models.dev data
}

type Result struct {
	// Overall statistics
	TotalChanges     int                                     // Total number of changes across all providers
	ProvidersChanged int                                     // Number of providers with changes
	ProviderResults  map[catalogs.ProviderID]*ProviderResult // Results per provider

	// Operation metadata
	DryRun      bool   // Whether this was a dry run
	Fresh       bool   // Whether this was a fresh sync
	CatalogPath string // Human workspace used by the synchronization
	Sources     []sources.ID
	// SourceObservations contains caller-owned freshness/audit projections from
	// every source used by this attempt, including no-change synchronizations.
	SourceObservations []catalogs.SourceObservationLink
	GenerationID       string // Durable generation activated by a non-dry sync
	SyncRunID          string // Correlation ID for the synchronization attempt
	Projection         *ProjectionResult
	// ReviewCandidates contains deterministic non-fatal records excluded
	// from the published canonical catalog after source authority resolution.
	ReviewCandidates []evidence.ReviewCandidate
}