assume

Documentation

Overview

Package assume loads external assumption files: bounds the engine treats as trusted user claims for named functions, without touching the target's source. Semantically an entry is a //bigo:cost directive applied from the outside; it reuses the directive grammar and never introduces a second bound syntax.

Malformed or unresolvable entries are hard errors, never skips: a silently dropped assumption corrupts a what-if measurement (spec §3).

Three limits are measured, not theoretical: interface methods and builtins cannot be named at all (campaign 1, proven on a fixture), and a key is separated from its bound at the first " O(" so that keys containing spaces — a method on a generic type with two or more type parameters — stay expressible (2026-08-11 review F5).

Index

• type Entry
  • func ParseFile(path string) ([]Entry, error)
  • func ParseText(text string) ([]Entry, error)
• type Set
  • func Load(path string) (*Set, error)
  • func NewSet(es []Entry) *Set
  • func (s *Set) Entries() []Entry
  • func (s *Set) Err() error
  • func (s *Set) For(key string, sig *types.Signature) (bound.Bound, []string, bool)
  • func (s *Set) Has(key string) bool
  • func (s *Set) Validate(prog *ssa.Program) error
  • func (s *Set) ValidateMatched(prog *ssa.Program) (unmatched []string, err error)

Types

type Entry

type Entry struct {
	Key  string
	Expr string
	Line int
	Dir  annotation.Directive
}

Entry is one parsed assumption: treat the function named Key as having the time bound Expr. Key is the cost table's vocabulary — package-qualified name, receiver-qualified for methods (costtable.FuncKey).

func ParseFile

func ParseFile(path string) ([]Entry, error)

ParseFile reads and validates an assumption file.

func ParseText

func ParseText(text string) ([]Entry, error)

ParseText parses assumption-file content from a string (tests, whatif).

type Set

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

Set is a loaded assumption file, compiled lazily per target signature. Safe for concurrent use: go/analysis runs packages in parallel.

func Load

func Load(path string) (*Set, error)

Load reads, parses, and indexes an assumption file.

func NewSet

func NewSet(es []Entry) *Set

NewSet indexes parsed entries. Duplicate keys were rejected at parse.

func (*Set) Entries

func (s *Set) Entries() []Entry

Entries returns the entries in file order (the document's trust surface).

func (*Set) Err

func (s *Set) Err() error

Err returns the first compilation error recorded by For, if any.

func (*Set) For

func (s *Set) For(key string, sig *types.Signature) (bound.Bound, []string, bool)

For returns the compiled bound and the argument-name vector for key against sig, compiling on first use. The names align with ssa.CallCommon.Args for a static call: a method's receiver is Args[0], so names[0] is a placeholder the bound cannot reference — receiver-dependent assumption bounds are not supported (parameters only).

A compilation failure is recorded (Err) and reported as no-match here: CallCost cannot error, and the whole-module drivers surface it via Validate before any analysis runs.

func (*Set) Has

func (s *Set) Has(key string) bool

Has reports whether key has an assumption, without compiling it.

func (*Set) Validate

func (s *Set) Validate(prog *ssa.Program) error

Validate checks every entry against the loaded program: each key must match at least one function, and each matched entry must compile against its signature. Hard errors both ways (spec §3) — the single-module drivers call this before analysis so a broken set never produces numbers.

func (*Set) ValidateMatched

func (s *Set) ValidateMatched(prog *ssa.Program) (unmatched []string, err error)

ValidateMatched compiles every entry that matches a function in prog and returns the keys that matched nothing, sorted. The error covers compilation failures only.

This is Validate's body with the unmatched-key verdict handed to the caller, because the right verdict depends on the population. Over ONE module an unmatched key is a hard error: it is almost always a typo, and a typo that silently contributes zero produces a fake NO-GO. Over a MULTI-module sweep the same key may be absent from one small module and central to the next — there it contributes zero to that module by arithmetic, not by corruption, and the sweep restores the protection by requiring each key to match somewhere in the population.