oracle

type CheckContext struct {
	Ledger *ledger.Store
	// History carries the system-under-test's own databases. Nil skips
	// history-kind checks.
	History *HistoryChannel
	// Metrics carries the run's Prometheus. Nil skips metrics-kind checks.
	Metrics   *MetricsChannel
	PostDrain bool      // the run has quiesced: liveness checks may assert emptiness
	Now       time.Time // evaluation instant (deadline comparisons)
	// Window bounds verification to the sessions and workflows created in
	// [Since, Until). A zero bound leaves that side unbounded.
	// Metrics checks diverge one-sidedly: their ranges cover [Since, Now]
	// rather than [Since, Until), because terminals recorded during the
	// drain tail must stay in range.
	Window Window
	// RetentionWindow floors the directory reconciliation's lookback so
	// engine retention is not mistaken for corruption; zero means
	// DefaultRetentionWindow.
	RetentionWindow time.Duration
	// contains filtered or unexported fields
}

type CheckFunc func(ctx context.Context, cc *CheckContext) (*Result, error)

type CheckKind int

type Class int

type HistoryChannel struct {
	Central  *pgxpool.Pool
	Workflow []WorkflowDB // every workflow DB in the deployment
}

type Invariant struct {
	Name        string // kebab-case, unique
	Class       Class
	Kind        CheckKind
	Severity    Severity
	Description string // one or two sentences, rendered into the catalog
	DocAnchor   string // optional doc/autocore.md anchor for background
	Check       CheckFunc
}

type InvariantResult struct {
	Name       string      `json:"name"`
	Class      Class       `json:"class"`
	Kind       CheckKind   `json:"kind"`
	Severity   Severity    `json:"severity"`
	Checked    int64       `json:"checked"`
	Violations []Violation `json:"violations,omitempty"`
	Skipped    bool        `json:"skipped,omitempty"`
	SkipReason string      `json:"skip_reason,omitempty"`
}

type MetricsChannel struct {
	// Query evaluates one instant PromQL query at the given instant and sums
	// the resulting vector to a single value. An empty vector sums to 0.
	Query func(ctx context.Context, promql string, at time.Time) (float64, error)
}

type Report struct {
	Results []InvariantResult `json:"results"`
}

type Result struct {
	Checked    int64       // population size examined
	Violations []Violation // empty = pass
	Skipped    bool        // channel not configured / not applicable in this mode
	SkipReason string
}

type Severity int

type Violation struct {
	Detail  string `json:"detail"`            // human-readable, self-contained
	Subject string `json:"subject,omitempty"` // session id / workflow key the violation anchors to, if any
}

type Window struct {
	Since time.Time
	Until time.Time
}

type WorkflowDB struct {
	Name string           // identifies the DB in violation details
	DBID persistence.DBID // identity in the central registry, for shard routing checks
	Pool *pgxpool.Pool
}