store

Documentation

Overview

Package store provides the persistence interface for periscope test results, rolling baselines, calibration data, and history management.

All implementations must be safe for concurrent reads. Writes are serialized by the caller (the single result-collector goroutine in runner.TestRunner).

Index

• Variables
• type Baseline
• type HistoryFilter
• type SQLiteStore
  • func NewSQLiteStore(path string) (*SQLiteStore, error)
  • func (s *SQLiteStore) AddCalibrationExample(ctx context.Context, example judge.CalibrationExample) (int64, error)
  • func (s *SQLiteStore) Close() error
  • func (s *SQLiteStore) GetBaseline(ctx context.Context, toolName string, dim types.Dimension) (*Baseline, error)
  • func (s *SQLiteStore) GetCalibrationExamples(ctx context.Context, rubricID string) ([]judge.CalibrationExample, error)
  • func (s *SQLiteStore) GetHistory(ctx context.Context, filter HistoryFilter) ([]*result.TestRun, error)
  • func (s *SQLiteStore) GetLatestCalibrationResult(ctx context.Context, rubricID string) (*judge.CalibrationResult, error)
  • func (s *SQLiteStore) GetTestRunByID(ctx context.Context, runID string) (*result.TestRun, error)
  • func (s *SQLiteStore) ListDistinctTools(ctx context.Context) ([]ToolDimensionPair, error)
  • func (s *SQLiteStore) PruneHistory(ctx context.Context, olderThan time.Time) (int64, error)
  • func (s *SQLiteStore) SaveCalibrationResult(ctx context.Context, res judge.CalibrationResult) error
  • func (s *SQLiteStore) SaveTestRun(ctx context.Context, run *result.TestRun) error
  • func (s *SQLiteStore) UpdateBaseline(ctx context.Context, toolName string, dim types.Dimension) error
• type Store
• type ToolDimensionPair

Variables

var (
	ErrNoBaseline    = errors.New("store: no baseline found for this tool/dimension")
	ErrNotFound      = errors.New("store: record not found")
	ErrAlreadyExists = errors.New("store: record already exists")
)

Sentinel errors.

Types

type Baseline

type Baseline struct {
	ToolName      string          `json:"toolName"`
	Dimension     types.Dimension `json:"dimension"`
	ComputedAt    time.Time       `json:"computedAt"`
	P95MSMean     float64         `json:"p95MsMean"`
	P99MSMean     float64         `json:"p99MsMean"`
	ErrorRateMean float64         `json:"errorRateMean"`
	RunCount      int             `json:"runCount"`
}

Baseline holds the rolling performance metrics used for regression detection.

type HistoryFilter

type HistoryFilter struct {
	Since     time.Time
	Until     time.Time
	MaxRuns   int
	ToolName  string
	Dimension types.Dimension
}

HistoryFilter controls which runs are returned by GetHistory.

type SQLiteStore

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

SQLiteStore implements Store using a SQLite database.

Concurrency model:

• Reads (GetBaseline, GetHistory, GetCalibrationExamples, etc.) are safe for concurrent access; SQLite WAL mode allows multiple simultaneous readers.
• Writes (SaveTestRun, UpdateBaseline, AddCalibrationExample, etc.) are serialized by the caller. In normal operation, all writes pass through the single result-collector goroutine in runner.TestRunner, so no additional locking is required here. Tests that call write methods from multiple goroutines must serialize access externally.
• If concurrent writes are attempted, they will serialize on the SQLite WAL write lock. This is safe but introduces latency. It is not the intended use.

Database options applied on Open:

• PRAGMA journal_mode = WAL
• PRAGMA foreign_keys = ON
• PRAGMA busy_timeout = 5000 (5 second timeout on write contention)

func NewSQLiteStore

func NewSQLiteStore(path string) (*SQLiteStore, error)

NewSQLiteStore opens or creates the SQLite file at path, applies WAL mode and foreign key pragmas, and runs the embedded schema migration (idempotent). Returns an error if the file cannot be opened or the migration fails.

func (*SQLiteStore) AddCalibrationExample

func (s *SQLiteStore) AddCalibrationExample(ctx context.Context, example judge.CalibrationExample) (int64, error)

AddCalibrationExample persists a new human-annotated calibration example.

func (*SQLiteStore) Close

func (s *SQLiteStore) Close() error

Close releases the database connection.

func (*SQLiteStore) GetBaseline

func (s *SQLiteStore) GetBaseline(ctx context.Context, toolName string, dim types.Dimension) (*Baseline, error)

GetBaseline returns the rolling baseline for a specific tool and dimension.

func (*SQLiteStore) GetCalibrationExamples

func (s *SQLiteStore) GetCalibrationExamples(ctx context.Context, rubricID string) ([]judge.CalibrationExample, error)

GetCalibrationExamples returns all human-annotated examples for a rubric.

