golden

Documentation

Overview

Package golden is a characterization ("golden master") harness for the SQL engine over SimFDB. For a curated corpus of (schema, seeded data, queries) it captures the engine's EXPLAIN plan AND result rows as a canonical text baseline committed under testdata/. The test diffs a fresh capture against the baseline every run: any behavior delta — a changed result (almost always a bug) or a changed plan (a cost-model / rule change) — surfaces as a reviewable golden diff at merge/release. Regenerate with GOLDEN_UPDATE=1 and review the diff before committing it.

This catches CHANGED, not WRONG: a bug baked into the baseline stays green, so it is the COMPLEMENT of the metamorphic oracle, never a substitute. It is only meaningful because SimFDB makes the engine's output a deterministic function of (schema, data, query) — pre-SimFDB the plan/result carried nondeterministic bits and a baseline was noise. See RFC-199 Tier 2 oracles.

Index

• func Capture(s Scenario) (string, error)
• type CaptureError
  • func (e *CaptureError) Error() string
  • func (e *CaptureError) Unwrap() error
• type CaptureSurface
  • func (s CaptureSurface) String() string
• type Scenario

Functions

func Capture

func Capture(s Scenario) (string, error)

Capture runs the scenario over a fresh SimFDB-backed SQL stack and returns the canonical text baseline: for each query, its EXPLAIN plan and its result rows in returned order (so the golden also locks row ordering — a plan change that reorders rows is a real, reviewable delta).

Types

type CaptureError

type CaptureError struct {
	Scenario string
	Query    string
	Surface  CaptureSurface
	Err      error
}

CaptureError reports a scenario query that did not run, and WHICH surface it failed on.

The surface is a field rather than something to read out of the message because the two guards that produce it are independently defeatable: a guard on only one surface still lets the other bake its error into a baseline. A test asserting "this input exercises the rows guard" has to be able to say so structurally, or it silently stops covering that guard the day the input starts failing at plan time instead.

func (*CaptureError) Error

func (e *CaptureError) Error() string

func (*CaptureError) Unwrap

func (e *CaptureError) Unwrap() error

type CaptureSurface

type CaptureSurface int

CaptureSurface names which of a query's two captured surfaces failed.

const (
	// SurfacePlan is the EXPLAIN. A query can fail here and run fine (an unplannable shape).
	SurfacePlan CaptureSurface = iota
	// SurfaceRows is executing the query. A query can fail here after EXPLAIN succeeded (any
	// error raised while evaluating rows — division by zero, a failing cast).
	SurfaceRows
)

func (CaptureSurface) String

func (s CaptureSurface) String() string

type Scenario

type Scenario struct {
	Name    string
	Seed    uint64
	Tables  []string // CREATE TABLE / CREATE INDEX statements placed inside the schema template
	Data    []string // INSERT statements run on the workload connection, in order
	Queries []string // SELECT targets; each is captured as its EXPLAIN plan + result rows
}

Scenario is one corpus entry: a schema (CREATE TABLE / CREATE INDEX bodies for a schema template), deterministic seed data, and the queries to capture. Seed drives SimFDB's clock/ version determinism (the data itself is literal, not random, so the baseline is stable and reviewable).