signal

type AttributedClick struct {
	ContentRef
	Subject    Subject // who clicked; may differ from the render's subject
	Position   uint32  // position claimed by the click
	OccurredAt time.Time
	EventID    string
	// Exposed reports whether the clicked content is in the render's list at
	// the requested stage. False means "not exposed at this stage", never negative.
	Exposed bool
}

type AttributedRender struct {
	RenderID   string
	QueryID    string
	Surface    string
	Ranker     string
	Language   string
	Subject    Subject
	OccurredAt time.Time
	Shown      []Placement
	Clicks     []AttributedClick
	// Continued is true when earlier clicks of this render were on the previous
	// page: the header repeats, the clicks do not. Merge by RenderID.
	Continued bool
}

type Attribution struct {
	RenderID string // the Exposure.RenderID the click came from
	Surface  string
	Position uint32 // 1-based position of the clicked item within that render
}

type AttributionOptions struct {
	// Window bounds exposure and click days (zero = all time).
	Window Window
	// Stage is the exposure stage clicks are attributed against (required).
	Stage ExposureStage
	// Surface restricts renders to one surface (empty = all).
	Surface string
	// After is the opaque cursor from the previous page's Next (empty = start).
	After string
	// Limit caps renders per page (default DefaultAttributionRenders).
	Limit int
	// ClickLimit caps click rows per page, attributed and unattributed
	// together (default DefaultAttributionClicks). A render with more clicks
	// than fit continues on the next page.
	ClickLimit int
}

type AttributionPage struct {
	Renders []AttributedRender
	// Unattributed are clicks in the window whose render has no exposure at
	// the requested stage (prefetched, cancelled, hidden or never recorded):
	// they cannot label anything.
	Unattributed []AttributedClick
	// Next is the cursor for the following page; empty when done.
	Next string
}

type CoEngagedHit struct {
	ContentRef
	Strength int64
}

type CoEngagedOptions struct {
	// ContentKinds limits result kinds. Empty = all.
	ContentKinds []string
	// Window bounds the event scan. Zero = all time.
	Window Window
	// MaxSubjects caps the engaged-subject set read from the anchor
	// (defaults to 10000).
	MaxSubjects int
	// SkipRollup forces the query-time event scan even when the content_pairs
	// rollup has rows (e.g. for freshness-critical reads).
	SkipRollup bool
	Limit      int // default 50
}

type Conn interface {
	Exec(ctx context.Context, query string, args ...any) error
	Query(ctx context.Context, query string, args ...any) (driver.Rows, error)
}

type ContentKey = contentref.ContentKey

type ContentMetrics struct {
	Viewers     uint64 // subjects with at least one view
	UserViewers uint64
	AnonViewers uint64
	Views       uint64 // view events (sessions)
	Completions uint64 // completed views
	Completers  uint64 // subjects with a completed view
	ActiveS     uint64 // summed view DurationS
	ScoreSum    int64  // summed view scores; ScoreSum/Views is the mean
	// ViewerEngagementSum sums each viewer's mean session score, normalized
	// and clamped to [0,1]. Every viewer contributes at most one unit.
	ViewerEngagementSum float64
	ReturningViewers    uint64 // subjects with more than one canonical view in the window
	Events              uint64 // canonical events of every type
	ValueSum            float64
	// PositiveSubjects / NegativeSubjects: subjects whose summed feedback
	// Value in the window is > 0 / < 0.
	PositiveSubjects uint64
	NegativeSubjects uint64
	SignalCounts     map[string]uint64 // canonical events per type
}

type ContentRef = contentref.ContentRef

type ErasureReport struct {
	// Remaining counts rows still attributable to the subjects per table after
	// the pass; every value is zero when erasure is complete.
	Remaining map[string]uint64
	// PairsRemoved counts content_pairs rows invalidated because an erased
	// subject contributed to a work in them; RefreshCoEngagement rebuilds them.
	PairsRemoved uint64
}

type Exec interface {
	Exec(ctx context.Context, query string, args ...any) error
}

type Exposure struct {
	RenderID   string // required, stable per render, shared with its clicks
	Stage      ExposureStage
	Revision   uint64
	QueryID    string
	Surface    string
	Ranker     string // ranking configuration identity for offline comparison
	Language   string
	Subject    Subject // optional for anonymous renders
	Shown      []Placement
	OccurredAt time.Time // required
}

type ExposureStage string

type HistoryOptions struct {
	// ContentKind limits results to one kind. Empty = all kinds.
	ContentKind string
	Status      HistoryStatus
	// Since drops rows whose relevant activity is older (e.g. host "clear
	// history before X" features). Seen statuses use the last view; HistoryAny
	// uses the last signal. Zero = no lower bound.
	Since  time.Time
	Limit  int // default 50
	Offset int
}

type HistoryStatus string

type InventoryRow struct {
	ContentKind string
	SignalType  string
	Events      uint64 // canonical events
	RawRows     uint64 // stored rows incl. unmerged superseded revisions and retries
	Subjects    uint64
	// ContentItems counts distinct content ids (works and their versions
	// count once per id).
	ContentItems uint64
	FirstAt      time.Time
	LastAt       time.Time
}

