oracle

type Canon ¶

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

Canon is a result in canonical comparable form. Exported so other differential harnesses (the standalone-vs-distributed oracle, #288) share the same comparison semantics as the kill-switch oracle.

Rows are rendered at two float precisions. Rounding floats can land a value exactly on a rounding boundary, where one ULP of accumulation- order noise between two CORRECT runs flips the rendered digit (observed: SUM at 14903.55 rendering 14903.5 vs 14903.6). A divergence therefore only counts when it survives BOTH precisions — real bugs (missing rows, nulls, dropped limits, wrong groups) differ at every precision, while a boundary hit at two independent quanta simultaneously is vanishingly rare. The cost: a float-only error smaller than the coarse quantum (~1e-4 relative) is absorbed; row-membership and integer errors are unaffected.

func Canonicalize(res *Result) *Canon

func CanonicalizeOrdered(res *Result) *Canon

func (b *Canon) Diff(other *Canon, q Query) string

func (b *Canon) Rows() int

type CmpMode ¶

type CmpMode int

CmpMode selects how strictly two results are compared.

const (
	// CmpUnordered compares the row multiset; row order is ignored.
	CmpUnordered CmpMode = iota
	// CmpOrdered compares rows positionally: the sequence is part of the answer.
	CmpOrdered
	// CmpCount compares row counts only.
	CmpCount
)

func (m CmpMode) String() string

type CompareSpec ¶

type CompareSpec struct {
	Mode CmpMode
	// Limit, when > 0, is the trailing LIMIT both sides must respect.
	Limit int
	// OrderKeys are the projected ORDER BY keys, in ORDER BY sequence. Under
	// CmpUnordered they turn into a positional comparison of just those
	// columns, which is tie-immune. Empty when the keys are not projected.
	OrderKeys []OrderKey
}

CompareSpec is everything the harness needs to compare one query's results without producing a false positive.

type Fingerprint ¶

type Fingerprint struct {
	// Rows is the row count; it is part of the identity, so a fingerprint
	// never matches a result of a different size.
	Rows int `json:"row_count"`
	// Fine and Coarse are the digests at 6 and 4 significant float digits.
	Fine   string `json:"fine"`
	Coarse string `json:"coarse"`
}

Fingerprint is a stored-comparable digest of a whole result: the row count plus one digest per precision of the canonical row rendering. It exists so a reference engine's answer can be committed to a file and compared later without that engine on the machine — the shape the DuckDB ground-truth gate needs.

Three properties the gate depends on, in the order they were learned the hard way:

• Every column is covered, strings and NULLs included. A per-column numeric sum (internal/harness's value signature) skips string columns entirely, which is how a NULLed name column (#314) shipped green. Here a NULL renders "<null>", distinct from the empty string, and a string cell contributes its bytes.

• Order sensitivity is the CALLER's decision, per query. With ordered set, the row sequence is part of the digest, so a dropped ORDER BY (#313/#316/#320) changes it; without, rows are sorted first, so an engine free to return them in any order is not held to one. Passing ordered for a query with no top-level ORDER BY would manufacture failures; passing it false for one that has an ORDER BY is the blind spot those three bugs walked through.

• Float summation order does not move it. The rows are rendered at two precisions and a match at EITHER counts, which is the same dual-precision policy Canon.Diff applies and for the same reason (see the Canon doc comment): one ULP of accumulation noise can flip a rendered digit at a rounding boundary, but not at two independent quanta at once.

func FingerprintOf(res *Result, ordered bool) Fingerprint

func (f Fingerprint) Match(got Fingerprint) (bool, string)

func (f Fingerprint) String() string

type OrderKey ¶

type OrderKey struct {
	Alias string
	Desc  bool
}

OrderKey names an output column that carries one ORDER BY key's value, together with the direction the query asked for.

type Query ¶

type Query struct {
	Name string
	SQL  string
	// CountOnly relaxes the comparison to row counts within Tolerance.
	// Reserved for queries whose row MEMBERSHIP legitimately shifts with
	// float accumulation order (threshold comparisons over float
	// aggregates, the TPC-H Q02/Q22 class) — cell-exact comparison would
	// flake on borderline rows even between two correct runs.
	CountOnly bool
	Tolerance int
}

Query is one corpus entry.

func ExpandLimits(queries []Query) []Query

type Result ¶

type Result struct {
	Columns []string
	Rows    []map[string]any
	// RowValues is the same rows POSITIONALLY, cells aligned with Columns,
	// and it mirrors wadjet.QueryResult.RowValues: non-nil only when two
	// output columns share a name and the map therefore cannot hold both.
	// canonRowsWith reads it in preference to Rows when it is set.
	//
	// Without it a duplicate name silently SHRINKS the comparison: the
	// ClickBench corpus's Q30 is ninety columns all named `sum` — the map
	// holds one — so an oracle arm that moved eighty-nine of them would
	// have compared eighty-nine copies of the same surviving cell and
	// agreed with itself. Duplicate names became ordinary at 042f9852,
	// where an unaliased column started carrying the name PostgreSQL gives
	// it, and const-arith-agg and int-arith are exactly the toggles those
	// columns exercise.
	RowValues [][]any
}

Result is the minimal result shape the harness compares. Rows are column-name-keyed, matching wadjet.QueryResult.

type RunFunc ¶

type RunFunc func(ctx context.Context, sql string) (*Result, error)

RunFunc executes one SQL query under the currently-set toggles.