provenance

type AuditResult struct {
	Valid       bool
	Issues      []string
	Warnings    []string
	Coverage    float64  // Percentage of fields with provenance
	Conflicts   int      // Number of unresolved conflicts
	MissingData []string // Fields without provenance
}

type ConflictInfo struct {
	Sources        []catalogmeta.SourceID // Sources that had conflicting values
	Values         []any                  // The conflicting values
	Resolution     string                 // How the conflict was resolved
	SelectedSource catalogmeta.SourceID   // Which source was selected
}

type Field struct {
	Current   Provenance     // Current value and its source
	History   []Provenance   // Historical values
	Conflicts []ConflictInfo // Any conflicts that were resolved
}

type Map map[string][]Provenance // key is "resourceType:resourceID:fieldPath"

type Provenance struct {
	Source           catalogmeta.SourceID            // Source that provided the value (e.g., "providers", "models_dev_git")
	Field            string                          // Field path
	Value            any                             // The actual value
	Timestamp        time.Time                       // When the value was set
	ObservationID    string                          // Stable identity of the winning source observation
	ObservedAt       time.Time                       // When the winning source was observed
	Revision         catalogmeta.ObservationRevision // Exact revision of the winning observation
	EvidenceChecksum string                          // Digest binding the winning normalized evidence
	Rejections       []Rejection                     // Higher-authority observations rejected before selection
	Authority        float64                         // Authority score (0.0 to 1.0)
	Confidence       float64                         // Confidence in the value (0.0 to 1.0)
	Reason           string                          // Reason for selecting this value
	PreviousValue    any                             // Previous value if updated
}

type ProvenanceFile struct {
	Provenance Map `yaml:"provenance"`
}

type Rejection struct {
	Source catalogmeta.SourceID // Source whose field observation was rejected
	Reason string               // Stable human-readable validation or applicability reason
}

type Report struct {
	Resources map[string]ResourceProvenance // key is "resourceType:resourceID"
}

type ResourceProvenance struct {
	Type   catalogmeta.ResourceType // Resource type (e.g., "model", "provider", "author")
	ID     string
	Fields map[string]Field
}

type Tracker interface {
	// Track records provenance for a field
	Track(resourceType catalogmeta.ResourceType, resourceID string, field string, history Provenance)

	// Find retrieves provenance for a specific field
	FindByField(resourceType catalogmeta.ResourceType, resourceID string, field string) []Provenance

	// FindByResource retrieves all provenance for a resource
	FindByResource(resourceType catalogmeta.ResourceType, resourceID string) map[string][]Provenance

	// Map returns the complete provenance map
	Map() Map

	// Clear removes all provenance data
	Clear()
}