correlation

type ActiveSession struct {
	AssetID        shared.ID
	EntityID       shared.ID
	IncidentID     shared.ID
	MinOccurredAt  time.Time
	MaxOccurredAt  time.Time
	ReflectedCount int
	MaxSeverity    shared.Severity
}

type Assignment struct {
	SignalID   shared.ID
	IncidentID shared.ID
	AssetID    shared.ID
	EntityID   shared.ID
	OccurredAt time.Time
	Severity   shared.Severity
	Outcome    AssignmentOutcome
}

type AssignmentOutcome string

type Checkpoint struct {
	Revision      uint64
	MaxObservedAt time.Time
	Watermark     time.Time
	Phase         Phase
	Completed     SourcePosition
	Snapshot      SourcePosition
	RetentionAsOf time.Time
	SourceCursor  SourcePosition
	StagedCursor  SignalPosition
	PolicyDigest  string
}

type Config struct {
	// Window is the session gap: within one (asset, entity) key, a signal more than Window after the
	// previous signal starts a NEW incident; otherwise it joins the current one. Must be > 0.
	Window time.Duration
	// MaxPerIncident caps how many signals an incident reflects individually (the Created signal plus
	// attaches). Beyond it, further signals are suppressed as a storm and recorded as a single note
	// (coverage-honest). Must be > 0.
	MaxPerIncident int
	// AllowedLateness is subtracted from the maximum observed event time to produce the
	// monotonic watermark used by incremental correlation. It must not be negative.
	AllowedLateness time.Duration
	// Actor is the attribution for emitted events; defaults to "correlator".
	Actor string
	// EngagementID is the authoritative scope stamped on newly created incidents.
	EngagementID shared.ID
	// PageSize bounds each source-materialization and staged-consumption invocation.
	// Zero uses the conservative default.
	PageSize int
	// MaxActiveSessions bounds the mutable state loaded into one correlation transaction.
	// Zero uses the conservative default.
	MaxActiveSessions int
	// MaxTimelineRefsPerDetection and MaxTimelineRefsPerPage bound causal fanout during source materialization.
	// Zero values use conservative defaults.
	MaxTimelineRefsPerDetection int
	MaxTimelineRefsPerPage      int
}

type IncrementalPlan struct {
	Events         []incident.IncidentEvent
	Added          []Assignment
	ActiveSessions []ActiveSession
	Next           Checkpoint
	TooLate        int
	Suppressed     int
	Evicted        int
}

type Phase string

type Signal struct {
	ID         shared.ID
	AssetID    shared.ID
	EntityID   shared.ID
	OccurredAt time.Time
	Severity   shared.Severity
	RuleID     string
	Title      string
	// Timeline is set only for a causally referenced endpoint transition.
	Timeline *incident.TimelineRef
}

type SignalPosition struct {
	OccurredAt time.Time
	ID         shared.ID
}

type SourcePosition struct {
	RecordedAt time.Time
	ID         shared.ID
}

type State struct {
	Checkpoint     Checkpoint
	KnownSignalIDs map[shared.ID]struct{}
	ActiveSessions []ActiveSession
}