Module explain 

Data-aware “explain” trace for a single rule against a single event.

Static tooling (validate, lint, LSP) answers “is this rule well-formed?” It cannot answer “given this event, why did the rule not match?” because it has no event data. explain_rule fills that gap: it walks the compiled condition tree against one event and records, for every node and field, whether it matched and why not.

Unlike the production evaluator in crate::compiler, the recording evaluator never short-circuits (all/any would hide failing branches) and never consults the bloom pre-filter (an optimization that would mask the real reason). It is a parallel, read-only path: the optimized hot path is untouched.

The verdict can never disagree with the production engine: every per-node matched boolean is computed from the same eval primitives the engine uses, so explain_rule(rule, event).matched == evaluate_rule(rule, event).is_some() holds (pinned by a property test).

Structs

ItemTrace

A single field-or-keyword leaf in a detection trace.

RuleExplanation

A structured explanation of why a rule did or did not match an event.

SelectionBranch

One selection inside a quantified selector trace.

Enums

ConditionTrace

A node in the explained condition tree, mirroring ConditionExpr.

DetectionTrace

A node in the explained detection tree, mirroring CompiledDetection.

MatchReason

Why a single leaf matched or did not.

Functions

explain_rule

Explain why rule did or did not match event.