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 ¶
const ( RootEntity = "entity" RootEvent = "event" )
RootEntity and RootEvent are the CEL root variables of an entity-source predicate.
Variables ¶
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 ¶
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.
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.