func (*SQLiteStore) GetHistory

func (s *SQLiteStore) GetHistory(ctx context.Context, filter HistoryFilter) ([]*result.TestRun, error)

GetHistory returns TestRuns matching the filter, newest first.

func (*SQLiteStore) GetLatestCalibrationResult

func (s *SQLiteStore) GetLatestCalibrationResult(ctx context.Context, rubricID string) (*judge.CalibrationResult, error)

GetLatestCalibrationResult returns the most recent calibration result for a rubric.

func (*SQLiteStore) GetTestRunByID

func (s *SQLiteStore) GetTestRunByID(ctx context.Context, runID string) (*result.TestRun, error)

GetTestRunByID retrieves a single TestRun by its unique run ID. Returns ErrNotFound if no run matches.

func (*SQLiteStore) ListDistinctTools

func (s *SQLiteStore) ListDistinctTools(ctx context.Context) ([]ToolDimensionPair, error)

ListDistinctTools returns all unique (toolName, dimension) pairs from stored test results.

func (*SQLiteStore) PruneHistory

func (s *SQLiteStore) PruneHistory(ctx context.Context, olderThan time.Time) (int64, error)

PruneHistory deletes TestRuns older than the given time.

func (*SQLiteStore) SaveCalibrationResult

func (s *SQLiteStore) SaveCalibrationResult(ctx context.Context, res judge.CalibrationResult) error

SaveCalibrationResult persists a calibration run result.

func (*SQLiteStore) SaveTestRun

func (s *SQLiteStore) SaveTestRun(ctx context.Context, run *result.TestRun) error

SaveTestRun persists a complete TestRun. Results and Summary are serialized as JSON.

func (*SQLiteStore) UpdateBaseline

func (s *SQLiteStore) UpdateBaseline(ctx context.Context, toolName string, dim types.Dimension) error

UpdateBaseline recomputes and stores the baseline for a specific tool and dimension from the last 5 runs in the history.

type Store

type Store interface {
	// SaveTestRun persists a complete TestRun after execution.
	SaveTestRun(ctx context.Context, run *result.TestRun) error

	// GetBaseline returns the rolling baseline for a specific tool and dimension.
	// The baseline is the mean of the most recent 5 successful runs on the same branch.
	// Returns ErrNoBaseline if fewer than 1 run exists for this tool/dimension.
	GetBaseline(ctx context.Context, toolName string, dim types.Dimension) (*Baseline, error)

	// UpdateBaseline recomputes and stores the baseline for a specific tool and dimension
	// from the last 5 runs in the history. Called after each run completes.
	UpdateBaseline(ctx context.Context, toolName string, dim types.Dimension) error

	// ListDistinctTools returns all (toolName, dimension) pairs that have at least
	// one run in the history. Used by `periscope baseline --update` to enumerate
	// all pairs that need baseline recomputation.
	ListDistinctTools(ctx context.Context) ([]ToolDimensionPair, error)

	// GetCalibrationExamples returns all human-annotated examples for a rubric.
	GetCalibrationExamples(ctx context.Context, rubricID string) ([]judge.CalibrationExample, error)

	// AddCalibrationExample persists a new human-annotated calibration example.
	// Returns the auto-assigned ID of the created record.
	// Used by `periscope calibrate import`.
	AddCalibrationExample(ctx context.Context, example judge.CalibrationExample) (int64, error)

	// SaveCalibrationResult persists a calibration run result.
	SaveCalibrationResult(ctx context.Context, res judge.CalibrationResult) error

	// GetLatestCalibrationResult returns the most recent calibration result for a rubric.
	// Returns ErrNotFound if no calibration has been run.
	GetLatestCalibrationResult(ctx context.Context, rubricID string) (*judge.CalibrationResult, error)

	// GetHistory returns TestRuns matching the filter, newest first.
	GetHistory(ctx context.Context, filter HistoryFilter) ([]*result.TestRun, error)

	// GetTestRunByID retrieves a single TestRun by its unique run ID.
	// Returns ErrNotFound if no run matches.
	GetTestRunByID(ctx context.Context, runID string) (*result.TestRun, error)

	// PruneHistory deletes TestRuns older than the given time.
	// Returns the number of runs deleted.
	PruneHistory(ctx context.Context, olderThan time.Time) (int64, error)

	// Close releases the database connection. Must be called when the store is no longer needed.
	Close() error
}

Store is the persistence interface. All methods are context-aware. Implementations must be safe for concurrent reads but expect serialized writes (all writes funnel through the single result-collector goroutine in runner.TestRunner).

type ToolDimensionPair

type ToolDimensionPair struct {
	ToolName  string          `json:"toolName"`
	Dimension types.Dimension `json:"dimension"`
}

ToolDimensionPair is one (toolName, dimension) combination from the run history.