provenance

package
v0.5.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 13, 2026 License: AGPL-3.0 Imports: 12 Imported by: 0

Documentation

Overview

Package provenance provides field-level tracking of data sources and modifications.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ModelResourceID added in v0.2.0

func ModelResourceID(providerID, modelID string) string

ModelResourceID returns the durable provider-scoped identity used for model provenance. Provider and model identifiers are opaque and escaped independently so slashes, colons, and percent signs cannot make two identities collide with one another or with the provenance key format.

func ParseModelResourceID added in v0.2.0

func ParseModelResourceID(resourceID string) (providerID, modelID string, ok bool)

ParseModelResourceID decodes an identity produced by ModelResourceID.

Types

type AuditResult

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
}

AuditResult contains audit findings.

type ConflictInfo

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

ConflictInfo describes a conflict that was resolved.

type Entry added in v0.2.0

type Entry struct {
	Source           evidence.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         evidence.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
}

Entry records the origin and history of one field value.

func (Entry) MarshalJSON added in v0.2.0

func (e Entry) MarshalJSON() ([]byte, error)

MarshalJSON makes interface-valued evidence independent of the concrete Go type used to construct it. This is required for immutable catalog payloads: after a payload is decoded, Value and PreviousValue contain generic JSON maps rather than the original source structs, but re-encoding must reproduce the exact generation bytes.

func (Entry) MarshalYAML added in v0.4.0

func (e Entry) MarshalYAML() ([]byte, error)

MarshalYAML uses the same canonical dynamic-value shape as MarshalJSON so a human workspace can reproduce the exact immutable catalog payload.

type Field

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

Field contains provenance history for a single field.

type File added in v0.2.0

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

File represents provenance stored on disk.

func Load added in v0.0.23

func Load(path string) (*File, error)

Load reads provenance data from a YAML file. Returns nil, nil if the file doesn't exist (not an error).

type Map

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

Map tracks provenance for multiple resources.

type Rejection added in v0.1.0

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

Rejection records why a higher-authority field observation did not win.

type Report

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

Report generates a human-readable provenance report.

func GenerateReport

func GenerateReport(provenance Map) *Report

GenerateReport creates a provenance report from a Map.

func (*Report) String

func (r *Report) String() string

String generates a string representation of the provenance report.

type ResourceProvenance

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

ResourceProvenance contains provenance for a single resource.

type Tracker

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

Tracker records and queries field-level provenance.

func NewTracker

func NewTracker(enabled bool) *Tracker

NewTracker creates a new provenance tracker.

func (*Tracker) Clear

func (p *Tracker) Clear()

Clear removes all provenance data.

func (*Tracker) FindByField

func (p *Tracker) FindByField(resourceType evidence.ResourceType, resourceID string, field string) []Entry

FindByField retrieves provenance for a specific field.

func (*Tracker) FindByResource

func (p *Tracker) FindByResource(resourceType evidence.ResourceType, resourceID string) map[string][]Entry

FindByResource retrieves all provenance for a resource.

func (*Tracker) Map

func (p *Tracker) Map() Map

Map returns the complete provenance map.

func (*Tracker) Track

func (p *Tracker) Track(resourceType evidence.ResourceType, resourceID string, field string, history Entry)

Track records provenance for a field.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL