spanembed

type Candidate struct {
	OrgID     string
	TraceID   string
	SpanID    string
	SessionID string // "" when the span derived without attribution

	// Input and Output are the span's stored delta-only content-block
	// arrays (JSONB), nil when empty.
	Input  json.RawMessage
	Output json.RawMessage

	// ExistingHash and ExistingModel describe the current embedding
	// row; both empty when the span has never been embedded.
	ExistingHash  string
	ExistingModel string

	// ExistingFailHash and ExistingFailModel describe a recorded
	// deterministic embed failure; both empty when the span has no
	// failure marker. A span whose current content and model match a
	// recorded failure is skipped instead of re-attempted.
	ExistingFailHash  string
	ExistingFailModel string
}

type ChunkRecord struct {
	OrgID       string
	TraceID     string
	SpanID      string
	SessionID   string
	Model       string
	ContentHash string
	Embeddings  [][]float32
}

type FailureRecord struct {
	OrgID       string
	TraceID     string
	SpanID      string
	SessionID   string
	Model       string
	ContentHash string
	Reason      string
	ErrorDetail string
	TokenCount  int
}

type Hit struct {
	TraceID    string
	SpanID     string
	SessionID  string
	Score      float32
	UserPrompt string
	Snippet    string
	Model      string
	StartedAt  time.Time
}

type Key struct {
	OrgID   string
	TraceID string
	SpanID  string
}

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

type PassConfig struct {
	// Model names the embedding model; stored per row so a model
	// switch re-embeds existing spans.
	Model string

	// Dimensions is the expected embedding dimensionality. The first
	// vector the model returns is checked against it, so a
	// model/dims misconfiguration aborts the pass with one clear
	// error instead of failing every row's insert against the sized
	// vector column.
	Dimensions uint

	// BatchSize bounds one candidate page (default DefaultBatchSize).
	BatchSize int

	// MaxTextBytes caps a span's rendered text; a larger span is recorded
	// as a "too_large" failure rather than embedded, bounding per-span
	// memory, chunk count, and embed cost. Zero takes DefaultMaxTextBytes;
	// negative disables the guard.
	MaxTextBytes int
}

type Report struct {
	// Scanned counts every candidate span considered.
	Scanned int `json:"scanned"`
	// Embedded counts spans embedded this pass (new or re-embedded
	// after a content/model change).
	Embedded int `json:"embedded"`
	// UpToDate counts spans skipped because their embedding already
	// matches the current content and model.
	UpToDate int `json:"up_to_date"`
	// Empty counts spans skipped because their delta content renders
	// to no text at all (e.g. a pure tool-call response).
	Empty int `json:"empty"`
	// Poisoned counts spans skipped because they already failed
	// deterministically under this content and model; they are not
	// re-attempted until their content or model changes.
	Poisoned int `json:"poisoned"`
	// Chunked counts spans whose text exceeded the model's context
	// window and was split into multiple embedded pieces.
	Chunked int `json:"chunked"`
	// ChunkRows counts total embedding rows written this pass (one per
	// piece), so chunked spans contribute more than one.
	ChunkRows int `json:"chunk_rows"`
	// Oversized counts spans the model rejected as too large (whether the
	// split then succeeded or exhausted the depth cap).
	Oversized int `json:"oversized"`
	// Failed counts spans whose embed or write failed this pass — both
	// transient faults (retried next pass) and deterministic ones (also
	// recorded and skipped thereafter).
	Failed int `json:"failed"`
	// Pruned counts orphaned embedding rows removed (their span was
	// pruned or reclassified by a re-derive).
	Pruned int64 `json:"pruned"`

	// OversizeTokens holds the reported/estimated token count of each
	// oversized span this pass — the per-observation source for the embed
	// worker's oversize-tokens histogram. Excluded from JSON to keep the
	// logged summary scalar.
	OversizeTokens []int `json:"-"`
	// FailuresByReason counts deterministic failures recorded this pass,
	// keyed by reason (e.g. "oversize", "api_400"). Excluded from JSON.
	FailuresByReason map[string]int `json:"-"`
}

type Sink interface {
	UpsertSpanChunks(ctx context.Context, rec ChunkRecord) error
	RecordFailure(ctx context.Context, rec FailureRecord) error
	PruneOrphans(ctx context.Context) (int64, error)
}

type Source interface {
	ListCandidates(ctx context.Context, after Key, limit int) ([]Candidate, error)
}

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

type StoreConfig struct {
	// TableName defaults to DefaultTableName.
	TableName string

	// Dimensions is the embedding dimensionality. The table's vector
	// column is created with exactly this size and EnsureSchema
	// fail-fasts when an existing table disagrees — model and dims are
	// a deliberate, explicit pairing (e.g. text-embedding-3-large@1024
	// in cloud, embeddinggemma@768 on a local/dev deployment).
	Dimensions uint

	// OrgID optionally scopes candidate listing and orphan pruning to
	// one tenant. Empty embeds every org.
	OrgID string
}