enrich

type Describer interface {
	Describe() string
}

type HostScoped interface {
	ForHosts(hosts []string) ingest.Enricher
}

type Job struct {
	ID string `json:"id"`
	// Kind is the empty enrichment kind unless this is a bulk queue action.
	Kind   JobKind `json:"kind,omitempty"`
	Source string  `json:"source"`
	// Approve is the queue scope for a QUEUE_APPROVE job (nil otherwise): the
	// snapshot of pending rows the run approves is taken from this filter.
	Approve *suggest.QueueQuery `json:"approve,omitempty"`
	// Done/Total are generic progress for a QUEUE_APPROVE run (enrichment uses
	// Stats instead): rows acted on so far, out of the kick-time snapshot.
	Done  int `json:"done,omitempty"`
	Total int `json:"total,omitempty"`
	// ApproveResult is the completed bulk-approve tally (DONE, QUEUE_APPROVE).
	ApproveResult *suggest.ApproveAllResult `json:"approveResult,omitempty"`
	// Filters are the run's [key, value] scope terms (ingest.MatchExtras
	// semantics -- the same scoping the synchronous run and the audit use).
	Filters [][2]string `json:"filters,omitempty"`
	// Hosts is the per-job peer-host override, for sources that take one
	// (the bibliocommons harvest): sweep a different peer list without a
	// restart. Empty keeps the source's configured hosts.
	Hosts []string `json:"hosts,omitempty"`
	// Target names what this run talks to (the source's descriptor at
	// creation, host overrides applied) -- stamped on the record so a
	// finished job still says what it pulled after the config changes.
	Target    string    `json:"target,omitempty"`
	Requester string    `json:"requester"`
	Status    JobStatus `json:"status"`
	// Stats is the live progress while RUNNING (updated per statsInterval
	// when the source reports counters) and the final tallies after.
	Stats *ingest.EnrichStats `json:"stats,omitempty"`
	// Result is the completed run's summary (DONE only).
	Result *Result `json:"result,omitempty"`
	// Error is the failure, classified the same way the synchronous
	// endpoint classifies it (FAILED only; generic, detail in the log).
	Error      string    `json:"error,omitempty"`
	CreatedAt  time.Time `json:"createdAt"`
	StartedAt  time.Time `json:"startedAt,omitzero"`
	FinishedAt time.Time `json:"finishedAt,omitzero"`
	// HeartbeatAt is the worker's liveness signal, rewritten on every stats
	// tick while the run is in flight; a RUNNING record whose heartbeat goes
	// stale is an orphan (its process died mid-run) and the next drain
	// fails it rather than leaving it RUNNING forever.
	HeartbeatAt time.Time `json:"heartbeatAt,omitzero"`
}

type JobKind string

type JobStatus string

type Mode string

type Result struct {
	Source string `json:"source"`
	Mode   Mode   `json:"mode"`
	// Works is the number of Works enriched (direct) or with candidates
	// queued (queue).
	Works int `json:"works"`
	// Suggestions is the exact count of NEW queue rows this run created
	// (queue mode): pairs already suggested, tombstoned, or resolved are
	// silent no-ops and do not count.
	Suggestions int `json:"suggestions,omitempty"`
	// Scope names the run's filter ("" when the whole corpus).
	Scope string `json:"scope,omitempty"`
	// Stats carries the enricher's own run counters (batches, skips,
	// resolved, elapsed) when the source reports them.
	Stats *ingest.EnrichStats `json:"stats,omitempty"`
}

type Service struct {
	Blob        blob.Store
	GrainPrefix string
	Queue       *suggest.Service
	Sources     map[string]Source
	// Summaries, when set, is the shared maintained summary source
	// (workindex) queue-mode runs read instead of a per-run
	// corpus walk; nil falls back to ScanSummaries.
	Summaries ingest.SummarySource
	// DB, when set, enables the async job surface (jobs.go): kick returns a
	// job id, a worker drains, GET polls live progress. Nil keeps runs
	// synchronous-only.
	DB store.Store
	// MaxParallel caps how many jobs a single drain runs at once across
	// distinct sources; 0 is unlimited (one per queued source). The drain
	// never runs two jobs of the SAME source concurrently regardless.
	MaxParallel int
	// Now overrides the job clock (tests).
	Now func() time.Time
	// contains filtered or unexported fields
}

type Source struct {
	Enricher ingest.Enricher
	Mode     Mode
	// Scheme keys the queued TermRefs (e.g. "lcsh"); queue mode only.
	Scheme string
}