embedworker

type Config struct {
	// Interval is how often a full embed pass runs. A pass also runs
	// once immediately at startup to clear the standing backlog.
	Interval time.Duration

	// MaxBackoff caps the jittered exponential backoff applied between
	// passes while the pass keeps failing on infrastructure (database or
	// embedding backend unreachable), so an outage costs one line per
	// retry at a widening cadence instead of hammering a dead backend
	// every Interval.
	MaxBackoff time.Duration

	// DrainTimeout bounds graceful shutdown: after the run context is
	// canceled, an in-flight pass may keep running this long before its
	// store/backend calls are aborted.
	DrainTimeout time.Duration

	// Ready optionally backs the readiness probe. Nil reports ready as
	// soon as the worker exists.
	Ready ReadyFunc

	// Metrics optionally injects a pre-built metrics surface so the
	// hosting command can mount /metrics before the store is reachable.
	// NewWorker builds a fresh one when nil.
	Metrics *Metrics
}

type Metrics struct {

	// Passes counts embed passes by outcome: ok / error (an
	// infrastructure failure — candidate listing or prune — that aborted
	// the pass; per-span failures are not pass failures).
	Passes *prometheus.CounterVec

	// PassDuration is the wall time of one full pass.
	PassDuration prometheus.Histogram

	// Per-span outcomes accumulated across passes. Together they close the
	// identity scanned = embedded + upToDate + empty + poisoned + failed,
	// so a dashboard can both account for every candidate and SEE the
	// re-stream cost: the embed pass lists and renders every main llm
	// span each pass, so a high upToDate (or scanned) with embedded≈0 is
	// the wasteful-rescan signature, invisible if only embedded/failed
	// were exposed. Failed is a per-span embed/write error retried next
	// pass; UpToDate skipped because content+model already match; Empty
	// skipped because the delta rendered to no embeddable text; Poisoned
	// skipped because the span already failed deterministically under this
	// content and model.
	SpansScanned  prometheus.Counter
	SpansEmbedded prometheus.Counter
	SpansUpToDate prometheus.Counter
	SpansEmpty    prometheus.Counter
	SpansPoisoned prometheus.Counter
	SpansFailed   prometheus.Counter

	// SpansChunked counts spans whose text exceeded the model context
	// window and was embedded as several pieces; ChunkRows counts the
	// pieces written (so chunked spans contribute more than one row).
	SpansChunked prometheus.Counter
	ChunkRows    prometheus.Counter

	// Oversize counts spans the model rejected as too large; OversizeTokens
	// is the distribution of their reported/estimated token sizes — the
	// answer to "how big are the inputs we're chunking?".
	Oversize       prometheus.Counter
	OversizeTokens prometheus.Histogram

	// SpanFailures counts deterministic per-span failures by reason (e.g.
	// oversize, api_400) — the recorded, non-retried failures, a subset of
	// SpansFailed broken out for alerting on a specific cause.
	SpanFailures *prometheus.CounterVec

	// OrphansPruned counts embedding rows removed because their span no
	// longer exists as a main llm span.
	OrphansPruned prometheus.Counter

	// ConsecutiveFailures mirrors the worker's in-memory outage counter:
	// non-zero means passes are currently failing on infrastructure and
	// backing off. Alert on sustained non-zero.
	ConsecutiveFailures prometheus.Gauge

	// LastSuccessTimestamp is the Unix time of the last successful pass.
	// Alert on staleness (time() - metric > interval): it catches a
	// wedged-but-not-erroring worker, which ConsecutiveFailures cannot.
	LastSuccessTimestamp prometheus.Gauge
	// contains filtered or unexported fields
}

type Pass interface {
	Run(ctx context.Context) (*spanembed.Report, error)
}

type ReadyFunc func(ctx context.Context) error

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