Core Concepts
The vocabulary of BlazeRules: rules, conditions, operators, actions, decisions, scores, risk bands, winning rules, and how a batch is evaluated.
This page defines the terms used throughout the BlazeRules documentation and explains the two outputs every evaluation produces: a categorical decision and a numeric score. Read this once and the rest of the docs read faster.
Glossary
| Term | Meaning |
|---|---|
| Rule set | A named, versioned collection of rules under the top-level ruleset: key. |
| Rule | A single unit with an id, an action, optional severity and weight, and a conditions: tree. |
| Condition tree | The boolean expression of a rule, built from and / or / not wrapping individual conditions. |
| Operator | The test applied to a field, given by op: (one of 50, e.g. gt, in, regex, ip_in_subnet). |
| Action | What a matching rule asks for: approve, flag, review, block, or score. |
| Severity | A qualitative level on a rule: LOW, MEDIUM, HIGH, or CRITICAL. |
| Weight | A numeric contribution a matching rule adds toward a record's score. |
| Score | A numeric value accumulated from the weights of the rules a record matched. |
| Risk band | A categorical bucket derived from the score, returned in result.risk_bands. |
| Decision | The single categorical verdict for a record, chosen from matched actions by precedence. |
| Winning rule | The rule that determined a record's decision, returned in result.winning_rule_ids. |
| Decision precedence | The ordered ladder that resolves which action wins when several fire. |
| Shadow rule | A rule evaluated for observation without affecting the live decision. |
| Batch | The unit of evaluation — many records evaluated together in one call. |
| Schema inference | Deriving column types from the first evaluated batch when no schema is supplied. |
| Derived column | A column computed once per batch from a window, model_score, or vector_distance. |
| Window | A stateful aggregate (count/sum/avg/ratio/min/max) over an entity's prior batches. |
| Lookup | A named CSV set (string/int/CIDR) referenced by in_lookup / not_in_lookup operators. |
Two outputs: decision and score
Every record produces both a decision and a score. They answer different questions and are computed differently.
Decision — the verdict
A single categorical outcome (e.g. BLOCK, REVIEW, APPROVE). When more than one rule matches a record, the decision precedence ladder picks the winner, and that rule becomes the record's winning rule (result.winning_rule_ids). Use result.indices_for_decision(...) and grouped_decision_indices() to route a batch by decision.
Score — the magnitude
A numeric value accumulated from the weight of every rule the record matched. The score is then mapped into a risk band (result.risk_bands). Scoring is additive across matched rules, independent of which single rule won the decision.
Decision precedence
When several rules fire on one record, their actions are resolved by a configurable ladder set at the top level of the rule file:
decisions:
default: approve
precedence: [approve, flag, review, block]default is the decision for a record that matched no rule. precedence orders the actions from lowest to highest priority, so the most severe matched action wins. The README documents the default ladder as block > review > flag > score > approve; the canonical sample file pins its own order as shown above. Tune it to your domain via the decisions: block.
Risk bands are HIGH, MEDIUM, and LOW: BLOCK or score >= 80 is high, REVIEW or score >= 40 is medium, FLAG or a positive score is low, and unmatched records are low. A shadow: true rule still appears in match counts, but it does not add score, change the decision, or become the winning rule.
Where to go next
All 50 operators, grouped by family, with copy-pasteable YAML.
Winning rules, precedence, weights, and risk bands in depth.
Stateful aggregates over an entity's prior batches.
Reference CSV sets from rules with the lookup operators.
Column types, schema inference, and field hints.