type LimitError struct {
	Field string
	Limit int
	Got   int
}

type Placement struct {
	ContentRef
	Position uint32
}

type PopularHit struct {
	ContentRef
	ContentMetrics
	Score float64
}

type PopularOptions struct {
	Window Window
	Limit  int // default 20

	// Weights tunes the default ranking formula.
	Weights RankWeights

	// RankExpr, when set, REPLACES the default ranking with a host-supplied
	// ClickHouse expression (trusted SQL). It may reference the window metric
	// columns: viewers, user_viewers, anon_viewers, views, completions,
	// completers, active_s, score_sum, viewer_engagement_sum, returning_viewers,
	// events, value_sum, positive_subjects,
	// negative_subjects.
	RankExpr string
}

type ProjectionKey struct {
	ContentKey
	Subject Subject
}

type RankWeights struct {
	// PriorWeight is the strength of the Bayesian prior in pseudo-views.
	// Defaults to 10.
	PriorWeight float64
	// PriorScore is the prior mean engagement score. Defaults to 0.
	PriorScore float64
	// QualityFloor keeps pure-volume ranking meaningful when hosts record no
	// scores. Defaults to 1.
	QualityFloor float64
}

type RefreshCoEngagementOptions struct {
	// Window bounds which events feed the rollup (zero = all time).
	Window Window
	// MaxContentPerSubject caps each subject's contribution to pair
	// generation (defaults to 100), bounding the cross-product.
	MaxContentPerSubject int
}

type RepairOptions struct {
	// Window limits candidate keys to those with an event on these days
	// (zero = all time).
	Window Window
	// IngestedSince limits candidates to keys with a row ingested at or after
	// it: the crash-repair scan. Zero = no bound.
	IngestedSince time.Time
	// After resumes strictly after this key in key order (nil = start).
	After *ProjectionKey
	// Limit caps candidate keys examined per call (default 1000).
	Limit int
	// Rebuild reprojects every candidate instead of only stale ones: after a
	// projection semantics change, a restore or a legacy import.
	Rebuild bool
}

type RepairResult struct {
	Examined int
	Repaired int
	// Next is the cursor for the following call; nil when the range is done.
	Next *ProjectionKey
}

type SchemaMismatchError struct {
	Database string
	Problems []string
}

type Scored struct {
	Score       int16
	Progress    uint32
	ProgressMax uint32
	Completed   bool
}

type Scorer interface {
	Score(ctx context.Context, s Signal) (Scored, error)
}

type ScorerFunc func(ctx context.Context, s Signal) (Scored, error)

type Signal struct {
	ContentRef
	Subject Subject

	// Type is host-defined except TypeView.
	Type string

	// EventID is the required stable source identity. Retries must reuse it;
	// never mint a new id (or time) per delivery attempt.
	EventID string

	// Revision orders cumulative snapshots of one EventID (for example a
	// checkpointed consumption session, or a subject's current preference):
	// the highest revision is the event, lower ones are superseded. Leave 0 for
	// immutable events. Conflicting content at an equal revision resolves by a
	// deterministic content hash, not by arrival order.
	Revision uint64

	// OccurredAt is the required immutable source time (a session's start). It
	// selects the UTC day the event counts in.
	OccurredAt time.Time

	// Consumption measurements, cumulative for the revision.
	DurationS   uint32 // active time
	Progress    uint32 // numerator (pages / scroll % / watched s)
	ProgressMax uint32 // denominator (page count / 100 / duration)

	// Value is explicit feedback (+1 like, -1 dislike, rating). State and
	// windows sum the canonical values.
	Value float64

	// Score is the engagement score; a registered Scorer fills it together with
	// Progress/ProgressMax/Completed.
	Score int16

	// Completed per the content kind's completion rule.
	Completed bool

	// Resume is an opaque host pointer for "pick up where you left off".
	Resume string

	// Payload holds bounded context, JSON-encoded at rest.
	Payload map[string]any
}

type State struct {
	Seen         bool // MaxProgress > 0
	FirstSeenAt  time.Time
	LastSignalAt time.Time
	LastViewAt   time.Time
	TotalEvents  uint32 // canonical events of every type
	Views        uint32 // canonical view events (sessions)
	Completions  uint32 // completed views
	ActiveS      uint64 // summed view DurationS
	MaxProgress  uint32 // progress bar = MaxProgress / ProgressMax
	ProgressMax  uint32
	Completed    bool
	Resume       string // latest non-empty resume pointer
	LastScore    int16  // score of the latest view
	// NetValue sums canonical feedback Values. Negative = current sentiment is
	// negative; recommendations exclude such content.
	NetValue float64
	Feedback uint32 // canonical events with a non-zero Value
}

type StateRow struct {
	ContentRef
	State
}

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

type Subject struct {
	UserID  string
	AnonKey string
}

type TopStatesOptions struct {
	ContentKinds []string
	// ExcludeNegative drops content the subject has net-negative explicit
	// feedback for (a disliked item must not seed recommendations).
	ExcludeNegative bool
	Limit           int // default 10
}

type Window struct {
	From time.Time // inclusive UTC midnight
	To   time.Time // exclusive UTC midnight
}