oracle

Documentation

Overview

Package oracle drives the canonical algorithm corpus — bigo's prime-directive instrument: real algorithms whose worst-case bounds are known from the literature, pinned in-source, compared against unaided inference by bound domination. An emitted bound that does not dominate its pin is a wrong bound and fails the build. Spec: vault superpowers/specs/2026-07-16-bigo-canonical-corpus-design.md.

Index

• func Collect(srcRoot string) (Report, []WrongBound, error)
• func CollectWith(srcRoot string, opts Options) (Report, []WrongBound, error)
• func ExtractPins(file *ast.File) (map[*ast.FuncDecl]Pin, error)
• type Entry
• type Kind
• type Options
• type Pin
• type Report
  • func (r Report) JSON() []byte
  • func (r Report) Markdown() []byte
• type Status
  • func Classify(emitted, pin bound.Bound) Status
  • func (s Status) String() string
• type WrongBound

Functions

func Collect

func Collect(srcRoot string) (Report, []WrongBound, error)

Collect analyzes every pinned function under srcRoot (GOPATH-shaped, like the metrics corpus) with the shipped, unaided InferTop/SpaceOf pipeline and classifies each dimension against its pin. Reconciliation is asserted, not logged: a pinned function that fails to load, resolve to SSA, or normalize its pin is an error, never a skip.

func CollectWith

func CollectWith(srcRoot string, opts Options) (Report, []WrongBound, error)

CollectWith is Collect under an explicit cost model. See Options.

func ExtractPins

func ExtractPins(file *ast.File) (map[*ast.FuncDecl]Pin, error)

ExtractPins returns the pinned function declarations of one file. Malformed pins are errors, never skips: a skipped pin would be a silently missing oracle entry, and the reconciliation count could not catch it.

Types

type Entry

type Entry struct {
	Pkg         string `json:"pkg"`
	Func        string `json:"func"`
	TimePin     string `json:"time_pin"`
	TimeGot     string `json:"time_got"`
	TimeStatus  string `json:"time_status"`
	SpacePin    string `json:"space_pin,omitempty"`
	SpaceGot    string `json:"space_got,omitempty"`
	SpaceStatus string `json:"space_status,omitempty"`
	Cause       string `json:"cause,omitempty"` // CauseKind of causes[0] when time is top
	Source      string `json:"source"`
}

Entry is one corpus function's golden row. All bounds are rendered strings; the golden is a document, not an API.

type Kind

type Kind string

Kind names which corpus a Report describes. It selects the golden's preamble and nothing else: the scoring rules are identical, and the two corpora differ in what their pins MEAN rather than in how they are classified.

const (
	// CanonicalCorpus pins literature bounds under the default cost model.
	CanonicalCorpus Kind = ""
	// KataCorpus pins human claims on submitted solutions under the kata model.
	KataCorpus Kind = "kata"
)

type Options

type Options struct {
	// Overlay prices calls on the TIME axis. Nil means the default model.
	Overlay *assume.Set
	// Corpus names which golden this run renders, so a reader cannot mistake a
	// human's average-case claim for a literature bound.
	Corpus Kind
	// SpaceOverlay prices calls on the SPACE axis.
	//
	// Separate from Overlay, and attached together or not at all: what a call
	// costs and what it allocates are two assertions, and a corpus scored with
	// kata time and default space would carry two cost models and say so
	// nowhere. That shape shipped once already (v1.52.1) and is why this is two
	// fields rather than one flag.
	SpaceOverlay *assume.Set
}

Options carries the cost model a corpus is scored under.

The canonical corpus passes the zero value: its pins are literature bounds, which are claims about an algorithm and not about any particular cost model. The kata corpus passes the kata profile, because a kata's graded claim is made IN that model — "one element comparison is one element operation" is what makes the author's O(n log n) the right answer for a comparison sort. Scoring a kata claim under the default model would answer a question nobody asked.

type Pin

type Pin struct {
	// Time is the literature worst-case time bound (Budget + where-Bindings).
	Time annotation.Directive
	// Space is the literature auxiliary-space/stack bound; nil when the
	// literature states none (then only time is scored).
	Space *annotation.Directive
	// Source is the mandatory citation. An entry without a citation does not exist.
	Source string
}

Pin is one corpus entry's parsed ground truth.

type Report

type Report struct {
	// Corpus selects the golden's preamble; empty for the canonical corpus, so
	// that file's JSON is unchanged by this field existing.
	Corpus        Kind           `json:"corpus,omitempty"`
	Total         int            `json:"total"`
	TimeByStatus  map[string]int `json:"time_by_status"`
	SpaceByStatus map[string]int `json:"space_by_status"`
	PerFamily     map[string]int `json:"per_family"`
	Entries       []Entry        `json:"entries"`
}

Report is the golden document. Deterministic by construction: sorted entries, sorted map keys (encoding/json), no timestamps, no absolute paths.

func (Report) JSON

func (r Report) JSON() []byte

JSON renders the committed golden: indented, sorted map keys, trailing newline.

func (Report) Markdown

func (r Report) Markdown() []byte

Markdown renders CORPUS.md or KATA.md. GENERATED output — regenerate via task corpus / task kata-corpus.

The preamble is chosen by r.Corpus rather than shared, because the two corpora pin different KINDS of claim and a reader who mistakes one for the other draws the wrong conclusion from a `loose` row: against literature it is a graduation target, against a human's average-case claim it is bigo and the author answering different questions.

type Status

type Status int

Status is one entry's per-dimension oracle outcome.

const (
	// Wrong means the emitted bound does not dominate the pin — strictly below
	// OR incomparable. A prime-directive break; fails the build unconditionally
	// and never appears in a golden (spec §4.2).
	Wrong Status = iota
	// Exact means emitted equals the pin.
	Exact
	// Loose means emitted strictly dominates the pin — sound; a graduation target.
	Loose
	// Top means emitted is ⊤ — safe; the annotate-or-trust evidence rows.
	Top
)

func Classify

func Classify(emitted, pin bound.Bound) Status

Classify compares an emitted bound against a normalized pin. Soundness is domination: Check(pin, emitted) == Within proves pin ≤ emitted. Everything unproven — Exceeds and Unknown alike, so incomparable included — is Wrong: an emitted bound that grows slower than the true bound in any regime is a wrong bound. A legitimately-incomparable-but-sound case is a pin-expression bug and is fixed by restating the pin, never by weakening this rule.

func (Status) String

func (s Status) String() string

type WrongBound

type WrongBound struct {
	Pkg, Func, Dim, Pin, Got string
}

WrongBound is a prime-directive break: an emitted bound that does not dominate its pin. Wrongs are returned separately and never rendered into a golden.

Named WrongBound, not Wrong: the plan's `type Wrong struct` collided with the Wrong Status constant in classify.go. Status is the one the tests and Classify name, so the struct took the new name.