entitycel

package
v0.57.1-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 20, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package entitycel binds a normalized entity (normalized-entity v1) to CEL and evaluates entity-source harness predicates over a required `entity` and a nullable `event` (ADR 0098, ADR 0147).

The binding preserves the distinctions the specification draws between absent, null, known, and unresolved data:

  • an absent field (it does not apply to the entity's kind) is omitted and follows ordinary CEL missing-key behavior;
  • a null field is CEL null;
  • an unknown field ($unknown: not_loaded, partial, unsupported, failed, consistency_unknown) is a CEL unknown at its attribute path;
  • a collection with complete coverage is an ordinary CEL list, and any other coverage (partial, not_loaded, unknown, unsupported, failed, or no recorded coverage) is a list whose remainder is unknown, so a known member can satisfy `exists` while emptiness, size, and absence stay unknown.

Evaluate reports a three-valued Result; unknown data can never become a false result.

Index

Constants

View Source
const (
	RootEntity = "entity"
	RootEvent  = "event"
)

RootEntity and RootEvent are the CEL root variables of an entity-source predicate.

Variables

View Source
var ErrMalformedEntity = errors.New("entitycel: malformed entity")

ErrMalformedEntity wraps a failure to bind the entity, such as an invalid coverage status. It is a data problem, distinct from a predicate that fails to compile or evaluate.

Functions

func Bind

func Bind(e *normentity.Entity) (map[string]any, error)

Bind converts e into the CEL value bound to the `entity` root variable. It fails on a malformed entity, such as an unknown coverage status or an extension value that does not set exactly one member; callers must treat that as unresolved data, never as a false predicate.

func NewEnv

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

NewEnv creates the CEL environment for entity-source predicates: root variables entity (required) and event (null when no event prompted the evaluation), both dyn.

Its comprehension macros (all, exists, exists_one, existsOne, map, filter) evaluate the comprehension twice when the range is a partial list: over the known members only, and over the known members followed by the unknown remainder. The result is kept only when both agree; otherwise it is unknown. A remainder may hold no members or several, so neither pass alone may decide the result.

func Validate

func Validate(expr string) error

Validate compiles an entity-source predicate and checks that it is a boolean. Unlike an event-only trigger, an empty predicate is invalid: an entity-source harness has no other routing rule.

Types

type Result

type Result int

Result is the three-valued result of an entity-source predicate. The zero value is Unknown so an unset result never reads as a definite answer.

const (
	// Unknown: the evidence does not settle the predicate.
	Unknown Result = iota
	// False: every completion of the evidence makes the predicate false.
	False
	// True: every completion of the evidence makes the predicate true.
	True
)

Predicate results.

func Evaluate

func Evaluate(ctx context.Context, expr string, entity *normentity.Entity, event map[string]any) (Result, error)

Evaluate evaluates an entity-source predicate over the bound entity and an optional event (map form). A nil event binds `event` to CEL null, as for an eventless (scheduled or bound-run) evaluation.

It returns True or False only when the known data settles the predicate, and Unknown when the result depends on unresolved fields or on members a partial collection may hold. Evaluation is bounded by an internal wall-clock timeout and stops when ctx is cancelled, returning an error in either case. A context that is already done on entry returns its error before any binding or compilation work; after that, both are checked only while comprehensions iterate, so a predicate with no comprehension is not interrupted mid-run. Callers must check ctx themselves after Evaluate returns. An error — a predicate that does not compile, a malformed entity (wrapping ErrMalformedEntity), or an evaluation error such as reading a field of a null event — is returned with Unknown and must never be read as false.

func (Result) String

func (r Result) String() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL