ingest

type AgentIdentifier interface {
	AgentIdentities() []AgentIdentity
}

type AgentIdentity struct {
	Authority string
	SameAs    []string
}

type Attribution struct {
	Source string
	// Basis names the match kind ("isbn", "title+author").
	Basis string
	// Key is the value that matched: the shared ISBN, or the peer's
	// title/author strings.
	Key string `json:",omitempty"`
	// Ref is a verifiable link (the peer OPAC's record page).
	Ref string `json:",omitempty"`
}

type AuthoritySubject = bibframe.AuthoritySubject

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

type Config struct {
	Feed   string
	Source string
	Params map[string]string
}

type CreatorClaim struct {
	QID        string
	Label      string
	Claims     []DemographicClaim
	MatchedVia string
	Retrieved  string
}

type CreatorSummary struct {
	QID    string
	Claims []DemographicClaim `json:",omitempty"`
}

type DemographicClaim struct {
	Property   string
	ValueQID   string
	ValueLabel string
}

type Endorsement struct {
	Count   int
	Sources []string
	// Attributions, when present, carry each source's verifiable claim.
	Attributions []Attribution `json:",omitempty"`
}

type EnrichStats struct {
	// Batches is how many external queries ran; SkippedBatches how many were
	// abandoned after retries (their works untouched; a re-run backfills).
	Batches        int `json:"batches"`
	SkippedBatches int `json:"skippedBatches,omitempty"`
	// Total, when a source can size its run up front (the bibliocommons
	// harvest drives one search per driver term), is the count Batches
	// progresses toward, in the source's own unit. 0 means the run sizes
	// lazily and progress is indeterminate.
	Total int `json:"total,omitempty"`
	// ResolvedCreators / Claims count what the run brought back.
	ResolvedCreators int `json:"resolvedCreators,omitempty"`
	Claims           int `json:"claims,omitempty"`
	// Candidates counts subject candidates found SO FAR, live -- honest
	// label: queue-time dedup and tombstone skips happen after the run,
	// so the final queued tally can be lower.
	Candidates int `json:"candidates,omitempty"`
	// ElapsedMS is the wall time inside the enricher's Enrich calls.
	ElapsedMS int64 `json:"elapsedMs"`
}

type Enricher interface {
	Name() string
	Enrich(ctx context.Context, works []WorkSummary) ([]Enrichment, error)
}

type Enrichment struct {
	WorkID   string
	Subjects []AuthoritySubject
	// Identities are outward links to external hubs, rendered as
	// owl:sameAs into the enrichment graph alongside any subjects.
	Identities []ExternalIdentity
	// Terms carries standalone term descriptions -- typically the
	// skos:broader ancestor chains of Subjects -- asserted into the
	// enrichment graph as labels + hierarchy only, with no link to the Work
	//. They keep ancestor nodes labeled in projections that roll
	// subtree data up the hierarchy even when no work carries the ancestor
	// directly.
	Terms []AuthoritySubject
	// Creators are the Work's creators resolved to external knowledge-base
	// entities carrying explicitly-stated demographic claims (the
	// creator-demographics audit axis; ingest/wikidata). Rendered into the
	// enrichment graph as a work->entity link plus the entity's claims and
	// resolution provenance.
	Creators []CreatorClaim
	// Confidence (0-1] qualifies queue-moderated enrichments; direct-mode
	// callers may threshold on it.
	Confidence float64
	// Origins, when present, parallels Subjects: Origins[i] names what
	// produced Subjects[i] in the source's own terms -- the uncontrolled
	// tag a reconciler matched, the work subject a crosswalk pivoted from,
	// the harvested heading -- so a queue row can say "from X".
	Origins []string `json:",omitempty"`
	// Endorsements, when present, parallels Subjects: Endorsements[i]
	// records the peer sources corroborating Subjects[i], so queue mode
	// can rank cross-source consensus above singletons.
	Endorsements []Endorsement `json:",omitempty"`
}

type ExternalIdentity struct {
	URI    string
	Scheme string
}

type ExtraProvider interface {
	Extras() map[string]string
}

type Factory func(Config) (Provider, error)

type MergeSeed struct {
	FromKey string
	ToKey   string
}

type MergeSeeder interface {
	MergeSeeds() []MergeSeed
}

