celspike

Documentation

Overview

Package celspike is a throwaway Spike A harness for CEL residual risks (ADR-0013). Excluded from the D-010 coverage gate; tests are real and runnable.

Index

• Constants
• func AsCELBool(v any) (bool, error)
• func AsCELNumber(v any) (any, error)
• func CompileExpr(env *cel.Env, expr string) (*cel.Ast, error)
• func CompileMessage(env *cel.Env, tmpl string) error
• func DecodeHCLSample(src string) (map[string]any, error)
• func DecodeYAMLMap(src string) (map[string]any, error)
• func EvalBool(env *cel.Env, ast *cel.Ast, activation any) (bool, uint64, error)
• func FormatTraceSummary(traces []LeafTrace) string
• func NewEnv() (*cel.Env, error)
• func ProgramOpts() []cel.ProgramOption
• func VouchSatisfied(state TriState) bool
• type All
• type Any
• type AuthorFacts
• type CoercionCase
• type ErrorClass
  • func ClassifyError(err error) ErrorClass
• type Facts
• type InterpSlot
  • func ParseMessageTemplate(tmpl string) []InterpSlot
• type Leaf
• type LeafTrace
• type Noder
• type Not
• type QuotaFacts
• type TriState
  • func (s TriState) String() string
• type WalkResult
  • func Walk(env *cel.Env, root Noder, activation any) WalkResult

Constants

const CostBudget uint64 = 1000

CostBudget is the recommended program cost limit measured in this spike. Archetype predicates in TestDeterminism stay well under this; see spike-a-cel.md.

Functions

func AsCELBool

func AsCELBool(v any) (bool, error)

AsCELBool accepts only real booleans — YAML 1.1 yes/no decode as strings in yaml.v3 and CEL's == against bool silently returns false (not an error). Adapter must reject.

func AsCELNumber

func AsCELNumber(v any) (any, error)

AsCELNumber prepares a decoded value for numeric CEL comparison under the chosen strategy: preserve int/float identity; never silently parse strings. Values outside int64 when presented as oversized floats surface as overflow errors.

func CompileExpr

func CompileExpr(env *cel.Env, expr string) (*cel.Ast, error)

CompileExpr compiles a CEL expression against the shared env.

func CompileMessage

func CompileMessage(env *cel.Env, tmpl string) error

CompileMessage checks every {{ }} slot against the shared activation env. Unknown fields fail at compile time with a positioned error — never "<no value>".

func DecodeHCLSample

func DecodeHCLSample(src string) (map[string]any, error)

DecodeHCLSample parses a tiny HCL snippet into Go values as HCL would.

func DecodeYAMLMap

func DecodeYAMLMap(src string) (map[string]any, error)

DecodeYAMLMap unmarshals YAML into map[string]any (gopkg.in/yaml.v3 defaults).

func EvalBool

func EvalBool(env *cel.Env, ast *cel.Ast, activation any) (bool, uint64, error)

EvalBool evaluates a checked AST to a boolean, returning cost when tracked.

func FormatTraceSummary

func FormatTraceSummary(traces []LeafTrace) string

FormatTraceSummary is a debug helper for tests.

func NewEnv

func NewEnv() (*cel.Env, error)

NewEnv builds the one activation model used for assert leaves and {{ }} interpolation.

func ProgramOpts

func ProgramOpts() []cel.ProgramOption

ProgramOpts returns program options enforcing the measured cost budget.

func VouchSatisfied

func VouchSatisfied(state TriState) bool

VouchSatisfied maps tri-state onto ADR-0007 vouch polarity: only TriPass satisfies; TriFail and TriError do not (error never proves).

Types

type All

type All struct {
	Children []Noder
}

All requires every child to pass (errors short-circuit as error).

type Any

type Any struct {
	Children []Noder
}

Any requires at least one child to pass.

type AuthorFacts

type AuthorFacts struct {
	Login  string   `cel:"login"`
	Groups []string `cel:"groups"`
}

AuthorFacts mirrors facts.author.

type CoercionCase

type CoercionCase struct {
	Name       string
	Source     string // "yaml" | "hcl" | "go"
	YAML       string
	HCL        string
	OldKey     string
	NewKey     string
	Expr       string
	WantBool   *bool  // nil → expect typed error
	WantErrSub string // substring of expected error when WantBool is nil
	Note       string
}

CoercionCase is one row of the executable YAML/HCL→CEL coercion table.

type ErrorClass

type ErrorClass string

ErrorClass distinguishes the four Spike A error classes in per-leaf traces.

const (
	// ClassNone is set on pass/fail traces (no error).
	ClassNone ErrorClass = ""
	// ClassMissingFact is a missing map key / undeclared reference at eval.
	ClassMissingFact ErrorClass = "missing_fact"
	// ClassUnknownField is a compile-time undefined field on a typed object.
	ClassUnknownField ErrorClass = "unknown_field"
	// ClassTypeMismatch is overload / conversion failure.
	ClassTypeMismatch ErrorClass = "type_mismatch"
	// ClassCostLimit is cel.CostLimit exceeded.
	ClassCostLimit ErrorClass = "cost_limit"
)

Spike A error classes distinguishable in LeafTrace.

func ClassifyError

func ClassifyError(err error) ErrorClass

ClassifyError maps a cel-go / adapter error onto a Spike A error class.

type Facts

type Facts struct {
	Quota  QuotaFacts  `cel:"quota"`
	Author AuthorFacts `cel:"author"`
}

Facts is the typed activation fragment for compile-time field checks (ADR-0016 §2).

type InterpSlot

type InterpSlot struct {
	Expr   string
	Offset int // byte offset of '{{' in the template
	Line   int
	Column int
}

InterpSlot is one {{ expr }} region in a message template.

func ParseMessageTemplate

func ParseMessageTemplate(tmpl string) []InterpSlot

ParseMessageTemplate extracts CEL slots from a message string.

type Leaf

type Leaf struct {
	ID      string
	CEL     string
	Message string
}

Leaf is a CEL expression with optional message template (unevaluated here).

type LeafTrace

type LeafTrace struct {
	ID         string
	State      TriState
	Message    string
	ErrorClass ErrorClass
	Err        error
}

LeafTrace is one leaf's explain record (id, result, message, optional error class).

type Noder

type Noder interface {
	// contains filtered or unexported methods
}

Noder is an all/any/not tree node or a CEL leaf.

type Not

type Not struct {
	Child Noder
}

Not inverts pass/fail; error stays error.

type QuotaFacts

type QuotaFacts struct {
	MaxPartitions int64 `cel:"max_partitions"`
}

QuotaFacts mirrors examples/archetypes/*/facts.yaml quota block.

type TriState

type TriState int

TriState is ADR-0007 amendment 1: true / false / error.

const (
	// TriPass is predicate true.
	TriPass TriState = iota
	// TriFail is predicate false.
	TriFail
	// TriError is evaluation/compile failure (ADR-0007 fail-safe).
	TriError
)

Tri-state outcomes for a leaf or tree node.

func (TriState) String

func (s TriState) String() string

type WalkResult

type WalkResult struct {
	State  TriState
	Traces []LeafTrace
}

WalkResult is the tree outcome plus per-leaf traces.

func Walk

func Walk(env *cel.Env, root Noder, activation any) WalkResult

Walk evaluates an all/any/not tree, capturing a LeafTrace per leaf.