runtime

type Bind struct {
	FromTree bool
	Idx      int16
	// Elem selects within a slice value: 0 binds the value whole; k>0
	// binds element k-1 (@in arity expansion on Tier 2 dialects).
	Elem int16
}

type CacheStats struct {
	// Hits counts accesses served from a memoized entry. Summed from
	// per-entry counters plus the folded counts of evicted entries, so
	// eviction never loses history; hit rate = Hits/(Hits+Misses).
	//
	// Hit counting starts at the first SetObserver, Stats, or
	// TopShapes call (sticky): a cache that is never observed pays
	// nothing for the counter on its lock-free hit path. Scrape-based
	// consumers read deltas between scrapes, which the warm-up does
	// not distort past the very first interval.
	Hits uint64
	// Misses counts compositions performed, including raced duplicates
	// whose entry was discarded (the work happened).
	Misses uint64
	// Inserts counts entries created — the driver-side proxy for
	// distinct SQL texts handed to the driver (each is what a
	// per-connection statement cache would prepare).
	Inserts uint64
	// Evictions counts second-chance evictions. A nonzero rate on a
	// steady workload means the shape set outgrows Capacity.
	Evictions uint64
	Entries   int // resident entries
	Capacity  int
	// SQLBytes is Σ len(sql) over resident entries. The lock-free read
	// path's lagging snapshot may briefly retain up to about twice
	// this (see the ComposedCache.fast comment).
	SQLBytes int64
}

type Case struct {
	Text       string
	ParamSpans []Span
	ParamIdx   []int16
}

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

type Expanded struct {
	SQL    string
	ArgIdx []int16
}

type Frag struct {
	Kind       Kind
	Text       string
	ParamSpans []Span  // :name token positions within Text
	ParamIdx   []int16 // flattened params-struct index per span
	GuardMask  uint64  // Guarded: all these bits must be set
	Sep        Sep
	Cases      []Case // Choose: named cases, then the default (if any)
	// OrderBy: the keys
	Default *Case // OrderBy: the @default clause body (may be nil)
}

type Kind uint8

type Observer interface {
	// ObserveCompose fires once per cache access: hit reports whether
	// a memoized entry was served (true) or composition ran (false).
	// Under a race, two compositions of one shape may both report
	// hit=false while a single entry is inserted — compose events can
	// exceed insertions, never undercount work. The key's slices are
	// shared with the caller: copy them before retaining the key.
	ObserveCompose(query string, key ShapeKey, hit bool)

	// ObserveExec fires from generated code after a database call
	// completes: the call's context (for trace correlation and metric
	// exemplars), its duration, its row count (rows returned for
	// queries, rows affected for execs; -1 when the count was unknown
	// — a driver error or an aborted scan), and the driver error if
	// any. It receives the shape key as its canonical encoding, not a
	// ShapeKey: generated code builds its key on the stack, and
	// passing that through an interface call would heap-allocate the
	// key's slices on every call, observed or not — the encoding is
	// built inside the observer guard instead, so only observed calls
	// pay for it. (ObserveCompose can pass the cache's retained key
	// for free, which is why the two differ. ObserveCompose carries no
	// context because the cache API takes none.)
	ObserveExec(ctx context.Context, query, shapeKey string, d time.Duration, rows int64, err error)

	// ObserveReject fires from generated code when a call is refused
	// before any SQL is sent: [ErrChooseRequired], [ErrOrderKey],
	// [ErrFilterRequired], [ErrTreeTooLarge], [ErrTreePredicate],
	// [ErrShapeKeyLimit]. Classify with errors.Is, never by message.
	ObserveReject(ctx context.Context, query string, err error)
}

type Sep uint8

type ShapeKey struct {
	Guards  uint64
	Choices []uint8
	// Orders holds one key sequence per @order-by block (elements are
	// key<<1|desc). nil inner = maximal/all keys (verification only);
	// empty = default-or-omit.
	Orders [][]uint8
	// Trees holds the canonical structural encoding of each
	// @filter-tree value (values excluded) — the cache-key component
	// for tree-shaped queries.
	Trees []string
	// Arities holds the element count of each @in slice, in template
	// order — a shape dimension on expanding dialects only (empty on
	// PostgreSQL, whose `= ANY` binds the slice whole).
	Arities []int32
}

type ShapeSpaceInfo struct {
	// Enumerable counts the reachable shapes of the enumerable
	// dimensions (guard sets × @choose ordinals × @order-by
	// selections), saturating at MaxUint64.
	Enumerable uint64
	// Exact is false when the true count exceeded Enumerable's range
	// (large @order-by permutation spaces).
	Exact bool
	// Unbounded marks dimensions the count deliberately excludes —
	// @filter-tree structure, and @in arity on expanding dialects —
	// under which used/reachable coverage is a floor, never a ratio.
	Unbounded bool
}

type ShapeUse struct {
	Query string
	Key   string // canonical ShapeKey encoding
	// Hits counts accesses served by the resident entry; it resets if
	// the shape is evicted and later recomposed.
	Hits     uint64
	SQLBytes int // len of the composed SQL
}

type Span struct{ Start, End int32 }

type Style uint8

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

type TreeCaps struct {
	MaxNodes int
	MaxDepth int
}