package ontology

import (
	"context"
	"errors"
)

// ErrThrottled signals a source hit its provider rate limit (a 429). The ingester treats it as a soft
// stop: it keeps and reports whatever was ingested before the limit.
var ErrThrottled = errors.New("ontology: source rate limited")

// OntologySource is the provider adapter contract, one per free federal vocabulary feed. Each handles its
// own paging internally and calls yield once per normalized record. A yield error stops the pull and is
// returned, so a storage or database failure aborts the run fail closed.
type OntologySource interface {
	// Name is the provenance label stamped on every record this source yields (for example PSC Manual).
	Name() string
	// Fetch pulls the source's scope and calls yield once per normalized record. On a provider rate limit
	// it returns ErrThrottled so the ingester can stop that source gracefully.
	Fetch(ctx context.Context, yield func(VocabRecord) error) error
}