type Provider interface {
	Name() string
	Role() Role
	Records(ctx context.Context) ([]Record, error)
}

type ReconcileResult struct {
	// Flagged Works were newly marked withdrawn this pass.
	Flagged int
	// Suppressed Works were auto-suppressed this pass.
	Suppressed int
	// Cleared Works returned to the feed and lost their withdrawal flag.
	Cleared int
	// Unsuppressed Works returned and lost a reconcile-set suppression.
	Unsuppressed int
	// FlaggedIDs lists the newly withdrawn Works, sorted.
	FlaggedIDs []string
}

type Record interface {
	Identity() identity.Record
	Work() codexbf.Work
	Instance() codexbf.Instance
}

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

type Result struct {
	Stats           bibframe.BuildStats
	MintedWorks     int
	MintedInstances int
	Retired         int
	Conflicts       []string
	// WorkIDs are the Works this run's records resolved to -- the presence
	// set the feed reconciliation pass diffs the corpus against.
	WorkIDs []string
}

type Role int

type StatsReporter interface {
	RunStats() EnrichStats
}

type SubjectEnricher interface {
	ControlledSubjects() []AuthoritySubject
}

type SummarySource interface {
	SummariesWithPaths(ctx context.Context) ([]WorkSummary, map[string]string, error)
}

type TermDescriber interface {
	DescribedTerms() []AuthoritySubject
}

type VerbatimProvider interface {
	Verbatim() []string
}

type WorkSummary struct {
	WorkID       string
	Title        string
	Contributors []string
	// ContributorIDs are the contributors' authority IRIs, where agents
	// arrive as IRI nodes (MARC $0/$1 via the crosswalk, or editor
	// hydration) -- the identifier-based creator-resolution keys
	// (VIAF/LCNAF/ISNI/ORCID -> Wikidata). Unordered, deduped.
	ContributorIDs []string `json:",omitempty"`
	ISBNs          []string
	// Tags are the Work's uncontrolled subject labels (feed genres,
	// approved folksonomy) -- the raw material tag-to-controlled-term
	// reconciliation enrichers match against.
	Tags []string
	// Subjects are the Work's controlled subject IRIs (bf:subject with an
	// IRI object, any graph) -- what authority merges rewrite.
	Subjects []string
	// Headings are the heading labels of those controlled subjects, where the
	// grain describes them (skos:prefLabel or rdfs:label on the authority
	// node) -- the keyword dimension of the diversity audit. Unordered and not
	// paired with Subjects: the audit unions per-work category hits, so
	// pairing carries no extra signal.
	Headings []string `json:",omitempty"`
	// Creators are the Work's creators as resolved by the wikidata
	// enrichment (lcat:creatorIdentity in the grain): entity id + cached
	// explicit claims. Deliberately no display label -- the creator audit is
	// aggregate-only and never lists people.
	Creators []CreatorSummary `json:",omitempty"`
	// Series and Languages are the similarity scorer's two strongest signals
	//: two books in one series are related whatever else they
	// share, and a reader of one language is rarely served a book in another.
	// Series holds the Work's series statements, read off its bf:relation
	// series relations; Languages are bf:language local names ("en").
	Series    []string `json:",omitempty"`
	Languages []string `json:",omitempty"`
	// Visibility and holdings signals for the admin works list:
	// the editor deliberately shows everything, so each row says what the
	// public projection would do with it.
	Suppressed bool   `json:",omitempty"`
	Tombstoned bool   `json:",omitempty"`
	Withdrawn  string `json:",omitempty"` // date the feed reconciliation flagged it
	Kept       bool   `json:",omitempty"` // curator keeps it despite withdrawal
	// Items counts physical holdings across the Work's instances;
	// HasAvailability reports a live-availability identifier (a digital
	// holding as long as the Work is not withdrawn).
	Items           int  `json:",omitempty"`
	HasAvailability bool `json:",omitempty"`
	// Extras carries the Work's lcat:extra/* literals -- deployment-defined
	// key/value metadata the feed graph attaches (bibframe.addWorkExtras),
	// e.g. sources: "loc, mombian". The admin works view facets provenance
	// on configured keys; multi-valued keys are comma-joined by
	// convention and split at facet time.
	Extras map[string]string `json:",omitempty"`
}